Logo
  • Other versions
  • Virage Group
  • Espace Magenta
  • Support ticket
  • Strat Monitor documentation
Project Monitor v7.7 Knowledge Center
Project Monitor v7.7 Knowledge Center
/Technical memos
Technical memos
/Webhooks memo
Webhooks memo
Webhooks memo

Webhooks memo

‣
Table of contents

1. What's a webhook for?

icon

Webhook A webhook is a way of notifying a third-party application when an event defined in Project MonitorProject Monitor occurs. For example: you can trigger the creation of a SharePoint space when a new project is created in Project MonitorProject Monitor. See WebhookWebhook Webhooks memoWebhooks memo

When an event occurs in Project MonitorProject Monitorthe webhook created in Project MonitorProject Monitor calls a Web Service defined in the third-party application. It is therefore necessary for the third-party application to define 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.

If required, the third-party application can then query Project MonitorProject Monitor to find out more about the objects in the Project MonitorProject Monitor. The third-party application can then, in turn, call a web service from Project MonitorProject Monitor (see our web services memo on this subject).

In this way, the third-party application can monitor changes within the Project MonitorProject Monitor to synchronize its information or carry out specific processing following these changes.

  • 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.
Figure 1: Webhooks logic diagram
Figure 1: Webhooks logic diagram

2. Setting up webhooks

2.1 Definition of a webhook

Go to settings : AdministrationAdministration >Advanced settings > Technical configuration > WebhookWebhook

A webhook is defined by :

  • A event within Project MonitorProject Monitorfor example, a project modification,
  • A URL to call in HTTP or HTTPS,
  • The method expected by the third-party application (GET, POST...)
  • Parameters passed in header, used for authentication, for example
  • A BODY parameter for POST, PUT or PATCH methods
  • One of two call modes:
    • Synchronous Useraction in Project MonitorProject Monitor that triggers the event ends when the notification to the third-party application is completed.
        • If an error occurs when calling the third-party application, the error status code is displayed on the screen.

        NOTE: In this mode, the performance of the Project MonitorProject Monitor are altered by the execution time of the third-party application's web service.

      1. Synchronous execution in the transaction Error preventsaction in Project MonitorProject Monitor.
      2. Synchronous executed outside the transaction: Theaction is executed even if the notification returns an error.
    • Asynchronous action ends in Project MonitorProject Monitor and notification follows. If an error occurs during notification, it is visible only in the current commands and in the application log file. This is the recommended and default setting.
      • For example, if a user modifies a project property, Project MonitorProject Monitor calls the web service designated by the associated webhook.

      If in synchronous mode, Project MonitorProject Monitor waits for the webservice to return before completing theaction and handing over to the user. If an error occurs and the call is made within the transaction, the property modification is cancelled, otherwise, if the call is made outside the transaction, the property modification is carried out anyway.

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

It is possible to deactivate a webhook. In this case, no call is executed following theaction in Project MonitorProject Monitor.

Example of a webhook definition :

Figure 3: Webhook settings
Figure 3: Webhook settings

Webhooks can be disabled in the properties file of the Project MonitorProject Monitor. Here are the two new parameters to be set:

#com.vc.mm.webhook.disabled=true / false
  • The value "true" deactivates webhooks on Project MonitorProject Monitor
  • The "false" value enables webhooks on Project MonitorProject Monitor (default value)
#com.vc.mm.webhook.exception=https://webhook.site
  • If webhook deactivation is set to "true", then :
    • All webhooks are disabled except those whose url starts with (in our example) https://webhook.site
    • From the Project MonitorProject Monitor a red banner is displayed "Only webhooks with URLs starting with https://webhook.site are active (after solving the formula)":
Figure 4: Webhook exceptions banner
Figure 4: Webhook exceptions banner
  • By default, the property is empty, so there is no exception.

It is possible to test strings in webhook URLs via the following parameter in the properties file of Project MonitorProject Monitor :

com.vc.atlas.formula.env_pm=dev
  • Example of URL in webhook definition :
