Substitution Variables
  • 14 Minutes to read
  • Dark
    Light
  • PDF

Substitution Variables

  • Dark
    Light
  • PDF

Article summary

Overview

Substitution variables are used in the creation of Dynamic Reports and Report Sets. A substitution variable replaces a complex multi-dimensional expression (Rule) with a specified value. Substitution variables must be added to Report Sets as lines to be reflected in reports. Planful provides over 40 system-defined substitution variables.

The purpose of using a substitution variable is to:

  • Improve report performance

  • Improve Report Set maintainability

  • Dynamically display report column/row headers

To access the Substitution Variable page, navigate to Maintenance > Reports > Cube Settings and click the Substitution Variable tab.

Description of Fields

Add (Substitution Variable)

To add a substitution variable to use in a reporting formula:

  1. Enter an identifier in the Code field.
  1. Select the reporting area where you want the substitution variable defined.
  1. Select the dimension where you want the substitution variable defined.
  1. Select the Substitution Value by opening the hierarchy dialog page. Use the hierarchy or filter functions to search for, and select, a specific value.

For information on system-defined substitution variables, click here.

Derived Variables

Click the Derived Variable button on the Substitution Variables page.

Derived Variables contain a formula that references a Substitution Variable and derives an appropriate value by evaluating the formula.

In the example below @CURYR@ is the substitution variable, which displays the current year for the Workforce reporting area. Derivatives of @CURYR@ are:

@CURYR+1@ = pulls data for the year following the current year

@CURYR+2@ = pulls data for 2 years from the current year

For information on system-defined derived variables, click here.

Grid Fields

Code

The name of the substitution variable as used in reporting formulas.

Reporting Area

The reporting area where the substitution variable is defined.

Dimension

The dimension where the substitution variable is defined.

Value

The value a substitution variable points to.

Derived Variables

The number of derivatives for the selected variable.

Understanding Substitution Variables

A substitution variable contains a Name and Value pair. For example:

Substitution Variable Name: @CURMNTH@

Substitution Variable Value: Jan-2018

The Substitution Variable Name is replaced by its Value when the report is executed, thereby making reporting flexible. In the example above, you may create a report column using a the @CURMNTH@ Substitution Variable. When the report is executed the Name is substituted by its Value (i.e. Jan-2018).

Let's say you want to create a Rule for the following:

  • Prior Year Quarter 1

  • Prior Year Quarter 2

  • Prior Year Quarter 3

  • Prior Year Quarter 4

This is how the Rule would look:

  • Q1 Prior year – Openingperiod(Ancestor(Parallelperiod(year,1,Time.CurrentMember),year))

  • Q2 Prior year - Openingperiod(Quarter,Ancestor(Parallelperiod(year,1,Time.CurrentMember),year)).lead(1)

  • Q3 Prior year - Openingperiod(Quarter,Ancestor(Parallelperiod(year,1,Time.CurrentMember),year)).lead(2)

  • Q4 Prior year - Openingperiod(Quarter,Ancestor(Parallelperiod(year,1,Time.CurrentMember),year)).lead(3)

You can also create prior year quarters as derived variables on the @CURQTR@ substitution variable:

  • @PRYRQTR1@ - Openingperiod(Quarter,Ancestor(Parallelperiod(year,1,@CURQTR@),year))

  • @PRYRQTR2@- Openingperiod(Quarter,Ancestor(Parallelperiod(year,1,@CURQTR@),year)).lead(1)

  • @PRYRQTR3@- Openingperiod(Quarter,Ancestor(Parallelperiod(year,1,@CURQTR@),year)).lead(2)

  • @PRYRQTR4@- Openingperiod(Quarter,Ancestor(Parallelperiod(year,1,@CURQTR@),year)).lead(3)

Note:
Substitution Variables can be used on any of the dimensions or attributes available and in any of the reporting areas. You cannot create a substitution variable that includes multiple dimensions, however, you can add multiple dimensions while defining static report sets. For example, if you want to define November MTD you can set the Rule to (@CURMTH@,[Measures].[MTD]) in your report set. If you want to set November for a selected department you might use the following (@CURMTH@,@CURDEPT@).

