Manage service parameters (Xparameter)

Xparameter externalizes service parameters and provides the ability to update parameters separately from the service itself. This separation creates an independent version history from the service and also allows users to execute Spark APIs against numerous parameter scenarios more efficiently.

Understand Xparameter terminology

Before we get into the specific mechanics, there are a couple terms to get familiar with.

Parameter: Numerical value(s) that describe a characteristic of a calculation model. They are adjustable variables/assumptions that determine the context in which the outputs are calculated against from the inputs (e.g. interest rates, inflation rate, tax base and rates, etc.).

Xparameter: A parameter range in a Spark service model that has been named Xparameter_<parameter>. This range is externalized from the service, creating an independent version history. Whenever the values of an Xparameter is updated, a new version of the Xparameter is created.

Parameter set: A JSON file containing all the Xparameters of the service with the versions defined. The parameter set's version ID, when defined in the Spark service API's request_meta informs the Spark engine which versions of the Xparameters should be used to run the calculations. This gives users the ability to run a Spark API of a single service version against different parameter scenarios. Whenever a new parameter set is configured, a new parameter set version is generated for it.

Compatibility group (Xparameter): A group of Xparameter versions in which the column numbers and headers are the same. When an Xparameter's column numbers or headers are altered in any way, a new compatibility group is created.

Compatibility group (parameter set): A group of parameter set versions in which the compatibility groups of every Xparameter are the same. When the collection of Xparameter compatibility groups in a parameter set version does not exist in any historical versions, then a new compatibility group is created. Every service version is assigned a parameter set compatibility group number based on which compatibility versions are embedded in the excel file at upload.

Default parameter set: The default parameter set is the most recent parameter set version uploaded to Spark within the service version's assigned compatibility group.

Xparameter hierarchy

Hierarchy of Xparameter

• Within a service (across versions), there can be multiple compatibility groups.

• Service versions and parameter set versions are grouped together by compatibility groups.

• This hierarchy defines which service versions are compatible with which parameter set versions based on the compatibility groups.

Compatibility versions

Compatibility Versioning

Each service version can be tied to a parameter set compatibility group. With this implementation, it is clear which parameter set versions are compatible with which service versions. The service version's parameter set compatiblity group is listed in Version details.

Compatibility versioning for Xparameters

• Compatibility group is dependent on the number of columns and the column header values. If the number of columns change or if any of the headers are renamed, this will cause a change in compatibility group.

• Compatibility version is dependent on the existing versions of the Xparameter within a particular compatibility group. If there are currently 3 versions of an Xparameter within the compatibility group 1, then the next Xparameter version within group 1 would have the compatibility version 4.

Compatibility versioning for parameter sets

• Compatibility group of a parameter set version is dependent on the collection of compatibility group numbers of the Xparameter versions contained within it. If the collection of the Xparameter group numbers within a parameter set version does not match that of any historical versions, this will create a new parameter set compatibility group.

• Compatibility version is dependent on the existing versions of the parameter sets within a particular compatibility group. If there are currently 3 versions of a parameter set within the compatibility group 1, then the next parameter set version within group 1 would have the compatibility version 4.

Map parameters

Syntax: Xparameter_<parameter>

1. Select the entire range of your parameter INCLUDING the headers (even if you're working with a single cell parameter, you must include a header).

2. Either go to the Name Box or open up the Name Manager in Excel

3. Name the selected range Xparameter_<parameter>. In the example below the parameter set was defined as SingleColumn.

4. Congratulations! You've created an Xparameter! Once your Excel model is uploaded onto Spark, the Xparameter ranges that you have defined will automatically be extracted from the service.

Example of Mapping an Xparameter

Edit parameters

There are two methods to editing and creating new versions of Xparameters:

Method 1: Editing the Xparameter values directly from your Excel model

This method is recommended when:

• You want to make changes to not only the values but also the dimensions of the Xparameter. For instance, if you want to add an additional column to an Xparameter, you should do so from the service Excel model.

• You want to edit multiple Xparameters' values simultaneously.

• You want to automatically create a parameter set with the updated values of the Xparameters in your Excel model.

1. Open up your Spark service's Excel model.

2. Edit the Xparameters as you'd like. If you change the dimensions of the Xparameter, make sure to update the named range to reflect the dimension changes.

3. Save the file.

4. Upload the file onto Spark, creating a new version of the service.

   • When you upload a file onto Spark with updated values or changes in dimensions in the Xparameter range, Spark will detect the change and create new versions of the Xparameters that have been edited.

   • If any edits to Xparameters are detected at upload (edited values OR dimension changes), a new parameter set will automatically be configured with the most recent versions of all Xparameters.

   • Reverting the values back to be the same as an older version of the Xparameter will still create a new version of the Xparameter (meaning 2 or more versions of an Xparameter can have identical content).

Method 2: Use backend APIs to edit Xparameters

This method is recommended when:

• You want to edit the values of just a single Xparameter.

• You want to edit the values of Xparameters programmatically in code.

The referenced APIs can be found below in the section Backend APIs.

1. Use API A) to get the latest version ID of the Xparameter you'd like to edit or use API E) to get the version IDs of all the Xparameter's versions.

