Configuration d'un circuit d'approbation (code)

Cet article s'applique aux licences DELIVER EMPOWER

Objet de l'article

Cet article explique comment créer et modifier des workflows en vue de leur utilisation pour des circuits d'approbation de documents, à l'aide de l'interface code JSON de Cooperlink.

Qu'est-ce qu'un workflow?

Cooperlink dispose d'un moteur qui permet de générer une succession d'actions automatisées ou à destination de l'utilisateur final (le workflow). Nous allons étudier ici la configuration du workflow en vue de son utilisation pour les circuits d'approbation de documents.

Prérequis

• La connaissance du code, et du JSON en particulier est nécessaire. Bases de la notation JSON.
• Le moteur de workflow utilise le concept de carte. Veuillez vous référer à la section correspondante pour plus d'information en cliquant ici.
• Une espace de travail doit préalablement exister. Pour plus d'information, voir Configurer un nouvel espace de travail en mode manuel (+ checklist).
• La connaissance des principes de base des workflows est requise. Voir article Généralités sur les workflows et terminologie.

Préparation à la création d'un circuit d'approbation 

Demande du client

Dans cet exemple, nous allons créer un circuit d'approbation pour documents d'architecture en deux étapes :

• A la première étape, l'architecte (AR), le BE Stabilité (STAB) et le BE Techniques spéciales (MEP) sont invités à consulter le document et à y répondre. Ils peuvent chacun approuver, approuver avec remarques, refuser ou indiquer ne pas être concerné par le document. Ils peuvent également commenter leur réponse, ajouter une pièce jointe ou annoter le document (PDF uniquement). En cas de réponse négative (au moins une pour l'ensemble des contributeurs de cette étape), le workflow s'arrête.
• A la deuxième étape, l'auteur de projet (PM) est invité à consulter le document et à y répondre. Il ne peut qu'accepter ou refuser le document. Il peut également commenter sa réponse. En cas de réponse positive, le workflow est clôturé avec succès.
• Dans tous les cas, en cas de réponse avec commentaire, celle-ci est considérée comme acceptée.
• Seuls l'architecte et l'auteur de projet sont obligatoires dans ce circuit d'approbation. Les autres contributeurs peuvent être consultés à la demande.

Etape 1. Créer une carte espace de travail

Créez une carte espace de travail, ou éditez une carte existante.  La carte espace de travail va permettre de pré-configurer certaines valeurs par défaut lors du démarrage du workflow (voir Pré-remplissage des données - Héritage entre cartes).

Associez cette carte à l'espace de travail concerné et attribuez des valeurs à ces champs en vous rendez dans les paramètres de l'espace de travail, section aperçu. 

Pour notre exemple de circuit d'approbation, la carte espace de travail contient les champs suivants :

Etape 2. Créer une carte documents

Créez une carte documents, ou éditez une carte existante.  La carte documents est la fiche d'identité du document sujet du circuit d'approbation. Les informations contenues dans cette carte documents pourront être réutilisées dans la carte de démarrage du workflow (voir Pré-remplissage des données - Héritage entre cartes).

Associez cette carte documents à l'espace de travail concerné.

Pour notre exemple de circuit d'approbation, la carte documents contient les champs suivants :

Etape 3. Créer la carte de démarrage workflow

Créez une carte workflows, ou éditez une carte existante.  La carte de démarrage est le formulaire affiché au démarrage d'un circuit d'approbation. Les informations de cette carte de démarrage seront partiellement pré-complétées (voir Pré-remplissage des données - Héritage entre cartes).

Notez l'identifiant (ID) de cette carte.

Pour notre exemple de circuit d'approbation, la carte de démarrage contient les champs suivants :

Etape 4a. Créer la carte de réponse workflow pour la première étape

Créez une seconde carte workflows, ou éditez une carte existante.  La carte de réponse est la carte transmis aux contributeurs pour réponse. 

Notez l'identifiant (ID) de cette carte.

Pour notre exemple de circuit d'approbation, la carte de réponse contient les champs suivants :

Etape 4b. Créer la carte de réponse workflow pour la seconde étape

Créez une seconde carte workflows, ou éditez une carte existante.  La carte de réponse est la carte transmis aux contributeurs pour réponse. 

Notez l'identifiant (ID) de cette carte.

Pour notre exemple de circuit d'approbation, la carte de réponse contient les champs suivants :

Configurer un nouveau modèle de workflow

