In BAMOE, Management APIs are provided to interact with business Process Definitions and active Process Instances. These APIs allow to obtain metadata information about Process Definitions, as well as provide management endpoints for active Process Instances.

Process Management API

The kie-addons-quarkus-process-management is an extension for BAMOE that enables process management features for business workflows in a Quarkus-based microservice architecture.

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-process-management</artifactId>
</dependency>

With the Process Management API endpoints, it’s possible to operate with the following Entities:

  • Processes (GET, POST, DELETE)

  • ProcessInstance (GET)

  • Node (GET, POST, DELETE)

  • ProcessError (GET)

  • WorkItem (GET)

The following sections describe the Process Management API in detail.

/management/processes

Type GET

Description

This endpoint returns the list of Process Definition names that are deployed in the runtime.

Inputs

Output

A JSON list of Process Definition names that are deployed in the runtime.

  • processName: String

Example

 
curl -X 'GET' \
'http://localhost:8080/management/processes' \
-H 'accept: */*'

/management/processes/{processId}

Type GET

Description

This endpoint returns the complete process information of the specified processId.

Inputs

  • processId: String (PathParameter)

Output

Process instance is returned with following information

  • id : String

  • name : String

  • type : String

  • version : String

  • description : String

  • annotations : List

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}' \
-H 'accept: */*'

/management/processes/{processId}/instances/{processInstanceId}

Type DELETE

Description

It aborts a specific process instance of a given process

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • Response will be returned with the variables details defined for the canceled process instance.

  • ProcessInstanceExecutionException is returned if a process instance cancel operation returns any error.

  • BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
curl -X 'DELETE' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}' \
-H 'accept: */*'

/management/processes/{processId}/instances/{processInstanceId}/error

Type GET

Description

This endpoint returns the error details corresponding to the failed process instance for the given processId

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • Response with the following process details will be returned.

    • processInstanceId: String

    • failedNodeId: String

    • errorMessage: String

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

  • A BAD REQUEST error with message "Process instance with id {processInstanceId} is not in error state" will be returned if no error details are found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/error' \
-H 'accept: */*'

/management/processes/{processId}/instances/{processInstanceId}/migrate

Type POST

Description

It migrates the process instance specified by the processID and processInstanceID to the target process and process instance.

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

  • targetProcessId: String (Query Parameter)

  • targetProcessVersion": String (Query Parameter)

Output

  • Response with the following process details will be returned.

    • processInstanceId: String

    • message: String

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

  • A BAD REQUEST error with error message if any issue occurs while doing the migration.

Example

 
 curl -X 'POST' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/migrate' \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '{
"targetProcessId": "string",
"targetProcessVersion": "string"
}'

/management/processes/{processId}/instances/{processInstanceId}/nodeInstances

Type GET

Description

This endpoint returns the list of workItems in the specified process instance

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • A list of WorkItem present in the specified process and the process instance will be returned.It includes following details

WorkItem:

  • id : String

  • nodeInstanceId : String

  • nodeId: WorkflowElementIdentifier

  • name : String

  • state : int

  • phase : String

  • phaseStatus : String

  • parameters : Map<String, Object>

  • results : Map<String, Object>

  • workItemHandlerName : String

  • externalReferenceId : String

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/nodeInstances' \
-H 'accept: */*'

/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}

Type POST

Description

It will re trigger the nodeInstance mentioned in the NodeInstanceId for the specified process & process instance

Inputs

  • nodeInstanceId : String (PathParameter)

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • Returns the response with variables details in the process instance

  • A ProcessInstanceExecutionException is returned if a process instance retrigger returns any error.

  • A NodeInstanceNotFoundException is returned if the mentioned node instance id is not found.

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'POST' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}' \
-H 'accept: */*' \
-d ''

/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}

Type DELETE

Description

It will cancel the nodeInstance mentioned in the nodeInstanceId of the specified process & process instance

Inputs

  • nodeInstanceId : String (PathParameter)

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • Returns the response with variables details in the process instance

  • A ProcessInstanceExecutionException is returned if a Process Instance returns any error.

  • A NodeInstanceNotFoundException is returned if the mentioned node instance id is not found.

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'DELETE' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}' \
-H 'accept: */*'

