Configuration of workflows (code)

This article applies to DELIVER EMPOWER licenses

NOTE : this article is currently only available in French

Purpose of the article

This article describes how to create and modify workflows for use in document approval circuits, using cooperlink's JSON code interface.

What is a workflow?

Cooperlink has an engine that allows you to generate a succession of automated actions or actions for the end user (the workflow). Here we will study the configuration of the workflow for use for document approval circuits.

Prerequisite

• Knowledge of code, and JSON in particular, is required.

• The workflow engine uses the map concept. Please refer to the corresponding section for more information by clicking here.

• A workspace must first exist. For more information, click here.

Principes de base

Un workflow est défini par un ensemble d'éléments de base

• Le type de cible targetType. Il définit le type de modèle de données auquel le workflow se rapporte.

• La carte de démarrage startCard. Elle est utilisée pour permettre à l'utilisateur de définir les valeurs du workflow configurables à l'exécution (à la volée).

• Les états states. Ils définissent les macro-étapes de l'exécution du workflow. Les états sont toujours exécutés en série (linéaire). L'étape actuelle du moteur est dénommé current step.

• Les actions actions. Il peut s'agir d'une action effectuée par le moteur de Cooperlink ou une action de l'utilisateur final. Pour les opérations effectuées en série, un état ne contient qu'une seule action. Pour les opérations effectuées en parallèle, un état contient plusieurs actions.

• Les actions d'attente waitFor. Les actions automatiques sont exécutées successivement tandis que les actions requérant une intervention de l'utilisateur sont mise en attente. Lorsque l'événement d'attente se réalise, un processus décisionnel identifie le résultat de sortie out et si le workflow doit continuer à se réaliser.

• Les séquences sequences. Elles définissent l'ordonnancement des actions.

Ces différents éléments peuvent se schématiser comme suit.

Les cartes

Les cartes jouent un rôle essentiel dans l'élaboration d'un workflow dans Cooperlink. En effet celles-ci servent aussi bien aux interactions avec les utilisateurs finaux, qu'à la configuration du workflow à la volée.

Carte de démarrage et configuration à la volée

Lorsqu'un utilisateur démarre un workflow, selon la configuration définie, la carte de démarrage peut récupérer les valeurs des cartes projet, espace de travail et document sur base des clés des champs. Ceci permet d'éviter les ré-encodages multiples et les erreurs de traitement.

Cartes (de réponse)

Les interactions avec les utilisateurs se passe à travers une carte de réponse. Cette carte est jointe à une tâche et assignée à l'utilisateur ou au partenaire. L'action d'attente waitFor scrute le remplissage de cette carte de réponse.

Résultat dans la carte du targetType (document)

