Item Variables allow you to create a custom Variable in your Application, for use and reuse in various features such as Show Values As, Calculated Items and more. When these Variables are updated, the update applies everywhere they are deployed. This article explains what Variables are and how to create, update, and use them.
You need Configure Application permission to be able to create and update Variables. You don’t need this permission to apply them.
The basics of Variables
Workspace administrators can create a custom Variable in your Application to be used in Page Selectors, Calculated Items, Show Values As and Filters. Updates to it appear everywhere automatically.
You can allow Members to change Variables during a session in Pigment, boosting convenience and flexibility.
Any Item that you use in a View and have to update frequently is a good use case for Variables. The Current User Variable is created by default.
Variables can either be static, dynamic or Member-based.
Common use cases
- Time Dimensions: “Current Week/Month” is often needed in multiple locations.
- Versions: cases include “Current Forecast” or “Current Budget”.
- Any time one Item in the set is a focus: “featured product”, “host city”, “flavor of the week”.
Member-based and dynamic Variables take their value from a Metric which can be managed within Shared Metrics. This lets you use one Metric to update multiple Variables across all the Applications in your Workspace.
Variables shouldn’t be used for security purposes. While Variables can be used to limit the selection Members see to help them find what they need, Members may be able to adjust their settings and make all Items visible to them.
What are the different types of Variables?
There are three types of Variables; static, dynamic and Member-based.
Static Variables are created in the Variables settings menu (walk-throughs are below) by choosing a Dimension and then choosing a value for that Variable from the Items comprised in that Dimension. The value remains as that Item until a Member with Configure Application permissions makes changes to it.
For dynamic and Member-based Variables, you set their values in a boolean Metric, containing a selection of Items from one Dimension in the case of dynamic and two in the case of Member-based. The second Dimension of Member-based Variables is a list of users, allowing data to be displayed on a per-user basis. For instance, it might only show data for the country where a specific user operates. Member-based Variables can’t be used in User list Variables.
How to create and update Variables
Static Variables
You can create and update static Variables through the following steps:
- In the Application where you would like the Variable, select the three dots at the bottom of the sidebar.
- Select Variables from the dialog that appears.
- Select Create Variables.
- Use the drop-down to select the Dimension you want to define a Variable for and click + Create a variable.
- Name the Variable.
- (Optional) Select whether Members can change its value during their sessions:
- Allow changes. The value for this Variable isn't fixed, and Members can view other values for this Variable wherever it's used.
- Don't allow. The value for this Variable is fixed, and Members can't select an alternative value.
- Select one of the Dimension list Items to be the Variable’s value.
- Click Save.
- To update your Variables after creation, just click the pencil icon by the Variable to be updated that says Edit Variable when you mouse over it.
You can also create static Variables from the Page Selector drop-down:
- When you have a Metric or Table open in your Application’s main pane that contains a Dimension in Pages, select the options icon to the right of the Page Selector. It is labeled Pages options when you mouse over it.
- Select the field Available items from the dialog that opens.
- Select Create or Manage Items variables at the bottom of the drop-down that opens.
You can add multiple Variables at the same time. The name of the Variable is seen by modelers when they define where to use the Variable, but it won’t 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.
Dynamic Variables
You create and update dynamic Variables as follows:
- First, create a Metric by selecting the + next to Blocks in the sidebar.
- For Data type choose Boolean.
- For Dimension(s) within this Metric, choose the Dimension containing the Item(s) you want to turn into a Variable.
- Select Create.
- Check the boolean checkboxes by the Item(s) you wish to be added to the Variable.
- Select the three dots at the bottom of the sidebar.
- Select Variables from the dialog that appears.
- Select + New Variable.
- From the Items Variables dialog that pops up, select the Dimension you chose in step 3 from the Dimensions drop-down and click + Create a variable.
- Name the Variable.
- Select Dynamic Variable type.
- (Optional) Select whether Members can change its value during their sessions:
- Allow changes. Members can view other values for this Variable wherever it's used.
- Don't allow. Members can't select an alternative value.
- For Select a Metric managing the selection, choose the Metric you created in step 4.
- Select Save.
- To update your Variables after creation, just click the pencil icon by the Variable to be updated that says Edit Variable when you mouse over it. To make changes to the Metric managing the Variable, open up that Metric through the Block explorer in the sidebar.
Member-based Variables
Member-based Variables are set up as above but require a boolean Metric with two Dimensions. In step 3 of the walk-through above, choose User as well as the Dimension you wish to set up the Variable on. Members must have Read access for the boolean Metric.
Please note, these Metrics shouldn’t reside in the Security folder.
When using a Page Selector that is set to single values with a dynamic or Member-based Metric that has multiple values set to TRUE, the first value in the list is used.
Changing Variable values during Pigment sessions
Variables can be changed during a Pigment session. This means that Members can switch between different Items in a defined Dimension, giving greater flexibility in data visualization.
When you choose Allow changes as documented above, and the Variable is used with Show Values As, a Calculated Item, or a Filter, the possible Item values are displayed for selection in a separate menu beside the Page Selector in your Application. It’s also available in whichever Board your Metric is used.
When a Member chooses a value other than the default Variable value in the selector, it only affects that Member in that session. For more information, see Use Page Selectors to Customize Context in Views and Boards.
Use your Variables
The Variables you create appear as options for selection, where eligible, above other options in the following tools (here the Variables are City of the Month or Current Month):
Page Selector
Calculated Item
Show Values As
Filters
When filtering on Dimensions and Metrics:
Display of Variables
Variables are displayed showing their names and the Item they are currently set to. If you allow Members to change the value of a Variable in a session, then the menu of possible values for your Variable is displayed beside your Page Selector above your Metric and also in whichever Board your Metric is used.
Member-based and dynamic Variables are displayed showing their names, with their type (Member-based or dynamic) beneath.
Variables by Scenario
We saw above that dynamic and Member-based Variables take their values from configuration Metrics. You can set up the configuration Metric to give different values to the Variable under different Scenarios, providing a powerful tool when comparing project alternatives. When you reach Step 5 above, simply add Scenarios and check different checkboxes according to which value applies under which Scenario.
For example, below, the configuration Metric P&L adjust config is set up to send three different values to a dynamic Variable. It is 0.00% under the Default Scenario, 1.00% under the CFO Scenario and 3.00% under the Faster Growth Scenario.
Now the dynamic Variable supplies Scenario-aware values for Show Values As and Calculated Items manipulations.
- In the case of Filters, Variable’s values under different Scenarios are combined, meaning that all available values across visible Scenarios are presented
- Page Selectors ignore Scenarios: only the values for the default Scenario apply
Frequently asked questions
Will I see a Member’s values if I impersonate them?
Yes, you use the impersonate functionality, you see the Items set up for a Member. For example, If I impersonate Carole and Carole’s Member-based Variables have her Default Item in a Page Selector set to France, I will see France listed. If the Default Item on the User Dimension Page Selector is set to the Current User Variable, and I impersonate Carole, then the Page Selector defaults to Carole.
What happens if I delete a Variable?
Before deleting a Variable, it’s important to identify any instances where this Variable might be used.
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 updates to the first available Item. If in a Multi Page Selector, it changes to All values.
Calculated Items or Show Values As
If you’re working with Variables in Calculated Items or with Show Values As, the Item will no longer be present and the calculation still goes through. For example, if you have ‘Current month’ and ‘Previous month’ Variables and your calculation Item is set to ‘Current Month - Previous Month’, when ‘Previous month’ is deleted you see only ‘Current month’s value in the calculated Item.
What happens if I delete an Item used in a Variable?
The Variables settings page displays a warning that the Variable needs to point to an existing Item.