Logic Documentation (Agreements)

Owned by Ondřej Tesař
Nov 01, 2024
13 min read

See also the architecture documentation here: https://pricefx.atlassian.net/wiki/display/ACCDEV/Architecture+Diagram+(Agreements)

Most of the logic used in Agreements Accelerator includes GroovyDoc, which provides additional valuable information.

Agreement Logics

AGR_FormulaBasedPricing

The core logic for Line Item calculations. The logic works in two contexts:

  1. Line Item Calculation context, which runs on each line item, calculates it and produces outputs

The agreement is calculated every time a Scenario is added. This is enabled by default – the accScenarioRecalc property within the Configuration section of the AGR_FormulaBasedPricing Agreement & Promotion Type (Agreements & Promotions > Agreement & Promotion Types) is set to true .

  1. Agreement Recalculation context, which runs during scheduled Calculation, that is used to gather data for Condition Records

The main premise of the line item logic is to run Calculation Engine (optionally run Forecast Engine) for each SKU and produce an output so the results can be saved to Condition Records.

The logic also generates various Result Matrices that allow to see the calculation results in a user-friendly way.

See the How to Add New Outputs to Line Item article for more details.

This logic – due to its size – has “separators” which group elements. The separators are empty elements with the following name pattern: ___SOME_NAME___.

  • WarningManager - Initializes the Warning Manager that handles most of the exceptions thrown by the Line Item Logic. For more details on WarningManager, see the Error Management (Agreements) article.

  • InputManager - Initializes the Input Manager solution from AGR_InputsLib. Configuration for the manager read from: libs.AGR_ProcessingLib.ConstConfig.INPUT_GENERATION_CONFIG.FORMULA_BASED_PRICING

  • LineItemValidation - Checks if the Line Item is valid, for now only if it’s inside a Scenario.

  • InputsGeneration - Generates Inputs from the initialized InputManager. If the logic is run in Recalculation Context, the inputs are read from api.currentItem instead.

  • InputsValidation - Checks if the Inputs are valid, for now only a check for empty Product Group is present.

  • AbortInputGeneration - Standard Abort Input Generation element.

  • __FORMULA_DATA__ - Separator element

  • FormulaData - Reads and stores the data for a selected Formula. The stored data is the Formula Company Parameter configuration, Formula Type name, name of the Engine Calculator Company Parameter and the values of the Inputs present on the Formula.

  • Formula - Extracts the Formula Company Parameter configuration from Formula Data.

  • FormulaTypeName - Extracts the Formula Type name from Formula Data.

  • EngineCalculatorParameterName - extracts the Engine Calculator Company Parameter name from Formula Data.

  • __INPUTS__ - Separator element

  • FormulaInputValues - Extracts the values of the Inputs present on the Formula from Formula Data.

  • HeaderInputs - Extracts the values of the Inputs present on the Header.

  • ScenarioInputs - Extracts the values of the Inputs present on the Scenario.

  • SelectedForecastEngineName - Reads the value of the Forecast Engine input and stores its value.

  • IsForecastUsed - Condition element that’s used to control the visibility of other elements. If SelectedForecastEngineName is not present, then Forecast is not used and some elements can be ignored.

  • ForecastInputValues - Only if Forecast is used. Extracts the values of the Forecast Engine inputs and stores them.

  • __CALCULATION_PARAMETERS__ - Separator element

  • AdditionalCalculationParameters - Allows you to add new Calculation Parameters to Calculation Engines. See How to Add New Calculation Parameters to Calculation Engines.

  • GeneralCalculationParameters - Assigns the main calculation parameters that then can be used by Calculation Engines (Forecast and Formula). The Calculation Parameters are defined here <link>

  • ___HISTORICAL_CALCULATION___ - Separator element

  • HistoricalPeriods - Only if Forecast is used. Defines the Historical Periods used for the Historical Data lookup. This element retrieves the forecastMonths flag from AGR_AdvancedConfiguration and applies it, but “to the past”.

  • HistoricalData - Only if Forecast is used. Reads the Advanced Configuration for Historical Data lookups from AGR_Historical_AdvancedConfiguration and performs the data query, based on the HistoricalPeriods. Returns the data grouped by period and SKU.

  • ___FORECAST_CALCULATION___ - Separator element

  • ForecastPeriods - Only if Forecast is used. Defines the Forecast Periods used for the Forecast Data calculations. This element retrieves the forecastMonths flag from AGR_AdvancedConfiguration and applies it.

  • ForecastEngineCalculator - Only if Forecast is used. Defines the instance of EngineCalculator for the selected Forecast Engine.

  • ForecastCalculationParameters - Only if Forecast is used. Appends GeneralCalculationParameters with Historical Data and Periods so they can be used for Forecast Engine calculations, and returns the whole structure.

  • ForecastCalculationResults - Only if Forecast is used. Calls the Forecast Engine for each period and each SKU selected and stores the Engine results grouped by Period and SKU

  • ___MAIN_CALCULATION___ - Separator element

  • EngineCalculator - Defines the instance of EngineCalculator for the selected Formula.

  • MainCalculationParameters - Appends GeneralCalculationParameters with Historical and Forecast Data and Periods so they can be used in Formula Type calculations and returns the structure.

  • CalculationResults - Calls the Formula Type Calculation Engine for each SKU and returns the result.

  • ProcessedCalculationOutputs - Performs various operations on the results returned from the Formula Calculation Engine. The operations include: Bounds application and currency and UOM conversions (based on selected Additional Output Types). Additional data is appended to the Formula Type Calculation Engine results that allow to store it in Condition Records.

  • ___OUTPUTS___ - Separator element

  • IsActiveOutput - Output element that propagates the IsActive Input value from

  • CalculationOutputsResultMatrixOutput - Output element that creates the Calculation Outputs Result Matrix.

  • ForecastCalculationOutputsResultMatrixOutput - Only if Forecast is used. Output element that creates the Forecast Calculation Outputs Result Matrix.

  • MarginChangeOutput - Only if Forecast is used. Calculates difference between Forecast and Historical margin and returns it as an output.

  • RevenueChangeOutput - Only if Forecast is used. Calculates difference between Forecast and Historical revenue and returns it as an output.

  • VolumeChangeOutput - Only if Forecast is used. Calculates difference between Forecast and Historical volume and returns it as an output.

  • OccurredWarningsOutput - Retrieves the occurred warnings to be read on Header logic. (Hidden output)

  • WarningMatrix - Displays the Warning Matrix from Warning Manager.

  • ___CONDITION_RECORDS___ - Separator element

  • ConditionRecords - This element gathers, processes and prepares the Condition Record output. The structure from this element should match what should be written into the Condition Record for this line item in a one to one fashion. This output is then read by the Record Creation Logic. (Hidden output)