Attributes and attribute hierarchies mapped on the Attribute Settings page are available in the Financial Reporting Area. Attributes mapped to properties are not available.

Types of Substitution Variables
  1. Standard Substitution Variables:Standard Substitution Variables point to a value, which can be updated by a Reporting Administrator using the Substitution Variable page located under the Maintenance menu. Substitution Variables can be established for any of the dimensions or attributes available in any of the reporting areas.
    • Example: Variable @CURYR@ contains the year value 2018, which internally points to the appropriate Time dimension member such as [Time].&[5045]. The value is used on column headers and the dimension member is used in MDX expressions.

  1. Derived Variables:Derived Variables contain a formula which references a Substitution Variable and derives an appropriate value by evaluating the formula.
    • A Derived Variable named ‘@CURMTH -1@’ can:

      • Reference the following Substitution Variable: @CURMTH@

      • Contains a formula, such as: @CURMTH.Lag(1).

      • Will result in the month preceding the Current Month based on setup.

      • At run time @CURMTH.Lag(1) is evaluated based on the value of @CURMTH@. Generally, the value is used for column headers and the dimension member is used in MDX expressions.

How to Set Up Substitution Variables
  1. Navigate to Maintenance > Reports > Cube Settings and click the Substitution Variables tab.
  1. Review the list of substitution variables defined in the application.
  1. Click the Add button to setup a new substitution variable on the Add Substitution Variable page.
  1. Complete the fields on the Add Substitution Variable page. Note that substitution variables are defined for a reporting area and dimension.
  1. Select the newly added substitution variable on the list page and click the Derived Variables button to view the corresponding derived variables.
  1. Add new derived variables by clicking the Add button on the Derived Variables list page.
  1. The Add Derived Variable page is opened. Complete the fields on this page.
How to Use Substitution Variables

Substitution variables are used in the creation of Dynamic Reports. A substitution variable replaces a complex multi-dimensional expression (Rule) with a specified value. Substitution variables must be added to Report Sets as lines to be reflected in reports. Planful provides over 40 system-defined substitution variables.

Here is a list of places where you can use substitution variables:

  • In rules and on row or column labels and headers.

  • To dynamically display report set lines.

  • As an efficient way to replace formula exceptions: For example, display the current period in the column header of a report by replacing the column set’s line name with a substitution variable, such as @CURMTH@. When the report is run, @CURMTH@ will be replaced with the actual month name Mar-19.

  • Combined with static text: For exampleYTD~ @CURMTH@ will display YTD~ Jan-18 and @CURYR@Actual will display 2018 Actual.

  • To improve report performance by avoiding the use of calculated or measured dimensions when building column sets: For example, the following Report Set is commonly used.

    YTD

    MTD

    Actual

    Budget

    Variance

    Actual

    Budget

    Variance

Setting up this Report Set requires the usage of complex Rules that typically require a column set on a Calculated or Measured dimension and utilizes the Reporting scenario for the Budget column. The following table displays commonly used formulas to deliver report columns.

Line Name

Formula Without Substitution Variables

YTD~Actual

([Measures].[YTD],[Scenario].&[1],[Calculated].&[1])

YTD~Budget

([Measures].[YTD],StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]")),[Calculated].&[1])

YTD~Variance

Custom Formula

MTD~Actual

([Measures].[MTD],[Scenario].&[1] ,[Calculated].&[1])

MTD~Budget

([Measures].[MTD],StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]")),[Calculated].&[1])

MTD~Variance

Custom Formula

Line Name

Formula Without Substitution Variables

YTD~Actual

([Measures].[YTD],[Scenario].&[1],[Calculated].&[1])

YTD~Budget

([Measures].[YTD],StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]")),[Calculated].&[1])

YTD~Variance

Custom Formula

MTD~Actual

([Measures].[MTD],[Scenario].&[1] ,[Calculated].&[1])

MTD~Budget

([Measures].[MTD],StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]")),[Calculated].&[1])

MTD~Variance

Custom Formula

While the rules above deliver the expected result, they are complex. This complexity adversely impacts report performance. The same report can be set up more efficiently using Substitution Variables. The table below displays how Substitution Variables compare to the formulas in the table above.

Line Name

Formula with Substitution Variables

