Gérer les workflows avec l'API (Campagnes)

Prérequis : 

• Plateforme API (par exemple: Postman) Postman
• Droits admin espace de travail
• Un token valide (avec droits admin) Créer des tokens
• Utilisateurs et équipes configurés dans DataGalaxy

TABLE DES MATIÈRES

• Télécharger les fichiers .json
• Informations de connexion à l'API DataGalaxy
• Créer une équipe
• Récupérer l'ID de vos équipes créées dans DataGalaxy
• Attribut déclenchant les transitions
• Récupérer l'ID des workflows créés dans DataGalaxy
• Créer un workflow
• Modifier un workflow
• Supprimer un workflow

Télécharger les fichiers .json

En bas de page, vous trouverez les fichiers .json à télécharger pour créer ou modifier des workflows.

• Environnement .json : Ce fichier contient toutes les variables utilisées dans les requêtes de la collection.
• Collection .json : Ce fichier contient toutes les requêtes nécessaires à la création de workflows pour les campagnes.

Informations de connexion à l'API DataGalaxy

Dans votre outil de développement (dans cet exemple, nous utilisons Postman), remplissez les variables utilisées par vos requêtes. Ces variables contiennent les informations de connexion à votre espace de travail DataGalaxy.

Les variables les plus importantes sont :

Dans Postman, vous avez deux façons différentes pour paramétrer les variables :

1. Depuis l’environnement : Entrez la même valeur dans “Initial value” et “Current value”.
    
2. Depuis le tableau collection, cliquez sur le bouton “Variables” en haut à droite de votre écran :

Créer une équipe

• Pour créer une équipe directement depuis l'API, utilisez l'appel : POST /teams

Utilisez le corps de la requête ci-dessous :

{
    "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"
        }
    ]
}

Récupérer l'ID de vos équipes créées dans DataGalaxy

• Utilisez l'appel : GET {{baseUrl}}/Teams

Pour récupérer l’ID des équipes créées dans DataGalaxy, utilisez la requête ci-dessous (corps de la requête) depuis votre collection Workflow importée :

{
  "total": 1,
  "results": [
    {
      "name": "",
      "description": "",
      "email": "",
      "access": "",
      "id": "",
      "iconHash": "",
      "owners": [
        ""
      ],
      "membersCount": 1,
      "members": [
        {
          "email": "",
          "role": ""
        }
      ]
    }
  ]
}

Dans le cas de l’équipe “CDO Office” créée dans mon espace de travail DataGalaxy, j’obtiens le résultat suivant après avoir envoyé la requête :

{
    "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": [
                "antoine.vadimon+sdbx@datagalaxy.com"
            ],
            "membersCount": 1
        },
    ],
    "total": 1
}

Nous récupérons plusieurs informations (nom, description, propriétaires, types d’accès, ID, etc.)

La partie de l’ID qui nous intéresse dans l’utilisation de la variable “TeamGuid” du workflow est la seconde partie, ici : 78cca48f-9f3b-4c8c-aaa8-59430120c904

Attribut déclenchant les transitions

Pour gérer le workflow, nous aurons besoin d'un attribut commun : un attribut d'objet qui peut être contrôlé afin de déclencher des transitions.Vous pouvez utiliser un attribut de type "Liste de valeurs" existant, tel que "Statut de l'entité". Dans cet exemple, nous allons créer notre propre attribut personnalisé de type "Liste de valeurs", appelé "Workflow Value List".

• Note : L'attribut doit être de type Liste de Valeurs et un attribut commun

Pour la création du workflow, nous avons besoin du chemin de l'attribut (attribute path) et des valeurs techniques de ses valeurs.

1. Pour récupérer tous les attributs communs, utilisez l'appel API suivant : GET {{baseUrl}}/v2/attributes?dataType=common.
2. L'appel API retournera tous les attributs communs. Recherchez votre attribut par son nom. 
3. Trouvez la clé de l'attribut (attribute key) pour construire le chemin de l'attribut. Pour tous les attributs communs personnalisés, vous devez ajouter un « . » en préfixe à la clé de l'attribut. Dans ce cas précis, le chemin de l'attribut sera .allCustomProp3.

Pour récupérer les valeur de l'attribut :

Toutes les valeurs d'attribut sont chargées en même temps que les informations de l'attribut. Pour la création du workflow, nous utilisons la valeur technique numérique.

Récupérer l'ID des workflows créés dans DataGalaxy

• Utilisez l'appel : GET {{baseUrl}}/workflow/space/{{spaceId}}/workflows

Une fois que la requête est envoyée, vous obtenez le résultat suivant :

[
    {
        "Guid": "ab6c4501-c9e5-4092-b47f-63ed89593be3",
        "Name": "DataGalaxy objects lifecycle workflow"
    },
    {
        "Guid": "44a1d813-731f-4110-bcef-2e4b61051da8",
        "Name": "Data Element Certification Campaign"
    }
]

Pour chaque workflow de campagne que vous avez dans DataGalaxy, vous récupérez le nom et l’ID.

Créer un workflow

• Pour créer un workflow, utilisez l'appel : POST {{baseUrl}}/Workflow

Ci-dessous, un exemple de création de workflow :

Dans cet exemple, l’équipe CDO Office souhaite lancer une campagne de certification pour les objets présents dans DataGalaxy.

1. Le CDO Office demande au Data Steward de mettre à jour les différentes informations relatives aux objets inclus dans la campagne → statut de l’objet : « proposé »
2. Le Data Steward examine les objets et apporte les modifications nécessaires → statut de l’objet : « en révision »
3. Le Data Steward informe le Data Owner une fois que l’objet a été examiné → statut de l’objet : « en validation »
4. Le Data Owner valide soit que les informations de l’objet sont correctes [1], soit demande des modifications au Data Steward [2] → statut de l’objet : « validé » [1] ou « en révision » [2]

Le corps de requête associé sera :

{
    "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": []
        }
    ]
}

La requête ci-dessus décrit toutes les phases du workflow. Pour chaque phase, nous avons les informations suivantes :

Une fois votre requête soumise, vous pouvez retrouver votre workflow lors de la création d'une campagne dans DataGalaxy.

Modifier un workflow

• Pour modifier un workflow, utilisez l'appel : PUT {{baseUrl}}/Workflow/Workflow_ID

1. Saisissez l'ID du workflow que vous souhaitez modifier dans la commande de requête.
2. Ajoutez le code dans le corps de la requête en fonction de vos besoins.

Supprimer un workflow

• Pour supprimer un workflow : DEL {{baseUrl}}/Workflow/Workflow_ID

Pour supprimer un workflow, il suffit de saisir l'ID du workflow ciblé dans l'appel de la requête.

Attention : Cette action est définitive !

Ci-dessous, les fichiers .json à télécharger :