AGR_FormulaBasedPricing_FormulaConfigurator

This is the Configurator logic for the Line Item that allows the selection of Formula. It also displays any Broadcasted inputs if the Formula defines them.

  • InputsGeneration - Initializes the Input Manager solution from AGR_InputsLib. Configuration for the manager read from: libs.AGR_ProcessingLib.ConstConfig.INPUT_GENERATION_CONFIG.FORMULA_BASED_PRICING_FORMULA_CONFIGURATOR and generates the Configurator Entries

  • BroadcastInputsGeneration - Initializes the Input Manager solution from AGR_InputsLib. Configuration for the manager is based on the selected Formula CFO, the Formula Type that’s a part of it controls the Broadcast inputs. The appropriate Input Generation Company Parameter is read, this element looks only for inputs marked as Broadcast.

AGR_FormulaBasedPricing_ProductConfigurator

This is the Configurator logic for the Line Item that displays the Product Group input that allows the SKU selection to be calculated.

  • InputsGeneration - Initializes the Input Manager solution from AGR_InputsLib. Configuration for the manager read from: libs.AGR_ProcessingLib.ConstConfig.INPUT_GENERATION_CONFIG.FORMULA_BASED_PRICING_PRODUCT_CONFIGURATOR and generates the Configurator Entries

AGR_FormulaBasedPricingHeader

This is the Header logic that defines the Header behavior for the Agreement. It defines inputs to be shown as well as outputs to be produced once calculation finishes. It also controls the default structure of the Agreement and Error Handling.

  • WarningManager - Initializes the Warning Manager that handles most of the exceptions thrown by the Line Item Logic. For more details on WarningManager, see the Error Management (Agreements) article.

  • ConstConfig - Stores Header related configuration constants.

  • InputManager - Initializes the Input Manager solution from AGR_InputsLib. Configuration or the manager read from: libs.AGR_ProcessingLib.ConstConfig.INPUT_GENERATION_CONFIG.FORMULA_BASED_PRICING_HEADER

  • InputGeneration - Generates Inputs as defined by the Configuration.

  • AbortInputGeneration - Standard Abort Input Generation element.

  • __PREPHASE__ - Separator element

  • StructureGeneration - Generates the default Structure of the Agreement (Scenario + Line Item) if such is not present. Adds inputs into all Scenarios present, if they haven’t been added yet. Validates the Folder structure, to prevent nesting.

  • __POSTPHASE__ - Separator element

  • WarningManagement - Validates if there is only one scenario active or if there are no scenarios active. More validations may be added later on.

  • ___OUTPUTS___ - Separator element

  • CalculationOutputsResultMatrix - Creates a Calculation Outputs Result Matrix that displays the currently Active Scenario Line Items.

  • ScenarioCalculationOutputsResultMatrix - To each folder adds a Scenario Calculation Outputs Result Matrix that displays the Scenario Line Items.

  • ___CUSTOM_OUTPUTS___ - Separator element

  • <custom_output> - an element that calls cProcessor.addOrUpdateOutput("ROOT", parameter). For more details, refer to How to Add New Outputs to Header.

  • ___WARNING_HANDLING___ - Separator element

  • WarningMatrix - Displays the Warning Matrix from Warning Manager.

AGR_FormulaBasedPricingHeader_AdditionalCalculationOutputTypesConfigurator

