15.3. Managing Workflows Over the REST Interface

In addition to the queries described previously, the following examples show the endpoints that are exposed for managing workflows over the REST interface. The example output is based on the sample workflow that is provided in openidm/samples/workflow.

openidm/workflow/processdefinition

List the available workflow definitions, for example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/processdefinition?_queryId=query-all-ids"
 
{
  "result": [
    {
      "name": "Managed User Approval Workflow",
      "_id": "managedUserApproval:1:3"
    }
  ]
}

List the workflows, based on certain filter criteria, for example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/processdefinition?_queryId=
filtered-query&category=Examples"
 
{
  "result": [
    {
      "name": "Managed User Approval Workflow",
      "_id": "managedUserApproval:1:3"
    }
  ]
}
openidm/workflow/processdefinition/{id}

Obtain detailed information for a process definition, based on the ID. (The ID can be determined by querying all available process definitions). For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/processdefinition/contractorOnboarding:1:3"
 
{
  "key": "managedUserApproval",
  "_rev": "0",
  "formProperties": [],
  "category": "Examples",
  "_id": "managedUserApproval:1:3",
  "processDiagramResourceName": null,
  "description": null,
  "name": "Managed User Approval Workflow",
  "deploymentId": "1"
}
openidm/workflow/processinstance

Obtain the list of running workflows (process instances). The query returns a list of IDs. For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/workflow/processinstance?_queryId=query-all-ids"

{
  "result": [
    {
      "processDefinitionId": "contractorOnboarding:1:3",
      "_id": "4"
    }
  ]
}

Obtain the list of running workflows based on specific filter criteria. For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/workflow/processinstance?_queryId=
filtered-query&businessKey=myBusinessKey"

Start a workflow process instance. For example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --data {"_key":"contractorOnboarding"}
 --request POST
 "http://localhost:8080/openidm/workflow/processinstance?_action=createProcessInstance"
openidm/workflow/processinstance/{id}

Obtain the details of the specified process instance. For example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET
 "http://localhost:8080/openidm/workflow/processinstance/4"

{
  "deleteReason": null,
  "processDefinitionId": "contractorOnboarding:1:3",
  "_rev": "0",
  "startTime": "2012-12-18T22:04:50.549+02:00",
  "startUserId": "user1",
  "_id": "4",
  "businessKey": null,
  "durationInMillis": null,
  "endTime": null,
  "superProcessInstanceId": null
}

Stop the specified process instance. For example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request DELETE
 "http://localhost:8080/openidm/workflow/processinstance/4"
openidm/workflow/taskdefinition

Query a task definition based on the process definition ID and the task name (taskDefinitionKey). For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/taskdefinition?_queryId=query-taskdefinition
&processDefinitionId=contractorOnboarding:1:6&taskDefinitionKey=decideApprovalTask"
{
  "dueDate": null,
  "taskCandidateGroup": [
    {
      "expressionText": "manager"
    }
  ],
  "formProperties": [
    {
      "type": {
        "values": {
          "accept": "Accept",
          "reject": "Reject"
...
openidm/workflow/taskinstance

Query all running task instances. For example:

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/taskinstance?_queryId=query-all-ids"
 
{
  "result": [
    {
      "name": "Contractor Approval",
      "_id": "70"
    }
  ]
}

Query task instances based on candidate users or candidate groups. For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/taskinstance?_queryId=filtered-query&taskCandidateUser=manager1"

or

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/taskinstance?_queryId=filtered-query&taskCandidateGroup=management"

Note that you can include both users and groups in the same query.

openidm/workflow/taskinstance/{id}

Obtain detailed information for a running task, based on the task ID. For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request GET       
 "http://localhost:8080/openidm/workflow/taskinstance/70"
 
{
  "dueDate": null,
  "processDefinitionId": "contractorOnboarding:1:3",
  "owner": null,
  "taskDefinitionKey": "decideApprovalTask",
  "name": "Contractor Approval",
...

Update task-related data stored in the Activiti workflow engine. For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --header "If-Match : *"
 --request PUT       
 --data '{"description":"updated description"}'
 "http://localhost:8080/openidm/workflow/taskinstance/70"

Complete the specified task. The variables required by the task are provided in the request body. For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST       
 --data '{"requestApproved":"true"}'
 "http://localhost:8080/openidm/workflow/taskinstance/70?_action=complete"

Claim the specified task. The ID of the user who claims the task is provided in the request body. For example: 

$ curl
 --header "X-OpenIDM-Username: openidm-admin"
 --header "X-OpenIDM-Password: openidm-admin"
 --request POST       
 --data '{"userId":"manager1"}'
 "http://localhost:8080/openidm/workflow/taskinstance/70?_action=claim"