Workflow APIs

We list here all the useful available workflow APIs if you want to programmatically change a workflow instance.

Java API

You can read the javadoc of the workflow engine main services:

The DocumentRouting Service
The Task Service

Note that most of the time provided Automation operations will do what you want to do and are easier to use.

Automation

The framework provides a few interesting Automation operation, in the category "Workflow Context".

Start Workflow: Starts a workflow with the given id and to initialize its workflow variable. The document id of the created workflow instance is available under the workflowInstanceId context variable. The id parameter is the id of the workflow definition, as it was configured in Studio.
Cancel Workflow: Cancels a workflow giving its id. The id parameter is the id of the document representing the workflow instance.
Resume Workflow: Allows to resume a node of the workflow. It probably was suspended waiting for a task to be solved. This operation allows to force the resuming, and will let the task in a "cancelled" state.
Complete task: Allows to close a task as if it was done via the user interface, with the ability to pass some data, as if it came from a form.
Set Workflow Variable: Allows to set workflow variables, either from within the execution of a workflow automation chain (input, output, transition) or externally, provided the workflow instance id.
Set Node Variable: Allows to set node variables within the execution of a workflow automation chain (input, output, transition).

REST API

Since 7.2, the framework provides a new REST API to initiate and run worflows. Endpoints documentation is available on:

the API Playground (see this documentation to add the needed contribution to be able to browse your local instance)
the REST API explorer of your instance at http://NUXEO_SERVER/nuxeo/api/v1/doc

A client sample nuxeo-travel-expenses (available on GitHub) based on Web Components and Polymer framework demonstrates how to use the workflow REST API.

Parallel Review Example

Below follows an example of how to start a Parallel Review Workflow and complete it via the REST API.

To start a parallel review on a given document, post to the workflow endpoint or the workflow adapter:
```
POST /api/v1/id/{documentId}/@workflow
{
    "entity-type":"workflow",
    "workflowModelName":"ParallelDocumentReview",
    "attachedDocumentIds":["{documentId}"]
}
```
A workflow object is returned with the workflowId, which will be used henceforth. Each workflow comprises a set of tasks, which must be completed in order for the workflow to change its state and eventually come to an end.
For each step, retrieve the respective task from the server, either via the task endpoint or task adapter.
```
GET /api/v1/id/{documentId}/@task?userId={userId}&workflowInstanceId={workflowId}&workflowModelName=ParallelDocumentReview
```
A task object is returned, with the respective taskId. In our case, the first step would return a Choose Participants task, where the user that started the workflow must choose the participants involved in the review. The task can than be completed via a PUT request to the task endpoint, with the respective action being supplied at the end of the path.
To start the review, use the start_review action in the request.
```
PUT /api/v1/task/{taskId}/start_review
{
    "entity-type":"task",
    "id":"{taskId}",
    "variables":{
        "comment":{initial_comment},
        "participants":"{userIds}",
        "assignees":"{userIds}",
        "end_date":"{end_date}"
    }
}
```
Here, the initial_comment, userIds, and end_date variables must be supplied by the user, and userIds must be a string encoding an array containing the ids of the participants. Supposing that only John was selected for the review, userIds would be represented as "[\"John\"]". The next task prompts the user to Approve, Reject or take No Action (N/A) in the review, and optionally leave a comment.
The review could be approved via the following request:
```
PUT /api/v1/task/{taskId}/approve
{
    "entity-type":"task",
    "id":"{tasId}",
    "comment":"{comment}"
}
```
The next task requires the user to Validate or Reject the review, in the light of the feedback provided by other participants. Completing this task will bring the workflow to an end.

Validating the review can be done as follows:

PUT /api/v1/task/{taskId}/validate
{
    "entity-type":"task",
    "id":"{taskId}",
    "comment":"{comment}"
}