Calling decision services

Your client application calls an endpoint through the decision runtime REST API to execute a decision service. The client calls the decision service by using the standard HTTP GET and POST commands that the web browsers use when they interact with remote servers.

A client application calls a decision service by creating a secure connection with a server, and then calling the decision service through the REST API.

Endpoint to execute with a decision ID (decisionId)
Endpoint to execute the last sorted version of a decision service
Endpoint to execute the last deployed version of a decision service
Request body
HTTP return codes and execution results

Endpoint to execute with a decision ID (decisionId)

The endpoint URI for a decision service uses the following format:

POST https://<server>:<port>/ads/runtime/api/v1/deploymentSpaces/{deploymentSpaceId}/decisions/{decisionId}/operations/{operation}/extendedExecute

For more information about the exact URL patterns for calling decision services, see Runtime REST API reference.

<server> is the hostname of the decision runtime, which is specified in the decision_runtime.ingress.hostname parameter.
<port> is the port of the decision runtime.

For more information about these parameters, see IBM Automation Decision Services parameters.

Table 1. Parameters that are used in the endpoint URI
Parameter	Mandatory or Optional	Description
deploymentSpaceId	Mandatory	URL encoded identifier that uniquely identifies the place where a decision was deployed.
decisionId	Mandatory	URL encoded identifier that uniquely identifies a decision to execute.
operation	Mandatory	Name of the operation. It is used to identify which decision service to execute within the decision service archive. The operation name is decided at authoring time.

Endpoint to execute the last sorted version of a decision service

The endpoint URI for a decision service that selects decisions based on their sorted version uses the following format:

POST https://<server>:<port>/ads/runtime/api/v1/selectors/lastSortedDecisionServiceVersion/deploymentSpaces/{deploymentSpaceId}/operations/{operation}/extendedExecute?decisionServiceId={decisionServiceId}

The version of a decision service refers to the decisionServiceVersion metadata of the decision service. For more information about the metadata, see Decision service metadata.

For more information about the exact URL patters for calling decision services, see Runtime REST API reference.

<server> is the hostname of the decision runtime, which is specified in the decision_runtime.ingress.hostname parameter.
<port> is the port of the decision runtime.

For more information about the parameters, see IBM Automation Decision Services parameters.

Table 2. Parameters that are used in the endpoint URI
Parameter	Mandatory or Optional	Description
deploymentSpaceId	Mandatory	URL encoded identifier that uniquely identifies the place where a decision was deployed.
operation	Mandatory	Name of the operation. It is used to identify which decision service to execute within the decision service archive. The operation name is decided at authoring time.
decisionServiceId	Mandatory	Query parameter that identifies the decision project from which the decision service archive is built. The decision service ID is decided at authoring time. Its value is that of the `decisionServiceId` metadata of the decision service.

Endpoint to execute the last deployed version of a decision service

The endpoint URI for a decision service that selects decisions based on their last deployment time uses the following format:

POST https://<server>:<port>/ads/runtime/api/v1/selectors/lastDeployedDecisionService/deploymentSpaces/{deploymentSpaceId}/operations/{operation}/extendedExecute?decisionServiceId={decisionServiceId}

The deployment time of a decision service refers to the deploymentTime metadata of the decision service. For more information about the metadata, see Decision service metadata.

For more information about the exact URL patters for calling decision services, see Runtime REST API reference.

<server> is the hostname of the decision runtime, which is specified in the decision_runtime.ingress.hostname parameter.
<port> is the port of the decision runtime.

For more information about the parameters, see IBM Automation Decision Services parameters.

Table 3. Parameters that are used in the endpoint URI
Parameter	Mandatory or Optional	Description
deploymentSpaceId	Mandatory	URL encoded identifier that uniquely identifies the place where a decision was deployed.
operation	Mandatory	Name of the operation. It is used to identify which decision service to execute within the decision service archive. The operation name is decided at authoring time.
decisionServiceId	Mandatory	Query parameter that identifies the decision project from which the decision service archive is built. The decision service ID is decided at authoring time. Its value is that of the `decisionServiceId` metadata of the decision service.