Etape 5. Créer un nouveau workflow

Accédez aux Paramètres de l'application, section Modèles de workflow. 

Créez un nouveau modèle de workflow.

Editez le label et la description comme suit : COMPANY - Workflow Example

Dans l'éditeur de code JSON, sélectionnez le mode Code. Sélectionnez tout le code (CTRL+A), copiez-le (CTRL+C) et collez le dans un éditeur de texte ou un éditeur de code (p.ex. Komodo Edit, Notepad++).

Etape 6a. Configurer le workflow - INTRODUCTION

Le code d'un workflow est décomposé en 4 grandes sections :

• Les propriétés de base du workflow
• Les étapes (states)
• Les actions (actions)
• Les séquences (sequences)

Etape 6a. Configurer le workflow - PROPRIETES DE BASE

Cette section contient tout d'abord un ensemble de propriétés non éditables. Elles sont calculés automatiquement par Cooperlink.

  "id": 117,
  "creationUserId": 509,
  "creationDate": "2022-11-11T09:40:00.938815Z",
  "lastUpdateUserId": 509,
  "lastUpdateDate": "2022-11-14T11:28:08.036529Z",
  "templateId": 123,

Ensuite s'ajoutent une série de propriétés éditables selon les besoins du workflow. Voir Propriété des workflows pour plus d'informations à ce sujet.

• Indiquez l'identifiant (ID) de la carte de démarrage à la propriété startCardDesignId
• Adaptez le masque de label pour nommer votre workflow selon votre souhait

  "label": "COMPANY - Workflow Example",
  "description": "COMPANY - Workflow Example",
  "targetType": "LIBRARY_MAPPING",
  "startCardDesignId": 189,
  "usePreviousStartCard": true,
  "labelMask": "{{company_project_document_type}}-{{company_project_package}}-{{company_project_number}}-rev{{company_project_revision}}-{{company_project_title}}",
  "longCommentsItem": "company_project_comment",
  "longCommentsLimit": 150,
  "longCommentsWarning": "Long comment. Please read next page.",
  "icon": "fa-building",

Etape 6b. Configurer le workflow - STATES

La propriété States constitue un tableau JSON. Le workflow est découpé en macro-étapes auxquelles nous donnons un titre sous forme de texte libre.

  "states": [
    {
      "name": "Approval Council"
    },
    {
      "name": "Approval PM"
    },
    {
      "name": "Approved"
    }
  ],

Etape 6c. Configurer le workflow - ACTIONS (structure)

Précédemment, nous avons créé des cartes de réponse que nous allons attribuer aux intervenants. Pour ce faire, nous allons créer une ou plusieurs actions de type .actions.createCard. Cette action est non bloquante, c'est-à-dire que si elle n'est pas assignée à un utilisateur/partenaire, elle est ignorée.

Ensuite, nous allons créer une action .actions.waitForOpenCard dans l'attente des actions utilisateurs. Cette action waitFor attend le résultat de ensemble des cartes de l'étape state avant d'être exécutée.

Pour l'exemple, nous allons créer la structure de code suivante à l'aide des étapes 6d et suivantes.

"actions": [
// actions first state
// waitFor actions first state
// actions second state
// waitFor actions second state
// waitFor action final state
}

Etape 6d. Configurer le workflow - ACTIONS STATE 1 (en parallèle)

Nous allons ici créer les actions de la première étape (state). Une action de type .createCard est assignée à l'architecte, le BE Stabilité et le BE Techniques spéciales.

Nous observons la structure suivante :