This is the Configurator logic for the Header that displays the Additional Calculation Output Types Result Matrix Configurator Table input.

  • InputGeneration - Initializes the Input Manager solution from AGR_InputsLib. Configuration for the manager read from: libs.AGR_ProcessingLib.ConstConfig.INPUT_GENERATION_CONFIG.ADDITIONAL_CALCULATION_OUTPUT_TYPES_CONFIGURATOR and generates the Configurator Entries

AGR_FormulaBasedPricingHeader_BoundsConfigurator

This is the Configurator logic for the Header that displays the Lower and Upper Bound inputs.

AGR_FormulaBasedPricingHeader_ForecastConfigurator

This is the Configurator logic for the Header that displays the Forecast Engine input as well as any inputs defined by the selected Forecast Engine.

Recalculation Logics

AGR_ConditionRecordCreation

This is a Condition Record Creation Logic that reads the Condition Record output produced by the Line Item and creates a Condition Record out of it. It is run only in the Agreement Recalculation context via Scheduled Calculation.

AGR_AgreementFeeder

This is a Feeder logic for the Scheduled Calculation. It is used to provide the Calculation with Agreements that need calculation. They need to fulfill certain criteria to be picked up by the Feeder.

General Library Logics

AGR_DashboardsLib

This library logic stores utility functions that are used by the Dashboards present in the Agreements Package.

AGR_ForecastEnginesLib

This library logic stores definitions of Forecast Engines that are used to calculation Forecast revenue in the Line Item calculation. The elements here should reflect the entries in AGR_ForecastTypes Company Parameter.

AGR_FormulaLib

This library contains various utility functions that are used for management of anything Formula related, be it Formula Designer Formulas or Input Based Formulas. It also contains the Const Config for all Formula based operations.

AGR_InputBasedFormulaEnginesLib

This library stores definitions of Input Based Formulas Calculation Engines that are used to calculate the revenue in the Line Item calculation. The elements here should reflect the entries in AGR_InputBasedFormulaTypes Company Parameter.

AGR_ProcessingLib

Main library of the Package. Contains various utility methods, for almost everything else that is not in AGR_FormulaLib or AGR_DashboardsLib. Also stores the main Const Config of the solution.

AGR_InputLib

This logic stores the InputManager, which is the solution that handles most input generation present in the Package (Input Library Logics below are used by it). It also contains any common input generation functions/utilities.

Input Library Logics

AGR_DashboardInputsLib

Input Generation library containing definitions for inputs used by package Dashboards. The elements in this library should reflect the entries from any Company Parameter that’s connected to Dashboard Input Generation.

AGR_ForecastInputsLib

Input Generation library containing definitions for inputs used by package Forecast Engines. The elements in this library should reflect the entries from any Company Parameter that’s connected to Forecast Input Generation.

AGR_FormulaInputsLib

Input Generation library containing definitions for inputs used by package Formulas. The elements in this library should reflect the entries from any Company Parameter that’s connected to Formula Input Generation.

AGR_InputGeneratorLib

Input Generation library containing definitions for inputs used by package Forecast Engines. The elements in this library should reflect the entries from any Company Parameter that’s connected to Agreement Input Generation.

Formula Designer Logics

AGR_FormulaDesigner_CustomBlocks

This logic contains the definitions of Function blocks for Formula Designer. This article describes both the structure and behavior of this logic <link>.

AGR_FormulaDesigner_CustomInputs

This logic contains the definitions of Input blocks for Formula Designer. This article describes both the structure and behavior of this logic <link>.

AGR_FormulaDesigner_Deployment

This logic defines the deployment process for Formula Designer - aka what happens after “Activate” button is pressed on a Formula Type.

Formula Logics

AGR_FormulaHeader

This logic defines the Header behaviour (“Details” tab) on Formula CFO. It generates the Inputs for the Formula Type in the Definition Section and “descriptor” inputs in Attributes Section.

AGR_FormulaHeaderAttributesConfigurator

This is Configurator logic for the Attributes Section of the Formula.

AGR_FormulaHeaderDefinitionConfigurator

This is Configurator logic for the Definition Section of the Formula. It generates any Inputs that have been defined on the Formula Type.

Input Based Formula Logics

AGR_InputBasedFormulaHeader

This is the Header logic for the Input Based Formula CFO. It generates the Formula Type selection and displays the Configurator that handles the Inputs defined by the selected Formula Type.

AGR_InputBasedFormulaHeaderConfigurator

This is the Configurator for the Header logic of Input Based Formula CFO. It generates the Inputs defined by the selected Formula Type.

AGR_Formula_ExceptionsConfigurator

This is the Configurator logic for the Product Exceptions Configurator Table for the Cost Plus Input Based Formula Type that is shipped together with the Package.

Dashboard Logics

AGR_DashboardScenarioComparison

This is the Dashboard logic for the Scenario Comparison Dashboard that is displayed as Tab on the Agreement. It contains the Comparison Result Matrix.

AGR_DashboardScenarioComparison_Configurator

This is the Configurator logic for the Scenario Comparison Dashboard that displays the Scenario selection.

Filter Logics

AGR_FormulaBasedTypeFilter

This is the Filter Logic for the Agreement Line Items that filters out any non-Accelerator Condition Types.