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
You 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. 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. Static Variables can be changed during a session in Pigment, giving end users the ability to interact conveniently with filters and other features.
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 (a walk-through is 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.
Dynamic and Member-based Variables take their values from boolean Metrics, containing 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 Scenarios or 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 dropdown 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.
This option is only available for static Variables.
- 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 dropdown:
- 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 dropdown 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.
- Select the boolean tickboxes 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.
- 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.
Scenarios
Variables currently cannot be defined by Scenario. For example, if a different month is checked for each Scenario in the boolean Metric used by the Variable configuration, only the default Scenario value will be considered for the Variable.
Member-based Variables
Member-based Variables are set up as above but require a boolean Metric with two Dimensions. In step 3 of the walkthrough above, choose User as well as the Dimension you wish to set up the Variable on.
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 static Variable values during Pigment sessions
Static 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. Find more guidance on this in Practical Examples and Best Practises for Changeable Static Variables.
When this option is enabled and the Variable is used with Show Values As, a Calculated Item, or a Filter, the available Item values are displayed 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. 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
When Variables are in use, Members don’t see the Variable name, only the Item name.
As shown above in the case of Current month, static Variables are displayed showing their names and the Item they are currently set to. If you allow Members to change the value of a static Variable in a session, then the menu of 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.
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.
Can I set different Member-based Variables for different Scenarios?
No, when setting up Member-based Variables on an application with Scenarios, you can’t set different Page Selectors based on the different Scenarios. Whatever the default Scenario is, those values are taken.
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.