Figure 5: sample URL
Figure 5: sample URL
https://'+(CONFIG.env_pm.equals('dev')?'webhook.site':'monServeurTest')+'/90cd2995-6d8c-4424-a7d5-edf451311819?id='+OBJET.ID
  • If env_pm is equal to dev then the URL will be :
    • https://webhook.site/90cd2995-6d8c-4424-a7d5-edf451311819?id=332499
  • If env_pm is not equal to dev then the URL will be :
    • 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

The webhook is triggered by an event in Project MonitorProject Monitor.

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

  • An event has been added, defined by the phase application object and an action (Create, Modify, Delete or All actions).
  • It is 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.

In the table below, you can note which actions in the Project MonitorProject Monitor trigger webhook events:

Event
Creation Project MonitorProject Monitor
Modification Project MonitorProject Monitor
Delete Project MonitorProject Monitor
PROJECT/Creation
Notified
PROJECT/Modification
Notified
Notified
PROJECT/Deletion
Notified
PROJECT/All actions
Notified
Notified
Notified
Event
Creation Project MonitorProject Monitor
Modification Project MonitorProject Monitor
Delete Project MonitorProject Monitor
USER/Creation
Notified
USER /Modification
Notified
USER /Delete
Notified
USER /All actions
Notified
Notified
Notified
Event
Creation Project MonitorProject Monitor
Modification Project MonitorProject Monitor
Delete Project MonitorProject Monitor
PHASE
Notified
PHASE
Notified
PHASE
Notified
PHASE actions
Notified
Notified
Notified

Modification event

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

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

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

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

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

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

2.3 Setting up webhook data

It is possible to parameterize the url, body and headers with Project MonitorProject Monitor.

In this case, it is necessary to surround fixed parts with apostrophes and concatenate variables with the sign + as for calculated attributes or measures.

  • Headers

In the Headers field, you must specify one header per line. A line is in the form <nom header> :<valeur header>. The header value can contain : but not the header name (the front part :).

For example, header without variable part:

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

Example with a variable part (object.id) :

project-id: OBJECT.ID

or

info : 'Modification'+OBJET.ID
  • Body

In the Body field, you specify a string that can be formatted in JSON, for example, as long as you respect the concatenation rule for fixed and variable parts, such as :

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

The URL will be constructed 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:

  • OBJECT: information on the object (Project, User, Phase) that triggered the notification (available properties: ID, CODE and LIBEL)
  • UP_ATTRIBUT: a platform text attribute identified by its code.
  • CONFIG transfer of a value defined in the Project MonitorProject Monitorfor example, a server name.
    • 🚦

    The CONFIG variable can only be used in On Premise installations, and is therefore not available in SaaS.

  • OBJECT_ATTRIBUT: information on an attribute (Project and Phase) that triggered the notification (available property: code of theattribute searched for).
    • Example: OBJECT_ATTRIBUT.CODE_ATTRIBUT
‣

The 'CONFIG' variable (not available in SaaS)

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.

During a test launch, Project MonitorProject Monitor pre-register your webhook.

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

For your information, the http://webhook.site allows you to simulate a third-party application and receive calls made by Project MonitorProject Monitor. Of course, Virage GroupVirage Group does not support this site provided by: https://github.com/fredsted/webhook.site.

2.5 Error messages

On Project MonitorProject Monitor webhook error messages are generated as soon as a third-party application responds with an error status code greater than 299. The webhook response body, if any, is added to the error message from Project MonitorProject Monitor.

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

"The webhook 'TEST' responded an error (status code:400) errormessage 19/3/18 17:19"

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

Below is an example of the "error message " returned by the third-party application to Project MonitorProject Monitor :

Figure 6: Webhook error message
Figure 6: Webhook error message
  • The "WEBHOOK_1" value corresponds to the Webhook "label" entered in the Project MonitorProject Monitor :
Figure 7: Webhook label
Figure 7: Webhook label
  • status code "300" and error message can be defined in the third-party application:
    • The format of the error message in the body is "free text, JSON format".
Figure 8: Third-party application settings in the event of an error
Figure 8: Third-party application settings in the event of an error
Logo

Produced by Virage Group