Campaign workflows are created, edited and deleted through the DataGalaxy API. This article walks through the connection variables, the teams and the triggering attribute a workflow needs, then a full certification workflow example.
What do you need before you start?
- An API platform: for example Postman
- Workspace admin rights
- A valid token: a token with admin rights, see Generate Tokens to Communicate with the API
- Users and teams: configured in DataGalaxy
Which .json files to download
The original article has .json files to download to create or modify workflows:
- Environment .json: contains all the variables used in the collection's requests.
- Collection .json: contains all the requests required to create workflows for campaigns.
How to set the API connection variables
In your development tool (this example uses Postman), fill in the variables used by your requests.
These variables contain the connection information for your DataGalaxy workspace. The most important ones are:
| Variable | Value |
|---|---|
| accessToken | The token you generated from your DataGalaxy account. |
| baseUrl | The access URL to the DataGalaxy API. You can find it in your environment under Profile > DataGalaxy API. |
| spaceId | Your DataGalaxy workspace ID, which you can find in your URL: https://client.app.datagalaxy.com/space/SPACEID/versionID/ |
In Postman, you can set variables in two ways:
- From the environment: enter the same value in Initial value and Current value.
- From the collection tab: click the Variables button at the top right of your screen.
How to create a team
To create a team directly from the API, use the call POST /teams with the request body below.
Request body:
{
"name": "Dream Team",
"description": "This team is composed of the best of the best.",
"email": "contact@dreamteam.com",
"access": "limited",
"owners": [
"john.smith@datagalaxy.com"
],
"members": [
{
"email": "john.smith@email.com",
"role": "member"
}
]
}| Field | Values |
|---|---|
| access | Three types of access: private (only team members can view the team sheet), limited (all users can view the team sheet but must request access to join), open (all users can view and join the team). |
| role | Two types of roles: member and owner. |
How to retrieve the ID of your teams
Use the call GET {{baseUrl}}/Teams. To retrieve the ID of the teams created in DataGalaxy, use the request below from your imported Workflow collection.
The response has this shape:
{
"total": 1,
"results": [
{
"name": "",
"description": "",
"email": "",
"access": "",
"id": "",
"iconHash": "",
"owners": [
""
],
"membersCount": 1,
"members": [
{
"email": "",
"role": ""
}
]
}
]
}For the "CDO Office" team created in the workspace of this example, the result after sending the request is:
{
"results": [
{
"name": "CDO Office",
"description": "CDO Data Office team",
"email": "",
"access": "private",
"id": "d1fdd2fa-adf5-452d-b13c-88a4eee855d1:78cca48f-9f3b-4c8c-aaa8-59430120c904",
"iconHash": null,
"owners": [
"owner@example.com"
],
"membersCount": 1
}
],
"total": 1
}The response contains several pieces of information (name, description, owners, access types, ID, and so on). The part of the ID that interests us for the TeamGuid workflow variable is the second part, here: 78cca48f-9f3b-4c8c-aaa8-59430120c904.
How to set the attribute that triggers transitions
To manage the workflow, we need a common attribute: an object attribute that can be controlled in order to trigger transitions. You can use an existing "Value list" attribute, such as "Entity status". In this example, we create our own custom "Value list" attribute, called "Workflow Value List".
To create the workflow, we need the attribute path and the technical values of its values.
- To retrieve all common attributes, use the API call
GET {{baseUrl}}/v2/attributes?dataType=common.
- Search the returned common attributes for your attribute by its name.
- Find the attribute key to build the attribute path. For all custom common attributes, add a "." as a prefix to the attribute key. In this case, the attribute path is
.allCustomProp3.
All attribute values are loaded at the same time as the attribute information. To create the workflow, we use the numeric technical value.
How to retrieve the ID of the workflows created in DataGalaxy
Use the call GET {{baseUrl}}/workflow/space/{{spaceId}}/workflows.
Once the request is sent, you get a result like this:
[
{
"Guid": "ab6c4501-c9e5-4092-b47f-63ed89593be3",
"Name": "DataGalaxy objects lifecycle workflow"
},
{
"Guid": "44a1d813-731f-4110-bcef-2e4b61051da8",
"Name": "Data Element Certification Campaign"
}
]For each campaign workflow you have in DataGalaxy, you retrieve the name and the ID.
How to create a workflow
To create a workflow, use the call POST {{baseUrl}}/Workflow.
In this example, the CDO Office team wants to launch a certification campaign for the objects present in DataGalaxy:
- The CDO Office asks the Data Steward to update the various information related to the objects included in the campaign → object status: "proposed".
- The Data Steward reviews the objects and makes the necessary changes → object status: "in review".
- The Data Steward informs the Data Owner once the object has been reviewed → object status: "in validation".
- The Data Owner either validates that the object's information is correct [1], or requests changes from the Data Steward [2] → object status: "validated" [1] or "in review" [2].
The associated request body is:
{
"SpaceGuid": "{{spaceId}}",
"Name": "Data Element Certification Campaign",
"AttributePath": "EntityStatus",
"Phases": [{
"Name": "New",
"Description": "Configure your campaign and add objects. Expect objects to be in a Proposed state in order to start Data Element certification campaign",
"PhaseType": "Initial",
"Transitions": [{
"TransitionName": "Start",
"TargetPhaseName": "Enrich objects",
"Description": "Start campaign and request Data Stewards to enrich objects. Expect objects to be in a Proposed state in order to start Data Element certification campaign",
"Direction": "Forward",
"ExpectedAttributeValues": [0]
}
],
"Assignees": [{
"TeamGuid": "78cca48f-9f3b-4c8c-aaa8-59430120c904"
}
]
}, {
"Name" : "Enrich objects",
"Description": "Data stewards must add/update required information and update Data Element status accordindly",
"PhaseType": "Regular",
"Transitions": [{
"TransitionName": "Request Data Owner validation",
"TargetPhaseName": "Data Owner validation",
"Description": "Objects should be at least enriched, and because rework can be requested later on for some objects, they can be in any more mature state",
"Direction": "Forward",
"ExpectedAttributeValues": [1, 2]
}
],
"Assignees": [{
"GovernanceRole": "DataStewards"
}
]
}, {
"Name": "Data Owner validation",
"Description": "DataOwner review ongoing, objects Data Element status can be promoted to Validated when appropriate. If acceptance criterias are not met, a new steward review can be requested",
"PhaseType": "Regular",
"Transitions": [{
"TransitionName": "Close Campaign",
"TargetPhaseName": "Closed",
"Description": "All objects Data Element status should be Certified in order to close the campaign",
"Direction": "Forward",
"ExpectedAttributeValues": [3]
}, {
"TransitionName": "Request rework",
"TargetPhaseName": "Enrich objects",
"Description": "Some objects couldn't be validated at this stage and require further work",
"Direction": "Backward",
"ExpectedAttributeValues": [0, 1, 2, 3]
}
],
"Assignees": [{
"GovernanceRole": "DataOwners"
}
]
},
{
"Name": "Closed",
"Description": "Campaign is closed",
"PhaseType": "Final",
"Transitions": [],
"Assignees": []
}
]
}The request above describes all the phases of the workflow. For each phase, you provide the following information:
| Field | Description |
|---|---|
| Name | Phase name |
| Description | Phase description |
| PhaseType | Phase type, with 3 types: Initial (first phase of the workflow), Regular (intermediate phase), Final (last phase) |
| TransitionName | Name of the transition between 2 phases |
| TargetPhaseName | Target phase name |
| Description (transition) | Transition description |
| Direction | Transition direction, with two types: Forward (the workflow goes to the next phase), Backward (the workflow goes to the previous phase) |
| ExpectedAttributeValues | The value corresponds to the campaign status: [0] Proposed, [1] In review, [2] In validation, [3] Validated |
| Assignees | Assigned role or team: GovernanceRole (owners, stewards, cdos, cisos, dpos, experts) or TeamGuid (the team ID, retrieved with GET Teams; only the second part of the ID should be used, as mentioned above) |
Once your request is submitted, you can find your workflow when creating a campaign in DataGalaxy.
How to edit a workflow
To edit a workflow, use the call PUT {{baseUrl}}/Workflow/Workflow_ID:
- Enter the ID of the workflow you want to modify in the request.
- Add the code in the request body according to your needs.
How to delete a workflow
To delete a workflow, use the call DELETE {{baseUrl}}/Workflow/Workflow_ID and enter the ID of the target workflow in the request.