EmailWorksheet macro

The EmailWorksheet macro is used to load the worksheet with passed context (item, location and period) and email the worksheet to the user. This macro is executed at scenario level.
The macro parameters determine the context and worksheet to be emailed. This table lists the parameters used to execute the EmailWorksheet macro. The multi panel worksheets are not supported in this macro.
Parameter Description
Export Type The format of file in which the worksheet is to be sent. Possible options:
  • PDF
  • XLS
Worksheet Name The name of the worksheet to execute and email.
User The email recipient for the worksheet.
Note: The user must have access to the worksheet.
Item Passed The item selection passed to the worksheet. This value can be a single element or set of elements.
Note: 
  • MDX definition is supported for set of elements.
  • If this value is not specified, the default worksheet definition (if defined) is used, else the top node of the default hierarchy is used.
  • You can use %itemcontext%, if the current item data context is required (This parameter is applicable only when the command is executed within a worksheet).
Location Passed The location selection passed to the worksheet. This value can be a single element or set of elements.
Note: 
  • MDX definition is supported for set of elements.
  • If this value is not specified, the default worksheet definition (if defined) is used, else the top node of the default hierarchy is used.
  • You can use %locationcontext%, if the current location data context is required (This parameter is applicable only when the command is executed within a worksheet)..
Period Passed The period selection passed to the worksheet. This value can be a single element or set of elements.
Note: 
  • MDX definition is supported for set of elements.
  • If this value is not specified, the default worksheet definition (if defined) is used, else the top node of the default hierarchy is used.
  • You can use %periodcontext%, if the current period data context is required (This parameter is applicable only when the command is executed within a worksheet).
The value for the Command field must be specified in this format:EmailWorksheet (Export type, Worksheet Name, User, [Item Passed], [Location Passed], [Period Passed]).
Note: The optional parameters are specified in [ ].
Table 1. Example
Requirement Parameters
Execute Demand Margin Analysis worksheet with default item, location and period selection from worksheet definition and email the PDF output to user ‘Scott’.

EmailWorksheet("PDF","Demand Margin Analysis","Scott").

EmailWorksheet("PDF","Demand Margin Analysis","Scott","","","").
Execute Demand Essentials worksheet with default item, location and period selection from worksheet definition and email the XLS output to user ‘Harry’. EmailWorksheet("XLS","Demand Essentials","Harry","","","").
Execute Forecast Accuracy Analysis worksheet with Brand A item node, default location selection and Rolling Weeks period node and email the PDF output to user ‘Harry’. EmailWorksheet("PDF","Forecast Accuracy Analysis","Harry","Brand A","","Rolling Weeks").

Validation and Execution

On successful validation and execution of the macro, the worksheet is loaded with the selected item, location and period and emailed to the specified user. These are the validation rules:

  • If the macro parameters are Null, the default value specified in worksheet for item, location and period selections are used.
  • If the macro parameters and the worksheet default parameters for item, location and period are Null, the top node selections of item, location and period are used.

Validation and error messages

This table lists the Cycle Period and scenario status and the related validation messages:
Cycle Period Status Scenario status Can Execute? Validation message
Pending N/A No Cannot run macro {0} because Cycle Period has status "Pending".
Running Any Yes N/A
Paused Any No Cannot run macro {0} because Cycle Period has status "Paused"
Completed Any Yes N/A
Aborted Any Yes N/A
Archived Any No Cannot run macro {0} because Cycle Period has status "Archived”.
Validation is performed when you execute the EmailWorksheet macro. If validation fails, the macro is aborted, and the related error message is displayed. This table lists the error messages displayed for various validation failures:
Validation Condition Error Message
Ensure that the worksheet is valid for the current user and module. worksheet {0} is not enabled for module {1} or user {2}.
Adding a worksheet screen capture is only supported for standard worksheets.

Multi-panel worksheets are not yet supported.

 Invalid parameter value {0}. Worksheet is not of Type = Standard.
Ensure that the export type corresponds to the available formats. Invalid parameter value {0}. Export type must be PDF or XLS.
Ensure that the specified user is valid and has a valid email address. user {0} cannot be found.
Ensure that the specified user has access rights to the required worksheet. User {0} does not have access rights to worksheet {1}
If specified, ensure that the item nodes are valid. item {0} cannot be found.
If specified, ensure the location nodes are valid. location {0} cannot be found.
If specified, ensure the period nodes are valid. period label {0} cannot be found.
If specified, ensure that the values for item nodes can be evaluated.

For some cases, the worksheet parameter, rv_item_passed cannot be used to initialize the macro parameter.

 Item Passed cannot be evaluated. Define an alternate selection.
If specified, ensure that the values for location nodes can be evaluated.

For some cases, the worksheet parameter, rv_location_passed cannot be used to initialize the macro parameter.

 Location Passed cannot be evaluated. Define an alternate selection.
If specified, ensure that the values specified for period nodes can be evaluated.

For some cases, the worksheet parameter, rv_period_passed cannot be used to initialize the macro parameter.

 Period Passed cannot be evaluated. Define an alternate selection.