---
title: Enable workflows
description: 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:
component: pingidm
version: 8.1
page_id: pingidm:workflow-guide:enable-workflows
canonical_url: https://docs.pingidentity.com/pingidm/8.1/workflow-guide/enable-workflows.html
keywords: ["Workflows", "Flowable Process Engine", "OSGi", "Configuration", "JDBC", "JavaScript", "Groovy"]
section_ids:
  configure-workflow: Configure the workflow engine
  conf-workflow-email: Configure workflow email
  workflow-datasource: Configure the workflow data source
  workflow-custom-objects: Custom workflow object mapping
---

# 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.

1. Log in to the admin UI.

2. From the navigation bar, select Configure > System Preferences.

3. On the System Preferences page, click the Workflow tab.

4. Enable the display of workflows, and click Save.

5. Optionally, [configure the workflow engine](#configure-workflow).

6. [Configure the workflow data source](#workflow-datasource).

## Configure the workflow engine

IDM creates the default `workflow.json` file with the following structure:

```json
{
    "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](#workflow-datasource).

* `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:

```json
{
    "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:

> **Collapse: Flowable email tasks**
>
> To use [workflow email tasks](https://flowable.com/open-source/docs/bpmn/ch07b-BPMN-Constructs/#email-task), add the email configuration to `workflow.json`.
>
> Example email configuration:
>
> ```json
> "mail" : {
>     "host" : "mail.example.com",
>     "port" : 1025,
>     "username" : "username",
>     "password" : "password",
>     "useSSL" : false,
>     "starttls" : true,
>     "defaultFrom" : "workflow@example.com",
>     "forceTo" : "overrideSendToEmail@example.com"
> }
> ```

> **Collapse: **
>
> Only JavaScript and Groovy are supported as `ScriptTask#scriptFormat` languages.
>
> [Emails sent using `scriptTask`](../external-services-guide/email.html#send-mail-script) utilize [IDM's email client configuration.](../external-services-guide/email.html)
>
> Example script:
>
> ```none
> 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](../install-guide/chap-repository.html). |

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](../objects-guide/repo-config.html#datasource-jdbc-json).

## Custom workflow object mapping

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

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