YTD~Actual

([Scenario].&[1] ,[Measures].[YTD])

YTD~Budget

(@CURBGT@,[Measures].[YTD])

YTD~Variance

Custom Formula

MTD~Actual

([Scenario].&[1],[Measures].[MTD])

MTD~Budget

(@CURBGT@,[Measures].[MTD])

MTD~Variance

Custom Formula

Performance for the Report Set depicted in the table above can be improved by moving the repeated member on the Page axis. The Report Set above uses [Measures].[MTD] and [Measures].[YTD] frequently. Move one of these members to the page level. For example, use the member [Measures].[YTD] on the Page axis rather than repeating [Measures].[YTD] on the first and second lines as shown in the table below.

Line Name

Formula with Substitution Variables

YTD~Actual

[Scenario].&[1]

YTD~Budget

@CURBGT@

YTD~Variance

Custom Formula

MTD~Actual

([Scenario].&[1],[Measures].[MTD])

MTD~Budget

(@CURBGT@,[Measures].[MTD])

MTD~Variance

Custom Formula

  • To improve report performance instead of reporting scenario functionality: For example, when using reporting scenario functionality to retrieve the budget and forecast for a selected year, you might use the following rule: StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]"))

While the rule above delivers the expected result, it slows report performance. A performance improvement is to use Substitution Variables as described below.

Line Name

Previous Approach to Formula

Formula with Substitution Variables

Current Budget

StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]"))

@CURBGT@

Current Forecast

StrToMember ("Scenario.&["+Time.Currentmember.properties("forecast_Id")+"]"))

@CURFCST@

Current Month Budget

(Time.Currentmember,StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]")),[CalculatedDim].&[1])

(@CURMTH,@CURBGT)

Prior Year YTD

(Parallelperiod(Year,1,Time.currentmember),[Measures].[YTD])

(@PREVYEAR@,[Measures].[YTD])

  • To improve efficiency in building report sets. Substitution Variables aide in the setup and maintenance of time-based Report Sets, such as Trailing 12 months, along with Budget and Forecast columns. The following example displays a Trailing 12-month Report Set:

Line Name

Previous Approach to Rule

Rule with Substitution Variables

Current Month

(Time.Currentmember,[CalculatedDim].&[1])

@CURMTH@

Current Month - 1

(Time.Currentmember.Lag(1),[CalculatedDim].&[1])

@CURMTH-1@

Current Month - 2

(Time.Currentmember.Lag(2),[CalculatedDim].&[1])

@CURMTH-2@

Current Month - 3

(Time.Currentmember.Lag(3),[CalculatedDim].&[1])

@CURMTH-3@

Current Month - 4

(Time.Currentmember.Lag(4),[CalculatedDim].&[1])

@CURMTH-4@

Current Month - 5

(Time.Currentmember.Lag(5),[CalculatedDim].&[1])

@CURMTH-5@

Current Month - 6

(Time.Currentmember.Lag(6),[CalculatedDim].&[1])

@CURMTH-6@

Current Month - 7

(Time.Currentmember.Lag(7),[CalculatedDim].&[1])

@CURMTH-7@

Current Month - 8

(Time.Currentmember.Lag(8),[CalculatedDim].&[1])

@CURMTH-8@

Current Month - 9

(Time.Currentmember.Lag(9),[CalculatedDim].&[1])

@CURMTH-9@

Current Month - 10

(Time.Currentmember.Lag(10),[CalculatedDim].&[1])

@CURMTH-10@

Current Month - 11

(Time.Currentmember.Lag(11),[CalculatedDim].&[1])

@CURMTH-11@

Current Month - 12

(Time.Currentmember.Lag(12),[CalculatedDim].&[1])

@CURMTH-12@

Current Budget

(Ancestor(Time.Currentmember,1,Year), StrToMember ("Scenario.&["+Time.Currentmember.properties("Budget_Id")+"]")),[CalculatedDim].&[1])

(@CURYR@,@CURBGT)

Current Forecast

(Ancestor(Time.Currentmember,1,Year), StrToMember ("Scenario.&["+Time.Currentmember.properties("forecast_Id")+"]")),[CalculatedDim].&[1])

