2.1.2 Modeling Release Notes, July

Substitution Variables and Expressions

Substitution variables are used in reports in place of dimension member names. In this release, reports can be defined using substitution variables that can be dynamically modified at runtime by end users, and administrators and designers now have the option to set up reports using substitution variables with expressions.

• The substitution variables can be dynamically modified at runtime. Previously, if a report was set up to use a substitution variable, the report would always run with the predefined value of the substitution variable. To change the value, an admin or designer had to change it manually using the Model > Model Administration > Substitution Variables page.

  • Any level of user can now change the value of substitution variables while running a report. The new value is used during that session, but the report reverts back to the original substitution variable value the next time the report is run. For example, a designer may set up a report with a substitution variable defined as CurMth = January 2017. The end user can change the value to July 2017 when running the report. The next time the report is run, January 2017 is used by default but again can be changed easily at runtime.

  • Selecting a different dimension member name is available in SpotlightXL and Spotlight.

• Administrators and designers can set up substitution variables with expressions. Expressions are added to a substitution to derive another member name from the same dimension.

• Substitution variables are most commonly used in the Time and Scenario dimensions.

Here is the overall process:

1. Admin or designer creates one or more substitution variables in the model.

2. Admin or designer creates one or more reports that use the substitution variables.

3. Any user with access to the report can run it and change the value of the substitution variable, provided they have security access to the dimension.

Select from the following topics for more details:

Creating Substitution Variables for Reports

Using Substitution Variables in Reports

Selecting a Different Value for a Substitution Variable at Runtime

Expressions

Expression Chains

Converting Existing Reports with Substitution Variables to Use Expressions

Using Substitution Variables with Excel-based Reporting

Best Practices

Limitations

Future Options

Creating Substitution Variables for Reports

To set up formatted reports with substitution variables for use at run-time, an administrator or designer must first create the substitution variables. This functionality was introduced in Release 1.2. As a reminder, here's how:

1. Select Model > Model Administration > Substitution Variables.

2. Select the model and dimension name from the list boxes.

3. Enter the variable name with plain text. Avoid using the symbol @ in the variable name. For example, CurMth or Current Month. Variable names are case sensitive.

4. Specify the starting value for this variable. This value must be the same as a dimension member name in your model. For example, Jan-17.

5. Optionally, specify the model that the variable will be used on.

6. Optionally, specify the dimension that the variable relates to. For example, Time.

7. Click Save.

If you make a mistake, simply delete the row containing the substitution variable that you created, then click Save to delete it.

Using Substitution Variables in Reports

To set up a report to use one or more substitution variables:

1. Lay out the report with standard items, such as headings, rows, and columns.

2. While in Report Design mode, select the cells containing the dimension member to be replaced with a substitution variable.

3. Click Design Manager. Notice that the current value is a regular dimension member, Jan-2017.

4. Click the Member Selection icon, then Select Member.

5. Click Select Member. At the top of the member selection box, notice that Substitution Variables are listed first.

6. Select @CurMth@ and click Select.

Now the Design Manager reflects the change from the original value (Jan-17) to the Substitution Variable @CurMth@. Also shown in light gray is the predefined value of CurMth.

7. Click Update. The report now displays @CurMth@ in place of the 4 cells you originally selected.

Now you need to update the data cells to also use the substitution variable.

1. Select all the data cells. In this example, columns B and C are data cells, while columns D and E contain Excel formulas.

2. Click Design Manager. Scroll to the Time dimension. Notice that the current value is a regular dimension member, Jan-2017.

3. Click the Member Selection icon, then Select Member.

4. Click Select Member. At the top of the member selection box, notice that Substitution Variables are listed first.

5. Select @CurMth@ and click Select.

Now the Design Manager reflects the change from the original value (Jan-17) to the Substitution Variable @CurMth@. Also shown in light gray is the predefined value of CurMth.

7. Click Update. The report now displays UPDATED in place of the data cells you originally selected.

8. Click Save to save your report.

Selecting a Different Value for a Substitution Variable at Runtime

When the end user runs a report, if it contains a substitution variable, a new icon automatically appears on the menu ribbon.

1. With the cursor anywhere in the report, click Substitution Variables. The Substitution Variables box appears. It shows the name of the variable and the current value.

2. Click the Member Select icon.

3. From the member selection box, select the month that you want to see in the report.

4. Click Select.

5. Click Refresh to refresh the report.

The report now displays data for Jul-17. Using this method, the user can easily move back and forth between months, quarters, or years, without updating the definition of the report and without the need for the designer or administrator to update the substitution variable value permanently.

Using Substitution Variables with Expressions

Modeling now supports the ability to enhance substitution variables by providing expressions. Expressions point to different members in the dimension in relation to the predefined value of the substitution variable.

Here is a basic annual revenue report. Expressions will make this report easier to maintain in coming years.

