Process flows API

Indicium's process flow API can be used to manually start a process flow, fetch the pending process action when the execution of the process flow has paused, continue the process flow or cancel the further execution of the process flow. If the first process action of a process flow is a (table) task, a (table) report an add row, an edit row or a delete row action, then the process flow will be started by the corresponding API call, this will trigger the flow automatically.

note

The API and API alias settings in the process flow form in the Software Factory are currently ignored by Indicium. It is not needed to enable these settings to use the process flow API.

1. Starting a process flow

A process flow can be started by sending a POST request without a body to the process flow's endpoint.

Request template

POST
/iam/appl/{process_flow_id}

Request example

POST
/iam/appl/open_document_add_customer

If the request is successful, Indicium will create a process flow resource and depending on the number of starting points of the process flow, Indicium will start the flow immediately or return the created process flow resource.

note

Creating a process flow resource is a synchronous process that can take a long time if the process flow is immediately started as well.

1.1 Single starting point

If the process flow has a single starting point (only one arrow leaving the Start process action), then Indicium will start the process flow immediately upon creating the resource. Depending on whether or not the process flow contains follow-up process actions that require user input, Indicium will respond as follows:

• If the process flow runs to its end without requiring any further input from a client, then Indicium will simply return a 204 No Content.

204 No Content

• If the process flow reaches a process action that requires client input, then Indicium will return a 201 Created together with a Location header that points to the pending process action. The client can continue the process flow by sending a POST request to the continue endpoint of this pending process action.

