Skip to content

Operate APIs

Introduction

Operate API is a REST API and provides searching, getting, and changing Operate data. Requests and responses are in JSON notation.

API documentation as Swagger

A detailed API description is also available as Swagger UI. Refer here to get the reference of Swagger UI.

Host URL for Optima Gateway environments will be as given below:

Environment {host-url}
Dev optima-dev.optumrx.com
Stage optima-stage.optumrx.com
Prod optima-prod.optumrx.com

Endpoints

Search Process Definitions

This API is used to search all the process definitions. (Note: Process Definition Key is unique to a particular BPMN model. Also, for the same BPMN model with different versions will have different process definition key.)

POST - https://{host-url}/gateway/operate/process-definitions/search

Request Body: 

{
  "filter": { object fields to match },
  "size": <number of items to return>, (required)
  "sort": [ {"field":"<name of field to sort on>", "order": "<ASC|DESC>" ], 
  "searchAfter": [ <identifier of item from which next search should start> ]
}

Response: 

{
  "items": [ { item 1 } , { item 2 } ... ],
  "total": <number of found items>,
  "sortValues": [<array of values to retrieve next page of results>]
}

Get Process Definition

This API is used to get a particular process definition by processDefinitionKey.

GET - https://{host-url}/gateway/operate/process-definitions/{key}

Response: 

{
 "key":             <number>
 "name":            <string>
 "version":         <number>
 "bpmnProcessId":   <string>
}

Get Process Definition as XML

This API is used to get the XML format of the process definition/BPMN model. This XML content can be saved as .bpmn file and be able to view the model in Camunda Modeler.

GET - https://{host-url}/gateway/operate/process-definitions/{key}/xml

Response: 

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions>
    ...
</bpmn:definitions>

Search Process Instances

This API is used to search all the process instances.

POST - https://{host-url}/gateway/operate/process-instances/search

Request Body: 

{
  "filter": { object fields to match },
  "size": <number of items to return>, (required)
  "sort": [ {"field":"<name of field to sort on>", "order": "<ASC|DESC>" ], 
  "searchAfter": [ <identifier of item from which next search should start> ]
}

Response: 

{
  "items": [ { item 1 } , { item 2 } ... ],
  "total": <number of found items>,
  "sortValues": [<array of values to retrieve next page of results>]
}

Get Process Instance

This API is used to get a particular process instance by processInstanceKey.

GET - https://{host-url}/gateway/operate/process-instances/{key}

Response: 

{
 "key":                     <number>
 "processVersion":          <number>
 "bpmnProcessId":           <string>
 "parentKey":               <number>
 "startDate":               <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
 "endDate":                 <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
 "state":                   <string>
 "processDefinitionKey":    <number>
}

Delete Process Instance

This API is used to delete an existing process instance by processInstanceKey.

DELETE - https://{host-url}/gateway/operate/process-instances/{key}

Response: 

{
 "message": <string> - What was changed
 "deleted": <number> - How many items were deleted
}

Get FlowNode Statistics

This API is used to get the flownode statistics of a particular process instance by processInstanceKey.

GET - https://{host-url}/gateway/operate/process-instances/{key}/statistics

Response: 

[
  {
    "activityId": <string>,
    "active": <number>,
    "canceled": <number>,
    "incidents": <number>,
    "completed": <number>
  },
  {
    "activityId": <string>,
    "active": <number>,
    "canceled": <number>,
    "incidents": <number>,
    "completed": <number>
  },
  ....
]

Get Sequence Flows

This API is used to get the sequence flows of a particular process instance by processInstanceKey.

GET - https://{host-url}/gateway/operate/process-instances/{key}/sequence-flows

Response: 

[<string>, ....]

Get Core Statistics

This API is used to get the core statistics of overall Operate module.

GET - https://{host-url}/gateway/operate/operate/process-instances/core-statistics

Response: 

{
  "running": 0,
  "active": 0,
  "withIncidents": 0
}

Search FlowNode Instances

POST - https://{host-url}/gateway/operate/flownode-instances/search

Request Body: 

{
  "filter": { object fields to match },
  "size": <number of items to return>, (required)
  "sort": [ {"field":"<name of field to sort on>", "order": "<ASC|DESC>" ], 
  "searchAfter": [ <identifier of item from which next search should start> ]
}

Response: 

{
  "items": [ { item 1 } , { item 2 } ... ],
  "total": <number of found items>,
  "sortValues": [<array of values to retrieve next page of results>]
}

Get FlowNode Instance

GET - https://{host-url}/gateway/operate/flownode-instances/{key}

Response: 

{
 "key":                     <number>
 "processInstanceKey":      <number>
 "processDefinitionKey":    <number>
 "startDate":               <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
 "endDate":                 <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
 "flowNodeId":              <string>
 "flowNodeName":            <string>
 "incidentKey":             <number>
 "type":                    <string>
 "state":                   <string>
 "incident":                <boolean>
}

Search Incidents

POST - https://{host-url}/gateway/operate/incidents/search

Request Body: 

{
  "filter": { object fields to match },
  "size": <number of items to return>, (required)
  "sort": [ {"field":"<name of field to sort on>", "order": "<ASC|DESC>" ], 
  "searchAfter": [ <identifier of item from which next search should start> ]
}

Response: 

{
  "items": [ { item 1 } , { item 2 } ... ],
  "total": <number of found items>,
  "sortValues": [<array of values to retrieve next page of results>]
}

Get Incident

GET - https://{host-url}/gateway/operate/incidents/{key}

Response: 

{
 "key":                     <number>
 "processDefinitionKey":    <number>
 "processInstanceKey":      <number>
 "type":                    <string>
 "message":                 <string>
 "creationTime":            <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>
 "state":                   <string>
}

Search Variables

POST - https://{host-url}/gateway/operate/variables/search

Request Body: 

{
  "filter": { object fields to match },
  "size": <number of items to return>, (required)
  "sort": [ {"field":"<name of field to sort on>", "order": "<ASC|DESC>" ], 
  "searchAfter": [ <identifier of item from which next search should start> ]
}

Response: 

{
  "items": [ { item 1 } , { item 2 } ... ],
  "total": <number of found items>,
  "sortValues": [<array of values to retrieve next page of results>]
}

Get Variable

GET - https://{host-url}/gateway/operate/variables/{key}

Response: 

{
 "key":                 <number>
 "processInstanceKey":  <number>
 "scopeKey":            <number>
 "name":                <string>
 "value":               <string> - Always truncated if value is too big in "search" results. In "get object" result it is not truncated.
 "truncated":           <boolean> - If true 'value' is truncated.
}

Search Decision Instances

POST - https://{host-url}/gateway/operate/decision-instances/search

Request Body: 

{
  "query": {
    "evaluated": true,
    "failed": true
  }
}

Response: 

{
  "decisionInstances": [
    {
      "id": <string>,
      "state": <string>,
      "decisionName": <string>,
      "decisionVersion": <number>,
      "evaluationDate": <dateString: yyyy-MM-dd'T'HH:mm:ss.SSSZZ>,
      "processInstanceId": <string>,
      "sortValues": []
    },
    ...
  ],
  "totalCount": <number>
}

Search Query

Every object has a search //search endpoint which can be requested by POST and a given query request.

Query

The query request consists of components for filter, size, sort, and pagination. 

{
   "filter": { object fields to match },
   "size": <number of items to return>,
   "sort": [ {"field":"<name of field to sort on>", "order": "<ASC|DESC>" ],
   "searchAfter": [ <identifier of item from which next search should start> ]
}

Filter

Specifies which fields should match. Only items that match the given fields will be returned. Example: 

{ "filter": { "processInstanceKey": 235 } }

Size

Maximum items that should be returned and must be a number. Example: 

{ "size": 23 }

Sort

Specify which field of the object should be sorted and whether ascending (ASC) or descending (DESC). Example: 

{ "sort": [{ "field": "name", "order": "DESC" }] }

Pagination

Specify the item where the next search should start. For this, you need the values from previous results. Copy the values from sortValues field from the previous results into the searchAfter value of query. Example: 

{
  "sort": [{ "field": "name", "order": "DESC" }],
  "searchAfter": ["the-name", 12345]
}

Combined query

The query components filter, size, sort, and searchAfter can be combined. Example:

Request Body: 

{
  "filter": {
    "processVersion": 2
  },
  "size": 50,
  "sort": [
    {
      "field": "bpmnProcessId",
      "order": "ASC"
    }
  ]
}

Response: 

  ...
  {
      "key": 2251799813699162,
      "processVersion": 2,
      "bpmnProcessId": "called-process",
      "startDate": "2022-03-17T11:53:41.581+0000",
      "state": "ACTIVE",
      "processDefinitionKey": 2251799813695996
    }
  ],
  "sortValues": [
    "called-process",
    2251799813699162
  ],
  "total": 654
}

Take the value of sortValues and copy it to searchAfter for the next 50 items:

Request Body: 

{
  "filter": {
    "processVersion": 2
  },
  "size": 50,
  "sort": [
    {
      "field": "bpmnProcessId",
      "order": "ASC"
    }
  ],
  "searchAfter": ["called-process", 2251799813699162]
}

Search Results

The API responds with a Results object. It contains an items array, total amount of found items, and sortValues for pagination. 

{
  "items": [ { item 1 } , { item 2 } ... ],
  "total": <number of found items>,
  "sortValues": [<array of values to retrieve next page of results>]
}

Items

An array of objects that matches the query.

Total

The total amount of found objects. This is an exact value until 10,000.

SortValues (Pagination)

Use the value (an array) of this field to get the next page of results in your next query. Copy the value to searchAfter in your next query to get the next page.

Example

{
  "items": [
    {
      "key": 2251799813699213,
      "processVersion": 2,
      "bpmnProcessId": "called-process",
      "startDate": "2022-03-17T11:53:41.758+0000",
      "state": "ACTIVE",
      "processDefinitionKey": 2251799813695996
    },
    {
      "key": 2251799813699262,
      "processVersion": 2,
      "bpmnProcessId": "called-process",
      "startDate": "2022-03-17T11:53:41.853+0000",
      "state": "ACTIVE",
      "processDefinitionKey": 2251799813695996
    }
  ],
  "sortValues": ["called-process", 2251799813699262],
  "total": 654
}