Request body

You can use the decision runtime REST API to call decisions by using the JSON payload.

The request body has the following format:

{
  "executionId": "<value_1>",
  "input": "<value_2>",
  "executionTraceFilters": "<value_3>"
}

Table 4. Parameters that are used in the request body
Parameter	Mandatory or Optional	Description
executionId	Optional	Optional identifier for the execution of the decision service. If this parameter is not set, the decision runtime creates a decision execution identifier that is globally unique.
input	Mandatory	JSON object that represents input data of the decision service. The JSON object can be obtained from the Run part in Decision Designer by editing the JSON data set.
executionTraceFilters	Optional	JSON object that specifies which traces are activated in which format. If this parameter is not set, the execution trace is `null` as a result. For more information about this parameter, see the Schemas section in Runtime REST API reference. Note: If you want to include an exception stack trace in the response payload when an incident occurs, you must set the decisionRuntimeService.stackTraceEnabled parameter to `true` at the time of installing the product. By default, this parameter is set to `false`. For more information about this parameter, see IBM Automation Decision Services parameters.

An example of the request body:

{
  "executionId": "executionId_0001",
  "input": {
    "customer": {
      "name": "Mary",
      "age": 20
    },
    "ageLimit": 21
  },
  "executionTraceFilters": {
    "executionDuration": true,
    "printedMessages": true,
    "decisionModel": {
      "inputParameters": "Object",
      "outputParameters": "Object",
      "inputNode": "Object",
      "outputNode": "Object"
    },
    "rules": {
      "boundObjectsAtStart": "Object",
      "boundObjectsAtEnd": "Object",
      "allRules": true,
      "executedRules": true,
      "nonExecutedRules": true
    },
    "ruleflow": {
      "allTasks": false,
      "executedTasks": false,
      "notExecutedTasks": false,
      "selectedRules": false
    }
  }
}

HTTP return codes and execution results

When your client application calls a decision service, you get an HTTP return code. The response body is formatted in JSON payload.

Table 5. HTTP return codes
HTTP return code	Description
200	The decision execution completed successfully. The output of the decision is returned in the response body.
404	The value of decisionId or operation is invalid. You see the following message in the response body: `"incidentCategory": "Decision not found",`
500	An error occurred while processing the decision execution request. An error message is returned in the response body.

The JSON body of the response has the following format:

{
  "decisionId": "<value_5>",
  "decisionOperation": "<value_6>",
  "executionId": "<value_7>",
  "executionTrace": "<value_8>",
  "output": "<value_9>",
  "incident": {
    "incidentID": "<incident_ID>",
    "incidentCategory": "<error_message>",
    "stackTrace": "<xyzException>:<stack_message>"
  }
}

executionTrace might be null if no execution trace filter is set.
output might be null if the execution is not completed due to an error.
incident is returned only when errors occur.

For more information about the execution trace and the incident, see the Schema section in Runtime REST API reference.

The following example shows a response body with the HTTP return code 200 (the execution was successful):

{
  "decisionId": "decisions/My-Getting-Started/mySalutationDecisionService/1.0.0-SNAPSHOT/mySalutationDecisionService-1.0.0-20200120.153649-11.jar",
  "decisionOperation": "myModel",
  "executionId": "24543a29-ce83-4e20-afbc-93fccf7949d5",
  "executionTrace": null,
  "output": "Good evening Prof. Jones!"
}

The following example shows a response body with the HTTP return code 500 (the execution failed):

{
  "decisionId": "decisions/My-Getting-Started/mySalutationDecisionService/1.0.0-SNAPSHOT/mySalutationDecisionService-1.0.0-20200120.153649-11.jar",
  "decisionOperation": "myModel",
  "executionId": "1f10653a-c21f-4653-854e-c6e56da4bdaf",
  "executionTrace": null,
  "output": null,
  "incident": {
    "incidentId": "edee977a-5d2e-47ca-b31e-4e866649016c",
    "incidentCategory": "Decision error",
    "stackTrace": "com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field \"nme\" (class newtype),  ...  }
}