--- title: Workflows description: Workflow objects are exposed under the /openidm/workflow context path. IDM provides access to the workflow module over REST, as listed in the following table: component: pingidm version: 8.1 page_id: pingidm:rest-api-reference:endpoints/rest-workflows canonical_url: https://docs.pingidentity.com/pingidm/8.1/rest-api-reference/endpoints/rest-workflows.html keywords: ["REST API", "Workflows"] --- # Workflows Workflow objects are exposed under the `/openidm/workflow` context path. IDM provides access to the workflow module over REST, as listed in the following table: | URI | HTTP Operation | Description | | ------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | /openidm/workflow/execution?\_action=message | POST | Invokes a message event. When the `processVariables` field is *non-null* the message is sent synchronously; otherwise, asynchronously. | | /openidm/workflow/execution?\_action=signal | POST | Invokes a signal event. When the `processVariables` field is *non-null* the message is sent synchronously; otherwise, asynchronously. | | /openidm/workflow/execution?\_action=trigger | POST | Triggers an execution asynchronously; for example, to continue a process instance that is waiting at a *Receive Task*. When the `transientVariables` field is *non-null* the trigger is sent synchronously; otherwise, asynchronously. | | /openidm/workflow/execution?\_queryFilter=true | GET | Queries the executions. Only supports `_queryFilter=true`. | | /openidm/workflow/execution?\_queryId=filtered-query\&filter | GET | Returns a list of executions, based on the specified query filter.> **Collapse: Filter Parameters** > > * `executionId` > > * `executionParentId` > > * `processDefinitionCategory` > > * `processDefinitionId` > > * `processDefinitionKey` > > * `processDefinitionName` > > * `processDefinitionVersion` > > * `processInstanceBusinessKey` > > * `processInstanceId` > > * `activityId` > > * `signalName` > > * `messageName` > > * `startedBefore` > > * `startedAfter` > > * `startedBy` > > * `processVariableName` > > * `processVariableValue` > > * `processVariableValueType` > > * `processVariableOperator` > > * `variableName` > > * `variableValue` > > * `variableValueType` > > * `variableOperator` | | /openidm/workflow/job?\_queryFilter=true | GET | Queries jobs. Only supports `_queryFilter=true`. | | /openidm/workflow/job?\_queryId=filtered-query\&filter | GET | Returns a list of jobs, based on the specified query filter. You can't combine `timersOnly=true` with `messagesOnly=true` in the same query.> **Collapse: Filter Parameters** > > * `jobId` > > * `processDefinitionId` > > * `processInstanceId` > > * `executionId` > > * `timersOnly` > > * `messagesOnly` > > * `withException` > > * `exceptionMessage` > > * `dueAfter` > > * `dueBefore` | | /openidm/workflow/job/deadletter?\_queryFilter=true | GET | Queries dead-letter jobs. Only supports `_queryFilter=true`. | | /openidm/workflow/job/deadletter?\_queryId=filtered-query\&filter | GET | Returns a list of dead-letter jobs, based on the specified query filter. You can't combine `timersOnly=true` with `messagesOnly=true` in the same query.> **Collapse: Filter Parameters** > > * `jobId` > > * `processDefinitionId` > > * `processInstanceId` > > * `executionId` > > * `timersOnly` > > * `messagesOnly` > > * `withException` > > * `exceptionMessage` > > * `dueAfter` > > * `dueBefore` | | /openidm/workflow/job/deadletter/id?\_action=execute | POST | Executes a dead-letter job. If successful, runs as a normal job. | | /openidm/workflow/job/deadletter/id?\_action=stacktrace | POST | Displays the stacktrace for a dead-letter job that triggered an exception. | | /openidm/workflow/job/deadletter/id | DELETE | Deletes a dead-letter job. | | /openidm/workflow/job/deadletter/id | GET | Reads a dead-letter job. | | /openidm/workflow/job/id?\_action=execute | POST | Forces the synchronous execution of a job, even if it is suspended. | | /openidm/workflow/job/id?\_action=stacktrace | POST | Displays the stacktrace for a job that triggered an exception. | | /openidm/workflow/job/id | DELETE | Deletes a job. | | /openidm/workflow/job/id | GET | Reads a job. | | /openidm/workflow/model?\_action=validate\_bpmn | POST | Validates a BPMN 2.0 XML file. | | /openidm/workflow/model | POST | Creates a new model. Omitting the `bpmnXML` field generates a template. Also refer to the `deploy` action. | | /openidm/workflow/model?\_queryFilter=query | GET | Queries the existing models. `bpmnXML` and `resourceMap` fields are omitted from results by default. | | openidm/workflow/model/id?\_action=deploy | POST | Deploys a model and creates associated process definitions. Existing process definition IDs will be returned if duplicate model detected. refer to `workflow/processdefinition` endpoints. | | /openidm/workflow/model/id?\_action=list\_deployments | POST | Lists process definition IDs for model deployments. | | /openidm/workflow/model/id | DELETE | Deletes a model. | | /openidm/workflow/model/id | GET | Reads a model. | | /openidm/workflow/model/id | PUT | Updates a model. | | /openidm/workflow/processdefinition?\_queryFilter=true | GET | Queries the process definitions. Only supports `_queryFilter=true`. Use the `READ` endpoint to get form-related fields. | | /openidm/workflow/processdefinition?\_queryId=filtered-query\&filter | GET | Returns a list of workflow process definitions, based on the specified query filter.> **Collapse: Filter Parameters** > > * `version` > > * `deploymentId` > > * `category` > > * `key` > > * `name` > > * `processDefinitionResourceName` | | /openidm/workflow/processdefinition/id | DELETE | Deletes a process definition. | | /openidm/workflow/processdefinition/id | GET | Reads a process definition with form-related fields included. | | /openidm/workflow/processdefinition/procdefid/taskdefinition?\_queryFilter=true | GET | Queries the task definitions. Only supports `_queryFilter=true`. | | /openidm/workflow/processdefinition/procdefid/taskdefinition/id | GET | Reads a task definition. | | /openidm/workflow/processinstance | POST | Creates a process instance. JSON request object must contain either the `_processDefinitionId` or `_key` fields, but not both. Additional JSON fields will be passed to the create-operation and utilized if applicable. | | /openidm/workflow/processinstance?\_queryFilter=true | GET | Queries the process instances. Only supports `_queryFilter=true`. | | /openidm/workflow/processinstance?\_queryId=filtered-query\&filter | GET | Returns a list of workflow process instances, based on the specified query filter.> **Collapse: Filter parameters** > > * `processDefinitionId` > > * `processDefinitionKey` > > * `processInstanceBusinessKey` > > * `processInstanceId` > > * `superProcessInstanceId` > > * `finished` > > * `unfinished` > > * `involvedUserId` > > * `startUserId` > > * `startedAfter` > > * `startedBefore` | | /openidm/workflow/processinstance/history?\_queryFilter=true | GET | Queries the process instance history. Only supports `_queryFilter=true`. | | /openidm/workflow/processinstance/history?\_queryId=filtered-query\&filter | GET | Returns a list of process instance history, based on the specified query filter.> **Collapse: Filter parameters** > > * `processDefinitionId` > > * `processDefinitionKey` > > * `processInstanceBusinessKey` > > * `processInstanceId` > > * `superProcessInstanceId` > > * `finished` > > * `unfinished` > > * `involvedUserId` > > * `startUserId` > > * `startedAfter` > > * `startedBefore` | | /openidm/workflow/processinstance/history/id | DELETE | Deletes process instance history. | | /openidm/workflow/processinstance/history/id | GET | Reads process instance history. `diagram` field returned when defined and requested in `_fields` parameter. | | /openidm/workflow/processinstance/id?\_action=migrate | POST | Migrates a process instance to a different process definition. To simulate the migration first, refer to the action `validateMigration`.> **Collapse: JSON Request Payload Model** > > ```json > { > "processDefinitionId": "string", > "variables": {}, > "fromActivityIdMap": { > "123": { > "toActivityId": "string", > "localVariables": {} > } > } > } > ``` | | /openidm/workflow/processinstance/id?\_action=validateMigration | POST | Simulates a process instance migration (`migrate` action). | | /openidm/workflow/processinstance/id | DELETE | Deletes a process instance. | | /openidm/workflow/processinstance/id | GET | Reads a process instance. `diagram` field returned when defined and requested in `_fields` parameter. | | /openidm/workflow/taskinstance?\_queryFilter=true | GET | Queries the task instances. Only supports `_queryFilter=true`. | | /openidm/workflow/taskinstance?\_queryId=filtered-query\&filter | GET | Returns a list of task instances, based on the specified query filter.> **Collapse: Filter parameters** > > * `executionId` > > * `processDefinitionId` > > * `processDefinitionKey` > > * `processInstanceId` > > * `assignee` > > * `taskCandidateGroup` > > * `taskCandidateUser` > > * `name` > > * `owner` > > * `description` > > * `priority` > > * `unassigned` | | /openidm/workflow/taskinstance?\_queryId=unassignedTaskQuery | GET | Queries unassigned task instances for which the authenticated user is authorized to assign. | | /openidm/workflow/taskinstance/history?\_queryFilter=true | GET | Queries the task instance history. Only supports `_queryFilter=true`. | | /openidm/workflow/taskinstance/history?\_queryId=filtered-query\&filter | GET | Returns a list of task instance history, based on the specified query filter.> **Collapse: Filter parameters** > > * `executionId` > > * `processDefinitionId` > > * `processDefinitionKey` > > * `processInstanceId` > > * `assignee` > > * `taskCandidateGroup` > > * `taskCandidateUser` > > * `taskId` > > * `taskName` > > * `owner` > > * `description` > > * `finished` > > * `unfinished` > > * `processFinished` > > * `processUnfinished` > > * `priority` > > * `deleteReason` | | /openidm/workflow/taskinstance/history/id | GET | Reads a task instance history. | | /openidm/workflow/taskinstance/id?\_action=claim | POST | Assigns a task to a `userId`. | | /openidm/workflow/taskinstance/id?\_action=complete | POST | To complete a task, supply the required task parameters, as specified in the BPMN 2.0 XML file. | | /openidm/workflow/taskinstance/id | DELETE | Deletes a task instance. | | /openidm/workflow/taskinstance/id | GET | Reads a task instance. | | /openidm/workflow/taskinstance/id | PUT | Updates a task instance. Must include one or more *supported* fields in JSON payload:> **Collapse: Supported fields** > > * `assignee` > > * `description` > > * `name` > > * `owner` > > * `category` > > * `dueDate` > > * `priority` | The following examples list the defined workflows. For a workflow to appear in this list, the corresponding workflow definition must be in the `openidm/workflow` directory: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/workflow/processdefinition?_queryId=query-all-ids" ``` Depending on the defined workflows, the output will be something like the following: ``` { "result": [ { "_id": "contractorOnboarding:1:5" }, { "_id": "contractorOnboarding:2:9" } ], "resultCount": 2, "pagedResultsCookie": null, "totalPagedResultsPolicy": "NONE", "totalPagedResults": -1, "remainingPagedResults": -1 } ``` The following example invokes a workflow named "myWorkflow". The `foo` parameter is given the value `bar` in the workflow invocation: ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{ "_key":"contractorOnboarding", "foo":"bar" }' \ "http://localhost:8080/openidm/workflow/processinstance?_action=create" ```