Defining Workflows
A Workflow Definition is composed of a set of Statuses and Transitions that a data record moves through during data remediation, and typically represents data remediation team work processes.
For Data Refinery Workbench, a Workflow Definition is designed to provide a framework that ensures the correct User Groups can work on data as it is permitted by an Administrator who can define and enforce those steps. This creates a Workflow process that regulates data changes by creating snapshots of data for review before being saved. Workflow Definitions are meant to guarantee quality by having a process to update, review, and approve data.
In order to manage Workflow Definitions, a user must work with Data Refinery Workbench APIs. This page will explain how to use Data Refinery Workbench APIs to get, create, update, and delete Workflow Definitions.
With the exception of retrieving an existing Workflow Definition through the GET API, a user must have the DEFINITION_ADMIN permission to create (POST), update (PUT), or delete (DELETE) Workflow Definitions.
Table of contents
How to Find an Existing Workflow Definition
The Workflow Definition GET API allows users to retrieve existing Workflow Definitions. To find an existing Workflow Definition, a user can query by ID, name, or entityTypeID. To obtain existing Workflow Definitions, use the following curl command below.
curl -X 'GET' \
'https://{host}/api/definitions/workflows?ID=1234&name=legal%20entity%20repair&entityTypeID=1' \
-H 'accept: application/json'
A sample return response can be found below.
Get WorkflowDefinition API Sample Response
// Some fields are omitted for brevity
[
{
"ID": 2,
"name": "legal entity repair",
"entityTypeID": 1,
"entityType": {
"ID": 1,
"name": "natural person"
},
"statuses": [
{
"ID": 3,
"name": "in progress",
"workflowDefinitionID": 2
},
{
"ID": 4,
"name": "accepted",
"workflowDefinitionID": 2
}
],
"transitions": [
{
"ID": 2,
"workflowDefinitionID": 2,
"isStartTransition": true,
"isEndTransition": true,
"validateOnTransition": false,
"fromStatusID": 3,
"fromStatus": {
"ID": 3,
"name": "in progress",
"workflowDefinitionID": 2
},
"toStatusID": 4,
"toStatus": {
"ID": 4,
"name": "accepted",
"workflowDefinitionID": 2
},
"groups": []
}
]
}
]
Refer to the DR Workbench API Definitions Reference to learn more about finding existing Workflow Definitions.
How to Create a Workflow Definition
The Workflow Definition POST API allows users to create a Workflow Definition.
Before Workflow Definitions can be created, Entity Types and User Groups must be created. See the Managing Entity Types page if these items have not been created.
In order to create a Workflow Definition, a user must be aware of the following rules and restraints:
- The GroupIDs element is an array of Group IDs, each of which must resolve to a User Group that exists AND is visible to the calling user.
- The transitions element is an array of Transition objects. Duplicate Transitions are defined as 2 or more Transitions that have the same From- and To- status pairs. There can be no duplicate Transitions in the transitions array.
- There must be exactly 1 start transition with IsStartTransition == true.
- There must be at least 1 end transition with IsEndTransition == true.
- For transitions where ValidateOnTransition == true, Attribute Validation will be performed when attempting to apply the transition. If validation fails, the transition will not be applied. See Attribute Validation for more information.
- One Workflow definition is limited to 10 statuses.
- One Workflow definition is limited to 25 transitions.
To create a Workflow Definition, use the following curl command below.
curl -X 'POST' 'https://{host}/api/definitions/workflows' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"entityTypeID": 1, // entityTypeID must already exist
"name": "legal entity repair",
"transitions": [
{
"fromStatus": "In Progress",
"toStatus": "In Review",
"isEndTransition": false,
"isStartTransition": true,
"validateOnTransition": true,
"groupIDs": [1]
},
{
"fromStatus": "In Review",
"toStatus": "Completed",
"isEndTransition": true,
"isStartTransition": false,
"groupIDs": []
}
]
}'
To view sample API responses to create new Workflow Definitions, refer to the DR Workbench API Definitions Reference.
How to Update a Workflow Definition
The Workflow Definition PUT API allows users to update an existing Workflow Definition. It can be used to change the Workflow Definition’s name, and add or remove its associated Transitions and Statuses. After an update, any Status that is no longer used in any Transitions is considered orphaned, and all orphaned Statuses are automatically deleted.
To update a Workflow Definition, use the following curl command below.
curl -X 'PUT' \
'https://{host}/api/definitions/workflows/{definitionID}' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"name": "Updated Workflow Name",
"transitions": [ // Transitions and Statuses can be added, removed, and edited here
{ // delete a transition
"transitionId": 92
"deleteTransition": true,
},
{ // add a new transition
"fromStatus": "Ready for Work",
"toStatus": "Work in Progress",
"isEndTransition": false,
"isStartTransition": true,
},
{ // edit an existing transition
"transitionId": 102,
"fromStatus": "Work in Progress",
"validateOnTransition": false
}
]
}'
To view sample API responses for updating a Workflow Definition, refer to the DR Workbench API Definitions Reference.
How to Delete a Workflow Definition
The Workflow Definition DELETE API allows users to delete a Workflow Definition. When a Workflow Definition is deleted, all of its Transitions, Statuses, and User Group assignments are also permanently deleted. A Workflow Definition with open Workflow Instances cannot be deleted.
To delete a Workflow Transition, follow the curl command below.
curl -X 'DELETE' \
'https://{host}/api/definitions/workflows/{definitionID}' \
-H 'accept: application/json'
To view sample API responses for deleting a Workflow Definition, refer to the DR Workbench API Definitions Reference.