1. Intelligent Advisor REST APIREST API for Intelligent Advisor 24B
  2. Use Cases
  3. Using the Deployments REST API

Using the Deployments REST API

The Deployments REST API is used to manage Intelligent Advisor Hub deployments, including upload, download, activation, and status.

From 12.2.28, a Deployments REST API request for all "interview" channel deployments will now include deployed flow projects. If you don't want those flow interviews to be returned (for example, if you are presenting a list of Policy Modeling projects for a user to link to from within a Fusion knowledge article), then you should set a filter (in q parameter) like q={"services":"interview","kind":"opm"}.

The Deployments REST API supports requesting deployments only from particular workspaces. To do this, you can set a filter like q={"workspace": ["Workspace 1", "Workspace2", "Workspace 3"]}.

Example GET All Deployments

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments

The response to a get all deployments request looks like the following:


{
    "items": [
        {
            "name": "Example 1",
            "description": "My Policy Modeling Project",
            "compatibilityMode": "latest",
            "activeVersionNo": 25,
            "workspace": [
                "Default Collection"
            ],
            "services": [
                "interview",
                "webservice"
            ],
            "serviceURLs": {
                "interview": "https://mysite.example.com/web-determinations/startsession/Example%201",
                "webservice": "https://mysite.example.com/determinations-server/display/Example%201"
            },
            "errors": [],
            "workspaceReferences": "current",
            "kind": "opm",
            "activeVersion": {
                "links": // ...
            },
            "versions": {
                "links": // ...
            },
            "logs": {
                "links": // ...
            },
            "debugLoggingState": {
                "state": "active",
                "endDate": "2021-06-05T10:31:05Z",
                "maxLogs": 1000
            }
            "debugLogs": {
                "links": // ...
            },
            "links": // ...
        },
        {
            "name": "Example 2",
            "description": "My Flow Project",
            "compatibilityMode": "latest",
            "activeVersionNo": 5,
            "workspace": [
                "2022 Flows"
            ],
            "services": [
                "interview"
            ],
            "serviceURLs": {
                "interview": "https://mysite.example.com/web-determinations/interview/start/Example%202"
            },
            "errors": [],
            "workspaceReferences": "current",
            "kind": "flow",
            "activeVersion": {
                "links": // ...
            },
            "versions": {
                "links": // ...
            },
            "logs": {
                "links": // ...
            },
            "debugLoggingState": {
                "state": "inactive",
                "maxLogs": 1000
            }
            "debugLogs": {
                "links": // ...
            },
            "links": // ...
        },
        // ... more deployments ...
    ]
}

The properties of the deployment debugLoggingState object are:

Property Name Description
state The state of debug logging for the deployment. Options are: "active", "expired", "inactive" and "terminated".
endDate (Optional) The date that debug logging for the deployment will expire.
maxLogs (Optional) The maximum number of debug logs that can be stored for the deployment. Set to 1000 by default.

Example GET Single Deployment

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example

The response to a single deployment request looks like the following:


{
    "name": "HealthyEating",
    "description": "Original HealthyEating project",
    "compatibilityMode": "latest",
    "activeVersionNo": 31,
    "workspace": "Secured workspace",
    "services": [
        "interview"
    ],
    "serviceURLs": {
        "interview": "https://mysite.example.com/web-determinations/startsession/HealthyEating"
    },
    "errors": [],
    "workspaceReferences": "current",
    "kind": "opm",
    "activeVersion": {
        "links": // ...
    },
    "versions": {
        "links": // ...
    },
    "logs": {
        "links": // ...
    },
    "debugLoggingState": {
        "state": "inactive",
        "maxLogs": 1000
    },
    "debugLogs": {
        "links": // ...
    },
    "links": // ...
}

Example GET Single Deployment, expand versions

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example?expand=versions

The response looks like the following:


{
    "name": "HealthyEating",
    "description": "New HealthyEating project",
    "compatibilityMode": "latest",
    "activeVersionNo": 5,
    "workspace": "Secured workspace",
    "services": [
        "interview"
    ],
    "serviceURLs": {
        "interview": "https://mysite.example.com/web-determinations/startsession/HealthyEating"
    },
    "errors": [],
    "workspaceReferences": "current",
    "kind": "opm",
    "activeVersion": {
        "links": // ...
    },
    "versions": {
        "items":
        [
            {
                "description": "Original HealthyEating project",
                "versionNo": 1,
                "addedBy": "admin",
                "activeVersionFlag": false,
                "opaVersion": "12.2.26",
                "date": "2022-07-06T01:14:10Z",
                "snapshot": {
                    "links": // ...
                },
                "kind": "opm",
                "urlParameters": {
                    "links": // ...
                },
                "locales": {
                    "links": // ...
                },
                "operations": [],
                "componentVersion": "49.0.0",
                "canUseCompatibilityMode": true,
                "mappings": {
                    "links": // ...
                },
                "links": // ...
            },
    "logs": {
        "links": // ...
    },
    "debugLoggingState": {
        "state": "inactive",
        "maxLogs": 1000
    },
    "debugLogs": {
        "links": // ...
    },
    "links": // ...
}

Example GET Active Deployment Version Seed URL Parameters

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/activeVersion/urlParameters

The response looks like the following:


{
    "type": "global",
    "properties": {
        "new_opportunity_summary": {
            "type": "text"
        },
        "products": {
        "type": "containingRelationship",
            "properties": {
                "features": {
                    "type": "containingRelationship",
                    "properties": {
                        "feature_name": {
                            "type": "text"
                        },
                        "feature_value": {
                            "type": "number"
                        },
                        "bleeding_edge": {
                            "type": "boolean"
                        }
                    }
                },
                "warranties": {
                    "type": "containingRelationship",
                    "properties": {
                        "warranty_period": {"type": "number"}
                    }
                }
            }
        }
    }
}

Example GET Active Deployment Version Locales

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/activeVersion/locales

The response looks like the following:


{
    "default-locale": "en-GB",
    "available": [
        "en-GB",
        "es-ES",
        "fr-FR",
        "nl-NL",
        "zh-CN"
    ]
}

Example GET Active Deployment Version Mappings

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/activeVersion/mappings

The response looks like the following:


{
    "serviceName": "ExampleDataConnector",
    "serviceType": "WebService",
    "inputMapping": [
        {
            entityId="global",
            tableName="Contact"
        }
    ],
    "outputMapping": [
        {
            entityId="global",
            tableName="Contact"
        }
    ]
}

The response for the different types of connections is:

Connection type Response
Web Service Returns serviceName and serviceType ("WebService"), as well as input and output mappings for the global entity
CX Sales and B2B Service Returns serviceName and serviceType ("EngagementCloud"), as well as input and output mappings for the global entity
B2C Service Returns the serviceName and serviceType ("ServiceCloud") only

Example GET All Deployment Versions

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions

The response looks like:


{
    "items": [
        {
            "description": "Travel Compensation",
            "versionNo": 3,
            "addedBy": "admin",
            "activeVersionFlag": true,
            "opaVersion": "12.2.26",
            "date": "2022-07-06T01:14:10Z",
            "snapshot": {
                "links": // ...
            },
            "kind": "opm",
            "urlParameters": {
                "links": // ...
            },
            "locales": {
                "links": // ...
            },
            "operations": [],
            "componentVersion": "49.0.0",
            "canUseCompatibilityMode": true,
            "mappings": {
                "links": // ...
            },
            "links": // ...
        },
        {
            "description": "Loan pre-approval",
            "versionNo": 4,
            "addedBy": "admin",
            "activeVersionFlag": true,
            "opaVersion": "12.2.28",
            "date": "2022-08-25T05:27:48Z",
            "snapshot": {
                "links": // ...
            },
            "kind": "flow",
            "project": {
                "name": "First flow project",
                "version": 1
            },
            "urlParameters": {
                "links": // ...
            },
            "locales": {
                "links": // ...
            },
            "operations": [],
            "componentVersion": "52.0.0",
            "canUseCompatibilityMode": true,
            "mappings": {
                "links": // ...
            },
            "links": // ...
        },
        // ... more versions ...
    ],
    "links": // ...
}

Example GET Deployment Version

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions/3

The response looks like:


{
    "description": "Travel Compensation",
    "versionNo": 3,
    "addedBy": "admin",
    "activeVersionFlag": true,
    "opaVersion": "12.2.26",
    "date": "2022-07-06T01:14:10Z",
    "snapshot": {
        "links": // ...
    },
    "kind": "opm",
    "urlParameters": {
        "links": // ...
    },
    "locales": {
        "links": // ...
    },
    "operations": [],
    "componentVersion": "49.0.0",
    "canUseCompatibilityMode": true,
    "mappings": {
        "links": // ...
    },
    "links": // ...
}

Example GET Deployment Version, expand snapshot

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions/3?expand=snapshot

The response looks like the following:


{
    "description": "Travel Compensation",
    "versionNo": 3,
    "addedBy": "admin",
    "activeVersionFlag": true,
    "opaVersion": "12.2.26",
    "date": "2022-07-06T01:14:10Z",
    "snapshot": {
        "base64": "...snapshot base-64 data...",
        "links": // ...
    },
    "kind": "opm",
    "urlParameters": {
        "links": // ...
    },
    "locales": {
        "links": // ...
    },
    "operations": [],
    "componentVersion": "49.0.0",
    "canUseCompatibilityMode": true,
    "mappings": {
        "links": // ...
    },
    "links": // ...
}

Example GET Deployment Version Snapshot

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions/5/snapshot

By default, the result is returned in JSON format. The response looks like the following:


{
    "base64": "...snapshot base-64 data...",
    "links": // ...
}

Example GET Deployment Version Snapshot as binary data

To get the result as a binary Zip file, send the GET request with the following HTTP request header:

Accept: application/zip

The result will be returned as a Zip file. The HTTP response headers will also include the following information:

  • Cache-Control
  • ETag
  • Last-Modified
  • Vary

These additional headers allow the content to be cached by the REST client, and allow for conditional GET or HEAD requests to check for content freshness.

Example GET All Deployment Logs

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/logs

The response looks like the following:


{
    "items":
    [
        {
            "date": "2016-11-04T00:33:59Z",
            "description": "Ad hoc project 'Example'. ",
            "updatedBy": "admin",
            "services": [
                "interview",
                "webservice"
            ],
            "activeVersion": 1
        },
        {
            "date": "2016-10-31T01:42:41Z",
            "description": "Ad hoc project 'Example'. ",
            "updatedBy": "admin",
            "services": [
                "mobile"
            ],
            "activeVersion": 1
        },
        // ... more log entries ...
    ],
    "links": // ...
}

Example GET All Deployment Debug Logs

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/debugLogs

The response looks like the following:


{
    "items": [
        {
            "uid": "fdfe51cd-f391-4271-8633-0b0293c18c88",
            "outcome": "error",
            "date": "2021-06-17T03:58:02Z",
            "product": "WEB_DETERMINATIONS",
            "function": "INTERVIEW",
            "deploymentVersion": 1,
            "events": {
                "links": // ...
            },
            "content": {
                "links": // ...
            },
            "links": // ...
        }
    ],
    "links": // ...
}

The properties of the individual items in the deploymentDebugLog collection are:

Property Name Description
uid The generated identifier for the debug log.
outcome The outcome of the debug log. "Error" means one or more errors were encountered. "ok" means no errors have been encountered.
date The date and time the debug log was created.
product The product that created the debug log. Options are: WEB_DETERMINATIONS or DETERMINATIONS_SERVER.
function The function that created the debug log. Options are: INTERVIEW.
deploymentVersion The deployment version that was active when the debug log was created.
events A collection of sub-resources representing the individual events recorded by the log.
content A sub-resource that provides the content of the debug log as a binary Zip file.

Example GET All Deployment Debug Log Events

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/debugLogs/69fd6578-7e7d-48b6-ae59-5bc1e57ed45e/events

The response looks like the following:


{
    "items": [
        {
            "id": 11,
            "date": "2021-06-17T03:58:02Z",
            "name": "HttpRequestPrepared",
            "description": "HTTP request sent",
            "outcome": "ok",
            "contentMimeType": "text/plain",
            "contentFileName": "2021-06-17T03:58:02Z - HTTP request sent.txt",
            "content": {
                "links": // ...
            },
            "links": // ...
        }
    ],
    "links": // ...
}

The properties of the individual items in the debugEvent collection are:

Property Name Description
id The generated identifier of the event.
date The date the event was recorded.
name The short name of the event.
description The description of the event.
outcome The outcome of the debug log. "Error" means the event was completed successfully. "ok" means the event encountered and error.
contentMimeType The MIME type of the data recorded as the event content. "text/xml" means the data is an XML document. "text/plain" means the data is plain text.
contentFileName The file name of the downloadable event content.
content A sub-resource that provides the content of the event as a data stream with the MIME type and file name identified by the contentMimeType and contentFileName properties.

Example GET Deployment Debug Log Content

The GET request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/debugLogs/69fd6578-7e7d-48b6-ae59-5bc1e57ed45e/content

By default, the REST resources will return the file content as a Base64-encoded property as part of a JSON payload, but the file data can be returned as a data stream by including the appropriate 'Accept' header in the request:

  • Accept: text/plain: Download the file as plain text
  • Accept: text/xml: Download the file as XML
  • Accept: application/zip: Download the file as a ZIP file
  • Accept: application/octet-stream: Download the file as binary data, leaving the client to decide how to open it
  • Accept: application/json: Download the file as a JSON payload

Example GET Project Definition for a Deployment Version

The GET request URL looks like:

/opa-hub/api/12.2.34/deployments/Example/versions/2/projectDefinition

If the deployment version is a decision service deployment, the decision service for this deployment version will be returned.

If the deployment version is a flow deployment, both the flow and the scheme for this deployment version will be returned.

The response looks like the following for a decision service deployment version:


{
    "definition": {
        "version": 7,
        "inputContract": {
            "properties": [
                {
                    "uid": "286u6t90e7qh",
                    "value": "num1",
                    "name": "num1",
                    "type": "number"
                },
                {
                    "uid": "r1mryux4nnt",
                    "value": "num2",
                    "name": "num2",
                    "type": "number"
                },
                {
                    "uid": "dxea8hm5fra",
                    "value": "num3",
                    "name": "num3",
                    "type": "number"
                }
            ]
        },
        "outputContract": {
            "properties": [
                {
                    "uid": "v9jlmcs37r",
                    "value": "result",
                    "name": "result",
                    "type": "number"
                }
            ]
        },
        "rules": {
            "Rules": [
                {
                    "type": "rule-block",
                    "lines": [
                        {
                            "text": "num1 plus num2 =(num1 + num2) ",
                            "level": 0
                        },
                        {
                            "text": "result = multiplier result",
                            "level": 0
                        }
                    ]
                },
                {
                    "text": "",
                    "style": "normal"
                }
            ]
        },
        "ruleLanguage": {
            "language": "en",
            "formats": {
                "decimalSeparator": ".",
                "thousandsSeparator": ",",
                "argumentSeparator": ",",
                "dateFormat": "m/d/yyyy"
            }
        },
        "documents": [],
        "references": {
            "uid": "t37jyv2382s",
            "items": [
                {
                    "uid": "5tjhkf1hb8a",
                    "kind": "decisionService",
                    "name": "Multiplier",
                    "modelObjectPath": "",
                    "deployment": "Multiplier",
                    "inputMapping": {
                        "$val1": "num1 plus num2",
                        "$val2": "num3",
                        "uid": "ubkvoyhdhd"
                    },
                    "outputMapping": {
                        "$result": "multiplier result",
                        "uid": "6sdofh6nxjl"
                    }
                }
            ]
        }
    },
    "links": // ...
}

Example POST Single Deployment

The POST request URL looks like:

/opa-hub/api/12.2.28/deployments

The basic structure expected for the POST request for the deployment resource looks like the following:


{
    "name": "Example",
    "workspace":
    [
        "Default Collection"
    ],
    "description": "Description of Example Project",
    "services":
    [
        "interview",
        "webservice",
        "mobile"
    ],
    "compatibilityMode": "latest",
    "versions":
    {
        "items":
        [
            {
                "description": "The initial version",
                "activeVersionFlag": true,
                "snapshot":
                {
                    "base64": "...base64 value..."
                }
            }
        ]
    }
}

When creating a new deployment, the deployment information, along with at least one version and snapshot, must be provided in the initial POST data.

Example POST Single Deployment for a Decision Service Project Version

The POST request URL looks like:

/opa-hub/api/12.2.28/deployments

A request to post a decision service project deployment looks like the following:


{
    "name": "Example77",
    "workspace": "Default Collection",
    "description": "A description of the Decision Service",
    "services": [
        "webserviceAssess"
    ],
    "compatibilityMode": "latest",
    "versions": {
        "items": [
            {
                "activeVersionFlag": true,
                "description": "Example of a Decision Service Deployment",
                "project": {
                    "name": "Example_Decision_Service_Project",
                    "version": 2
                }
            }
        ]
    }
}

Example POST Single Deployment for a Flow Project Version

The POST request URL looks like:

/opa-hub/api/12.2.28/deployments

A request to post a flow project deployment looks like the following:


{
    "name": "RestAPIExampleFlowDeployment",
    "workspace": "Default Collection",
    "description": "A description of the Flow",
    "services": [
        "interview"
    ],
    "compatibilityMode": "latest",
    "versions": {
        "items": [
            {
                "activeVersionFlag": true,
                "description": "A description of the Flow version",
                "project": {
                    "name": "RestAPIExampleFlow",
                    "version": 1
                }
            }
        ]
    }
}

Example POST List of Deployments

The POST request URL looks like:

/opa-hub/api/12.2.28/deployments

The structure expected for the POST request for the deployment resource looks like the following:


{
    "items":
    [
        {
            "name": "Example",
            "workspace":
            [
                "Default Collection"
            ],
            "description": "Description of Example Project",
            "services":
            [
                "interview",
                "webservice",
                "mobile"
            ],
            "compatibilityMode": "latest",
            "versions":
            {
                "items":
                [
                    {
                        "description": "The initial version of Example Project",
                        "activeVersionFlag": true,
                        "snapshot":
                        {
                            "base64": "...base64 value..."
                        }
                    }
                ]
            }
        },
        {
            "name": "Example 2",
            "workspace":
            [
                "Default Collection",
            ],
            "description": "Description of Example Project 2",
            "services":
            [
                "webservice",
                "mobile"
            ],
            "compatibilityMode": "latest",
            "versions":
            {
                "items":
                [
                    {
                        "description": "The initial version of Example 2",
                        "activeVersionFlag": true,
                        "snapshot":
                        {
                            "base64": "...base64 value..."
                        }
                    }
                ]
            }
        }
    ]
}

Example POST Single Deployment Version

The POST request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions

The basic structure expected for the POST request for the deployment version resource is as follows:


{
    "description": "A new version of Example Project",
    "activeVersionFlag": true,
    "snapshot":
    {
        "base64": "...base64 value..."
    }
}

This creates a new version for an existing deployment and activates the new version immediately.

Example POST List of Deployment Versions

The POST request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions

The structure expected for the POST request for the deployment version resource is as follows:


{
    "items":
    [
        {
            "description": "A new version",
            "activeVersionFlag": false,
            "snapshot":
            {
                "base64": "...base64 value..."
            }
        },
        {
            "description": "A new active version",
            "activeVersionFlag": true,
            "snapshot":
            {
                "base64": "...base64 value..."
            }
        }
    ]
}

This creates two new versions for an existing deployment, the second of which is activated immediately.

Example POST a references report

This is a report containing all the references to the deployed decision service from other deployments or projects.

The POST request URL looks like:

opa-hub/api/12.2.33/deployments/Example/referencesTo

The request takes two required parameters:

Parameter Description Valid expressions
targets Which references to the decision service to include: only the deployments, only the projects, or both deployments and projects "deployments", "projects", or "all"
scope Whether the report should include only active deployments, latest deployments and projects, or all versions of a deployment or project that refer to the deployed decision service "active", "latest", or "all"

For example:


{
    "targets": "all",
    "scope": "all"
}

By default, the response is in JSON format and gives:

  • total reference count

  • hidden reference count

  • entries for each non-hidden item, each item consisting of:

    • the name

    • the version number

    • a fingerprint value

    • a kind, one of "opm", "flow", "decision"

    • active, true if the deployment is currently active, otherwise false (only for deployments, absent for projects)

    • the workspace

Where both deployments and projects are targets of the request, these are grouped separately.

For example:


{
    "deployments": {
        "totalEntries": 3,
        "hiddenEntries": 1,
        "entries": [
            {
                "name": "The Dependent",
                "versionNo": 3,
                "fingerprint": "3e0a163598f077a525870a8bcf87ececa9499f9f0ce1e76c82b69422c2adedfb",
                "kind": "opm",
                "activeFlag": false,
                "workspace": "Default Collection"
            },
            {
                "name": "Another Dependent",
                "versionNo": 2,
                "fingerprint": "d65d3db263eb8c81d5d24510247e95e2a3607b47942cc282b1e10a71f817894f",
                "kind": "opm",
                "activeFlag": false,
                "workspace": "Default Collection"
            }
        ]
    },
    "projects": {
        "totalEntries": 1,
        "hiddenEntries": 0,
        "entries": [
            {
                "name": "The Dependent",
                "versionNo": 2,
                "fingerprint": "208aa344612af00858d4737a72fa8f681bab4f1dda96cbc47aaccdcfa4d9dc0a",
                "kind": "opm",
                "workspace": "Default Collection"
            }
        ]
    }
}

The data may also be encoded as CSV data, suitable for Excel. The client may request CSV data in one of two ways:

  • Provide an HTTP Accept header that specifies that CSV data is preferred. The format is: Accept: text/csv

  • Provide a query parameter in the URL that specifies that CSV data is required. The format is: GET /opa-hub/api/12.2.33/deployments/<deploymentName>/?mediaType=text/csv

For example:


To Name,To Project Type,To Workspace,From Name,From Version,From Project Type,From Workspace,From Category,From Active
Impacted users,Decision service,Default Collection,The Dependent,3,Policy Modeling,Default Collection,Deployment,No
Impacted users,Decision service,Default Collection,Another Dependent,2,Policy Modeling,Default Collection,Deployment,No
Impacted users,Decision service,Default Collection,<Hidden>>,,,,Deployment,,
Impacted users,Decision service,Default Collection,The Dependent,2,Policy Modeling,Default Collection,Project,

The first line is a header line.

All other lines correspond to entries in the JSON format above. The CSV format does not include fingerprint information, but does include workspace names of both to- and from- ends of a reference.

Example PATCH Deployment

The request URL looks like:

/opa-hub/api/12.2.28/deployments/Example

The structure expected for a PATCH request for the deployment resource is as follows:


{
    "compatibilityMode": "current",
    "services":
    [
        "interview",
        "mobile"
    ],
    "workspace":
    [
        "Default Collection"
    ]
}

Example PATCH Deployment Version

The request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions/1

The structure expected for a PATCH request for the deployment version resource is as follows:


{
    "activeVersionFlag": false
}

Example DELETE Deployment

The request URL looks like:

/opa-hub/api/12.2.28/deployments/Example

The response is an HTTP 204 response, with no JSON data returned.

Example DELETE Deployment Version

The request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/versions/1

The response is an HTTP 204 response, with no JSON data returned.

Example DELETE Deployment Debug Logs

The request URL looks like:

/opa-hub/api/12.2.28/deployments/Example/debugLogs

The response is an HTTP 204 response, with no JSON data returned.