Dashboard variables

Dashboard variables allow you to create flexible and reusable dashboards. Instead of being limited to only seeing hard-coded tile objects, variables allow dashboard viewers to switch between objects on the fly. Variables can also be used with shared dashboards.

Getting started

Watch the video below to see how variables work.

Use case examples

The following examples detail some of the ways you can use dashboard variables to your streamline your SquaredUp experience.

Create a template dashboard for pipelines

You can create a reusable dashboard template that allows viewers to select the specific pipeline they want to investigate.

For example, instead of building separate dashboards for each pipeline, you can configure a dashboard variable that controls which pipeline is displayed across all tiles. Viewers can then switch between pipelines using the variable dropdown, and the dashboard updates automatically to show the relevant data.

This approach reduces duplication, keeps dashboards easier to maintain, and ensures teams always work from a consistent layout.

Create a filterable dashboard for microservices

You can create a dashboard that displays information about all your microservices by default, then allow viewers to narrow the view to a specific service when needed.

For example, a dashboard might initially show alert activity, deployment status, and performance metrics across your entire microservice environment. Using a dashboard variable, viewers can select a single microservice to focus on, helping them quickly investigate issues or review service health without leaving the dashboard.

This makes the dashboard useful both as a high level overview and as a focused troubleshooting workspace.

Creating dashboard variables

Variables are created when in edit mode on a dashboard. You can only add one variable per dashboard at this time.

1. Navigate to a dashboard or create a new one.
2. Ensure you are in edit mode. To edit a dashboard click the Edit
   button at the top of the dashboard.
3. Click Add dashboard variable
   next to the dashboard title.
4. Configure the following settings in the Add dashboard variable window:
   1. Objects:
      Either select an existing collection from the drop down list, or click Add collection to create a new collection. The objects in the collection are the possible options for the dashboard variable. See Collections.
      
      Note

      You can view and edit collections for a workspace, by clicking on Objects on the left nav bar of that workspace, then on the edit

      button next to the collection you wish to edit.

   2. Default value:
      Select one of the following:
      • All objects: The dashboard defaults to selecting the objects in the specified collection whenever the dashboard is loaded.
      • None: The dashboard displays no objects when loaded Monitoring and KPIs disabled.
        When a dashboard with no default is loaded, you're prompted to pick a variable from the dashboard variable dropdown. If only one object exists in the selection, the dashboard will default to it regardless of this setting.
        • Allow multiple selection:
          Allows the selection of multiple objects in the dashboard variable dropdown. This is enabled by default when Default value is set to All objects but can be manually toggled if the Default value is None.
          

5. Click Add. The variable is enabled for the dashboard and the dropdown field displays next to the title.
   

6. Configure the individual tiles on the dashboard to use the dashboard variable, as described below.

Using dashboard variables

Once you’ve created a dashboard variable, you can then make use of it in your tiles.

They can be linked to tiles in several different ways, depending on how the tile is configured and which data stream you are using.

If a dashboard variable already exists when you create a tile, SquaredUp will often prompt you to use it automatically where relevant. However, if a tile is created before a dashboard variable is added, the variable will need to be manually linked to that tile.

Manually linking a variable simply means editing the tile and connecting one of its inputs to the dashboard variable so the tile updates when the variable value changes.

There are three common ways to link a dashboard variable to a tile.

Link via the Objects tab

If your data stream supports scoped objects, you can link a dashboard variable directly from the Objects tab in the tile editor.

To link a variable here:

1. Create / edit a data tile as normal.
2. On the Objects tab, select the collection with the variable icon
   which indicates this collection is used for the dashboard variable drop down list.
   
   Disabling tile variables
   Note

   If you are editing a tile that was created before a dashboard variable was configured, you must deselect the current collection and then select the collection with the variable icon

3. Complete the tile configuration as normal.
4. Click Save. The tile is now updated automatically whenever you change the variable at the top of your dashboard.
   
   Note

   When creating dashboards and tiles it’s possible to enable monitoring or publish the data as a KPI, which runs in the background without needing to view a dashboard.

   Because of this, Monitoring and KPI are only available when the dashboard variable has a default value.

   This also means that monitoring uses the default value (e.g. all objects) when calculating the latest health state.

Link via the Parameters tab object picker

Some data streams expose their object scope selection via the Parameters tab of the tile editor instead of the Objects tab (for example, the Project context field of the WIQL Query data stream).

In this circumstance, if you have dashboard variable currently enabled where you are configuring the tile, then you can select that variable when selecting the object scope.

To link a variable here:

1. On a dashboard, click Add dashboard variable
   next to the dashboard title and select the variableyou want to use.
2. Create / edit a data tile as normal.
3. On the Parameters tab, when prompted to select the object/s to scope to click Use dashboard variable.
   

4. Complete the tile configuration as normal.
5. Click Save. The tile is now updated automatically whenever you change the variable at the top of your dashboard.

Link via expressions

Expressions allow you to manipulate, format, and parameterize data throughout SquaredUp using Mustache-style placeholders {{ }} combined with JavaScript.

You can choose to insert dashboard variables into expressions, wherever expressions can be used in SquaredUp (for example, in a parameter such as the JQL query field or when creating a script).

See Expressions for more information.

Was this article helpful?