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.

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

Log in to the 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.
Optionally, configure the workflow engine.
Configure the workflow data source.

Configure the workflow engine

IDM creates the default workflow.json file with 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 datasource 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 utilize IDM’s email client configuration.

Example script:

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

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 are using a JDBC repository for IDM data, you will 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 are using a DS repository for IDM data, you must configure a separate JDBC repository as the workflow datasource. 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").

For more information about the fields in this file, refer to JDBC Connection Configuration.

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}\""

IDM 7.4.1

Enable workflows

Configure the workflow engine

Configure workflow email

Configure the workflow data source

Custom workflow object mapping