Define the following substitution variable:

FirstMth = Jan-16

Now go to Report Design to use this variable.

1. Select all the cells in the worksheet.

2. Click Design Manager.

Each member in the Time dimension will be replaced with a substitution variable or expression.

3. Select Jan-16.

4. Click the Member Selection icon, then Select Member.

5. Select @FirstMth@ and click Select. Now the Design Manager reflects the change from the original value (Jan-16) to the Substitution Variable @FirstMth@. Also shown in light gray is the predefined value of FirstMth.

6. Repeat steps 3-5 for Feb-16.

7. While still on Feb-16, click the Member Selection icon again, then Expression.

The Expression box appears and FirstMth is already selected.

8. Click Add Function.

9. Click Lead.

The Expression box now shows the Offset option. By default, the offset is 1. Offset refers to the number of members above or below the current member in the dimension hierarchy. Offset works within the current level and it skips over rollup members.

Lead refers to members below the current member in the hierarchy. For example, Jan-16, Lead(1) points to Feb-16. Lead is equivalent to fetching the next member in the hierarchy within the current level.

Lag refers to members above the current member in the hierarchy. For example, Jan-16, Lag(1) points to Dec-15. Lag is equivalent to fetching the previous member in the hierarchy within the current level.

10. Click Update to accept Lead(1).

11. Repeat steps 3-5 and 7-10 for the rest of the months to express all of the months in relation to FirstMth.

For the year 2016, a different expression is needed.

12. Repeat steps 3-5 for 2016.

13. While still on 2016, click the Member Selection icon again, then Expression.

    The Expression box appears and FirstMth is already selected.

14. Click Add Function.

15. Click Parent. The parent of Jan-16 is Q1-16, so we want the parent of the parent to go up 2 levels to 2016. This is done by chaining two expressions together. For more information on chaining expressions, see Expression Chains.

16. Click Add Function again.

17. Click Parent. Now you see @FirstMth@.Parent.Parent, and 2016 is displayed to show you what value is returned with this expression.

16. Click Update.

The Time dimension now reflects all members in relation to the substitution variable FirstMth.

17. Click Update to save your changes and exit the Design Manager.

The report now displays UPDATED in place of the data cells, and @FirstMth@ and the expressions in place of the monthly headings.

18. Save the report design by clicking Save or Save As. Consider changing the name to preserve the original report until you are confident that the new report is accurate.

Now when you run the report, you can use the Substitution Variables box to change the starting value to the first month of any year in your hierarchy.

After selecting Jan-17, click Refresh.

Notice that the same report now works for other fiscal years. Users just need to select the first month of the fiscal year and entire report is derived from that substitution variable dynamically. Because of the introduction of expressions, administrators or designers can design reports that are more dynamic in nature. And it will reduce the report maintenance going forward.

Expressions

Consider the following dimension hierarchy for a fiscal year that begins in July each year. Assume that the model contains only these three years.

Expression Syntax

The following expressions are available for use with substitution variables. Assume that @CurYear@ is FY2018 and @CurMth@ is Jul 2017.

Expression Chains

You can chain expressions together. Each entry in the expression builds on the results of the previous entry, reading from left to right.

@CurMth@.Parent.FirstChild = Jul 2017. CurMth’s Parent is Q1 2018 and the First Child of Q1 2018 is Jul 2017.

@CurMth@.Lag(3).Parent = Q4 2017. CurMth’s 3-month Lag is Apr 2017 and the Parent of Apr 2017 is Q4 2017

@CurMth@.Parent.Lead(2) = Q3 2018. CurMth’s Parent is Q1 2018 and 2 quarters ahead is Q3 2018.

When adding functions to a substitution variable, you may find the need to change the order or to remove one of the expressions. Click the menu button next to the expression to make the changes.

If you want to cancel out from adding expressions, click inside the Design Manager or press Esc.

Converting Existing Reports with Substitution Variables to Use Expressions

Many existing reports are set up with multiple substitution variables. These reports can be converted to use one substitution variable and many expressions for easier maintenance.

Consider the following model and its current list of substitution variables.

These substitution variables are used in all of the company reports that show data by month, quarter, or year. Below is a report of Salaries by Department. You can see the use of 17 substitution variables in the report.

To convert this report and any other reports to use a single substitution variable, first decide which member should be the starting point that you can create expressions from. For example, if you start with the first month of your fiscal year, then you can use Sibling, Lead, or Lag to offset at the same level to other months. Or go back one level with Parent and use Lead or Lag to offset to quarters, or go back two levels with Parent.Parent and use Lead or Lag to offset to years. Or you can start with the year and use Child expressions to get to the quarters and months.

For this example, we will base all the time entries in the report on the first month of the year. A Designer or Admin user must create the substitution variable.