(@CURYR@,@CURFCST)

  • To overcome Rule Limitations. You cannot use the same dimension on two axes simultaneously. For example, a report that requires a Report Set on the Time dimension, will not allow selection of Time dimension members at the Page level. To set up a trailing 12-month report, define the column set on either the Calculated or Measure dimension. Time should be on the Page axis. This setup does not use substitution variables so performance will not be optimal. With Substitution Variables, the report column set can be set up on the Time dimension directly and the required selections can be made using Substitution Variables, which will result in improved performance.
How to Transition Existing Reports to Use Substitution Variables

Transition an existing report to utilize Substitution Variables to take advantage of the following benefits:

  • Improve Financial report performance.

  • Improve the ease and maintenance of Report Sets.

  • Display the report column/row headers dynamically.

  • Provide you with additional flexibility in changing report parameters.

Substitution Variables and their derivatives may be found by navigating to Maintenance > Reports > Cube Settings > Substitution Variables. This list displays system-defined variables, as well as any custom variables you create.

In Practice

Complete the following steps to transition your existing reports to Substitution Variables:

  1. Review the report and corresponding row and column set(s) in order to determine how you want to proceed. For example, if the column set is built on the measures dimension or calculated dimensions, consider how the report may be modified to use time or scenario on the column. Also consider using Substitution Variables in column headers and row titles.

  2. Make a copy of the existing report prior to beginning the transition. This copy will be modified during the transition, but you may compare the end result with the original report/report set(s) to validate data.

  3. If you plan to change the dimension upon which the report set is built, you must create a new report set as it is not possible to change an existing report set to run on a different dimension. If you plan to use the same dimension for your new report set, you may copy the original report set. This copy will be modified during the transition and you can then compare the end result with the original report/report sets to validate data.

  4. Modify the formulas on the Advanced Rule page from the current string to include the appropriate Substitution Variables. For example; In a rolling twelve month column set, you can remove the expression “Time.CurrentMember.lag(1)” and replace it with “@CURMTH-1@” for the column pulling the last month’s data.

  5. Modify the column headers/row titles as necessary. A column previously titled using Formula Exceptions to display the appropriate month or hardcoded to fixed text can be replaced with a Substitution Variable in the column header within the column set. This header may include the Substitution Variable alone, or included with static text. For example; If the month is May, the column header within the column set may be “@CURMTH-2@” to display “March.” Or, it may be “YTD @CURMTH-2@” to display “YTD March.”

  6. Save the copied and modified report set. Adjust the dimensions on the copied report if you created new report sets to accommodate the Substitution Variables. When you have the report highlighted within the Reports file cabinet, select “Setup” to view the Report Details and Report Settings. For example, you may need to move one dimension to the Page (such as Measures) and another to the Column (such as time) to use the new column set.

  7. Run the newly transitioned report. Compare the results to the original report/report set(s) and make adjustments if necessary. You may change the values of the Substitution Variables at run time, however, these changes will not be saved with the report.

  8. In addition, moving highly repeated members of Rules to the page level will improve report performance. If “*Measures+.*MTD+” is used in many of the Rule within a report set, you may move Measures to the page and include the measures dimension in the Rule only in fields where you do not want MTD.

  9. Delete or rename the original report, which is no longer in use. Rename the transitioned report accordingly.

Substitution Variables and Dynamic Reports
  • Substitution variables displayed are filtered based on Reporting Area. For example, @CURBDGT@ may be defined under the Financial Reporting Area and therefore can only be used if you select Financial as the Reporting Area while creating a Dynamic Report.

  • In the example below, you can see a list of subsitution variables available under the Financial Reporting Area for the Time dimension.

When you select a substitution variable to use in a Dynamic Report, you can also select one of the following Options:

  • Selected - The report returns the members selected.

  • Children - The report returns the first level children of the selected members.

  • All Children - The report returns all of the descendants of the selected members.

  • Sel+Children - The report returns the selected members and the first level children of the selected members.

  • Sel+AllChildren - The report returns the selected members and all of the descendants of the selected members.

  • Leaves - The report returns the posting levels below the selected members.

  • Sel+Leaves - The report returns the selected members and the posting levels below the selected members.

  • Sel+Parents - The report returns the selected members and the summary levels above the selected members.

