PingIDM 7.5.0

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.

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.

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.

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.

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.

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.

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.

JSON Request Payload Model 
{
  "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.

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.

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:

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"