/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}/sla

Type PATCH

Description

This endpoint updates the SLA Due Date of the specified node in a process instance

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

  • nodeInstanceId: String (PathParameter)

  • expirationTime: String (JSON payload)

Output

  • The result of the operation as string.

  • A BAD REQUEST error is returned if processId, processInstanceId or nodeInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId, processInstanceId or nodeInstanceId is not found.

Example

 
 curl -X 'PATCH' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}/sla' \
-H 'accept: */*'
-H 'Content-Type: application/json'
-d '{
  "expirationTime": "2025-12-31T00:00:00.000Z"
}'

/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}/timers

Type GET

Description

This endpoint returns the list of active timers associated with the given node instance of the defined process instance

Inputs

  • nodeInstanceId: String (PathParameter)

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • A list of active timers associated with the given node instance of the defined process instance. It includes the following details

  • targetProcessId : String

  • processInstanceId : String

  • nodeInstanceId : String

  • timerId: String

  • description : String

  • A BAD REQUEST error is returned if nodeInstanceId, processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if nodeInstanceId, processId or processInstanceId is not found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/nodeInstances/{nodeInstanceId}/timers' \
-H 'accept: */*'

/management/processes/{processId}/instances/{processInstanceId}/nodes/{nodeId}

Type POST

Description

It will trigger the node for the specified nodeId corresponding to the mentioned process and process instance.

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

  • nodeId : String (PathParameter)

Output

  • Returns the response with variables details of the process instance

  • A ProcessInstanceExecutionException is returned if a Process Instance returns any error.

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'POST' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/nodes/{nodeId}' \
-H 'accept: */*' \
-d ''

/management/processes/{processId}/instances/{processInstanceId}/retrigger

Type POST

Description

It will retrigger instance in error status for the specified process & process instance

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • Returns the response with variables details in the process instance

  • A ProcessInstanceExecutionException is returned if a Process Instance returns any error.

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A BAD REQUEST error is returned if processInstanceId is not in error state.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'POST' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/retrigger' \
-H 'accept: */*' \
-d ''

/management/processes/{processId}/instances/{processInstanceId}/skip

Type POST

Description

It will skip instance in error status corresponding to the mentioned process and process instance

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • Returns the response with variables details in the process instance

  • A ProcessInstanceExecutionException is returned if a Process Instance returns any error.

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A BAD REQUEST error is returned if processInstanceId is not in error state.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'POST' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/skip' \
-H 'accept: */*' \
-d ''

/management/processes/{processId}/instances/{processInstanceId}/sla

Type PATCH

Description

This endpoint updates the SLA Due Date of a process instance

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

  • expirationTime: String (JSON payload)

Output

  • The result of the operation as string.

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'PATCH' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/sla' \
-H 'accept: */*'
-H 'Content-Type: application/json'
-d '{
  "expirationTime": "2025-12-31T00:00:00.000Z"
}'

/management/processes/{processId}/instances/{processInstanceId}/timers

Type GET

Description

This endpoint returns the list of active timers associated with the given process instance

Inputs

  • processId: String (PathParameter)

  • processInstanceId: String (PathParameter)

Output

  • A list of active timers associated with the given process instance. It includes the following details

  • targetProcessId : String

  • processInstanceId : String

  • nodeInstanceId : String

  • timerId: String

  • description : String

  • A BAD REQUEST error is returned if processId or processInstanceId is missing in the request.

  • A NOT FOUND error is returned if processId or processInstanceId is not found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}/instances/{processInstanceId}/timers' \
-H 'accept: */*'

/management/processes/{processId}/migrate

Type POST

Description

It will migrate all active process instances of the processID to the target process

Inputs

  • processId: String (PathParameter)

  • targetProcessId: String (Query Parameter)

  • targetProcessVersion: String (Query Parameter)

Output

Returns the response with details of the migrated instances including:

  • id : String

  • numberOfProcessInstanceMigrated : String

  • A BAD REQUEST error is returned if any error occurred during migration.

Example

 
 curl -X 'POST' \
'http://localhost:8080/management/processes/{processId}/migrate' \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '{
"targetProcessId": "string",
"targetProcessVersion": "string"
}'

/management/processes/{processId}/nodes

Type GET

Description

It will get the process nodes corresponding to the mentioned process

Inputs

  • processId: String (PathParameter)

Output

  • Returns the list of node details corresponding to the process. Below details will be included.

    • id : String

    • uniqueID : String

    • nodeDefinitionId : String

    • metadata : String

    • type : String

    • name : String

  • A BAD REQUEST error is returned if any error occurs.

  • A BAD REQUEST error is returned if processId is missing in the request.

  • A NOT FOUND error is returned if processId is not found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}/nodes' \
-H 'accept: */*'

