# 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_`. 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 `Xparameter`s 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 `Xparameter`s 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 [Service Documentation](/navigation/service-documentation.md#version-details). #### **Compatibility versioning for `Xparameter`s** * 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_` 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_`. 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](/files/PeCtBYuB0TROp6qzrNIQ) ## Edit parameters There are two methods to editing and creating new versions of `Xparameter`s: ### 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 `Xparameter`s' values simultaneously. * You want to automatically create a parameter set with the updated values of the `Xparameter`s in your Excel model. 1. Open up your Spark service's Excel model. 2. Edit the `Xparameter`s 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 `Xparameter`s that have been edited. * If any edits to `Xparameter`s are detected at upload (edited values OR dimension changes), a new parameter set will automatically be configured with the most recent versions of all `Xparameter`s. * 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 `Xparameter`s 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](#backend-apis "mention"). 1. Use [API A)](#1-get-info-on-the-entire-list-of-xparameter-and-the-parameter-set-files) to get the latest version ID of the `Xparameter` you'd like to edit or use [API E)](#e-get-the-entire-list-of-xparameter-versions) to get the version IDs of all the `Xparameter`'s versions. 2. Use [API B)](#2-download-an-xparameter-file) to download the latest `Xparameter` version file. 3. Open the file in a text editor such as [VS-Code](https://code.visualstudio.com/), [Atom](https://atom.io/), 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)](#4-upload-an-xparameter-or-a-parameter-set-file) to upload the `Xparameter` file back onto Spark. 7. Use [API A)](#1-get-info-on-the-entire-list-of-xparameter-and-the-parameter-set-files) to get the latest version ID of the `Xparameter` that has just been uploaded or use [API E)](#e-get-the-entire-list-of-xparameter-versions) 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 `Xparameter`s 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 `Xparameter`s in the Excel model, upload it back onto Spark. 3. New versions of `Xparameter`s will be created if the values/dimensions of the `Xparameter`s 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 `Xparameter`s 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 `Xparameter`s, 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](#backend-apis "mention"). 1. Use [API A)](#1-get-info-on-the-entire-list-of-xparameter-and-the-parameter-set-files) to get the version ID of the latest paramere set. 2. Use [API C)](#3-download-a-parameter-set-file) to download the latest parameter set file. 3. Open the file in a code-editor such as [VS-Code](https://code.visualstudio.com/), [Atom](https://atom.io/), etc. 4. Use [API A)](#1-get-info-on-the-entire-list-of-xparameter-and-the-parameter-set-files) to get the version ID of the latest version ID of the `Xparameter`s that have just been edited or use [API E)](#e-get-the-entire-list-of-xparameter-versions) to get the version IDs of all the `Xparameter`'s versions. 5. Copy and paste the version IDs of the edited `Xparameter`s into the parameter set file. 6. Save the parameter set file. 7. Use [API D)](#4-upload-an-xparameter-or-a-parameter-set-file) to upload the parameter set file back onto Spark. 8. Use [API A)](#1-get-info-on-the-entire-list-of-xparameter-and-the-parameter-set-files) or [API F)](#5-get-the-entire-list-of-parameter-set-versions) to get the version ID of the parameter set that has just been uploaded. 9. Use [API G)](#6-get-the-xparameter-values-within-a-parameter-set-version) if you want to see the `Xparameter` values that are contained in a parameter set. ## Define a parameter set version in the payload {% hint style="info" %} 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. {% endhint %} 1. Set up your Spark API request payload. This can be find oun the [API Tester](/navigation/api-tester.md). 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](#backend-apis "mention") [API F)](#5-get-the-entire-list-of-parameter-set-versions). 4. Add the parameter set version ID to the value of the `parameterset_version_id` field. ### Sample request ```json { "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 `Xparameter`s 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)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#authorization) although `x-synthetic-key` may not be supported. **Sample response** ```json { "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)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#authorization) although `x-synthetic-key` may not be supported. **Sample response** ```json [ { "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)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#authorization) although `x-synthetic-key` may not be supported. **Sample response** ```json { "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)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#authorization) although `x-synthetic-key` may not be supported. **Request headers** Note that the `Content-Type` should be `multipart/form-data` **Sample request** ```javascript 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** ```json { "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)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#authorization) although `x-synthetic-key` may not be supported. **Sample response** ```json { "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)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#authorization) although `x-synthetic-key` may not be supported. **Sample response** ```json { "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)](/spark-apis/execute-api/execute-api-v3.md) [Execute API (v3)](/spark-apis/execute-api/execute-api-v3.md#authorization) although `x-synthetic-key` may not be supported. **Sample response** ```json { "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 `Xparameter`s Below an example of a Spark service with `Xparameter`s. You can upload this file to Spark to understand how `Xparameter` works. {% file src="/files/WruNO64KyMJgvixoKEn4" %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.coherent.global/build-spark-services/other-mapping-options/manage-service-parameters.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.