Préambule

Ce document présente le fonctionnement des workflows Camunda® de validation dans Project Monitor et Perf Monitor, du point de vue utilisateur et du point de vue conception. Il s’adresse aux consultants qui doivent mettre en place des workflows de validation dans l’application. Camunda® est disponible depuis la V6.5.2.

Convention de rédaction

Terme	Description
PM	Project Monitor
PeM	Perf Monitor
WF	Workflow – Process
Fichier JPDL	Fichier “text” contenant le code d’un workflow de validation chargé dans Project Monitor afin de pouvoir être utilisé par l’application. Ce fichier a pour extension *.jpdl.xml
Fichier BPMN	Fichier créé à partir du modeler Camunda® contenant le code d’un workflow de validation, chargé dans Project Monitor afin de pouvoir être utilisé par l’application. Ce fichier a pour extension *.bpmn
API	Application Programming Interface
REST	Representation State Transfer
HTTP	HyperText Transfer Protocol

Définition de

Principe d’architecture

Le nouveau moteur de workflow Camunda® propose de définir les workflows selon le standard BPMN (Business Process Model and Notation).

Il s’appuie sur l’utilisation des webservices.

Les API que l’on peut appeler dans le modeler Camunda® sont répertoriées dans la page Mémo Webservices selon les standards suivants :

• le principe d’architecture REST (Representational State Transfer),
• le protocole HTTP (Hyper Text Transfer Protocol),
• le format de données JSON (JavaScript Object Notation).

Outils de test

Afin de s’assurer que chaque webservice utilisé dans le modeler Camunda® est juste, il est nécessaire de tester les requêtes au préalable.

Pour se faire plusieurs outils de type API REST :

• Rest Client (Mozilla Firefox ®)
• Postman

🖇️

Pour en savoir plus sur les API REST, consultez le lien suivant :

Une API REST, qu'est-ce que c'est ?

Une API REST (également appelée API RESTful) est une interface de programmation d'application (API ou API web) qui respecte les contraintes du style d'architecture REST et permet d'interagir avec les services web RESTful. L'architecture REST (Representational State Transfer) a été créée par l'informaticien Roy Fielding.

www.redhat.com

Informations générales

Architecture technique

Pour envisager de migrer un environnement client sur le nouveau moteur de Workflow Camunda®, il est nécessaire de déployer Camunda® sur le serveur applicatif.

⏲ La procédure de déploiement est en cours de rédaction !

Modeler Camunda®

Il est nécessaire de disposer du modeler de Camunda® pour générer les fichiers bpmn 👇

https://camunda.com/download/modeler/

Workflow Camunda®

Camunda® vs JPDL

PM avec Camunda®

Principes du workflow dans Project Monitor

Les principes du workflow Project Monitor ne changent pas fondamentalement, la migration vers Camunda® a été pensée de manière ISO à JPDL.

• Aussi, le workflow se déclenche sur le statut de projet, le statut de document ou manuellement.
• Il est hérité du gabarit de création du projet.
• Il avance par validation de tâche.

Selon les webservices publics, il sera même possible d’ajouter des actions à ce jour inexistantes dans JPDL, comme la création de nouveaux objets dans le projet par exemple.

Paramétrage préalable

Activation Add-on

L’activation de l’add-on se fait au niveau MM > Plateformes.

Dans la liste des add-ons, activer l’add-on Workflow.

Utilisateur technique

Pour que Camunda® et Project Monitor puissent fonctionner, il faut créer un utilisateur technique avec les droits suffisants sur les actions de WF à mener.

Il est par conséquent nécessaire d’attribuer à l’utilisateur un rôle général avec des droits étendus.

Concordance des codes

Il est nécessaire pour assurer que le WF soit compatible avec Project Monitor que les codes utilisés dans les webservices correspondent à ceux de Project Monitor :

• Code Rôle
• Code valeur de liste statut tâche
• Code valeur de liste type de tâche
• Code valeur de liste statut projet/jalon/phase
• ...

Les actions workflow Camunda®

Le fichier de workflow de Camunda® doit être créé dans le modeler Camunda®.

Chaque WF doit contenir au minimum :

• un event start,
• une task,
• un event end.

Chaque étape du WF est liée à l’étape suivante par un “flow”.

Structure du modeler

Le modeler de Camunda® est constitué de :

1. Action de WF
2. Schéma
3. Panneau de propriétés

