Introduction to the Scenario Analysis API

Posting a Template

After defining a template, the first step is generally to post the template definition, thus making the template available for use. To do so, call the following endpoint, using the template JSON as the request body:

POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/templates

Other Template Basics

Similar endpoints let you retrieve information about, update, or delete templates.

• Get information about all templates in a namespace:

  GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/templates
  

  

• Get information about a template:

  GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/templates/{templateName}
  

  

• Synchronize a template:

  PUT {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/templates/{templateName}
  

  

• Update a template:

  PATCH {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/templates/{templateName}
  

  

• Delete a template:

  DELETE {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/templates/{templateName}
  

  

Exporting and Importing Templates

To export a template and all associated code, use the following API call:

GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/export/{templateName}

When successful, this call generates a .ZIP file that contains all the following elements:

• A JSON file containing the template definition

• For transformation rules: All expressions and preprocessors referenced by the template

• For validation rules: All validation code referenced by the template

• For impact rules: All impact calculation code referenced by the template

• For call actions: All business processes referenced by transformations used in the template

• For recommendation rules: All business rule classes referenced by the template

This file is written to TempDirectory/namespace>/TemplateExport.zip

Similarly, to export all templates in a namespace, use the following API call:

GET {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/export

To import a template (and all associated code elements), obtain a ZIP file created by template export and use the following API call:

POST {{IRIS-SERVER-URL}}/api/{NAMESPACE}/scsam/v1/import

Use the ZIP file as the request body.

Other Template Options

The Scenario Analysis API has additional endpoints for posting, updating, or deleting parts of templates:

• {SERVER}/api/{$namespace}/scsam/v1/transformations and HTTPS://{SERVER}/api/{$namespace}/scsam/v1/transformationrules. This API supports CRUD operations on the transformation component of a template. Transformation and related rules defines the change of state for a given scenario. Each trasnformation can have several transformation rules.

• {SERVER}/api/{$namespace}/scsam/v1/validations and HTTPS://{SERVER}/api/{$namespace}/scsam/v1/validationrules. This API supports CRUD operations on the validation component of a template component. Validation and related rules defines the business logic to verify if an option for a given scenario is valid or not. Each validation can have more than one transformation rule.

• {SERVER}/api/{$namespace}/scsam/v1/impacts and HTTPS://{SERVER}/api/{$namespace}/scsam/v1/impactrules. This API supports CRUD operations on the impact component of a template. Impact and related rules defines the business logic to calculate the business impact (such as time, cost, and so on) for a given scenario.

Starting a Scenario Analysis Run

To start a scenario analysis run, use an API call of the following form:

POST {{IRIS-SERVER}}/{{NAMESPACE-PATH}}/scsam/v1/scenarioanalysis

In this call, include a JSON object of the following form:

{
     "templateName" : "Out Of Inventory"
     "contexts" : [
         {
            "parameterName" : "destinationLocationId",
            "value" : "ChicagoDC-001"
         },
         {
            "parameterName" : "quantity",
            "value" : "25000"
         },
         {
            "parameterName" : "productId",
            "value" : "Aurora-Protein-Bar-001"
         }
     ]
}

Where:

• The {{IRIS-SERVER}} part is the server information of the InterSystems IRIS® instance. In a locally deployed server, it may look like http://localhost:52773

• templateName is the name of the template to use.

• contexts is the context object and contains the input parameters for this scenario analysis.

This call returns a unique identifier for this scenario analysis run, for example: F010CA41-D5DD-11F0-8BE5-0232C0A8CC13

Getting the Status of a Scenario Analysis Run

To check the status of a scenario analysis run, use an API call of the following form:

{{IRIS-SERVER}}/{{NAMESPACE-PATH}}/scsam/v1/scenarioanalysis/{{SA-uid}}

Where SA-uid is the unique identifier for the scenario analysis run, returned by the API when you started the run.

The status is one of the following:

This call returns a JSON object with information about the scenario analysis run and its current status.

When the scenario analysis is complete, this JSON object also includes a recommendation, and a report array with details on all the options. For example:

{
    "recordCreatedTime" : "2025-12-10T15:36:04.06Z",
    "lastUpdatedTime" : "2025-12-10T15:36:10.362Z",
    "uid" : "F010CA41-D5DD-11F0-8BE5-0232C0A8CC13",
    "templateName" : "Out Of Inventory",
    "status" : "Complete",
    "report" : [... not shown here],
    "recommendation" : "F23DEAF-D5DD-11F0-8BE5-0232C0A8CC13",
    "priority" : "2",
    "createUser" : "SuperUser",
    "contextId" : "F0109C7F-D5DD-11F0-8BE5-0232C0A8CC13",
    "startTime" : "2025-12-10T15:36:07.559Z",
    "endTime" : "2025-12-10T15:36:10.362Z"}

The recommendation property is the ID of a scenario contained in the report array. Each object in this array contains details for one snapshot that was considered. (Note that invalid snapshots are not included.) The following shows an example of one object in the report array:

{
    "recordCreatedTime" : "2025-12-10T15:36:08.521Z",
    "lastUpdatedTime" : "2025-12-10T15:36:08.647Z",
    "snapshotId" : "F23DEAF-D5DD-11F0-8BE5-0232C0A8CC13",
    "templateName" : "Out Of Inventory",
    "transformationRuleName" : "Move Inventory ( warehousId : NewarkDC-001",
    "impactResultItems" : [
       {
            "recordCreatedTime" : "2025-12-10T15:36:08.584Z",
            "lastUpdatedTime" : "2025-12-10T15:36:08.584Z",
            "impactName" : "Time impact",
            "impactResult" : "1"
       },
       {
            "recordCreatedTime" : "2025-12-10T15:36:08.647Z",
            "lastUpdatedTime" : "2025-12-10T15:36:08.647Z",
            "impactName" : "Cost impact",
            "impactResult" : "6250"
       }
    ]
}

Resolving a Scenario Analysis

At the end of a scenario analysis run, you typically want to resolve it, which causes the system to invoke the logic needed to resolve the specific supply chain issue, such as authorizing a stock transfer between warehouses. (This logic is implemented as a call action in the template, and generally works by calling third-party APIs.)

To resolve a scenario analysis run, use an API call of the following form:

{{IRIS-SERVER}}/{{NAMESPACE-PATH}}/scsam/v1/resolvescenarioanalysis

In this call, include a JSON object of the following form:

{
     "scenarioAnalysisId" : "F010CA41-D5DD-11F0-8BE5-0232C0A8CC13",
     "snapshotId" : "F23DEAF-D5DD-11F0-8BE5-0232C0A8CC13"
}

The scenarioAnalysisId property must be the unique ID of the scenario analysis run, and the snapshotId must be the unique ID of the snapshot you want to use.

This call returns a JSON object of the following form:

{
     "Status" : "Success",
     "Message" : "Successfully resolved analysis."
}

When you resolve a scenario analysis run, in addition to invoking the applicable call action, the system performs the following cleanup work:

• Updating the status of the analysis run to Resolved.

• Storing the selected snapshotId as the final resolution.

• Deleting snapshots for all unused options.

See Also

• Scenario Analysis API ReferenceOpens in a new tab

• Introduction to Scenario Analysis