201 Created
Location: /iam/appl/open_document_add_customer(#)/add_customer

1.2 Multiple starting points

If the process flow has multiple starting points (more than one arrow leaving the Start process action), then Indicium cannot know which one to execute and thus cannot start the process flow immediately upon creating the resource. In this case, Indicium will respond with a Location header that points to the created process flow resource. The client, who made this request, does know which action causes the process flow to start and can append the URL in the Location header with the ID of the process action that is the starting point of the flow and call continue on it.

201 Created
Location: /iam/appl/open_document_add_customer(#)

1.3 API trigger

In addition to manually starting a process flow, a process flow can also be triggered by an API action, like adding a row, deleting a row or executing a task. When an API action that is a starting point of a flow is committed successfully, then the process flow resource will be created automatically and Indicium will start the process flow immediately (so sending a POST request to the process flow's endpoint to create the process flow resource is in this case not needed).

Keep in mind that when a flow has multiple starting points that are API triggers, Indicium does know which of these actions must be executed and the process flow will in this case also be started immediately (so calling continue on the process action is not needed).

Request example

POST
/iam/appl/customer

Response

Depending on whether or not the process flow contains follow-up process actions that require user input, Indicium will respond as follows:

• If the process flow reaches a process action that requires client input, then it will return a PendingProcessAction header that points to the pending process action. The client can continue the process flow by sending a POST request to the continue endpoint of this pending process action.

201 Created
Location: /iam/appl/customer(#)
PendingProcessAction: /iam/appl/add_customer_open_document(#)/open_document

• If the process flow runs to its end without requiring any input from a client, then no PendingProcessAction header will be returned.

201 Created
Location: /iam/appl/customer(#)

2. Fetching the suggestions of the current process action

When an active process flow reaches a process action that requires user input or some type of action to occur in the GUI, then Indicium will pause the process flow and send a Location or PendingProcessAction header that points to the process action that requires input from the client. This allows to fetch the necessary information to perform the client side of the process action before calling the continue endpoint on it to make the process flow resume execution.

note

Fetching the suggestions of the current process action is a synchronous operation which is very fast. Clients can wait for this request synchronously without any issue.

Request template

GET
/iam/appl/{process_flow_id}({id})/{process_action_id}

Request example

GET
/iam/appl/open_document_add_customer(#)/go_to_row_customer

Response

If the currently pending process action is fetched successfully, Indicium will respond with a 200 OK and the response will contain an array with a suggested GUI action that one can choose to follow in order to continue the process flow. A suggestion always contains an action_type which maps to a GUI action, optionally a context parameter that indicates where this action should occur and optionally some input parameters that are relevant to the action (the available input parameters per process action can be found here).

note

When fetching an API action, no input parameters will be returned.

200 OK

{
    "resource_id": #,
    "suggestions": [
        {
            "action_type": "go_to_row",
            "context": {
                "tab_id": "customer"
            },
            "input": {
                "go_to_row_try_filter_row": "row_try_filter_row_on",
                "go_to_row_search_mode": "go_to_row_search_top_down",
                "customer_id": 123
            }
        }
    ]
}

In some cases, Indicium will not return a status code 200 OK:

• If a process action is fetched that is not the pending process action that has caused the process flow to pause, then Indicium will respond with a 303 See Other and the response will contain a Location header that points to the process action that is currently pending.

303 See Other
Location: /iam/appl/open_document_add_customer(#)/open_document_

• If the process flow or the process action does not exist (this can be due to lack of permissions for the user), then Indicium will respond with a 404 Not Found.

404 Not Found

3. Continuing a process flow

When the execution of a process flow has paused because the attention of the GUI is required and the GUI has performed the necessary actions, the process flow can be continued by sending a POST request to the continue endpoint of the process action, providing the output parameters of the process action in the body of the request. The output parameters that can be provided depend on the type of process action, but every process action has at least a status_code output parameter that must be provided by the GUI. The value that the status_code parameter should take in varying situations can be found here.

note

The open_document action for example requires the GUI to supply the current context of the opened document and a document ID, together with the mandatory status_code parameter.

Request template

POST
/iam/appl/{process_flow_id}({id})/{process_action_id}/continue

{
    "{parameter_1}": {value_1},
    "{parameter_2}": {value_2},
    "{parameter_3}": {value_3}
}

Request example

POST
/iam/appl/open_document_add_customer(#)/open_document/continue

{
    "context": "/iam/appl/customer(1)",
    "open_doc_doc_id": 1,
    "status_code": 0
}

note

Continuing a process flow is a synchronous operation that can be quite slow, depending on the process actions in the process flow. In most situations, clients can wait for this request synchronously without any issue, but there are cases in which it can block the user interface for a long time. Since Indicium performs the operation synchronously, it is possible that the request timeout is reached when a process action takes very long.

Response

Depending on whether or not the process flow contains follow-up process actions that require user input, Indicium will respond as follows:

• If the process flow runs to its end without requiring any further input from a client, then Indicium will simply return a 204 No Content.

204 No Content

• If the process flow reaches another process action that requires client input, then Indicium will return a 204 No Content and the response will contain a new Location header that points to this pending process action. The client can continue the process flow again by sending a POST request to the continue endpoint of this pending process action.

204 No Content
Location: /iam/appl/open_document_add_customer(#)/add_customer

In some cases, Indicium will not return a status code 204 No Content:

• If the continue call is made on a process action that is not the pending process action that has caused the process flow to pause, then Indicium will respond with a 303 See Other and the response will contain a Location header that points to the process action that is currently pending.

303 See Other
Location: /iam/appl/open_document_add_customer(#)/add_customer

• If the process flow or the process action does not exist (this can be due to lack of permissions for the user), then Indicium will respond with a 404 Not Found.

404 Not Found

Continuing with an API process action

When the process flow is paused by a (table) task, a (table) report, an add row, an edit row or a delete row process action, then the flow must be continued by providing the ID of the process flow resource as a processFlowResource query string parameter to the corresponding API call. When the request is done successfully, then the process flow will be continued.

Request template

POST
/iam/appl/my_entity?processFlowResource={id}

Request example

POST
/iam/appl/customer?processFlowResource=#

Response

Depending on whether or not the process flow contains follow-up process actions that require user input, Indicium will respond as follows:

• If the process flow reaches another process action that requires client input, then it will return a PendingProcessAction header that points to the pending process action. The client can continue the process flow again by sending a POST request to the continue endpoint of this pending process action.

201 Created
Location: /iam/appl/customer(#)
PendingProcessAction: /iam/appl/add_customer_open_document(#)/open_document

• If the process flow runs to its end without requiring any input from a client, then Indicium will give the regular response to the request without the PendingProcessAction header.

201 Created
Location: /iam/appl/customer(#)

4. Cancelling the execution of a process flow

It is possible to cancel the further execution of an active process flow when the end of the process flow is not yet reached. This can be done by sending a DELETE request on the process flow resource. When the request is successful, Indicium will respond with a 204 No Content and will destroy the process flow resource.

Request template

DELETE
/iam/appl/{process_flow_id}({id})

Request example

DELETE
/iam/appl/open_document_add_customer(#)

Response

204 No Content