1. Define the following substitution variable for the model Sample Salaries and the dimension Time:

FirstMth = Jan 2015

2. Open the report and go into Design mode.

3. Select all the cells in the worksheet, then click Design Manager. Scroll down to the Time dimension.

4. Select the @Month1@ variable, which is currently set to Jan 2015.

5. Click the Member Select button and click Select Member.

6. Scroll to find the new variable that you created, FirstMth. Select it and click Select.

The New Value column now shows the @FirstMth@ substitution variable. In grey, Jan 2015 is displayed.

7. Click Update. The report now displays UPDATED in place of the data cells and @FirstMth@ in place of Jan 2015.

8. With all the cells in the worksheet still select, click Design Manager again.

9. Scroll down to the Time dimension and select @Month2@.

10. Repeat steps 5-6 to replace @Month2@ with @FirstMth@.

11. Click the Member Select button and click Expression.

12. Click Add Function and select Lead.

13. Keep the default Offset of 1, and click Update.

The New Value column now shows the @FirstMth@.Lead(1) substitution variable plus expression. In grey, Feb 2015 is displayed.

14. Repeat steps 5-6 and 11-12 for the rest of the months, adding one more to the Offset for each subsequent month. Now all the months are expressed in relation to FirstMth.

15. Click Update to insert these changes into the report.

16. With all the cells in the worksheet still select, click Design Manager again.

17. Scroll down to the Time dimension and select @Qtr1@.

18. Repeat steps 5-6 to replace @Qtr1@ with @FirstMth@.

19. Click the Member Select button and click Expression.

20. Click Add Function and select Parent.

21. Click Update.

22. Select @Qtr2@.

23. Repeat steps 5-6 to replace @Qtr2@ with @FirstMth@.

24. Click the Member Select button and click Expression.

25. Click Add Function and select Parent.

26. Click Add Function and select Lead with Offset of 1.

27. Click Update.

28. Repeat for the remaining quarters, by creating the following chain expressions for them:

@FirstMth@.Parent.Lead(2) = Q3 2015

@FirstMth@.Parent.Lead(3) = Q4 2015

29. Click Update to insert these changes into the report.

30. With all the cells in the worksheet still select, click Design Manager again.

31. Scroll down to the Time dimension and select @Year@.

32. Repeat steps 5-6 to replace @Year@ with @FirstMth@.

33. Click the Member Select button and click Expression.

34. Click Add Function and select Parent.

35. Again, click Add Function and select Parent.

36. Click Update

37. Click Update to insert these changes into the report.

38. Now save the report design by clicking Save or Save As. Consider changing the name to preserve the original report with multiple substitution variables until you are confident that the new report is accurate.

39. Compare the data to your original report to ensure it is accurate.

40. Click Run to go into Run mode.

When running the report, now you can click the Substitution Variables button on the ribbon to change the FirstMth variable to the first month of any year.

Using Substitution Variables with Excel-based Reporting

If you have reports with substitution variables and expressions, you can use them with Excel-based Reporting.

Open a formatted report and click Capture Data.

When the report is first converted to Excel-based Reporting formulas, you see the substitution variables and expressions in place of the dimension members.

Click Refresh.

Notice that there is no Substitution Variables button on the ribbon, so you cannot change the value of the substitution variable from an Excel-based report. In a future release, similar options will be added so that substitution variables can be changed in Excel-based reports.

Best Practices

1. Define the master list of substitution variables that you expect to use in all of your standard company reports. This should be a fairly short list, such as: CurMth, CurQtr, CurYr, CurBudget, CurForecast, and so on. Then use expressions to access all other necessary members of your dimension hierarchy.

2. Limit the chain of expressions to two.

Limitations

1. Substitution variables are not supported in cascaded reports.

2. Substitution variables cannot be changed at runtime in Excel-based Reports.

3. Substitution variables cannot be changed at runtime in a Snapshot.

4. We recommend to chain together only two expressions in this first release of substitution variables with expressions.

Future Options

The following options will be added in future releases:

• Ability to synchronize substitution variables between Planful Planning and Planful Modeling applications.

• Ability to change substitution variable values at the time of Calculation definition.

• Ability to change substitution variable values in Excel-based Reporting.

Additional Application Settings

Administrators can now set several options to be defaults for Views and Reports. Previously you had to set them one by one using View or Report Properties. These settings set the defaults for views and reports. Existing views and reports will not automatically adopt these defaults.

Select Manage, Application Administration, Application Settings. After making changes, click Save. Then logoff and login again to see the effect of the changes.

View Settings

Suppress Rows and Suppress Columns are options that determine whether rows and columns containing all zeros, all blanks, or a combination of zeros and blanks will be displayed in a view. Use the drop-down to select the types of data to suppress. The default is None.

• None

• Zero

• Blank

• Both - Zero & Blank

