Home > Server > REST API > REST API Endpoints > Workflow and Task Resource Endpoints
Server

Workflow and Task Resource Endpoints

Updated: December 17, 2024

Endpoints

Workflow

Path Endpoint
GET /api/v1/workflow Gets workflow instances launched by current user
GET /api/v1/workflow/{workflowId} Finds workflow instance by its ID
GET /api/v1/workflow/{workflowInstanceId}/graph Gets JSON serialization of workflow instance graph
GET /api/v1/id/{docId}/@workflow Gets workflow instances launched on given document
GET /api/v1/path/{docPath}/@workflow Gets workflow instances launched on given document
POST /api/v1/id/workflow Starts workflow instance
POST /api/v1/id/{docId}/@workflow Starts workflow instance on given document
POST /api/v1/path/{docPath}/@workflow Starts workflow instance on given document
DELETE /api/v1/path/workflow/{workflowInstanceId} Deletes workflow instance by its ID

Task

Path Endpoint
GET /api/v1/task Queries tasks by user and workflow IDs
GET /api/v1/task/{taskId} Gets task by its ID
GET /api/v1/id/{docId}/@task Lists tasks of given document
GET /api/v1/path/{docPath}/@task Lists tasks of given document
PUT /api/v1/task/{taskId}/{action} Completes task
PUT /api/v1/task/{taskId}/reassign Reassigns task
PUT /api/v1/task/{taskId}/delegate Delegates task

Workflow Model

Path Endpoint
GET /api/v1/workflowModel/{modelName} Finds workflow model by name
GET /api/v1/workflowModel/{modelName}/graph Gets JSON serialization of workflow model graph
GET /api/v1/workflowModel Gets workflow models

Task Extended Fields

You can use the following fetch properties to resolve some fields when retrieving tasks:

Fetch Property Description
targetDocumentIds Resolves the document targeted by the task
actors Resolves the actors of a task

Example:

curl -X GET 'http://localhost:8080/nuxeo/api/v1/task?userId={userId}' -H 'X-NXfetch.task: targetDocumentIds,actors' -u user:password

Parallel Review Example

Below is an example of how to start a Parallel Review Workflow and complete it with Nuxeo REST API.

  1. To start a parallel review on a given document, POST to the workflow endpoint or the workflow adapter:

    POST http://NUXEO_SERVER/nuxeo/api/v1/id/{documentId}/@workflow
{
    "entity-type":"workflow",
    "workflowModelName":"ParallelDocumentReview",
    "attachedDocumentIds":["{documentId}"]
}

    A workflow object is returned with the workflowId, which can be used later. Each workflow is composed of a set of tasks which must be completed in order for the workflow to change its state and eventually come to an end.

  2. For each step, retrieve the respective task from the server, either via the task endpoint or task adapter.

    GET http://NUXEO_SERVER/nuxeo/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 then be completed with a PUT request to the task endpoint, the respective action being supplied at the end of the path.

  3. To start the review, use the start_review action in the request.

    PUT http://NUXEO_SERVER/nuxeo/api/v1/task/{taskId}/start_review
{
    "entity-type":"task",
    "id":"{taskId}",
    "variables":{
        "comment":{initial_comment},
        "participants":”{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 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.

  4. The review could be approved via the following request:

    PUT http://NUXEO_SERVER/nuxeo/api/v1/task/{taskId}/approve
{
    "entity-type":"task",
    "id":"{taskId}",
    "comment":"{comment}"
}

    The next task requires the user to Validate or Reject the review, depending on the feedback provided by other participants. Completing this task will bring the workflow to an end.

  5. Validating the review can be done as follows:

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

Learn More

  • Test these endpoints on your local instance with Nuxeo API Playground (see documentation to configure your local instance).
  • Checkout the Nuxeo REST API explorer of your instance at http://NUXEO_SERVER/nuxeo/api/v1/doc.
Related Documentation