2. Use API B) to download the latest Xparameter version file.

3. Open the file in a text editor such as VS-Code, Atom, etc.

4. Edit the Xparameter values (if you want to change the dimensions of the Xparameter, please use method 1 of updating an Xparameter written above).

5. Save the Xparameter file.

6. Use API D) to upload the Xparameter file back onto Spark.

7. Use API A) to get the latest version ID of the Xparameter that has just been uploaded or use API E) to get the version IDs of all the Xparameter's versions.

8. You can now use this version ID to create a new parameter set.

Configure parameter sets

There are two methods to configuring new parameter sets:

Method 1: Configure parameter sets directly from your Excel model

This method is recommended when you're editing Xparameters with the intention of configuring a new parameter set.

1. Edit any Xparameters in the Excel model by either creating new versions of the Xparameter or returning to previous versions of Xparameter.

2. Once you're happy with the values in ALL of the Xparameters in the Excel model, upload it back onto Spark.

3. New versions of Xparameters will be created if the values/dimensions of the Xparameters are different from those in the most recent version of the service. Please note that even if the edited values in an Xparameter's cell range are identical to an older version of the Xparameter, a new version of the Xparameter will still be created.

4. A new parameter set will be configured with the versions of the Xparameters found in the Excel model file as long as it's not identical to the MOST RECENT version of the parameter set. If there is an older parameter set version that exists already with the same versions of the Xparameters, a new version of the parameter set will still be configured.

Method 2: Use backend APIs to configure parameter sets

This method is recommended when you want to create a parameter set programmatically in code.

The referenced APIs can be found below in the section Backend APIs.

1. Use API A) to get the version ID of the latest paramere set.

2. Use API C) to download the latest parameter set file.

3. Open the file in a code-editor such as VS-Code, Atom, etc.

4. Use API A) to get the version ID of the latest version ID of the Xparameters that have just been edited or use API E) to get the version IDs of all the Xparameter's versions.

5. Copy and paste the version IDs of the edited Xparameters into the parameter set file.

6. Save the parameter set file.

7. Use API D) to upload the parameter set file back onto Spark.

8. Use API A) or API F) to get the version ID of the parameter set that has just been uploaded.

9. Use API G) if you want to see the Xparameter values that are contained in a parameter set.

Define a parameter set version in the payload

If a parameter set version is not defined in the API call request_meta, the most recent version of the parameter set will be used.

1. Set up your Spark API request payload. This can be find oun the API Tester.

2. In the request_meta, add a new field parameterset_version_id. Depending on where this is added, you may need to add comma separators.

3. Get the version ID of the parameter set version you'd like to use. Details can be found in Backend APIs API F).

4. Add the parameter set version ID to the value of the parameterset_version_id field.

Sample request

{
    "request_data": {
    "inputs": {
        "Value": 1 
        } 
    }, 
    "request_meta": { 
        "version_id": "ad47a144-0e75-4e2e-a170-854aa3de3ece", 
        "transaction_date": "2022-07-15T11:14:22.424Z", 
        "call_purpose": "", 
        "source_system": "", 
        "correlation_id": "", 
        "service_category": "", 
        "compiler_type": "Type3", 
        "requested_output": null,
        "parameterset_version_id": "4743024e-379e-4b99-9c16-304b32c36fdd"
    } 
}

Backend APIs

