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 {mdm-regular-product-name} using the API and the user interface must be authenticated and meet one of the following criteria:

  • Have one role with Grant full access to the model 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 item 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

http://<hostName>/semarchy/mdm-app/<modelName>/<applicationName>/mytasks/admin

Specific search results

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

Specific workflow instance view

http://<hostName>/semarchy/mdm-app/<modelName>/<applicationName>/mytasks/admin/<workflowInstanceId>

Specific workflow instance editor with a step

http://<hostName>/semarchy/mdm-app/<modelName>/<applicationName>/mytasks/admin/<workflowInstanceId>/<stepInstanceId>

Workflow instance list

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

Column Description

Workflow

Workflow instance label and identifier.

Description

Description of the workflow instance.

Status

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

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

Priority assigned to the workflow instance. Possible values are:

  • Low

  • Normal

  • High

  • Critical

Workflow ID

Identifier of the workflow instance.

Actions

Administration secion 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 step details section.

Workflow instance editor

Workflow history

This graphical view 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.

Step details

This section displays the details of the selected workflow step. When no step is selected, it is empty.

The following details are displayed for all steps:

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

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

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

Initiator

Name of the user who initiated the workflow.

Description

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.

Assignee

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

Candidate Assignee(s)

Name of the users who can claim this user task.

Transition

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

Branches

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