1. À quoi sert un webhook ?

Un webhook est un moyen de notifier une application tierce lorsqu’un évènement défini dans Project Monitor survient. Par exemple, vous pouvez déclencher la création d’un espace SharePoint lorsqu’un nouveau projet est créé dans Project Monitor.

Lorsqu’un évènement survient dans Project Monitor, le webhook créé dans Project Monitor appelle un Web Service défini dans l’application tierce. Il est donc nécessaire que l’application tierce définisse des Web Services.

Les web services SOAP ne sont pas supportés.

Le webhook peut transmettre à l’application tierce des données simples sur l’objet à l’origine du déclenchement (id, code ou libellé). Ces informations sont paramétrées dans le webhook et dépendent des possibilités du Web Service appelé.

Eventuellement, l’application tierce peut ensuite interroger Project Monitor pour obtenir plus d’informations sur les objets de Project Monitor. L’application tierce peut donc, à son tour, appeler un web service de Project Monitor (voir notre mémo web services à ce sujet).

L’application tierce peut de cette manière surveiller les changements au sein de Project Monitor pour synchroniser ses informations ou procéder à des traitements spécifiques suite à ces changements.

• Un évènement déclenche une requête HTTP POST vers une URL configurée sur l’application tierce.
• Les évènements déclencheurs :
• Création, modification et/ou suppression d’un utilisateur
• Création, modification et/ou suppression d’un projet
• La requête HTTP retourne l’id, le code ou le libellé de l’objet déclencheur.

2. Paramètrage des webhooks

2.1 Définition d’un webhook

L’accès au paramétrage des webhooks se fait dans le thème admin, carte « Webhook » :

Un webhook est défini par :

• Un événement au sein de Project Monitor, par exemple une modification de projet,
• Une URL à appeler en HTTP ou HTTPS,
• La méthode attendue par l’application tierce (GET, POST, …)
• Des paramètres passés en header, utilisés par exemple pour l’authentification
• Un paramètre BODY pour les méthodes de type POST, PUT ou PATCH
• Un mode d’appel parmi les deux suivants :
• Synchrone : L’action de l’utilisateur dans PM qui déclenche l’événement se termine quand la notification vers l’application tierce est terminée.

Si une erreur lors de l’appel à l’application tierce survient, le code statut en erreur est affiché à l’écran.

NOTA BENE : Dans ce mode, les performances de Project Monitor sont altérées par le temps d’exécution du web service de l’application tierce.

• Synchrone exécuté dans la transaction : L’erreur empêche l’action dans Project Monitor.
• Synchrone exécuté en dehors de la transaction : L’action est exécutée même si la notification renvoie une erreur.
• Asynchrone : L’action se termine dans Project Monitor et la notification est faite à la suite. Si une erreur lors de la notification intervient, elle visible uniquement dans les commandes en cours et dans le fichier de log de l’application. Il s’agit du paramétrage recommandé et par défaut.

Par exemple, si un utilisateur modifie une propriété d’un projet, PM appelle le web service désigné par le webhook associé.

Si on est en mode synchrone, PM attends le retour du webservice avant de finir l’action et de rendre la main à l’utilisateur. Si une erreur survient et que l’appel se fait dans la transaction, la modification de la propriété est annulée, sinon, si l’appel se fait en dehors de la transaction, la modification de la propriété est tout de même effectuée.

Si on est en mode asynchrone, la modification de la propriété est effectuée et l’appel au webservice est fait par la suite, en tâche de fond.

Il est possible de désactiver un webhook. Dans ce cas aucun appel n’est exécuté suite à l’action dans Project Monitor.

Exemple de définition d’un webhook :

Il est possible de désactiver les webhooks depuis le fichier properties de Project Monitor. Voici ci-dessous les deux nouveaux paramètres à mettre en place :

#com.vc.mm.webhook.disabled=true / false

• La valeur « true » permet de désactiver les webhooks sur Project Monitor
• La valeur « false » permet d’activer les webhooks sur Project Monitor (valeur par défaut)

#com.vc.mm.webhook.exception=https://webhook.site

• Si la désactivation des webhooks est activée « true » alors :
• Tous les webhooks sont désactivés sauf ceux dont l’url commence par (dans notre exemple) https://webhook.site
• Depuis l’interface de PM une bannière rouge est affichée « Seuls les webhooks dont les URLs commençant par https://webhook.site sont actifs (après résolution de la formules) » :

• Par défaut la propriété est vide, il n’y a donc pas d’exception

Il est possible de tester des chaines dans l’URL des webhooks via le paramètre suivant dans le fichier properties de Project Monitor :

com.vc.atlas.formule.env_pm=dev

• Exemple d’URL dans la définition du webhook :

'https://'+(CONFIG.env_pm.equals('dev')?'webhook.site':'monServeurTest')+'/90cd2995-6d8c-4424-a7d5-edf451311819?id='+OBJET.ID

• Si « env_pm » est égale à « dev » alors l’URL sera :
Copy

