LogoLogo
Give FeedbackGovStack Home
23Q4
23Q4
  • Workflow
  • 1 Version History
  • 2 Description
  • 3 Terminology
  • 4 Key Digital Functionalities
  • 5 Cross-Cutting Requirements
  • 6 Functional Requirements
  • 7 Data Structures
  • 8 Service APIs
  • 9 Internal Workflows
  • 10 Other Resources
Powered by GitBook

Copyright © 2024

On this page

Was this helpful?

Export as PDF

8 Service APIs

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

Last updated 1 year ago

Was this helpful?

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 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 .

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).

Get process definition

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.

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

Get the status of an existing process instance

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

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

GovStack non-functional requirements document
this GitHub repository

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

get

Listing of all processes with basic information

Responses
200
list of processes
application/json
404
Processes not found
500
Internal server error, please contact administrator
get
GET /processes HTTP/1.1
Host: 
Accept: */*
{
  "ArrayOfProcesses": {
    "type": "array",
    "example": [
      {
        "id": "ReviewInvoice:1:bf20fe53-5548-11ed-9dd4-0242ac150002",
        "key": "ReviewInvoice",
        "category": "http://bpmn.io/schema/bpmn",
        "version": 1
      },
      {
        "id": "invoice:1:bf2013f1-5548-11ed-9dd4-0242ac150002",
        "key": "invoice",
        "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
        "version": 1
      }
    ]
  }
}

returns detailed information about a process

get

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

Path parameters
processIdstringRequired

The id for a defined process in the workflow engine.

Example: bf20fe53-5548-11ed-9dd4-0242ac150002
Responses
200
process found and representation returned
application/json
404
Process not found
500
Internal server error, please contact administrator
get
GET /processes/{processId} HTTP/1.1
Host: 
Accept: */*
{
  "id": "text",
  "processDefinition": {
    "id": "invoice:1:bf2013f1-5548-11ed-9dd4-0242ac150002",
    "key": "invoice",
    "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
    "version": 1
  }
}

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

get

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

Query parameters
processIdstringOptional

The id for a defined process in the workflow engine.

Example: bf20fe53-5548-11ed-9dd4-0242ac150002
Responses
200
An array of process instances
application/json
404
Process instance not found
500
Internal server error, please contact administrator
get
GET /instances/ HTTP/1.1
Host: 
Accept: */*
{
  "ProcessInstances": {
    "type": "array",
    "example": [
      {
        "id": "020229ae-9fd5-11ed-94af-0242ac150002",
        "processRef": "ReviewInvoice:1:bf20fe53-5548-11ed-9dd4-0242ac150002",
        "initTime": "2023-01-31T08:45:11",
        "lastChangeTime": "2023-05-23T02:34:00",
        "state": "running"
      },
      {
        "id": "ff0f25e2-a792-11ed-b524-0242ac150002",
        "processRef": "invoice:1:bf2013f1-5548-11ed-9dd4-0242ac150002",
        "initTime": "2023-11-08T17:23:00",
        "lastChangeTime": "2023-11-08T17:23:00",
        "state": "suspended"
      }
    ]
  }
}

return execution status details for a single process instance

get

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

Path parameters
instanceIdintegerRequired

Numeric ID of a process instance

Example: 95aef406-3a7a-11e5-85b6-dafa20524153
Responses
200
A detailed process instance status object
application/json
404
Process instance not found
500
Internal server error, please contact administrator
get
GET /instances/{instanceId} HTTP/1.1
Host: 
Accept: */*
{
  "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"
}
  • 8.1 Workflow Processes
  • List processes
  • GETreturns a list of workflow processes i.e., definitions of process
  • Get process definition
  • GETreturns detailed information about a process
  • Instantiate (start) a process instance
  • POSTinstantiates a process execution; creates a process instance
  • 8.2 Workflow Instances
  • List process instances
  • GETreturns a list of process instances; can be constrained by processId to get instances of specific process type
  • Get the status of an existing process instance
  • GETreturn execution status details for a single process instance
  • Stop a running process instance
  • Service APIs List

instantiates a process execution; creates a process instance

post

Create a process instance and register it with the execution engine

Path parameters
processIdstringRequired

The id for a defined process in the workflow engine.

Example: bf20fe53-5548-11ed-9dd4-0242ac150002
Body
processStartedBystringRequired
Responses
201
Process started; registered for execution with unique process instance ID.
application/json
404
Process not found
500
Internal server error, please contact administrator
post
POST /processes/{processId}/start HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 102

{
  "processStartedBy": "text",
  "InstanceValues": [
    [
      {
        "creditor": "Niall",
        "amount": 100,
        "invoiceNumber": 123
      }
    ]
  ]
}
{
  "id": "95aef406-3a7a-11e5-85b6-dafa20524153",
  "processRef": "invoice:1:15e97a1c-312d-11e5-aca3-a0e120524153",
  "suspended": false,
  "ended": false,
  "state": "running"
}