How to create a Parameter Handler

The Parameter Handler has the responsibility to apply the Scenario Parameters values to the Datasets which will be used by the engine. It is run during the ApplyingScenarioParameters step of the ScenarioRun Life Cycle.

Python project

A Parameter Handler is a Python project stored by default in run_templates/%CSM_RUNTEMPLATE_ID%/parameters_handler/. The storage place can be set in the Solution.yaml definition.

The Parameter Handler must contains at least a main.py file which is the entry point called by the Cosmo Tech Platform. It can define to a requirements.txt file to define specific dependancies. Apart from this considerations the Python project can be organize the way you want.

The main.py Python script will be executed in an environment definining the followinf Env Vars:

AZURE_TENANT_ID="12345678"
AZURE_CLIENT_ID="12345678"
AZURE_CLIENT_SECRET=azertyuiop
CSM_API_URL=https://api.comostech.com
CSM_API_TOKEN=azertyuiopqsdfghjklm
CSM_PARAMETERS_HANDLER_PROVIDER=local
CSM_PARAMETERS_HANDLER_PATH=run_templates/hundred/parameters_handler/
CSM_DATASET_ABSOLUTE_PATH=/mnt/scenariorun-data
CSM_PARAMETERS_ABSOLUTE_PATH=/mnt/scenariorun-parameters

The goal of a Parameter Handler project is to modify in place the Dataset files in $CSM_DATASET_ABSOLUTE_PATH with the information of the input parameters in $CSM_PARAMETERS_ABSOLUTE_PATH. It is the responsibility to the Parameter Handler to backup copy file before modifications

Dataset files

Dataset files in $CSM_DATASET_ABSOLUTE_PATH are CSV files compatible with the CosML loaders. Each Dataset is stored in a directory named with the Dataset Id to avoid file name conflict in $CSM_DATASET_ABSOLUTE_PATH/{%DATASETID%}.

Input parameters parameters.json file

Input parameters values are stored in a json file in $CSM_PARAMETERS_ABSOLUTE_PATH/parameters.json has the following structure:

parametersValues:
  type: array
  description: the list of Solution Run Template parameters values
  items:
    type: object
    description: the value of Analysis parameter for a Scenario for this ScenarioRun
    properties:
      parameterId:
        type: string
        description: the parameter Id
      varType:
        type: string
        readOnly: true
        description: the parameter value type
      value:
        type: string
        description: the parameter value

Input parameters values example file:

{ "parametersValues": [{"parameterId": "prefix", "varType": "string", "value": "new"}]}

Parameters referencing Datasets

Some input parameters have the special varType %DATASETID%. In this case the Dataset has been previously fetch in a directory in $CSM_PARAMETERS_ABSOLUTE_PATH/{%DATASETID%}.