--- title: Enable workflows description: Enable the PingIDM Flowable workflow engine by adding workflow.json and datasource.jdbc-default.json to your project configuration 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 llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Workflows", "Flowable Process Engine", "OSGi", "Configuration", "JDBC", "JavaScript", "Groovy"] section_ids: workflow-datasource: Configure the workflow data source enable-workflows-manually: Enable workflows manually enable-workflows-legacy-ui: Enable workflows using the legacy admin UI configure-workflow: Configure the workflow engine conf-workflow-email: Configure workflow email flowable_email_tasks: Flowable email tasks scripttask: scriptTask 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. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | To [enable](enable-workflows.html) and manage workflows, edit the configuration files directly, use the REST interface, or use the [legacy admin UI](../setup-guide/legacy-admin-ui.html). | ## 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](../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"`). Learn more about the [JDBC Connection Configuration](../objects-guide/repo-config.html#datasource-jdbc-json). ## 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`. 1. Create `workflow.json` in your project's `conf/` directory with the following content: ```json { "useDataSource" : "default", "workflowDirectory" : "&{idm.instance.dir}/workflow", "userResource" : { "path" : "managed/user", "queryFilter" : "/userName eq \"${username}\"" }, "groupResource" : { "path" : "managed/group", "queryFilter" : "/id eq \"${gid}\"" } } ``` > **Collapse: 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`. 2. (Optional) [Configure the workflow engine](#configure-workflow). 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](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.pingidentity.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | When you enable workflows in the legacy admin UI, IDM creates `workflow.json` in your project's `conf/` directory. 1. Sign on to the legacy 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. (Optional) [Configure the workflow engine](#configure-workflow). 6. [Configure the workflow data source](#workflow-datasource). ## Configure the workflow engine The default `workflow.json` file has 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 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](#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: #### 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" } ``` #### `scriptTask` Only JavaScript and Groovy are supported as `ScriptTask#scriptFormat` languages. [Emails sent using `scriptTask`](../external-services-guide/email-send.html#send-mail-script) use [IDM's email client configuration](../external-services-guide/email.html). Example script ```none 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: ```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}\""` |