CallForecastEngine macro

The CallForecastEngine macro calls the specified forecast engine to generate forecast for a selected item and location.

This supports the generation of forecasts for the selected item/location at the base-level or a grouped forecast for the selection with output prorated to the appropriate level to store scenario values. This macro is executed at scenario level.

For executing the macro, the value of the Command field must be specified in this format:

Engine Name, [Algorithm], [Spreading Measure Code], [Item Hierarchy level], [Item Hierarchy selection], [Location Hierarchy level], [Location Hierarchy selection], [SMP Measure], [Optimize], [Filter]

Note: The optional parameters are specified in [ ].

This table lists the parameters used in the macro:


Parameter Name	Description
Engine Name	The name of the forecast engine to call. The engine determines the type of engine and the default settings. Note: This parameter must be defined for the current cycle and module.
Algorithm	The algorithm used in the forecast generation process. Possible values: BATS BEST CROSTONS EVENTSONLY EXPONENTIALMOVINGAVERAGE HOLTWINTERS LEASTSQUARES MOVINGAVERAGE MULTIPLEREGRESSION Note: If not defined, the default algorithm from the specified engine is used. If default algorithm is not defined in the engine setting, BEST is used.
Period Constant Spread Measure	The measure code to be used as a spreading factor for storing scenario values, replacing the Period Constant Spread Measure in the engine, where the calculated item or location is not the level to store scenario values. Null spreading measure = default specified in Forecast Engine Settings. Note: Spreading to base periods uses the engine's Time-Phased Spread Measure, if specified, or the cycle's period spread measure is used.
Item hierarchy level	The level (from the item hierarchy) at which the forecast engine generates the forecasts. Note: If not specified, the default value from the Forecast Engine Settings is used.
Item hierarchy selection	The base elements at the Item hierarchy level to determine the item selection. The value is passed as a node. For example, ‘Brand A’. Note: If not defined, all the valid items are processed. You must adhere to the data security rules of the user when selecting the items.
Location hierarchy level	The level (from the location hierarchy) at which the forecast engine generates the forecasts. Note: If not specified, the default value from the Forecast Engine Settings is used.
Location hierarchy selection	The base elements at the Location hierarchy level to determine the location selection. The value is passed as a node. For example, ‘EMEA’. Note: If not defined, all the valid locations are processed. You must adhere to the data security rules of the user when selecting the locations.
Optimize	Indicates, optimization process of the forecast engine. Possible values: On: The engine must optimize the parameters based on the passed data set before calculating the forecast. Off: The passed parameters and default values are used for the forecast calculation. Note: If not specified, the default value from the Forecast Engine Settings is used. This field is only applicable for the BEST or Holt-Winter algorithm.
Time-Phased Spread Measure	Indicates the measure to be used when spreading forecast engine results to period. Null Time-Phased Spread Measure = default specified in Forecast Engine Settings. Note: If default Time-Phased Spread Measure is not defined, the Cycle’s Period Spread Measure is used.
Filter	The filter criteria that is applicable for the selected item and location (at period constant (PCONST)) at the specified Item and Location hierarchy level. Note: The item@location that pass the criteria, for period constant (PCONST) are used in the forecast generation. Filters containing measures, which are calculation rules, can only be used if defined as a Business Metric. If not specified, filter criteria are not applied. See, Filter Parameter syntax.

On macro execution, if the item or location hierarchy selection parameters use the %itemcontext% or %locationcontext% syntax and the data context is using My Selections. A check is performed to ensure that the Item or Location hierarchy level (specified in the macro or derived from the engine) is at the base level of the hierarchy used in the My Selection, as specified in the Cycle. If the level is not at Base, the macro fails and this message is reported:

Forecast Generation cannot be executed.
Item Level must be set to the base level of the Hierarchy used in the My Selection, specified in the Cycle.
Location Level must be set to the base level of the Hierarchy used in the My Selection, specified in the Cycle.

Note: My Selection cannot be explicitly specified in the Macro parameters, and can only be derived when using the %itemcontext% or %locationcontext% syntax in the item hierarchy selection and location hierarchy selection parameters.

When BEST algorithm is used, the macro call the forecast engine with fitModelPickingAlgorithm() which allows the engine to fit using the algorithm with the lowest decision criteria. The selected algorithm is returned as output.

When the algorithms other than BEST, fitModelGivenAlgorithm() is used for calling the forecast engine.

This table lists the examples of the CallForecastEngine macro:


Requirement	Syntax
Call ‘Test Engine’ passing all the default engine settings and calculating for all items and locations. Results are spread using the default spreading measure.	CallForecastEngine("Test Engine")
Call ‘BATS engine’, using the default engine algorithm, for valid SKU-level items under the Brand A node in the item hierarchy, for Customer-level locations under the US node in the location hierarchy. No spreading is required as the specified levels are equal to the level for storing scenario values.	CallForecastEngine("BATS engine","","","SKU","Brand A","Customer","US")
Call ‘BATS engine’, using the default engine algorithm, for the aggregated node Brand A in the item hierarchy, for the aggregated Region node US in the location hierarchy. Uses the Spread measure defined in Engine (TUPLE_EXISTS) to spread results to the base item and location Cycle.level to store scenario values.	CallForecastEngine("BATS Engine","","","Brand","Brand A","Region","US")
Call ‘New Engine’, passing the LEASTSQUARES algorithm, spreading results to base items and locations via TUPLE_EXISTS measure (as defined in the Forecast Engine), calculating all Product Groups and all Regions at monthly calendar level (as specified by the engine's period level).	CallForecastEngine("New Engine","LeastSquares","","Product Groups","","Regions","","","")
Call ‘Best Fit’, passing the Best (Picking) algorithm, spreading results via Spreading Measure defined in Engine, calculating all Product Groups and all Regions. Parameter optimization is done prior to selecting the algorithm and generating the forecast.	CallForecastEngine("Best Fit","BEST","","Product Groups","","Regions","","","TRUE")
Call "Best engine", using the default engine algorithm, for the aggregated node Brand A in the item hierarchy, for the aggregated Region node US in the location hierarchy. Filter the item@location resultant selection based on DPLS_FMISSINGFORECAST = 0 at pconst for the selected levels. This selection will then have a forecast generated and uses the spread measure defined in the engine to spread results to the base item and location Cycle.level to store scenario values.	CallForecastEngine("Best Engine","","","Brand","Brand A","Region","US","","","","","[DPLS_FMISSINGFORECAST] = 0")

Validations are performed when you execute the macro. If any of the validation fails, the macro is aborted, and the related error message is displayed.

This table lists the Scenario Macro commands as compared to the Cycle Period/Scenario status and 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	WIP	Yes	N/A
Running	Review, Rejected, Stopped, Approved, Published	No	Cannot run macro {0} because Scenario has status {1}
Paused	Any	No	Cannot run macro {0} because Cycle Period is not ‘running’
Completed	Any	No	Cannot run macro {0} because Cycle Period has status ‘Completed’
Aborted	Stopped	No	Cannot run macro {0} because Cycle Period has status ‘Aborted’
Archived	Any	No	Cannot run macro {0} because Cycle Period has status ‘Archived'

This table lists the error message displayed during the macro execution:


Validation Condition	Error Message
Check the Forecast engine name exists.	forecast engine {0} cannot be found.
Where specified, or using defaults defined in the forecast engine settings, ensure the measures are valid for this cycle.Module and Enabled (parameter mappings and spreading measure.	measure "{0}" cannot be found.
Where specified, or using defaults defined in the forecast engine settings, ensure the item level	item hierarchy level "{0}" cannot be found.
Where specified, or using defaults defined in the forecast engine settings, ensure the location level is valid.	location hierarchy level "{0}" cannot be found.
Where specified, or using defaults defined in the forecast engine settings, ensure the period level is valid. Note the specified calendar level must be Months for an engine of type BATS.	period level {0} cannot be found. period level {0} must be Months or CMonths for engine type=BATS
Where specified, ensure the item and location nodes are valid.	item {0} cannot be found. location {0} cannot be found.
Where specified, ensure the algorithm is valid	the specified algorithm {0} is not supported. Valid entries are: (Best, BATS, Crostons, EventsOnly, ExponentialMovingAverage, HoltWinters, LeastSquares, MovingAverage and MultipleRegression).
Where specified, or using defaults defined in the forecast engine settings, ensure the measures are not defined as Market Intelligence type measures (parameter mappings).	measure "{0}" cannot be of type Market Intelligence.
Where specified, or using defaults defined in the forecast engine settings, ensure the measures are not defined as Transactional Data type measures (parameter mappings).	measure "{0}" cannot be of type Transactional Data
Where specified, or using defaults defined in the forecast engine settings, ensure the measures are not defined as Order type measures (parameter mappings).	measure "{0}" cannot be of type Orders.
User must have permission to run a Forecast Engine	Forecast Generation on module "{0}" is not permitted for user "{1}"
Invalid Filter Syntax in filter parameter.	Filter is invalid.
Measures used in filter parameter cannot be found.	Filter Measure "{0}" cannot be found.
%measureContext% variable is only valid in a multi-panel destination worksheet that has panel link with Pass Measure = TRUE. A macro button must be defined on the destination worksheet to facilitate the access of the macros. If the macro is run from anywhere else (main toolbar, or Process module) then the macro fails because it is unable to identify the measure context.	Measure %measurecontext% cannot be found.
Measures defined as calculation rules used in filter must be set up as a business metric.	Filters cannot be run on measures based on calculation rules. The measure must be defined as a Business Metric to fetch calculated values.
Where specified, or using defaults defined in the forecast engine settings, ensure the item level is valid.	item hierarchy level "{0}" cannot be found.
When the `%itemcontext%` syntax is specified as the Item Hierarchy Selection and the data context Item is a My Selection, verify that the Item Hierarchy Level is at the Base level of the hierarchy, as defined in the Cycle of My Selection. If Item Hierarchy Level is not specified, validate that the Engines Default Item Level is at the base level.	"Item Level" must be set to the base level of the Hierarchy used in the My Selection, specified in the Cycle.
When the `%locationcontext%` syntax is specified as the Location Hierarchy Selection and the data context Location is a My Selection, verify that the Location Hierarchy Level is at the Base level of the hierarchy, as defined in the Cycle of My Selection. If the Location Hierarchy level is not specified, validate that the Engines Default Location Level is at the base level.	"Location Level" must be set to the base level of the Hierarchy used in the My Selection, specified in the Cycle.