https://webhook.site/90cd2995-6d8c-4424-a7d5-edf451311819?id=332499

• Si « env_pm » n’est pas égale à « dev » alors l’URL sera :
Copy

https://monServeurTest/90cd2995-6d8c-4424-a7d5-edf451311819?id=332499

• Si le client dispose de 2 plateformes « TEST » et « PROD » ce paramètre permet de différencier les webhooks de « PROD » et de « TEST » dans une seule URL.

2.2 Événements des webhooks

Le webhook est déclenché sur un événement dans Project Monitor.

Cet événement est défini par un objet de l’application (Projet, Utilisateur) et une action (Création, Modification, Suppression ou Toutes actions).

Depuis la version 6.2.1 :

• Un évènement a été ajouté et il est défini par l’objet de l’application phase et une action (Création, Modification, Suppression ou Toutes actions)
• Il est désormais possible de filtrer sur les projets. Si le filtre est activé alors le webhook sera déclenché que sur les projets filtrés. Ce filtre est activable seulement pour les objets phase et projet.

Dans le tableau ci-dessous, vous pouvez noter quelles actions dans Project Monitor déclenchent les événements des webhooks :

Événement de modification

Pour un projet les actions suivantes déclenchent les webhooks associés en modification :

• Modification d’une propriété (code, libellé, statut, chef de projet, …)
• Modification d’un attribut
• Modification d’un rattachement
• Modification de l’équipe
• Modification des liens projets
• Modification du gabarit

Pour un utilisateur les actions suivantes déclenchent les webhooks associés en modification :

• Modification d’une propriété (login, nom, prénom, date de fin, …)
• Modification d’un rôle général

Pour une phase les actions suivantes déclenchent les webhooks associés en modification :

• Modification d’une propriété (nom, code, date de début, date de fin, …)
• Modification d’un attribut
• Modification de la dépendance
• Modification d’un document

2.3 Paramétrage des données des webhooks

Il est possible de paramétrer l’url, le body et les headers avec des variables de Project Monitor.

Dans ce cas, il est nécessaire d’entourer les parties fixes par des apostrophes et de concaténer les variables avec le signe « + » comme pour les attributs ou mesures calculées.

• Headers

Content-Type: application/json; charset=utf-8

project-id : OBJET.ID

info : ‘Modification ‘+OBJET.ID

• Body

‘{ idObjet :’+ OBJET.ID+ ‘}’

• URL

L’URL sera construite de la même façon :

Par exemple, l’URL peut avoir la forme suivante :

'https://application-tierce/url-web-service?id='+OBJET.ID

Il existe 4 types de variables :

• OBJET : information sur l’objet (Projet, Utilisateur, Phase) ayant déclenché la notification (propriétés disponibles : ID, CODE et LIBELLE)
• UP_ATTRIBUT : un attribut texte de la plateforme identifié par son code.
• CONFIG : reprise d’une valeur définie dans le fichier de configuration de Project Monitor, par exemple un nom de serveur. La variable CONFIG n’est utilisable qu’en installation on-premise et donc non disponible en SaaS.
• OBJET_ATTRIBUT : information sur un attribut (Projet et Phase) ayant déclenché la notification (propriété disponible : code de l’attribut recherché)
• Exemple : OBJET_ATTRIBUT.CODE_ATTRIBUT

2.4 Fonction de test

Sur la fiche d’un webhook, il est possible de tester celui-ci par un clic sur la roue crantée.

Vous pouvez alors sélectionner un projet ou un utilisateur pour simuler l’événement.

Lors d’un lancement de test, Project Monitor procède à un enregistrement préalable de votre webhook.

Lors du test, il y a plus d’information envoyé à l’utilisateur, notamment les résultats correspondants aux valeurs calculés.

À titre d’information, le site http://webhook.site permet de simuler une application tierce et de recevoir les appels effectués par Project Monitor. Bien entendu, Virage Group n’opère de support sur ce site fourni par : https://github.com/fredsted/webhook.site.

2.5 Les messages d’erreur

Sur Project Monitor les messages d’erreur sur les webhooks sont générés dès qu’une application tierce répond avec un code statut d’erreur supérieur à 299. L’éventuel « body » de la réponse du webhook est rajouté au message d’erreur de Project Monitor.

Le message d’erreur est générique avec une partie variable comportant le libellé du webhook, le code du statut et le message d’erreur. Exemple ci-dessous :

« Le webhook ‘TEST’ a répondu une erreur (code status :400) message d’erreur 19/3/18 17 :19 »

Le message « message d’erreur » correspond au body de réponse de l’application tierce.

Voici ci-dessous un exemple de « message d’erreur » retourné par l’application tierce vers Project Monitor :

• La valeur « WEBHOOK_1 » correspond au « libellé » du Webhook inscrit dans PM :

• Le code statut « 300 » et le message d’erreur sont définissables dans l’application tierce :
• Le format du message d’erreur dans le body est « texte libre, format JSON ».