Seuls les boutons d’action suivant sont utilisables en v6.5.2 :

• Event start
• Flow
• Task
• Gateway

Créer un fichier BPMN

🚦

Cette action nécessite un paramétrage.

Pour créer un nouveau fichier de workflow, deux solutions :

• Créer un nouveau fichier et cliquer sur le bouton BPMN diagram (Camunda Platform):
• Utiliser un fichier BPMN existant ci-dessous 👇 en l’ouvrant depuis Fichier > Ouvrir fichier
demo1.bpmn13.0KB

Lors de la création du fichier BPMN, le panel de properties est accessible sur la droite.

Il faut renseigner les éléments structurants suivants qui seront ensuite repris dans Project Monitor :

Camunda®	Project Monitor
id	code
Name	Libellé

Le nom du fichier BPMN à la sauvegarde n’est pas une entrée essentielle car non reprise dans Project Monitor.

En revanche, elle permet de gérer les versions dans votre environnement en développement.

Lors de l’import d’un WF, c’est l’id qui permet d’identifier s’il s’agit d’un nouveau WF ou d’une nouvelle version de WF.

Créer une action

Les actions sont créées par Drag&Drop.

Il suffit de saisir une action dans le menu et de cliquer glisser dans la zone “schéma”.

Idéalement on procédera en deux étapes :

• Modélisation du WF dans son intégralité
• Paramétrage de chaque action

Une fois glissée dans le schéma, chaque action disposera de son propre menu de paramétrage 👉

Au clic sur la clé, le menu s’affiche et permet de déterminer la nature de l’action.

Le panel “properties” s’ouvre pour réaliser le paramétrage.

Chaque paramétrage d’action est détaillé ci-dessous.

Créer un “event start”

✅

Cette action ne nécessite aucun paramétrage.

Chaque WF doit commencer par un évènement. Il est donc nécessaire de créer un Event start 👉

Créer une “task”

🚦

Cette action nécessite un paramétrage.

Le principe du WF de Project Monitor est de travailler avec des tâches de WF, aussi il est nécessaire de matérialiser chaque étape à valider par une Task 👉

Il existe plusieurs types de tâche :

• Les tâches de WS Service task
• Les tâches user User task

Service task

🚦

Le paramétrage est essentiel et DOIT respecter les paramètres et leur casse.

Le service task crée la tâche de WF Project Monitor.

Elle se matérialise par l’icône roue crantée.

Elle utilise dans le panel properties les webservices et les variables de WF.

General

Id	Id de la tâche
Name	Nom de la tâche
Implementation	Connector

Connector

	Nom de la variable	Variable assignment type	Variable assignment value	Valeur