Callback Jobs Service Management API

In BAMOE, the Callback Jobs Service Management API endpoints are used to manage callbacks into the runtime engine from an external job service. These callbacks allow external systems, such as the job service, to trigger the execution of a TriggerJobCommand. If successful, the process instance linked to this command gets signalled and resumes its execution. This API is provided by the following extension:

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kogito-addons-quarkus-jobs-management</artifactId>
</dependency>
Note
 This API endpoint is not primarily intended for manual invocation.

Job Resource API

In BAMOE, the usage of this API is currently not recommended. To work with Jobs, you can use the Data-Index GraphQL API instead.

Job Resource V2 API

In BAMOE, the usage of this API is currently not recommended. To work with Jobs, you can use the Data-Index GraphQL API instead.

Jobs Service Management Resource API

In BAMOE, this API is currently not used. It might be removed in future versions of the product.

Source File Management API

The Source File Management API endpoints in BAMOE allow users to dynamically retrieve BPMN source files at runtime. This API is provided by the following extension:

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-source-files</artifactId>
</dependency>

With the Source File Management endpoints, it’s possible to operate with the following Entities:

  • SourceFile (GET)

/management/processes/sources

Type GET

Description

It will get source files corresponding to the uri mentioned as the query parameter.

Inputs

  • uri: String (QueryParameter)

Output

  • Returns the source file corresponding to the uri mentioned.

  • A NOT FOUND error is returned if uri is not found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/sources?uri={uri}' \
-H 'accept: */*'

/management/processes/{processId}/source

Type GET

Description

It will get source file corresponding to the process.

Inputs

  • processId : String (PathParameter)

Output

  • Returns the list of SourceFiles corresponding to the process. Below details will be returned.

    • uri : String

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}/source' \
-H 'accept: */*'

/management/processes/{processId}/sources

Type GET

Description

It will get SourceFiles corresponding to the mentioned processId

Inputs

  • processId : String (PathParameter)

Output

  • Returns the list of SourceFiles corresponding to the processId. Below details will be returned.

    • uri : String

Example

 
 curl -X 'GET' \
'http://localhost:8080/management/processes/{processId}/sources' \
-H 'accept: application/json'

Process Svg Resource API

In BAMOE, the Process Svg Resource API endpoints can be used to obtain a graphical representation of a process in SVG format. There are two variants of SVGs, a static one for the Process Definition itself, as well as a dynamic one for an active process instance which also contains information about the process execution. This API is provided by following extension:

<dependency>
  <groupId>org.kie</groupId>
  <artifactId>kie-addons-quarkus-process-svg</artifactId>
</dependency>

/svg/processes/{processId}

Type GET

Description

This endpoint returns the svg file for a Process Definition.

Inputs

  • processId : String (PathParameter)

Output

  • Returns the svg resource for a Process Definition. The content type of the returned data is image/svg+xml.

  • A NOT FOUND error is returned if the processId is not found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/svg/processes/{processId}' \
-H 'accept: */*'

/svg/processes/{processId}/{processInstanceId}

Type GET

Description

This endpoint returns the svg file for a process instance.

Inputs

  • processId : String (PathParameter)

  • processInstanceId : String (PathParameter)

Output

  • Returns the svg resource for a process instance, including markup information of the executed nodes. The content type of the returned data is image/svg+xml.

  • If the processInstanceId is not found, the svg of the Process Definition is returned.

  • A NOT FOUND error is returned if the processId is not found.

Example

 
 curl -X 'GET' \
'http://localhost:8080/svg/processes/{processId}/{processInstanceId}' \
-H 'accept: */*'