• Un objet JSON qui représente l'action createCard pour l'architecte
• Un objet JSON qui représente l'action createCard pour le BE Stabilité
• Un objet JSON qui représente l'action createCard pour le BE Techniques spéciales

    {
      "objectType": ".actions.CreateCard",
      "key": "company_project_action_ar",
      "title": {
        "literal": "AR"
      },
      "description": {
        "literal": "Please consult document and fill in form"
      },
      "assignedUser": {
        "metaDataDefinition": {
          "elementType": "CARD",
          "name": "company_project_ar"
        }
      },
      "dueDate": {
        "remainingDays": 7,
        "metaDataDefinition": null,
        "onlyWorkingDays": false
      },
      "addTask": true,
      "cardDesignId": 190
    },
    {
      "objectType": ".actions.CreateCard",
      "key": "company_project_action_stab",
      "title": {
        "literal": "STAB"
      },
      "description": {
        "literal": "Please consult document and fill in form"
      },
      "assignedUser": {
        "metaDataDefinition": {
          "elementType": "CARD",
          "name": "company_project_stab"
        }
      },
      "dueDate": {
        "remainingDays": 7,
        "metaDataDefinition": null,
        "onlyWorkingDays": false
      },
      "addTask": true,
      "cardDesignId": 190
    },
    {
      "objectType": ".actions.CreateCard",
      "key": "company_project_action_mep",
      "title": {
        "literal": "MEP"
      },
      "description": {
        "literal": "Please consult document and fill in form"
      },
      "assignedUser": {
        "metaDataDefinition": {
          "elementType": "CARD",
          "name": "company_project_mep"
        }
      },
      "dueDate": {
        "remainingDays": 7,
        "metaDataDefinition": null,
        "onlyWorkingDays": false
      },
      "addTask": true,
      "cardDesignId": 190
    },

Etape 6e. Configurer le workflow - WAITFOR STATE 1

Chaque étape est terminée par une action de type .actions.WaitForOpenCards. Le moteur de workflows Cooperlink attend donc les réponses aux différentes cartes précédemment attribuées.

    {
      "objectType": ".actions.WaitForOpenCards",
      "key": "company_project_wait_state1",
      "stateName": "Approval Council",
      "completeIfNOK": true
    },

IMPORTANT : le stateName doit être strictement identique à l'un des states créés à l'étape 6b

Etape 6f. Configurer le workflow - STATE 2 (en série)

Nous allons répétez une opération similaire pour la deuxième étape (state). Ici il n'y a qu'une seule action avant l'instruction .waitForOpenCards, cela signifie que cette instruction est exécutée en série, c'est-à-dire après que les autres actions ont été clôturées.

   {
      "objectType": ".actions.CreateCard",
      "key": "company_project_action_pm",
      "title": {
        "literal": "PM"
      },
      "description": {
        "literal": "Please consult document and fill in form"
      },
      "assignedUser": {
        "metaDataDefinition": {
          "elementType": "CARD",
          "name": "company_project_pm"
        }
      },
      "dueDate": {
        "remainingDays": 7,
        "metaDataDefinition": null,
        "onlyWorkingDays": false
      },
      "addTask": true,
      "cardDesignId": 190
    },

Etape 6g. Configurer le workflow - WAITFOR STATE 2

Nous ajoutons également une instruction d'attente pour la seconde étape (state).

    {
      "objectType": ".actions.WaitForOpenCards",
      "key": "company_project_wait_state2",
      "stateName": "Approval PM",
      "completeIfNOK": true
    },

Etape 6h. Configurer le workflow - ACTION FINALE

Lorsqu'un workflow se termine, il affiche par défaut le nom du dernier state. Afin d'afficher dans l'application un nom convivial à l'utilisateur lorsque le workflow s'est terminé avec succès, il est de bonne pratique de créer un state ainsi qu'une action de finalisation du workflow comme suit :

    {
      "objectType": ".actions.WaitForOpenCards",
      "key": "company_project_wait_final",
      "stateName": "Approved"
    }

Etape 6i. Configurer le workflow - SEQUENCES

Les séquences définissent les relations entre les actions (c'est-à-dire les flèches entre les actions). Il faut donc indiquer au moteur de workflow l'ordre d'exécution des actions.

"sequences": [
    {
      "endPoint": null,
      "from": "company_project_action_ar",
      "to": "company_project_action_stab"
    },
    {
      "endPoint": null,
      "from": "company_project_action_stab",
      "to": "company_project_action_mep"
    },
    {
      "endPoint": null,
      "from": "company_project_action_mep",
      "to": "company_project_wait_state1"
    },
    {
      "endPoint": null,
      "from": "company_project_wait_state1",
      "to": "company_project_action_pm"
    },
    {
      "endPoint": null,
      "from": "company_project_action_pm",
      "to": "company_project_wait_state2"
    },
    {
      "endPoint": null,
      "from": "company_project_wait_state2",
      "to": "company_project_wait_final"
    }
  ]

Sur base du schéma ci-avant, les actions company_project_actions_ar, company_project_actions_stab et company_project_actions_mep sont exécutées en parallèle. L'action company_project_actions_pm est par contre exécutée après que les autres actions ont été clôturées (en série).

Félicitations!

Vous avez terminé la configuration du workflow.