Enable workflows

IDM embeds a Flowable Process Engine that starts in the OSGi container. Workflows are not active by default. IDM needs two configuration files to activate the workflow bundle:

workflow.json: The Flowable engine configuration, including the data source.
datasource.jdbc-default.json: The default data source for Flowable.

To enable and manage workflows, edit the configuration files directly, use the REST interface, or use the legacy admin UI.

Configure the workflow data source

The Flowable engine requires a JDBC database. The connection details to the database are specified in the datasource.jdbc-default.json file. If you’re using a JDBC repository for IDM data, you’ll already have a datasource.jdbc-default.json file in your project’s conf/ directory. In this case, when you enable workflows, IDM uses the existing JDBC repository and creates the required Flowable tables in that JDBC repository.

If you’re using a DS repository for IDM data, you must configure a separate JDBC repository as the workflow data source. For more information, refer to Select a repository.

To specify a Flowable data source separate from your existing IDM repository, create a new datasource configuration file in your project’s conf/ directory (for example, datasource.jdbc-flowable.json) with the connection details to the separate data source. Then, reference that file in the useDataSource property of the workflow.json file (for example, "useDataSource" : "flowable").

Learn more about the JDBC Connection Configuration.

Enable workflows manually

The workflow bundle only activates when both files are present. The Flowable engine can’t start without a JDBC data source, so configure the data source before you create workflow.json.

Create workflow.json in your project’s conf/ directory with the following content:

{
    "useDataSource" : "default",
    "workflowDirectory" : "&{idm.instance.dir}/workflow",
    "userResource" : {
        "path" : "managed/user",
        "queryFilter" : "/userName eq \"${username}\""
    },
    "groupResource" : {
        "path" : "managed/group",
        "queryFilter" : "/id eq \"${gid}\""
    }
}

Create the configuration over REST instead

You can create the same configuration object over REST. A PUT request replaces the entire object, so check whether a workflow configuration already exists before you send one:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
"http://localhost:8080/openidm/config/workflow"
{
  "code": 404,
  "reason": "Not Found",
  "message": "Not Found"
}

A 404 Not Found response means no workflow configuration exists yet, so it’s safe to create one. If the request returns a configuration object instead, edit that object and send it back using a PUT request.

To create the configuration:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=1.0" \
--request PUT \
--data '{
    "useDataSource" : "default",
    "workflowDirectory" : "&{idm.instance.dir}/workflow",
    "userResource" : {
        "path" : "managed/user",
        "queryFilter" : "/userName eq \"${username}\""
    },
    "groupResource" : {
        "path" : "managed/group",
        "queryFilter" : "/id eq \"${gid}\""
    }
}' \
"http://localhost:8080/openidm/config/workflow"
{
  "_id": "workflow",
  "useDataSource": "default",
  "workflowDirectory": "&{idm.instance.dir}/workflow",
  "userResource": {
    "path": "managed/user",
    "queryFilter": "/userName eq \"${username}\""
  },
  "groupResource": {
    "path": "managed/group",
    "queryFilter": "/id eq \"${gid}\""
  }
}

IDM writes the object to conf/workflow.json.

(Optional) Configure the workflow engine.

With both workflow.json and a JDBC data source in place, IDM activates the workflow bundle and exposes the workflow/ endpoint.

Enable workflows using the legacy admin UI

Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI.

Both UIs are available as separate downloads from the Backstage download site:

To install the Platform admin UI, follow the steps in Install the Platform admin UI for standalone IDM.
To continue using the legacy admin UI, follow the steps in Install the legacy admin UI.

When you enable workflows in the legacy admin UI, IDM creates workflow.json in your project’s conf/ directory.

Sign on to the legacy admin UI.
From the navigation bar, select Configure > System Preferences.
On the System Preferences page, click the Workflow tab.
Enable the display of workflows, and click Save.
(Optional) Configure the workflow engine.
Configure the workflow data source.

Configure the workflow engine

The default workflow.json file has the following structure:

{
    "useDataSource" : "default",
    "workflowDirectory" : "&{idm.instance.dir}/workflow",
    "userResource": {
        "path": "managed/user",
        "queryFilter": "/userName eq \"${username}\""
    },
    "groupResource": {
        "path": "managed/group",
        "queryFilter": "/id eq \"${gid}\""
    }
}

useDataSource: The data source configuration file that points to the repository where Flowable should store data.

By default, this is the datasource.jdbc-default.json file. For information about changing the data store that Flowable uses, refer to Configure the Workflow Data Source.
workflowDirectory: Specifies the location where IDM expects to find workflow processes. By default, IDM looks for workflow processes in the project-dir/workflow directory.

In addition to these default properties, you can configure the Flowable engine history level:

{
    "history" : "audit"
}

When a workflow is executed, information can be logged as determined by the history level. The history level can be one of the following:

none This level results in the best performance for workflow execution, but no historical information is retained.
activity Logs all process instances and activity instances, without details.
audit This is the default level. All process instances, activity instances, and submitted form properties are logged so that all user interaction through forms is traceable and can be audited.
full This is the highest level of history logging and has the greatest performance impact. This history level stores all the information that is stored for the audit level, as well as any process variable updates.

Configure workflow email

Workflows can send an email using the following methods:

Flowable email tasks

To use workflow email tasks, add the email configuration to workflow.json.

Example email configuration:

"mail" : {
    "host" : "mail.example.com",
    "port" : 1025,
    "username" : "username",
    "password" : "password",
    "useSSL" : false,
    "starttls" : true,
    "defaultFrom" : "workflow@example.com",
    "forceTo" : "overrideSendToEmail@example.com"
}

`scriptTask`

Only JavaScript and Groovy are supported as ScriptTask#scriptFormat languages.

Emails sent using scriptTask use IDM’s email client configuration.

Example script

openidm.action("external/email", "send", { "to": "bob@example.com" }, { waitForCompletion: true });

Custom workflow object mapping

For custom object mapping, edit the default workflow.json configuration:

"userResource": {
    "path": "managed/user",
    "queryFilter": "/userName eq \"${username}\""
},
"groupResource": {
    "path": "managed/group",
    "queryFilter": "/id eq \"${gid}\""
}

Do not replace ${username} or ${gid} in the queryFilter; for example:

OK: "queryFilter": "/callSign eq \"${username}\""
NOT OK: "queryFilter": "/callSign eq \"${callsign}\""

PingIDM