This article will discuss how to create, use, and update Application Variables. This feature allows you to create a variable for items and Scenarios that can be used in multiple areas, such as page selectors, and updated all at once.
What are variables?
This functionality allows you to create a custom variable at the application level to be used in Page Selectors, Show Value as (Coming soon), or Calculated Items, that can be dynamically updated all at once. First create a variable, define it with a specific item or scenario, and then use it in multiple different page selectors, or calculated items. Then, when it's time to update boards or the views they are used in, you update the variable with the new item or Scenario, then the value changes in every location you used it in.
Common use cases
Time Dimensions are a common use case, as they change and are often used in multiple locations, making it a pain to update. Some examples of variables could be Current Month, and Last Month. Versions are also another common variable use case. With multiple forecasts that can change, you might have a case for a Current Forecast or Current Budget. Any instance where you have an item or scenario in a view or calculated item/show value as that you have to update frequently is a good use case for variables.
You need “Configure Application” permission to be able to create and update variables. You do not need this permission to apply them.
It's important to first note that variables are set at the application level. While you can use a Shared dimension from another Application, when you create a variable it can only be used in that Application. For example, you can create a Current Month variable that uses a shared dimension from a data hub, however that Variable can only be used in the application it was created in.
How can you use variables?
There are three main uses cases for variables; Page selectors, Show value as items(Coming soon), and Calculated items that need to be updated periodically.
In each of these uses, you first define the variable on a dimension. Once defined, you can apply the variable across multiple uses, such as the Default Item or Available items in a Page Selector, item within Show Value as, or item within a Calculated item.
When it comes time to update that variable, you update it in the variables management screen and it will update in every instance you have used the variable.
For example, if you created a Current Month variable, you could this variable as a page selector for a Board that needs to open on a particular month, use it within a Calculated item, and as a Show Value as item (Coming soon).
When the month needs to be updated, you change the variable and every one of those instances is updated, relieving the need to update in multiple places.
How do you create variables?
Users with the “Configure Application” will be able to create and update variables. You do not need that permission to use a variable, just to create and update.
You can add multiple variables at the same time. The name of the variable will be seen by modelers when they define where to use the variable, but will not be seen by end users. You can’t have two variables with the same name, however, you can use the same item/scenario in multiple variables.
How to use Variables
When setting up a Page Selector, Item within a Calculated item, or Show Value as (coming soon), you will see the variables for the dimension listed at the top. The name of the Variable will be listed, along with the current item set to it below. When a variable is being used, the name of the variable will appear with the settings but the end user will only see the value displayed. For example, if you use a Current Month variable in a Page selector, when you open the Page Options, it will be displayed as Current Month, but the end user will only see the item it is set to.
How do I update Variables?
First access the Variable management screen, by opening an application, selecting Settings, and then Variables. In the Variable management screen, variables are organized by dimension or scenarios. Select the dimension, you wish to update and hit the edit variables icon. Here you can use the dropdown to select the new item. You can also hit the + Add new variable, to add another variable. Once updated, this change will take place across all instances this variable is used.
What happens if I delete a variable?
Before deleting a Variable, it’s important to identify any instances where this variable might be used.
If used in Page Selectors
If you delete a variable that is used in a page selector, there are two possible actions. If the variable is used in a single page selector, it will update to the 1st available item. If in a Multi Page selector, it will change to All values
If used in Calculate Items/ Show Values As
If used in a Calculated item or Show value as, the item will no longer be present and the calculation will still go through. For example, if you have a Current and Previous month variable and your calculation item is set to Current Month - Previous Month. If the Previous Month is deleted, you will see the Current Month’s value in the calculated item.
What happens if I delete an item used in a variable?
We will warn you on the Variables Settings page that the Variable needs to point to an existing item. If it is used as a default item in a page selector, you will get the following message displayed.