A) Get info on the entire list of Xparameter and the parameter set files

This API will return information on all the Xparameter and parameter set files associated with a specific service. Use this API to find the latest version ID and file names of the Xparameters and/or parameter set.

Method GET

URI https://excel.{environment}.coherent.global/api/filemanager/GetFolderDocs?folderPath=/apps/parameters/{folder}.{service}

Authorization

The required Authorization follows the Execute API (v3) Authorization although x-synthetic-key may not be supported.

Sample response

{
    "message": null,
    "data": {
        "folders": [],
        "documents": [
            {
                "id": "d3457ee0-8545-40ef-a549-0d2bfg23870c72",
                "name": "parameterset.json",
                "latestVersionId": "42342024e-379e-4b99-9c16-304b45c36fdd",
                "path": "/apps/parameters/{{FolderName}}.{{ServiceName}}/parameterset.json",
                "createdAt": "2022-07-15T08:27:10.682947+00:00",
                "createdBy": "e902ccea-4b52-45c4-803a-2b1d3c873755",
                "updatedAt": "2022-07-15T08:33:04.089841+00:00",
                "metadata": null
            },
            {
                "id": "e2cf3f60-c143-4ec0-83e4-caf248905642",
                "name": "ExampleXparameter1.json",
                "latestVersionId": "74ab324f-cb8c-34d1-aa0d-54ce910df2fc",
                "path": "/apps/parameters/{{FolderName}}.{{ServiceName}}/ExampleParameter1.json",
                "createdAt": "2022-07-15T08:27:10.477858+00:00",
                "createdBy": "e902ccea-4b52-45c4-803a-2b1d3c873755",
                "updatedAt": "2022-07-15T08:33:03.879653+00:00",
                "metadata": null
            },
            {
                "id": "6a563c81-511d-43e0-8f34-00ef0f479241",
                "name": "ExampleXparameter2.json",
                "latestVersionId": "53768e54-30dd-7478-ba94-957a1eecc87b",
                "path": "/apps/parameters/{{FolderName}}.{{ServiceName}}/ExampleXparameter2.json",
                "createdAt": "2022-07-15T07:09:39.666818+00:00",
                "createdBy": "e902ccea-4b52-45c4-803a-2b1d3c873755",
                "updatedAt": "2022-07-15T07:14:45.733376+00:00",
                "metadata": null
            }
        ]
    },
    "errorCode": null,
    "status": "Success"
}

B) Download an Xparameter file

This API will return the entire contents of an Xparameter version defined by the user. This content can then be downloaded as a JSON file to be edited and reuploaded. Use this API to download an Xparameter file.

Method GET

URI https://excel.{environment}.coherent.global/api/filemanager/DownloadDocumentByVersion/{xparameter_version_id}/{filename}.json

Authorization

The required Authorization follows the Execute API (v3) Authorization although x-synthetic-key may not be supported.

Sample response

[
    {
        "Column1": 100,
        "Column2": 1
    },

    {
        "Column1": 200,
        "Column2": 2
    },
    {
        "Column1": 300,
        "Column2": 3
    }
]

C) Download a parameter set file

This API will return the entire contents of a parameter set version defined by the user. This content can then be downloaded as a text file to be edited and re-uploaded. Use this API to download a parameter set file.

Method GET

URI: https://excel.{environment}.coherent.global/api/filemanager/DownloadDocumentByVersion/{parameterset_version_id}/parameterset.json

Authorization

The required Authorization follows the Execute API (v3) Authorization although x-synthetic-key may not be supported.

Sample response

{
    "Parameters": {
        "ExampleXparameter1": {
            "$ref": "74ab324f-cb8c-34d1-aa0d-54ce910df2fc"
        },
        "ExampleXparameter2": {
            "$ref": "6753768e54-30dd-7478-ba94-957a1eecc87b"
        }
    }
}

D) Upload an Xparameter or a parameter set file

This API allows you to upload Xparameter and parameter set files onto Spark. Once you've edited an Xparameter or created a parameter set, use this API to upload the files.

WARNING: Please make sure your filename and type is identical to the original. If the file name and type are not identical, Spark will not know which Xparameter or parameter set to create a new version for.

Method POST