Additionally, you can specify Yes or No to allow or disallow Designers and Reviewers from making changes to the Suppress Rows and Suppress Columns settings in the properties of individual views. The default is Yes.

When done making changes to Application Settings, click Save. Then logoff and login again to see the effect of the changes.

Report Settings

Suppress Rows, Suppress Columns, and Refresh on POV Change can be set for all formatted reports.

For Refresh on POV Changes, specify Yes or No to automatically refresh the report when the user changes the Point of View. The default is No.

Suppress Rows and Suppress Columns are options that determine whether rows and columns containing all zeros, all blanks, or a combination of zeros and blanks will be displayed in a report. Use the drop-down to select the types of data to suppress. The default is None.

• None

• Zero

• Blank

• Both - Zero & Blank

Additionally, you can specify Yes or No to allow or disallow Designers from making changes to these settings in the properties of individual reports. The default is Yes.

When done making changes to Application Settings, click Save. Then logoff and login again to see the effect of the changes.

Audit Log Enhancements

The Audit Log has been enhanced to include additional entries and search with date ranges and paging.

Only administrators have access to the Audit Log. Select Manage, Application Administration, Audit Log.

Additional Entries

The Audit Log now provides log entries for the following activities in the application:

• View - Get Data

• View - Get Data for All Open Views

• Report - Refresh

• Report - Refresh All Open Reports

• Report - Substitution Variables Refresh

• Excel-based Reporting - Refresh

• Excel-based Reporting - Refresh All

Date Ranges and Paging in the Audit Log

The Audit Log now has options for viewing entries between two dates, and for paging through large volumes of entries.

The fields highlighted with yellow background are in this release.

From Date - Starting date for which you want to view audit details. The date must be in the format MM/DD/YYYY. By default, From Date shows today's date.

To Date - Ending date for which you want to view audit details. The date must be in the format MM/DD/YYYY. By default, To Date shows today's date.

Total Records - This is a display field only. It shows the number of audit log entries found.

Page Size - This is a display field only. It shows the number of entries shown on each page. The maximum page size is 1000.

Current Page - This is a drop-down list. If there are more than 1000 entries, they are divided into multiple pages. Select which page you want to view then click Refresh. In the example below, page 1 has 1000 entries, and page 2 has 448 entries.

Breakback Changes

The Breakback feature was introduced in Version 2.1.1. As we continue to improve this feature, we are introducing two changes in Version 2.1.2:

• Hold is Available for Multiple Dimensions

• Breakback on Rollups with Different Operators is Available

Hold is Available for Multiple Dimensions

In Version 2.1.1, Hold was available only for one dimension at a time. For example, you could run Breakback on 2017 and hold one or more members of the Time dimension: Jan-17 and Feb-17, or Q1-2017 and Q2-2017.

In Version 2.1.2, you can hold members from more than one dimension.

In the following example, revenue targets are increased for Mountain Bikes in 2016 but Quarter 1 in International markets is not increased.

1. Select Cell C10, Mountain Bikes for 2016. Notice that the Q1 value for International is 443,595 and Q1 value for North America is 118,249.

2. Select the Breakback button on the ribbon.

3. Select the Current spread.

4. Under Amount, specify the amount you want to spread. In this case, 2.6M.

5. Under the Hold box, select Add Dimension Member.

6. Specify the Time dimension and select Q1 2016. (In Excel, you can also click the Select Range button and simply click on the cell containing the member you want to Hold.)

7. Select Add Dimension Member again and specify the Department dimension and International member.

8. Click the Run Calculation button to run the calculation associated with this view after the Breakback is performed.

9. Click Run Breakback.

Here is the resulting data. Notice that Q1 International remains at 443,595, but Q1 North American has increased to 124,000. Q3 and Q4 also had proportional increases.

Breakback on Rollups with Different Operators Available

In Version 2.1.1, when using Breakback on rollups, all children in the hierarchy must be defined with the plus (+) operator. For example, months roll up to quarters and quarters roll up to a year using the + operator.

In Version 2.1.2, you can use Breakback on rollups with children with any operator, but you must first enable this capability on the Application Settings page. By default, it is disabled.

As a Best Practice, we recommend using Breakback only on rollups with the + operator. Running Breakback will change the data at the leaf level, and if the rollups use any operator other than +, the results of the Aggregation may be unpredictable.

By default, Enable Breakback on other rollup operators is set to No, and Breakback will report an error if you try to use it on rollups with varying operators.

Enabling Breakback on Other Rollup Operators

An administrator must make this change.

1. Select Manage, Application Administration, Application Settings.

2. Scroll down to the Model section and look for Enable Breakback on other (~!-) rollup operators.

3. Select Yes or No from the drop-down.

4. Click Save.

5. Logoff and login again to see the effect of the changes.

Known Issues

The following issues are specific to Excel-based Reporting.