Cooperlink enregistre le résultat du workflow dans la carte de la cible (le document en l'occurence) en identifiant la clé du champ correspondant.

Exemple de création d'un circuit d'approbation

Demande du client

Dans cet exemple, nous allons créer un circuit d'approbation de document en trois étapes :

• A la première étape, un utilisateur interne au choix est invité à consulter le document et à y répondre. Celui-ci ne peut qu'accepter ou refuser le document. Il peut également commenter sa réponse. En cas de réponse négative, le workflow s'arrête.

• A la seconde étape, 3 partenaires sont invités à consulter le document et à y répondre. Ils peuvent chacun approuver, refuser ou indiquer ne pas être concerné par le document. Ils peuvent également commenter leur réponse. En cas de réponse négative (au moins une), le workflow s'arrête.

• A la troisième étape, un partenaire 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.

Pour permettre à l'utilisateur interne et aux partenaires de se prononcer, il est nécessaire de communiquer :

• Le numéro de révision du document (valeur auto-incrémentée "0, a, b, c, ..." après chaque circuit d'approbation)

• L'objet de la demande (texte libre)

• Le lot concerné (valeur parmi une liste prédéfinie Lot1, Lot2, Lot3)

Etape 1. Créer ou identifier une carte espace de travail

Créez une carte espace de travail, ou identifiez une carte existante. Pour plus d'informations, cliquez ici. Liez également cette carte avec votre espace de travail en cliquant ici.

La demande du client précise :

• L'existence d'un utilisateur interne (nous l’appellerons ex_intern1) et 4 partenaires (ex_partner1 à ex_partner4)

• Le numéro de révision ex_rev au premier circuit d'approbation est 0

Ajouter les champs suivants à la carte espace de travail :

• Validateur interne, type User, clé ex_intern1

• Partenaire N, type User, clé ex_partnerN (N = 1, 2, 3, 4)

• Révision par défaut, type Text, clé ex_rev

Une fois enregistré, accédez au tableau de bord de l'espace de travail et remplissez les champs de la carte avec les valeurs suivantes :

• Utilisateur interne au choix

• Partenaires au choix

• Révision par défaut : 0

Etape 2. Créer ou identifier une carte document

Créez une carte document, ou identifiez une carte existante. Pour plus d'informations, cliquez ici.

Ajoutez le champ suivant à la carte document :

• Statut workflow, type Text, clé ex_document_status, cocher option Read only

Enregistrez vos changements.

Etape 3. Créer ou identifier une carte de démarrage

Créez une carte de démarrage, ou identifiez une carte existante. Pour plus d'informations, cliquez ici.

Définissez les champs suivants à la carte de démarrage (type card) :

• Objet de la demande, type Text, clé ex_request, cocher Champs requis

• Lot, type ValueList, clé ex_package, valeurs Lot1, Lot2, Lot3

• Révision, type ValueList, clé ex_rev, valeurs 0|Intial, A|Revision A, B|Revision B, C|Revision C, D|Revision D, cocher option AutoIncrement

• Utilisateur interne, type User, clé ex_intern1, cocher Champs requis

• Partenaire N, type User, clé ex_partnerN (N = 1, 2, 3, 4), cocher Champs requis pour partner4 uniquement

Les valeurs d'une liste sont séparées par la touche Entrée.

Pour plus d'informations sur le format valeur|texte_affiché des listes de valeur, référez-vous à l'article en cliquant ici.

IMPORTANT : notez l'identifiant id de la carte (p.ex. 121).

Etape 4. Créer ou identifier une carte de réponse

Sur la base de la demande du client, nous constatons qu'il peut y avoir deux types de réponse. Nous allons donc créer 2 cartes de réponse différentes.

4.1. Première carte

Créez une première carte de réponse, ou identifiez une carte existante. Pour plus d'informations, cliquez ici.

Définissez les champs suivants à la carte de réponse (type card) :

• Réponse, type ValueList, clé ex_response, valeurs A|Accepté, B|Refusé, cocher option Champ requis, Outcome A

• Commentaire, type Text, clé ex_comment

IMPORTANT : notez l'identifiant id de cette première carte de réponse (p.ex. 122)

4.2. Seconde carte

Réitérez la même opération avec une seconde carte. Cette fois définissez les champs comme suit (type card) :

• Réponse, type ValueList, clé ex_response, valeurs A|Accepté, B|Refusé, NA|Non concerné, cocher option Champ requis, Outcome A, NA

• Commentaire, type Text, clé ex_comment

IMPORTANT : notez l'identifiant id de cette seconde carte de réponse (p.ex. 123)

Etape 5. Créer un nouveau workflow

Accédez aux Paramètres de l'application, section Workflows templates.

Créez un nouveau modèle de workflow en cliquant Nouveau design de workflow.

Nommez votre workflow en remplissant les champs label et description.

• Label : Approbation document

• Description : Circuit d'approbation pour documents

Créez le workflow en cliquant sur Créer design.

CONSEIL : Afin de rafraîchir l'écran, cliquez de nouveau sur l'onglet Workflows templates, et cliquez ensuite sur le workflow nouvellement créé.

Dans l'éditeur de code JSON, sélectionnez le mode Code ou Text. 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 - PROPRIETES DE BASE

Le fichier de configuration du workflow identifie un ensemble de propriétés de base :

NOTE : seuls les champs sur fond blanc peuvent être modifiés. 

Ajoutez les propriétés suivantes :

• usePreviousStartCard : true

• startCardDesignId : indiquez l'identifiant de la carte créée à l'étape 3

Etape 6b. Configurer le workflow - STATES

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

Les propriétés utiles de states sont :

Code :

"states":[
   {
      "name":"Interne"
   },
   {
      "name":"Externe 1"
   },
   {
      "name":"Externe 2"
   },
   {
      "name":"Approuvé"
   }
],

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. Elle est donc toujours exécuté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 le code suivant :

"actions": [
{
 // ex_action_intern1 (create card)
 // Voir étape 6d
}
{
 // ex_wait_action_intern1 (wait for)
 // Voir étape 6e
}
{
 // ex_action_partner1 (create card)
 // Voir étape 6f
}
{
 // ex_action_partner2 (create card)
 // Voir étape 6f
}
{
 // ex_action_partner3 (create card)
 // Voir étape 6f
}
{
 // ex_wait_action_parter3 (wait for)
 // Voir étape 6f
}
{
 // ex_action_partner4 (create card)
 // Voir étape 6f
}
{
 // ex_wait_action_parter4 (wait for)
 // Voir étape 6f
}
{
 // ex_wait_final (wait for)
 // Voir étape 6g
}

Etape 6d. Configurer le workflow - ACTIONS STATE 1 (créer carte de réponse)

Chaque étape state est une succession d'une ou plusieurs actions non bloquantes.

Les propriétés utiles de l'action sont :

Code :

{
   "objectType":".actions.CreateCard",
   "key":"ex_action_intern1",
   "title":{
      "literal":"Approbation Interne"
   },
   "description":{
      "literal":"Merci de prendre connaissance du document en pièce jointe et répondre aux questions ci-après."
   },
   "assignedUser":{
      "metaDataDefinition":{
         "elementType":"CARD",
         "name":"ex_intern1"
      }
   },
   "dueDate":{
      "remainingDays":10
   },
   "addTask":true,
   "cardDesignId":122
},

Nous assignerons la première carte de réponse à l'approbateur interne.

En indiquant la valeur true à la propriété addTask, une instance de la carte cardDesignId est associée à une tâche, assignée à un utilisateur. La tâche se voit attribuer les valeurs suivants :

• Titre de la tâche : titre de l'action

• Description de la tâche : description de l'action (literal)

• Date de fin : date d'exécution de l'action + dueDate (jours)

Le champ Outcome, définit à l'étape 4, détermine les valeurs de réponse qui donnent lieu à une réponse positive en clôture de l'instance de la carte cardDesignId.

Etape 6e. Configurer le workflow - WAITFOR STATE 1

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

Propriétés :

Code :

{
   "objectType":".actions.WaitForOpenCards",
   "key":"ex_wait_action_intern1",
   "stateName":"Interne",
   "outMetaData":"ex_document_status",
   "outValueIfOK":"Approuvé Interne",
   "outValueIfNOK":"Refusé Interne",
   "completeIfNOK":true
},

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

CONSEIL : à l'étape 2, nous avons créé le champ ex_status dans la carte document. Par simplicité, nous avons défini un champ de type texte, vous permettant de définir n'importe quel type de résultat lors de la configuration workflow (texte libre pour outValueIfOK / outValueIfNOK).

Etape 6f. Configurer le workflow - STATES 2 et 3

Répétez les opérations des étapes 6d et 6e pour les STATES 2 et 3.

Pour exécuter des actions en parallèle, il suffit :

• De créer des actions .actions.CreateCard de façon séquentielle

• De terminer l'étape par une action .actions.WaitForOpenCards

Nous assignerons :

• La seconde carte de réponse aux partenaires 1 à 3

• La première carte de réponse au partenaire 4

Etape 6g. 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": "ex_wait_final",
 "stateName": "Approuvé"
}

Etape 6h. Configurer le workflow - SEQUENCES

Les séquences définissent les relations entre les actions.

Propriétés :

Code :

"sequences":[
   {
      "endPoint":null,
      "from":"ex_action_intern1",
      "to":"ex_wait_action_intern1"
   },
   {
      "endPoint":null,
      "from":"ex_wait_action_intern1",
      "to":"ex_action_partner1"
   },
   {
      "endPoint":null,
      "from":"ex_action_partner1",
      "to":"ex_action_partner2"
   },
   {
      "endPoint":null,
      "from":"ex_action_partner2",
      "to":"ex_action_partner3"
   },
   {
      "endPoint":null,
      "from":"ex_action_partner3",
      "to":"ex_wait_action_partner3"
   },
   {
      "endPoint":null,
      "from":"ex_wait_action_partner3",
      "to":"ex_action_partner4"
   },
   {
      "endPoint":null,
      "from":"ex_action_partner4",
      "to":"ex_wait_action_partner4"
   },
   {
      "endPoint":null,
      "from":"ex_wait_action_partner4",
      "to":"ex_wait_final"
   }
]

Sur base du schéma ci-avant, les actions ex_action_partner1, ex_action_partner2, ex_action_partner3 sont exécutées en parallèle. L'action ex_action_partner4 est exécutée une fois les actions précédentes terminées.

Félicitations!

Vous avez terminé la configuration du workflow.

Pour votre facilité, vous trouverez le fichier de configuration en cliquant ici.