Connector id	http-connector	String or Expression	#NA
Input parameters	headers	Map	Accept	application/json
			Content-type	application/json
			X-PM-API-ID (remplace X-PM-API-LOGIN	user id
			X-PM-API-PASSWORD	user pw
	method	String or Expression	POST
	url	String or Expression	url	http://localhost:8080/monitorupgrade/api
	payload	String or Expression	BeanTacheEntree	Voir liste de variables

Liste des variables Payload

Les variables suivantes sont appelées dans le payload (webservice) pour exécuter les tâches de WF sur le projet et l’instance de WF du projet :

• "projet": { "id": #{execution.getVariable('projectId')}} —> récupère l’id projet de l’instance en cours
• "idInstance":"#{execution.getProcessInstanceId()}” —> récupère l’id de l’instance de WF
• "id": #{execution.getVariable('documentId')} —> récupère l’id document de l’instance en cours
• "idWorkflow":"validation_statut_tache1” —> définit la user task en attente de l’exécution de la tâche
• #{statusCode=='CODE_STATUT_TACHE'}
• #{execution.getVariable('projectLabel')} —>récupère le libellé du projet
• "code" : "CODE-DONNE-POUR-LA-TACHE" —> Permet de déterminer un code pour la tâche
• "parent" : {"code":"CODE-DONNE-POUR-LA-TACHE-PARENTE"} —>Permet de rattacher une tâche à une tâche parente
• "listeRolesParticipants" : ["ARBITRE_DEMANDE","ROLE_CONTRIBUTEUR"] —> Permet de définir une liste de code rôle (exemple : pouvoir notifier plusieurs rôles et participants sur une tâche)
• #{execution.getVariable('userCamundaId')} —> Récupère l’id de l’utilisateur qui exécutera le processus (à renseigner dans le header X-PM-API-ID)
• #{execution.getVariable('codeVar1')} —> Permet de récupérer une variable via Project Monitor (par exemple le code d’un gabarit à appliquer)

Liste des variables URL :

• #{execution.getVariable('projectId')}/attributes/CODEATTRIBUT —> Permet de récupérer la valeur d’un attribut dans Camunda
• http://localhost:#{execution.getVariable('port')}/monitorupgrade/tasks —> Permet d’exécuter le workflow depuis n’importe quel port (autre que le 8080)
• http://localhost:#{execution.getVariable('port')}/monitorupgrade/tasks/parent/#{execution.getVariable('objectId')}/status/#{execution.getVariable('codeVar1')} —> Permet de récupérer l’ID d’une tâche parente (#{execution.getVariable('objectId')}) et de lui appliquer le statut paramétré dans l’automatisation (#{execution.getVariable('codeVar1')})

Connector outputs d’une service task

Il est possible de configurer des “connector outputs” au sein d’une service task afin de recevoir des messages d’information ou d’erreur à l’exécution du web service présent dans un processus dans Project Monitor. Voici le paramétrage à appliquer sur chaque service task :

Process variable name	Assignment type	Format	Type	Script
errorLabel	Script	JavaScript	Inline script	var statusCode = connector.getVariable('statusCode'); if (statusCode >= 400) { var response = JSON.parse(connector.getVariable('response')); if (response.message) { response.message; } else if (response.error) { response.error; } else if (response[0] && response[0].beanWsErreur && response[0].beanWsErreur.message) { response[0].beanWsErreur.message; } }
infosLabel	Script	JavaScript	Inline script	var headers = connector.getVariable('headers'); if (headers.get('X-Context-Info')) { headers.get('X-Context-Info'); }
warningsLabel	Script	JavaScript	Inline script	var headers = connector.getVariable('headers'); if (headers.get('X-Context-Warning')) { headers.get('X-Context-Warning'); }
taskId (uniquement dans une service task de type création de tâche	Script	JavaScript	Inline script	var response = JSON.parse(connector.getVariable('response')); response[0].beanWsItem.id;

User task

✅

Cette action ne nécessite pas de paramétrage

Le user task définit le paramètre d’écoute de la tâche, la plupart du temps le statut tâche et permet l’avancement du WF dans Project Monitor.

Elle se matérialise par l’icône User.

Une tâche user task est toujours précédée d’une service task.

Créer un “flow”

🚦

Cette action peut porter du paramétrage lorsque c’est nécessaire.

L’évènement flow sert à modéliser le chemin du process d’un évènement à un autre 👉

Lorsque le flow porte une décision de WF, il est nécessaire de paramétrer le statut écouté.

General

id	id
Name	Nom
Condition type	Expression
Expression	#{statusCode=='STATUT_TACHE_REFUSEE'}

Créer une “gateway”

Une gateway permet de créer plusieurs chemin de WF.

Deux types de gateway en V6.5.2 fonctionnent correctement :

• Exclusive gateway

Une gateway exclusive permet de déterminer de plusieurs chemins indépendants qui mèneront chacun vers une fin de WF.

• Parallel gateway

Une gateway parallèle permet de créer plusieurs évènements ou tâches en parallèle et qui se rejoignent vers un event end commun.

Créer un “event end”

✅

Cette action ne nécessite pas de paramétrage.

Chaque flow du processus décrit doit finir par un event end.

Sauvegarder le fichier de WF

Le nom de fichier sert à identifier les versions de WF, mais n’est pas utilisé par ailleurs dans Project Monitor.

Configurer les propriétés d’un fichier de workflow ou d’automatisation

À la création d’un fichier BPMN, il faut indiquer s’il sera utilisé comme un workflow ou une automatisation dans Project Monitor. Il faut modifier les propriétés du fichier BPMN dans un éditeur de texte (Notepad par exemple) ou via la fonction afficher au format XML dans Camunda®.

Sur la ligne 2, rechercher la valeur targetNameSpace et indiquer les variables suivantes en fonction du fichier BPMN paramétré :

• targetNamespace="auto" → le fichier est un fichier d’automatisation
• targetNamespace="bpmn" → le fichier est un fichier de workflow

Si le processus doit s’exécuter sur un type de déclencheur particulier, il est possible d’ajouter des extension properties au sein du fichier BPMN global. Il sera demandé de renseigner un nom et une valeur :

Voici toutes les options possibles d’éléments déclencheurs :

Pour que le code variable ne soit plus renseigné manuellement dans Project Monitor, il est possible d’indiquer à Camunda® quel est l’élément concerné par la variable et quelle liste de valeur afficher.

Il suffit d’ajouter de nouvelles extension properties au sein du fichier BPMN :

Exemple 1 :

L’automatisation Modifier le statut des tâches au changement du statut de phase/jalon est paramétrée comme suit :

• targetNamespace=”auto” (propriété présente dans la version XML du fichier BPMN)

• Extension properties :
• forMilestone = true
• forPhase = true
• codeVar1-objectDefinedType = TACHE
• codeVar1-attributeListCode = ETAT

Ce qui veut dire que le fichier est une automatisation (targetNamespace=”auto”), qu’il ne peut se déclencher que sur le statut phase ou jalon (forMilestone et forPhase) et que la variable utilisée dans la propriété “objet unique” se basera sur un attribut de tâche (codeVar1-objectDefinedType = TACHE), qui porte le code ETAT, affichant ainsi la liste associée étant le statut tâche (codeVar1-attributeListCode = ETAT) :

Exemple 2 :

L’automatisation “Appliquer un gabarit” est paramétrée comme suit :

• targetNamespace=”auto” (propriété présente dans la version XML du fichier BPMN)
• Extension properties :
• codeVar1-objectType = GABARIT_PROJET
• codeVar1-permission = ACT_UTILISER_GABARIT_PROJET

Ce qui veut dire que le fichier est une automatisation (targetNamespace=”auto”), qu’il peut s’exécuter sur tous les déclencheurs disponibles, que la variable utilisée dans la propriété “objet unique” se basera sur la liste des gabarits de projet (codeVar1-objectType = GABARIT_PROJET) et vérifiera que l’utilisateur qui paramètrera l’automatisation possède bien le droit Utilisation de gabarits dans les projets tout en respectant le paramétrage de cloisonnement sur la plateforme (codeVar1-permission = ACT_UTILISER_GABARIT_PROJET) :

Créer un workflow conditionné : le cas Appliquer un gabarit

Il est possible de conditionner l’exécution de certains web services paramétrés dans un fichier BPMN via un tableau de décision, configurable dans un fichier DMN (Decision Model and Notation). Un fichier DMN présente un tableau permettant de modéliser des prises de décision et des règles métier via le langage FEEL (Friendly Enough Expression Language), basé sur la création d’expression au lieu de code spécifique.

Pour créer un workflow conditionné, il faudra avoir a minima une business rule task, des flows conditionnés et créer un fichier DMN en plus du fichier BPMN représentant le workflow.

Dans l’exemple ci-dessous, un gabarit sera appliqué en fonction des informations récupérées sur le projet (informations des attributs budget et ressource) :

Créer une service task pour récupérer les informations projet

Créer une service task permet de récupérer une information d’un attribut projet. Si l’instance décisionnelle doit récupérer plusieurs informations, créer autant de service task qu’il y a d’informations à récupérer. Ces service task doivent être positionnées soit successivement, soit entre deux parallel gateway.

Connector inputs

Connector outputs (sera utilisé dans le fichier DMN)

Créer une business rule task

La business rule task récupère les informations de décision et règles métier présentes dans le fichier DMN pour exécuter la bonne décision dans le processus.

Elle se matérialise par l’icône tableau.

General

Id	Id de la business rule task
Name	Nom de la business rule task

Output (pour renvoyer une erreur s’il n’y a pas de décision trouvée)

Process variable name	errorCode
Assignment type	String or expression
Expression	#{execution.getVariable('result')==null?'ERR_WORKFLOW_NO_DECISION':null}

Implementation

Type	DMN
Decision reference	ID de la decision
Binding	Latest
Tenant ID
Result variable	result
Map decision result	Sélectionner la méthode de résultat à appliquer

Créer un “flow” décisionnel

🚦

Le paramétrage est essentiel et DOIT respecter les paramètres.

L’événement flow décisionnel sert à modéliser le chemin du process d’un événement à un autre en fonction du résultat trouvé dans un tableau décisionnel. Cela permet d’indiquer en cas de résultat nul ou non nul, le chemin à prendre pour continuer le workflow.

id	id
Name	Nom
Condition type	Expression
Expression pour résultat non nul	#{execution.getVariable('result')!=null}
Expression pour résultat nul	#{execution.getVariable('result')==null}

Dans l’exemple ci-contre, le workflow appliquera le gabarit si tous les paramètres récupérés sont réunis pour exécuter une décision. Si les paramètres récupérés ne permettent pas d’exécuter une décision, alors le workflow prend fin.

Créer une service task pour exécuter la décision

General

Id	Id de la service task
Name	Nom de la service task

Implementation

Type	Connector
Connector ID	http-connector

Connector inputs

Connector outputs

Créer un fichier DMN

Créer un fichier DMN permet de configurer un tableau de décisions à exécuter en fonction des règles établies.

Un fichier DMN a forcément un nom et un ID. Dans notre exemple, le fichier DMN va analyser les informations récupérées en amont des attributs budget et ressource pour vérifier s’il y a une règle qui répond à une décision à exécuter :

• Le gabarit “Projet standard” sera appliqué sur le projet en instance de workflow si le budget est supérieur à 50000€ et les ressources supérieures à 150 j/h
• Le gabarit “Cycle en V” sera appliqué sur le projet en instance de workflow si le budget est inférieur ou égal à 50000€ et les ressources inférieures ou égales à 150j/h
• Le workflow se terminera si aucune décision n’est trouvée (flow conditionnés sur le fichier BPMN)

Fonctionnement dans Project Monitor

Une fois réalisée la modélisation du process dans le modeler Camunda®, il est possible de le charger dans Project Monitor.

Toutefois, il est nécessaire de s’assurer que l’add-on a été activé.

Activation de l’Add-on

L’activation de l’Add-on se fait au niveau MM, connecté en savirage.

Dès que l’add-on est activé, plusieurs conséquences sont effectives dans Project Monitor :

Proposition de check list avant activation de l’add-on :

Upload WF

L’administration des WF se fait de la même manière qu’avec les fichiers JPDL, depuis l’administration avancée > Workflow.

Plusieurs WF peuvent être chargés dans Project Monitor. Plusieurs versions de WF peuvent être chargées au fur et à mesure de l’évolution des processus.

Le versionning permet aux projets existants engagés dans un processus de terminer l’ensemble des étapes quand bien même le processus aurait changé.

Camunda® apporte la possibilité de visualiser les schéma de WF, les instances en cours à chaque étape, naviguer vers les instances de projet.

Les fichiers DMN se charge de la même manière que les fichiers BPMN dans Project Monitor mais ne seront pas visibles dans l’administration de Project Monitor. Il faut se connecter à Camunda Cockpit pour visualiser le fichier DMN chargé dans Project Monitor.

Associer le WF à un gabarit

Le WF a été importé dans l’administration, il faut alors l’associer à un gabarit.

C’est la seule manière à partir de laquelle un projet hérite d’un WF sous-jacent.

Si le projet n’a pas été créé depuis le gabarit il est possible a posteriori d’appliquer unitairement ou en masse le gabarit aux projets. Il deviendra ainsi possible de déclencher le WF sur les projets existants.

Définir un statut déclencheur

Lors de l’association d’un WF à un gabarit, il est possible de définir le mode de déclenchement du WF sur les projets :

• déclenchement manuel
• déclenchement par statut projet
• déclenchement par statut document
• déclenchement par statut de tâche
• déclenchement par statut de phase
• déclenchement par statut de jalon
• déclenchement par valeur d’attribut

Il suffira alors de sélectionner la valeur de liste dans le sélecteur proposé :

Si le déclenchement se fait sur le statut tâche, phase ou jalon, alors il est possible de définir le type de tâche, phase ou jalon sur lequel le processus sera déclenché :

Si le déclenchement se fait sur le statut document, tâche, phase ou jalon, alors il est possible d’exécuter le processus sur le dernier élément déclencheur (par exemple, le gabarit sera appliqué lorsque tous les documents du projet seront validés) :

Visualisation des WF

Il existe deux modes de visualisation des workflows :

• La visualisation dans le projet
• La visualisation en admin

Visualisation projet

Visualisation admin

Historique des workflows

Chaque définition de workflow dispose de son propre historique. Cela permet d’identifier quelles création/modification/suppression ont été réalisées.

Exemple de fichier de Workflow

Exemple workflow conditionné + tableau décisionnel

Exemple avec libellé du projet dans le libellé de la tâche

Exemple avec lien entre 2 tâches

Exemple avec Notification de plusieurs participants

Automatisations

FAQ