‣

Table of contents

‣

history changes

1. What's a webhook for?

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. Voir Webhook Webhooks memo

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.

SOAP web services are not supported.

The webhook can transmit simple data (id, code or label) about the triggering object to the third-party application. This information is parameterized in the webhook and depends on the capabilities of the Web Service called.

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.

• An event triggers an HTTP POST request to a URL configured on the third-party application.
• Triggering events :
• Creating, modifying and/or deleting a user
• Creating, modifying and/or deleting a project
• The HTTP request returns the id, code or label of the trigger object.

2. Paramétrage des webhooks

2.1 Definition of a webhook

Accéder au paramétrage : Administration > Paramétrages avancés > Configuration technique > Webhook

A webhook is defined by :

• A é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
• One of two call modes:
• Synchronous : L’action de l’utilisateur dans Project Monitor qui déclenche l’événement se termine quand la notification vers l’application tierce est terminée.

If an error occurs when calling the third-party application, the code status in error is displayed on the screen.

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, Project Monitor appelle le web service désigné par le webhook associé.

Si on est en mode synchrone, Project Monitor attend 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.

In asynchronous mode, the property is modified and the webservice is called afterwards, in the background task .

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

Example of a webhook definition :

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

• If webhook deactivation is set to "true", then :
• Tous les webhooks sont désactivés sauf ceux dont l’url commence par (dans notre exemple) https://webhook.site
• Depuis l’interface de Project Monitor 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) » :

• By default, the property is empty, so there is no 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.formula.env_pm=dev

• Example of URL in webhook definition :

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

• If env_pm is égal à dev alors l’URL sera :
Copy

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

• If env_pm n’est pas égal à dev alors l’URL sera :
Copy

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

• If the customer has 2 platforms, "TEST" and "PROD", this parameter differentiates between "PROD" and "TEST" webhooks in a single URL.

2.2 Webhook events

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

This event is defined by an application object (Project, User) and a action (Create, Modify, Delete or All actions).

Since version 6.2.1 :

• An event has been added, defined by the application object phase and a action (Create, Modify, Delete or All actions).
• It is now possible to filter on projects. If the filter is activated, the webhook will only be triggered on filtered projects. This filter can only be activated for phase and project objects.

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

Event	Creation Project Monitor	Modification Project Monitor	Suppression Project Monitor
PROJECT/Creation	Notified
PROJECT/Modification		Notified	Notified
PROJECT/Deletion			Notified
PROJECT/All actions	Notified	Notified	Notified

Event	Creation Project Monitor	Modification Project Monitor	Suppression Project Monitor
USER/Creation	Notified
USER /Modification		Notified
USER /Delete			Notified
USER /All actions	Notified	Notified	Notified

Event	Creation Project Monitor	Modification Project Monitor	Suppression Project Monitor
PHASE/Creation	Notified
PHASE/Modification		Notified
PHASE/Deletion			Notified
PHASE/All actions	Notified	Notified	Notified

Modification event

For a project, the following actions trigger the associated modification webhooks:

• Property modification (code, label, status, project manager, ...)
• Modification of a attribute
• Modification of a structure link
• Team modification
• Modifying project links
• Modification of the template

For a user, the following actions trigger the associated webhooks in modification mode:

• Modification of a property (login, last name, first name, end date, etc.)
• Modification of a general role

For a phase the following actions trigger the associated webhooks in modification :

• Property modification (name, code, start date, end date, etc.)
• Modification of a attribute
• Modification of dependency
• Modification of a document

2.3 Setting up webhook data

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: OBJECT.ID

info : 'Modification'+OBJET.ID

• Body

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

• URL

The URL will be built in the same way:

For example, the URL could take the following form:

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

There are 4 types of 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 Test function

On the webhook page, you can test the webhook by clicking on the cogwheel.

You can then select a project or user to simulate the event.

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

During the test, more information is sent to the user, including the results corresponding to the calculated values.

À 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 Error messages

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.

The message error code is generic, with a variable part containing the webhook label, the status code and the message error code. Example below:

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

The message " message error" corresponds to the response body of the third-party application.

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 Project Monitor :

• The status code "300" and the message error code can be defined in the third-party application:
• The message error format in the body is "free text, JSON format".