This article discusses how to create, use, and update Item 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 can be updated all at once.
Table of Contents
Permissions need
You need the Configure Application permission to be able to create and update variables. You don’t need this permission to apply them.
What are variables?
This functionality allows you to create a custom variable at the application level to be used in Page Selectors, or Calculated Items, that can be dynamically updated all at once. One type of variable that is already available in Pigment and doesn’t require any configuration is the Current User variable, available only for the User Dimension’s Page Selectors.
First create a variable, define it with a Static variable or use a Metric driven Dynamic or Member-based variable. Then you can use it in multiple different Page Selectors. Static and Dynamic variables can also be used in calculated items, however Member-based are only for Page Selectors.
One of the major advantages of using variables is that 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. For example, if you decide to use the Current User variable as a Default Item in the User Dimension’s Page Selector, the Current User defaults to whichever Member lands on that View or Board.
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 that you have to update frequently is a good use case for variables. You can set them within the variables page with a Static variable or create a boolean metric to update Dynamic or Member-based variables.
Member-based and Dynamic variables allow you to customize Page Selectors Default and Available items with Shared Metrics. This way you can use one Metric to update multiple variables across your entire Workspace.
Security
Variables shouldn’t be used for security purposes. It is only used to limit the selection to help users quickly find the item they need. Depending on a user’s permission settings for Configure Views and/or Configure Boards they could adjust this setting and make items available to them.
Variables must be created in every application you want to use them in. However, since they support Shared Metrics, you can reuse the same Metric to set a variable across multiple applications, which makes maintenance easier. For example, you can create a Current Month variable that is created from a Metric in a data hub, however you need to create the variable in each Application that you want to use it in.
How can you use variables?
There are three types of variables; Static, Dynamic and Member-based. Static and Dynamic variables are the same for every Member. Static variables are defined in the variables management screen, while Dynamic variables reference a boolean Metric making it easier to update. Member-based variables are defined by a boolean configuration Metric composed of the User Dimension and the variable Dimension.
Static and Dynamic variables can be used in Page Selectors and Calculated items that need to be updated periodically.
Member Variables and Current User Variables are only available for Page Selectors and can be used to set Default Item or Available items in a Page Selector
How do you create variables?
Current user variables are different to Static, Dynamic, and Member-based variables because they can't be configured and are always available in your Application.
Users with the Configure Application can create and update variables. You don’t need that permission to use a variable, just to create and update one.
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.
How to set up Static variables
Static variables are completely created within the Items variables screen. These steps take you to the variables management screen for creation. You can also create from the Page Selector dropdown by clicking Create Items variables.
- Open the Application you want to create a variable to be used in
- On the sidebar, click Settings
- Navigate to the Variables section
- Click New variables
- Use the dropdown to select the Dimension you want to define a variable on
- Click + Add Static variable
- Name the Variable
- Select the item for the variable.
- Click Save.
How to set up Dynamic Variables
Dynamic Variables require a boolean Metric with only the Dimension you wish to set up the variable on. For example, if you wanted to use Current Month in a Calculated Item, you would set up a Metric with the Month
list and format as a Boolean, then select which month is the current one or write a formula so it’s automatically updated.
How to set up Member-based Variables
Member-based variables require a boolean Metric that contains the User list and the Dimension you wish to set up the variable on. For example, if you wanted each Member to have their own Country as the Page Selector, you would set up a Metric with the User
and the Country
list and format it as a Boolean. Once set up, you can use a formula or manually input the different values.
Please note, these Metrics shouldn’t reside in the Security folder.
When using a Page Selector that is set to single values with a Member-based Metric that has multiple values set to TRUE, the first value in the list is used.
Adding a Member- based or Dynamic Variable
After you have created your Metric to be used, follow the steps below to create the variable.
- Open the Application you want to create a variable to be used in
- On the sidebar, click Settings
- Navigate to the Variables section
- Click New Variables
- Use the dropdown to select the Dimension you want to define a variable on
- Click + Add Member-based Variable or + Dynamic Variable
- Name the variable
- Under item, choose the Metric you created earlier.
- Click Save.
How to use variables
When you set a Page Selector or Item within a Calculated item, you see established variables for the Dimension listed at the top. Select the option you would like to use, Members won’t see the name of the option, only the item or items the variable is set to.
Member-based and Dynamic variables are displayed by the name of the variable and underneath the variable you’ll see Member-based Variable or Dynamic Variable to let you know the type. Static variables show the name of the variable and then the Item it is currently set to.
Member-based variables can’t be used in Calculated items. Member-based variables aren’t available for Scenario or User list variables.
How do I update variables?
Static 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.
Member-based and Dynamic Variables
Member-based Variables and Dynamic Variables can be updated by adjusting the options within the configuration Metric. For example, if a Member is currently reassigned from Product A to Product B, you would just change the Boolean next to the Member in the User list.
Item variable FAQ
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 will update to the 1st available item. If in a Multi Page Selector, it will change to All values
Calculated Items
If you use a variable in a Calculated item, 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?
The variables Settings page displays a warning 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.