Invoke Workflows

You can invoke workflows and business processes from any trigger point within IDM, including reacting to situations discovered during reconciliation. Workflows can be invoked from script files, using the openidm.create() function, or directly from the REST interface.

The following sample script extract shows how to invoke a workflow from a script file:

/*
 * Calling 'myWorkflow' workflow
 */

var params = {
  "_key": "myWorkflow"
};

openidm.create('workflow/processinstance', null, params);

The null in this example indicates that you do not want to specify an ID as part of the create call. For more information, see openidm.create(resourceName, newResourceId, content, params, fields).

You can invoke the same workflow from the REST interface with the following REST call:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{"_key":"myWorkflow"}' \
"http://localhost:8080/openidm/workflow/processinstance?_action=create"

For more information, see "Workflows".

There are two ways in which you can specify the workflow definition that is used when a new workflow instance is started.

_key specifies the id attribute of the workflow process definition, for example:
```
<process id="sendNotificationProcess" name="Send Notification Process">
```
If there is more than one workflow definition with the same _key parameter, the latest deployed version of the workflow definition is invoked.
_processDefinitionId specifies the ID that is generated by the Flowable Process Engine when a workflow definition is deployed; for example:
```
"sendNotificationProcess:1:104";
```
To obtain the processDefinitionId, query the available workflows, for example:
```
{
  "result": [
    {
      "name": "Process Start Auto Generated Task Auto Generated",
      "_id": "ProcessSAGTAG:1:728"
    },
    {
      "name": "Process Start Auto Generated Task Empty",
      "_id": "ProcessSAGTE:1:725"
    },
    ...
  ]
}
```
If you specify a _key and a _processDefinitionId, the _processDefinitionId is used because it is more precise.

Use the optional _businessKey parameter to add specific business logic information to the workflow when it is invoked. For example, the following workflow invocation assigns the workflow a business key of "newOrder". This business key can later be used to query "newOrder" processes.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
--data '{"_key":"myWorkflow", "_businessKey":"newOrder"}' \
"http://localhost:8080/openidm/workflow/processinstance?_action=create"

Access to workflows is based on IDM roles, and is configured in your project's conf/process-access.json file. For more information, see "Secure Access to Workflows".