The option selected (i.e. Leaves, Children, etc.) also applies to substitution variables used. For example, if you select the @CURYR@ substitution variable as the member for a Time dimension on the column or a Dynamic Report and then you select the Leaves option, the Dynamic Report output will display with all current month output. This is because the @CURYR@ substitution variable has current month leaf members.

System-Defined Substitution Variables

The following Substitution Variables are available in your application by default.


Variable Name

Variable Type

Purpose

1

@CURMTH@

Substitution Variable

Current Month

2

@CURMTH+1@

Derived Variable

Next Month

3

@CURMTH+2@

Derived Variable

2 Months after Current Month

4

@CURMTH+3@

Derived Variable

3 Months after Current Month

5

@CURMTH+4@

Derived Variable

4 Months after Current Month

6

@CURMTH+5@

Derived Variable

5 Months after Current Month

7

@CURMTH+6@

Derived Variable

6 Months after Current Month

8

@CURMTH+7@

Derived Variable

7 Months after Current Month

9

@CURMTH+8@

Derived Variable

8 Months after Current Month

10

@CURMTH+9@

Derived Variable

9 Months after Current Month

11

@CURMTH+10@

Derived Variable

10 Months after Current Month

12

@CURMTH+11@

Derived Variable

11 Months after Current Month

13

@CURMTH+12@

Derived Variable

12 Months after Current Month

14

@CURMTH-1@

Derived Variable

Previous Month

15

@CURMTH-2@

Derived Variable

2 Months prior to Current Month

16

@CURMTH-3@

Derived Variable

3 Months prior to Current Month

17

@CURMTH-4@

Derived Variable

4 Months prior to Current Month

18

@CURMTH-5@

Derived Variable

5 Months prior to Current Month

19

@CURMTH-6@

Derived Variable

6 Months prior to Current Month

20

@CURMTH-7@

Derived Variable

7 Months prior to Current Month

21

@CURMTH-8@

Derived Variable

8 Months prior to Current Month

22

@CURMTH-9@

Derived Variable

9 Months prior to Current Month

23

@CURMTH-10@

Derived Variable

10 Months prior to Current Month

24

@CURMTH-11@

Derived Variable

11 Months prior to Current Month

25

@CURMTH-12@

Derived Variable

12 Months prior to Current Month

26

@CURBDGT@

Substitution Variable

Current Budget

27

@CURFCST@

Substitution Variable

Current Forecast

28

@CURQTR@

Substitution Variable

Current Quarter

29

@CURQTR+1@

Derived Variable

Next Quarter

30

@CURQTR+2@

Derived Variable

2 Quarters after Current Quarter

31

@CURQTR+3@

Derived Variable

3 Quarters after Current Quarter

32

@CURQTR+4@

Derived Variable

4 Quarters after Current Quarter

33

@CURQTR-1@

Derived Variable

Prior Quarter

34

@CURQTR-2@

Derived Variable

2 Quarters prior to Current Month

35

@CURQTR-3@

Derived Variable

3 Quarters prior to Current Month

36

@CURQTR-4@

Derived Variable

4 Quarters prior to Current Month

37

@CURYR@

Substitution Variable

Current Year

38

@CURYR+1@

Derived Variable

Next Year

39

@CURYR+2@

Derived Variable

2 years after Current Year

40

@CURYR-1@

Derived Variable

Previous Year

41

@CURYR-2@

Derived Variable

2 Years prior to Current Year

Derived Variables

Derived variables contain a formula that references a Substitution Variable and derives an appropriate value by evaluating the formula.

In Practice

Let's say you need to set up a derived variable which will result in the month preceding the Current Month. To do so, use a Derived Variable named @CURMTH -1@, which references a Substitution Variable @CURMTH@ and contains the formula; such as @CURMTH.Lag(1).

If you need to set up a derived variable off of substitution variable @CURMTH@ (current month) to list all the days in the month. Your hierarchy is set up where Jan 2017 has 1/1/2017 through 1/31/2017. To do so, use the following options:

@CurMth@ = Jan-17

@CurMth.Day01@ = @CurMth@.FirstChild

@CurMth.Day02@ = @CurMth@.FirstChild.lead(1)

