Workflow administration

This page describes how to administer workflows.

Data-driven workflows, available in Semarchy xDM 2023.1 and later, are subject to specific licensing requirements; please confirm your eligibility to use such new functionality by consulting your license agreement or by contacting your Semarchy account representative prior to use.
All customers can still use the workflow feature available in previous versions (now known as legacy workflows). For more information, see Workflows (legacy).

Authentication and privileges

Applications or users administrating workflows in Semarchy xDM using the API and the user interface must be authenticated and meet one of the following criteria:

  • Have one role with the Grant full access to the model option selected in the model privileges.

  • Have the Workflow Administrator role, as defined in the workflow definition.

  • Be either the initiator of the workflow instance, or a candidate or an assignee of any user task of the workflow instance (applies to workflow administration REST API, for read-only endpoints only—​that is, list or get workflow instances, list or get user task instances).

Workflow administration UI

Access the workflow administration section

The workflow administration section is available from My Tasks, by clicking the Administration vertical tab at the bottom of the editor navigation panel.

This section presents the list of workflow instances. The list can be filtered based on the workflow instance ID and the workflow instance status.

Workflow instance list in Administration section

You can also access the Administration section using the following URLs:

View URL

Administration section with no filter


Specific search results

http://<hostName>/semarchy/mdm-app/<modelName>/<applicationName>/mytasks/admin?search=encoded search criteria

Specific workflow instance view


Specific workflow instance editor with a step


Workflow instance list

The workflow administration section displays the list of workflow instances in a tabular format with the following columns:

Column Description


Label of the workflow definition and identifier of the instance.


Description of the workflow instance.


Status of the workflow instance. Possible values are:

  • Completed: all the steps in the workflow instance have been completed.

  • In progress: the workflow instance is not complete.

  • In progress with errors: the workflow instance is not complete and its current root step has an error.

  • Killed: the workflow instance has been killed.

  • Killed with errors: the workflow instance has been killed and its current root step has an error.


Initiator of the workflow instance.

Current Root Step

Step in progress in the given workflow instance.

Assigned To

Assignee of the step in progress. If the current root step is part of a parallel block, then this column is empty.

Start Date

Start date of the workflow instance.

End Date

End date of the workflow instance.

Due Date

Due date to complete the workflow instance.


Priority assigned to the workflow instance. Possible values are:

  • Low

  • Normal

  • High

  • Critical

Workflow ID

Identifier of the workflow instance.


Administration section action menu

From the Administration section’s Options menu Options menu, you can perform the following actions on the workflow instances:

  • Kill a workflow instance: select the workflow that you want to cancel and select Kill. The step at which the workflow instance was cancelled is represented with the Circle backslash Killed icon.

  • Examine workflow instance details: click any workflow in the list to open its details, or select a workflow and click Details in the action menu. This opens the workflow details view.

  • Customize the column arrangement: click Select columns, then select or deselect items and drag them up or down to rearrange the columns in the table based on what matters most to you.

  • Sort rows in the table view: click Sort rows and select the columns used to sort, as well as their sort order.

Workflow details view

The workflow details view features a workflow history diagram and a workflow details section.

By default, this section shows general information about the workflow instance. To examine a specific step’s details, click on one of the step icons in the diagram. To return to the overall instance details, simply click on a blank space around the diagram.

Workflow details view

Workflow history diagram

This graphical view is titled with the label of the selected workflow, and displays the completed and ongoing step(s) of the workflow instance as a diagram.

Click a step to view its details. The selected step appears with a scaled-up icon.

In the diagram, you can perform the following actions:

  • Back to workflow instance Back to workflow instance: unselect a selected step and return to the workflow instance.

  • Zoom out Zoom out: zoom out of the diagram.

  • Zoom in Zoom in: zoom in on the diagram.

  • Fit to page Fit to page: fit the diagram into the page.

Workflow instance details

This panel displays the details of a workflow instance:

Property Description

Workflow Definition

Label of the workflow definition.

Workflow ID

Identifier of the workflow instance.


Status of the workflow instance (see the list of possible values).

Start Date

Date and time when the workflow instance was initiated.

End Date

Date and time when the workflow instance was completed.

Due Date

Date and time when the workflow is expected to be completed.


The avatar and name (or username) of the user who initiated the instance.


Description of the instance that can be specified in the workflow startup dialog.


Priority of the instance, defined by the initiator in the workflow startup dialog (see the list of possible values).

Step details

This panel is titled with the name of the selected step, and presents the following information:

Property Description

Step Type

Type of step as defined in the workflow.
For more information, see Data-driven workflows.

Step ID

Identifier of the step in the workflow.


Status of the step. Possible values are Initializing, Completed, In Progress, Killed, or In Error.


(Only available if the status of the step is In Error.)
The error message of the step.

Start Date

Date and time when the user started working on the step.

End Date

Date and time when the step was completed.

The following details are displayed for start events:

Property Description


Name of the user who initiated the workflow.


Description added by the initiator when starting the workflow.

The following details are displayed for user tasks:

Property Description

Creation Date

Date and time when the step was created.


Name of the user to whom the step is currently assigned.

Candidate Assignee(s)

Name of the users who can claim this user task.


(Empty if the user task is in progress.)
Name of the transition that followed this task.

The following detail is displayed for routes:

Property Description

Selected Route

Name of the route into which the workflow progressed.

The following details are displayed for parallel blocks:

Property Description

Parallel Block

Name of the parallel block.


Names of the branches in the parallel block.

Depending on the selected step, the following actions may be available:

Action Description

Retry Retry

This action is available for a step in error within a workflow that has not been killed. The administrator can restart the workflow from the failed step.

Refresh Candidates Refresh Candidates

This action is available for unassigned user tasks. The administrator can refresh the list of potential candidates following updates to assignment criteria or changes in user roles or eligibility since the task’s creation.

Release Release

This action is available for assigned user tasks. The administrator can release a task to assign it to another user.

Assign Assign

This action is available for a user task that has been released (i.e., no longer assigned to a user). The administrator can assign the task to another candidate.

Workflow administration REST API

The following API endpoints are available to administer workflows:

  • Workflow Definitions:

    • Start workflow instances.

  • Workflow Instances:

    • List and get workflow instances.

    • Kill a workflow instance.

    • Retry a specific failed step of a workflow instance.

  • User Task Instances:

    • List and get user task instances.

    • Assign a user task.

    • Release a user task.

    • Refresh the list of candidates for a given user task.

For a complete description of each API endpoint, see the REST API documentation.

Workflow data and metadata purge

The purge schedule of workflow metadata and workflow step data depends on the retention policy of a given workflow definition.

By default, workflow metadata and workflow step data are configured to be purged every day at midnight.

To override the default purge schedule, workflow designers can configure the xdm.workflow.purgejobs.cronSchedule property in the startup configuration using cron expressions.


xdm.workflow.purgejobs.cronSchedule = 0 0 0 LW * ? *

This configuration schedules purges on the last weekday of the month at midnight for all data locations.

If you choose to set the startup configuration using Java system properties, make sure to use the appropriate syntax (i.e., single quotes around the cron expression, and no spaces before and after the equal sign). For example, the following parameter will schedule purges in all data locations on the first day of every month at midnight:

-Dxdm.workflow.purgejobs.cronSchedule='0 0 0 1 * ? *'