How to Add New Calculation Parameters to Calculation Engines

There are two ways to add Calculation Parameters to Calculation Engines. They depend on the use case, but are as follows:

The parameter has a value that is retrievable only during the execution.
The parameter has a value that can be provided by the user.

Use Case 1: The Parameter Has a Value That Is Retrievable Only During the Execution

1. (Optional) Make the Parameter Available in the Formula Designer

To use the parameter in the Formula Designer, you must first define it in the formulaDesigner Advanced Configuration Options (Administration > Configuration > System Configuration >Advanced Configuration Options).

All such parameters are defined under additionalParameters key and should follow this format:

"additionalParameters": {
    "MY_NEW_PARAMETER": { <- name
      "label": "SKU", 
      "type": "string"
    }
  }

name: The name of the parameter. It is the key that is present in the Engine Calculation Parameters column in the Company Parameters table (AGR_FormulaTypes for Formula Designer engines, or AGR_InputBasedFormulaTypes for parameters defined manually).
label: The label that will be displayed in the Formula Designer, in the Parameters tab and on the block itself.
type: The data type of the parameter. Currently, only “string” and “number” are supported.
- For Input-Based Formulas if there’s a need for any other complex objects to be stored, they can always be encoded to JSON using api.jsonEncode() function and decoded on the calculation method itself later. This approach does not work for Formulas created via Formula Designer.

After the Parameter has been defined in the formulaDesigner, you need to proceed with the next step.

2. Define the Calculation Parameter in the Line Item Logic

There is an element called AdditionalCalculationParameters present in the AGR_FormulaBasedPricing Line Item Logic in the ___CALCULATION_PARAMETERS___ separator section – this is the place to put all new Calculation Parameters.

Each parameter is a key-value pair (Map), where the key is the parameter's name and the value is the associated data.

If the parameter has been defined in the formulaDesigner Advanced Configuration Option, the name has to match the name used additionalParameters section.

If the parameter is not supposed to be used by Formula Designer, but only by Input-Based Formula Engines, it can be created “at hand” in the element – just add a new entry with a new name and a value and use that name in the Engine Calculation Parameters column in the Company Parameters table.

It is a good practice to store these parameters in libs.AGR_FormulaLib.ConstConfig.PREDEFINED_CALCULATION_PARAMETERS Map for easy reference and later modifications.

New parameter example:

return [(libs.AGR_FormulaLib.ConstConfig.PREDEFINED_CALCULATION_PARAMETERS.MY_NEW_PARAMETER) : 5]

Use Case 2: The Parameter Has a Value That Can Be Provided by the User

If the value of the parameter can be provided by the user, then the parameter can be defined as an input. There are two ways to create inputs:

Manually – for more details, see the How to Modify, Add and Remove Inputs article
Via Formula Designer input block – for more details, refer to Formula Designer (Agreements) | Creation of Custom Input Blocks

This approach is possible, because all input names (including hidden inputs) are stored as Calculation Parameters and can be used in the Calculation Method.