@CurMth.Day03@ = @CurMth@.FirstChild.lead(2)

Because the Time dimension is not symmetrical, meaning every month does not have the same # of days, you could change @CurMth@ to Feb-17, but since Feb only has 28 days, the last 3 derived variables would get the 1st 3 days in March.

Now, let's say you need to reflect data for 3 years back and you are using the @CURYR@ substitution variable. To do so, define a derived variable on the current year substitution variable as @CURYR-3@.

System-Defined Derived Variables

There are 49 derived variables for the @CURYR@ substitution variable on the Time dimension. These derived variables are available for Financial and Workforce reporting areas.

You can access the derived variables by navigating to Maintenance > Reports > Cube Settings > Substitution Variables > @CURYR@> Derived Variables.

Note:
The derived variables of @CURYR@ are not displayed if the value of @CURYR@ is not set to a valid year.

The followings derived variables are available.


Variable Name

Variable Type

Purpose

1

@CURYRQ1@

Derived Variable

Quarter 1

2

@CURYRQ2@

Derived Variable

Quarter 2

3

@CURYRQ3@

Derived Variable

Quarter 3

4

@CURYRQ4@

Derived Variable

Quarter 4

5

@NYRQ1@

Derived Variable

Next year Quarter 1

6

@NYRQ2@

Derived Variable

Next year Quarter 2

7

@NYRQ3@

Derived Variable

Next year Quarter 3

8

@NYRQ4@

Derived Variable

Next year Quarter 4

9

@PRYRQ1@

Derived Variable

Previous year Quarter 1

10

@PRYRQ2@

Derived Variable

Previous year Quarter 2

11

@PRYRQ3@

Derived Variable

Previous year Quarter 3

12

@PRYRQ4@

Derived Variable

Previous year Quarter 4

13

@CURM01@

Derived Variable

1st month of the year

14

@CURM02@

Derived Variable

2nd month of the year

15

@CURM03@

Derived Variable

3rd month of the year

16

@CURM04@

Derived Variable

4th month of the year

17

@CURM05@

Derived Variable

5th month of the year

18

@CURM06@

Derived Variable

6th month of the year

19

@CURM07@

Derived Variable

7th month of the year

20

@CURM08@

Derived Variable

8th month of the year

21

@CURM09@

Derived Variable

9th month of the year

22

@CURM10@

Derived Variable

10th month of the year

23

@CURM11@

Derived Variable

11th month of the year

24

@CURM12@

Derived Variable

12th month of the year

25

@NYRM01@

Derived Variable

1st month of the next year

26

@NYRM02@

Derived Variable

2nd month of the next year

27

@NYRM03@

Derived Variable

3rd month of the next year

28

@NYRM04@

Derived Variable

4th month of the next year

29

@NYRM05@

Derived Variable

5th month of the next year

30

@NYRM06@

Derived Variable

6th month of the next year

31

@NYRM07@

Derived Variable

7th month of the next year

32

@NYRM08@

Derived Variable

8th month of the next year

33

@NYRM09@

Derived Variable

9th month of the next year

34

@NYRM10@

Derived Variable

10th month of the next year

35

@NYRM11@

Derived Variable

11th month of the next year

36

@NYRM12@

Derived Variable

12th month of the next year

37

@PRYRM01@

Derived Variable

1st month of the previous year

38

@PRYRM02@

Derived Variable

2nd month of the previous year

39

@PRYRM03@

Derived Variable

3rd month of the previous year

40

@PRYRM04@

Derived Variable

4th month of the previous year

41

@PRYRM05@

Derived Variable

5th month of the previous year

42

@PRYRM06@

Derived Variable

6th month of the previous year

43

@PRYRM07@

Derived Variable

7th month of the previous year

44

@PRYRM08@

Derived Variable

8th month of the previous year

45

@PRYRM09@

Derived Variable

9th month of the previous year

46

@PRYRM10@

Derived Variable

10th month of the previous year

47

@PRYRM11@

Derived Variable

11th month of the previous year

48

@PRYRM12@

Derived Variable

12th month of the previous year

49

@2YRPriorM12@

Derived Variable

12th month of 2nd year prior to the current year


Was this article helpful?