URI https://excel.{environment}.coherent.global/api/filemanager/SaveDocument?folderPath=/apps/parameters/{folder}.{service}

Authorization

The required Authorization follows the Execute API (v3) Authorization although x-synthetic-key may not be supported.

Request headers

Note that the Content-Type should be multipart/form-data

Sample request

formData: {
    'privacyLevel': 'Private',
    'file': {
      'value': fs.createReadStream('5F7RyC9w6/ExampleXparameter1.json'),
      'options': {
        'filename': '',
        'contentType': null
      }
    }
  }

This is what the request body should look like on Postman.

Sample response

{
    "message": null,
    "data": null,
    "errorCode": null,
    "status": "Success"
}

E) Get the entire list of Xparameter versions

Description: This API will return the version IDs of every Xparameter version. Use this API if you want to use an older version of an Xparameter to create a parameter set.

Method GET

URI https://excel.{environment}.coherent.global/{tenant}/api/v3/parameter/folders/{folder}/services/{service}/{xparametername}

Authorization

The required Authorization follows the Execute API (v3) Authorization although x-synthetic-key may not be supported.

Sample response

{
    "response_data": [
        "2743024e-379e-3b42-9c16-304b32c36fdd",
        "f2370f37-381c-3895-889a-c0428abdebde",
        "9fee37c3-cedf-293d-8d90-7f0ecb2d1fd6",
        "k1b2f151-7102-3095-b110-7df7874c2098",
        "937a2380-0b3a-4bn1-aed5-86a50c4d6ff7",
        "48b28716-ea66-8a32-9bcb-95af230f21a4",
        "ce53d852-9afb-45f3-adf5-177e502e999a",
        "23547296-485f-2291-bccf-a3277c52a655"
    ],
    "status": "Success",
    "response_meta": {
        "system": "SPARK",
        "request_timestamp": "2022-07-15T08:33:28.470Z"
    },
    "error": null
}

F) Get the entire list of parameter set versions

This API will return the version IDs of every parameter set created for a service. Use this API if you want to use an older version of a parameter set in an API call and you can't remember the version ID.

Method GET

URI https://excel.{environment}.coherent.global/{tenant}/api/v3/parameter/folders/{folder}/services/{service}

Authorization

The required Authorization follows the Execute API (v3) Authorization although x-synthetic-key may not be supported.

Sample response

{
    "response_data": [
        "4743024e-379e-3b42-9c16-304b32c36fdd",
        "c2370f37-381c-3895-889a-c0428abdebde",
        "7fee37c3-cedf-293d-8d90-7f0ecb2d1fd6",
        "b1b2f151-7102-3095-b110-7df7874c2098",
        "337a2380-0b3a-4bn1-aed5-86a50c4d6ff7",
        "28b28716-ea66-8a32-9bcb-95af230f21a4",
        "be53d852-9afb-45f3-adf5-177e502e999a",
        "83547296-485f-2291-bccf-a3277c52a655"
    ],
    "status": "Success",
    "response_meta": {
        "system": "SPARK",
        "request_timestamp": "2022-07-15T08:33:28.470Z"
    },
    "error": null
}

G) Get the Xparameter values within a parameter set version

This API will return the Xparameter values within a parmeter set version. Use this API if you have a parameter set version ID but you're not sure what Xparameter values it contains.

Method GET

URI https://excel.{environment}.coherent.global/{tenant}/api/v3/parameter/versions/{parameter_set_version_id}

Authorization

The required Authorization follows the Execute API (v3) Authorization although x-synthetic-key may not be supported.

Sample response

{
    "response_data": {
        "Parameters": {
            "ExampleXparameter1": [
                {
                    "Column1": 100,
                    "Column2": 1
                },
                {
                    "Column1": 200,
                    "Column2": 2
                },
                {
                    "Column1": 300,
                    "Column2": 3
                }
            ],
            "ExampleXparameter2": [
                {
                    "Column1": 10
                }
            ]
        }
    },
    "status": "Success",
    "response_meta": {
        "system": "SPARK",
        "request_timestamp": "2022-07-15T08:33:43.917Z"
    },
    "error": null
}

Sample Spark service with Xparameters

Below an example of a Spark service with Xparameters. You can upload this file to Spark to understand how Xparameter works.

11KB

Xparameter_Test_File.xlsx

Open