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 specifies the configuration of the Flowable engine, including the data source that the engine will use.
datasource.jdbc-default.json the default data source for Flowable.

To enable workflows:

When you enable workflows in the Admin UI, IDM creates the workflow.json file 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

Specifies 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, see "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

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.

Important

If you are using a DS repository for IDM data, you must configure a separate JDBC repository as the workflow datasource. For more information, see Select a Repository.

To specify that Flowable should use a data source that is separate from your existing IDM JDBC 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, see "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}\""
}

Note

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

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