Service (REST API) Endpoint

Each service, once published generates a custom OpenAPI definition of that service based on its own input, outputs and internal characteristics.

Service Execution

The main resource of each service is to execute the service.

This endpoint allows to execute a decision service (DMN) or start a new workflow process (BPMN) or case (CMMN) instance.

Manage running instances

This applies to workflow processes (BPMN) and cases (CMMN) services only

Endpoints to manage running service instances allows to obtain information about currently active instances.

List running service instances

Query the currently running instances using filters.

Parameter Description

tags

Filter based on the tags of an instance. All must match if more than one is given.

name or id

Filter based on the name or identifier of the instance. Support for partial matches (like matches).

Sorting and paging are also supported on this endpoint.

The returned information contains an overview of the services instances currently running including its identifier, name, tags, type, creation date, last update date, state and service identifier information.

Service instance details

Query the detailed state of a service instance given its identifier.

This endpoint returns additional information over the previous endpoint that query and list service instances.

Information Description

resume points

triggers that can be used to resume this service instance with their URLs, types and properties

outputs

the current value of the data marked as output for the service

errors

list of any error messages when the instance is in error state

messages

list of any messages for this instance

children instances

list of sub instances started from this service instance

parent instance identifier

If this is a child instance

Delete a service instance

This endpoint permanently aborts (deletes) the given service instance (by identifier). This has a cascading effect and also deletes any sub instances of this instance.

This operation also deletes any data associated with the service instance

Create or delete a service instance tag

These endpoints allow to manipulate tags associated with a service instance (by identifier). Tags are very useful to be able to effectivaly search for instance and are quite often used with message events via message correlation. These operations allow to add or remove tags dynamically on individual instances.

Retrieve history of service instance

This endpoint retrieves a list of service steps that are currently active, completed as well as the initiator of the service instance (who started it).

Each element of the list of active steps contains the following information:

Information Description

id

the step identifier that can be correlated with the model

instanceId

the unique identifier that represents given step within service instance

name

the step name

type

the type of element that was activated

model name

the name of the model

model id

the identifier of the model

started on

the timestamp when the step was started

Each element of the list of completed steps contains the following information:

Information Description

id

the step identifier that can be correlated with the model

instanceId

the unique identifier that represents given step within service instance

name

the step name

type

the type of element that was activated

model name

the name of the model

model id

the identifier of the model

completed by

the email address of the user that completed this step

completed on

the timestamp when the step was completed

Running service instance data

This applies to workflow processes (BPMN) and cases (CMMN) services only

Managing running service instance data allows to manipulate data associated with the selected instance.

Endpoints exists to:

  • read complete data set

  • read selected data object (by name)

  • update (optionally selected) data set

  • delete selected data object (by name)

Running case instance file

This applies only to case (CMMN) based services

These endpoints are similar to managing running instance data but allow to be more focused on the unstructured aspects of the case instance. It allows to navigate through the case file using path based approach.

Endpoins exists to:

  • read top-level case file items

  • read selected case file item (by path)

  • update selected case file item (by path)

  • delete selected case file item (by path)

Case instances can have both structured (backed by data types) and unstructured data (files and folders). Structured case file items are accessed by their name and returned completely. While unstructured case file items are accessed by their path (place in the hierarchy of the case file) and returns only the metadata of the item.

Example: Case file that consists of a folder named documents and consists of one folder private and two files report.pdf, logo.png can be accessed via following paths

  • /documents/report.pdf

  • /documents/logo.png

  • /documents/private

Manage service instance resume points

This applies to workflow processes (BPMN) and cases (CMMN) services only

When your model uses User Task that are assigned to either groups or individuals, this endpoint allows to modify the original assignments.

Resume point that references a user task can be reassigned in two ways:

  • by delegating to other performers (users or groups) by one of the current performers

  • by reassining to other performers (users or groups) by an admin (does not have to be currrent performer)

Only admin or current performers can reassign user tasks

You can reassign selected resume point by

  • providing users that should be eligible to work on it

  • providing groups that members of should be eligible to work on it

  • unassigning current performers

unassign property of the payload of this endpoint controls if new users are appended to the existing performers (when set to false) or replacing them (when set to true)

Leave users and groups empty to offer selected resume point to anyone within your instance.

Triggering service instance via messages

This applies to workflow process (BPMN) services only

When your model accepts messages through message events (start/intermediate), an endpoint is generated for each message.

Sending data to that endpoint triggers asynchronously the right service instance based on the correlation expressed in the model.

User task search

This applies to workflow processes (BPMN) and cases (CMMN) services only

When working with workflows and cases, there are certain automation patterns that involve human actors. In such scenarios users are usually focused on finding tasks assigned to them regardless of which service a given task belongs to. This responsibility is behind the user task search endpoints that allow human actors to easily find the tasks they are expected to work on.

The approach provided by these endpoints is to allow users to easily narrow down the scope of user tasks they are searching through

  • all tasks across all environments and services

  • tasks across all services in selected environment

  • tasks across all services in selected environment and group

  • tasks across all versions of a selected service in selected group and environment

  • tasks from selected version of selected service in selected group and environment

User task search always applies security filter that is based on task assignees (performers assigned in the modeler). This ensures that only eligible users will see the tasks.

Users can also filter based on task name and id to narrow down the results. This filter is based on like operator meaning it can match partially the task name or id.

In addition, sorting and paging can also be used to post process result set.

Manage service instance nodes

This applies to workflow processes (BPMN) and cases (CMMN) services only

Managing service instances' nodes is considered an administration of the running service instances. This endpoint allows to manipulate running instances in terms of what nodes are active. This allows to perform following operations

  • move active token from one step to another - remove token from one step and put it on another

  • activate selected step - set token on it

  • deactivate selected step - remove token from it

There are no changes to service instance data while activating or deactivating nodes.

In addition to manipulating active service instance, this endpoint also allows to get list of nodes that provide required information to be able to manipulate the nodes

  • unique identifier - used to move token operation

  • name - name of the step

  • type - type of the step e.g. UserTask, Event, etc

Service information

This applies to workflow processes (BPMN) and cases (CMMN) services only

Returns information about models included in the service. Models can be of following types:

  • dmn for decision models

  • bpmn for process models

  • cmmn for case models

In addition to the type, there is also name and unique identifier of the model provided.