8 Service APIs

This section provides a reference for APIs that should be implemented by this Building Block.

This section provides a reference for APIs that should be implemented by this Building Block. The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.

The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here.

All APIs will be defined using the OpenAPI (Swagger) standard. The API definitions will be hosted outside of this document. This section may provide a brief description of the required APIs. This section will primarily contain links to the GitHub repository for OpenAPI definition (YAML) files as well as to a website hosted by GovStack that provides a live API documentation portal.

This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.

The tests for the Workflow Building Block can be found in this GitHub repository.

8.1 Workflow Processes

List processes

• Retrieves the list of workflow processes deployed on the workflow engine.

• Provides for each process the information: definition ID, version, status (active/suspended).

returns a list of workflow processes i.e., definitions of process

Listing of all processes with basic information

GET/processes

Response

200404500

list of processes

Body

application/json

idstring

generated by a system surrogate primary key

processDefinitionProcessDefinition (object)

Request

JavaScriptCurlPython

const response = await fetch('/processes', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "id": "text",
    "processDefinition": {
      "id": "invoice:1:bf2013f1-5548-11ed-9dd4-0242ac150002",
      "key": "invoice",
      "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
      "version": 1
    }
  }
]

Get process definition

returns detailed information about a process

Pass in the ID of the process and it will return all information about that process

GET/processes/{processId}

Path parameters

processId*string

The id for a defined process in the workflow engine.

Example: "bf20fe53-5548-11ed-9dd4-0242ac150002"

Response

200404500

process found and representation returned

Body

application/json

idstring

generated by a system surrogate primary key

processDefinitionProcessDefinition (object)

Request

JavaScriptCurlPython

const response = await fetch('/processes/{processId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "text",
  "processDefinition": {
    "id": "invoice:1:bf2013f1-5548-11ed-9dd4-0242ac150002",
    "key": "invoice",
    "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
    "version": 1
  }
}

Instantiate (start) a process instance

• Instantiates a given process definition Id. Responds with instance Universal Unique Identifier.

• Process variables (just a PAYLOAD object - process, should be able to extract from the payload JSON object attributes) may be supplied in the request body.

• If the start event has mandatory variables, the workflow engine will perform backend validation.

instantiates a process execution; creates a process instance

Create a process instance and register it with the execution engine

POST/processes/{processId}/start

Path parameters

processId*string

The id for a defined process in the workflow engine.

Example: "bf20fe53-5548-11ed-9dd4-0242ac150002"

Body

application/json

Process instance initiation payload (initial 'state' for the process)

processStartedBy*string

InstanceValuesListOfProperties (array of object)

Response

201404500

Process started; registered for execution with unique process instance ID.

Body

application/json

idstring

The unique process instance ID.

Example: "95aef406-3a7a-11e5-85b6-dafa20524153"

processRefstring

The process definition ID.

Example: "invoice:1:15e97a1c-312d-11e5-aca3-a0e120524153"

suspendedboolean

States if process instance is suspended

Example: false

endedboolean

States if process instance has ended

Example: false

statestring

Provides the execution state of the process instance

Example: "running"

Request

JavaScriptCurlPython

const response = await fetch('/processes/{processId}/start', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "processStartedBy": "text"
    }),
});
const data = await response.json();

Response

201

{
  "id": "95aef406-3a7a-11e5-85b6-dafa20524153",
  "processRef": "invoice:1:15e97a1c-312d-11e5-aca3-a0e120524153",
  "suspended": false,
  "ended": false,
  "state": "running"
}

8.2 Workflow Instances

List process instances

• Retrieves the list of running process instances for a given workflow process definition ID.

• Get Instances workflow process by ID (GET) /instances?processId=123

returns a list of process instances; can be constrained by processId to get instances of specific process type

Optionally include a processId in the query params to filter by that process

GET/instances/

Query parameters

Response

200404500

An array of process instances

Body

application/json

idinteger

generated by a system surrogate primary key

Example: "020229ae-9fd5-11ed-94af-0242ac150002"

processRefstring

reference to the process definition

Example: "ReviewInvoice:1:bf20fe53-5548-11ed-9dd4-0242ac150002"

initTimestring

Initiation Timestamp

Example: "2023-11-08T17:23:00"

statestring

see BPMN specification v.2.0 section 13.2.2

Example: "running"

lastChangeTimestring

last change Timestamp

Example: "2023-11-08T17:23:00"

Request

JavaScriptCurlPython

const response = await fetch('/instances/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

[
  {
    "id": "020229ae-9fd5-11ed-94af-0242ac150002",
    "processRef": "ReviewInvoice:1:bf20fe53-5548-11ed-9dd4-0242ac150002",
    "initTime": "2023-11-08T17:23:00",
    "state": "running",
    "lastChangeTime": "2023-11-08T17:23:00"
  }
]

Get the status of an existing process instance

• Retrieves the status of a single process instance given an instance ID.

return execution status details for a single process instance

By passing in the process instance ID, get full details on its execution, including server logs emitted.

GET/instances/{instanceId}

Path parameters

instanceId*integer

Numeric ID of a process instance

Example: "95aef406-3a7a-11e5-85b6-dafa20524153"

Response

200404500

A detailed process instance status object

Body

application/json

idinteger

generated by a system surrogate primary key

Example: "020229ae-9fd5-11ed-94af-0242ac150002"

processRefstring

reference to the process definition

Example: "ReviewInvoice:1:bf20fe53-5548-11ed-9dd4-0242ac150002"

initTimestring

Initiation Timestamp

Example: "2023-11-08T17:23:00"

statestring

see BPMN specification v.2.0 section 13.2.2

Example: "running"

lastChangeTimestring

last change Timestamp

Example: "2023-11-08T17:23:00"

Request

JavaScriptCurlPython

const response = await fetch('/instances/{instanceId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "id": "020229ae-9fd5-11ed-94af-0242ac150002",
  "processRef": "ReviewInvoice:1:bf20fe53-5548-11ed-9dd4-0242ac150002",
  "initTime": "2023-11-08T17:23:00",
  "state": "running",
  "lastChangeTime": "2023-11-08T17:23:00"
}

Stop a running process instance

• Stops execution of a running process instance

Service APIs List

1. List processes. (GET) /processes

   • Retrieves the list of workflow processes deployed on the workflow engine.

   • Provides for each process the information: definition ID, version, status (active/suspended).

2. Get individual process definition. (GET) /processes/{processId}

3. Instantiate a process instance. (POST) /processes/{processId}/start

   • Instantiates a given process definition Id. Responds with instance Universal Unique Identifier.

   • Process variables (just a PAYLOAD object - process, should be able to extract from the payload JSON object attributes) may be supplied in the request body.

   • If the start event has mandatory variables, the workflow engine will perform backend validation.

4. List process instances. (GET) /instances

   • Retrieves the list of running process instances for a given workflow process definition ID.

   • Get Instances workflow process by ID (GET) /instances?processId=123

5. Get the status of an existing process instance by instance ID. (GET) /instances/{instanceId}

   • Retrieves the status of a single process instance given an instance ID.

6. Stop a process instance (POST) /processes/{processId}/stop

   • Stops a running processs instance