Les webhooks sont une méthode largement utilisée pour permettre à plusieurs applications d’interagir les unes avec les autres, en utilisant des requêtes HTTP POST pour se transmettre des rappels. Pour plus d’informations, consultez la page de Wikipedia sur les webhooks. Les webhooks sont couramment utilisés pour envoyer des notifications par e-mail ou par SMS, publier des messages sur les réseaux sociaux, écrire automatiquement du contenu dans une feuille de calcul et mettre à jour les bases de données d’entreprise.
Dans ArcGIS Survey123, il est désormais possible de configurer et d’activer les webhooks lorsqu’une réponse à une enquête est envoyée. Par exemple, après un envoi réussi d’informations à une couche d’entités, l’appel du webhook peut déclencher une autre action, notamment l’envoi d’un courrier électronique de notification, l’ajout du contenu de l’enquête à une feuille de calcul et l’envoi d’une alerte.
Outre le fournisseur de webhooks attitré de votre lieu de travail, divers services de processus tiers sont disponibles, parmi lesquels Microsoft Power Automate, Make (auparavant Integromat), Zapier et tray.io. Tous ces services peuvent servir à incorporer Survey123 comme déclencheur pour un processus automatisé. Ainsi, Microsoft Power Automate et Make ont chacun un connecteur Survey123 intégré, ce qui vous permet d’incorporer Survey123 à votre processus de webhook simplement, et sans avoir besoin de configurer le webhook dans le site Web Survey123 ou de saisir une payload URL.
Attention :
Lorsque vous créez ou modifiez un webhook pour une enquête, cette dernière doit être mise à jour dans l’application de terrain Survey123 pour que les modifications prennent effet.
Il existe de nombreuses façons d’utiliser Survey123 comme déclencheur dans vos processus. Les trois sections suivantes expliquent comment configurer un webhook pour envoyer un courrier électronique de notification quand une réponse reçue à une question contient une certaine valeur.
À la fin de cette rubrique, toutes les propriétés disponibles dans la charge utile d’événement du webhook sont répertoriées à titre de référence.
Configurer un webhook dans Make
Make (auparavant Integromat) est une plateforme d’automatisation en ligne. Connectez-vous à un compte gratuit pour commencer. Make possède des modèles à utiliser comme point de départ pour inclure des pièces jointes dans vos notifications électroniques, ajouter des enregistrements aux feuilles de calcul et créer des éléments de calendrier.
- Accédez à https://www.make.com/ et connectez-vous.
- Sur la page Scenarios, cliquez sur le bouton Create a new scenario (Créer un scénario).
- Cliquez sur l’icône du module au milieu de l’écran. Recherchez Survey123 et sélectionnez-le.
- Sélectionnez le module déclencheur Watch survey (Visionner l’enquête).
Ce module est conçu pour exécuter le scénario à chaque fois qu’une réponse est envoyée à l’enquête.
Une fenêtre contextuelle s’affiche pour vous aider à configurer le module Watch survey (Visionner l’enquête).
Conseil :
Il est également possible d’utiliser le module Create report (Créer des rapports) pour générer un rapport dans le cadre d’une réponse à l’enquête.
- Cliquez sur Add (Ajouter) et attribuez un nom à votre webhook.
Ce nom doit être exclusif à l’enquête pour laquelle vous configurez le webhook.
- Si vous utilisez le module Survey123 pour la première fois dans Make, configurez une connexion à votre organisation ArcGIS. Vous n’aurez à le faire qu’une fois, car Make enregistre vos informations pour une utilisation ultérieure. Sous Connection (Connexion), cliquez sur Add (Ajouter) et nommez la connexion à ArcGIS.
- Pour vous connecter à ArcGIS Online, cliquez sur Save (Enregistrer) afin de vous connecter à votre organisation ArcGIS.
- Pour vous connecter à ArcGIS Enterprise, inscrivez Make auprès de votre portail. Pour plus d’informations, reportez-vous à l’article de blog Survey123 Tricks of the Trade: Make.
- Sélectionnez, à partir de votre organisation ArcGIS, une enquête à laquelle vous voulez vous connecter.
- Pensez aux options à inclure dans votre webhook, et cliquez sur Save (Enregistrer).
Il est recommandé de conserver la valeur par défaut Yes (Oui) pour tous les paramètres avancés, ce qui vous confère le plus de flexibilité lors de la personnalisation de votre webhook.
- Cliquez sur OK.
Votre webhook est créé et le module Watch survey (Visionner l’enquête) est configuré.
- Cliquez sur le bouton Add another module (Ajouter un autre module) sur le côté droit du module Watch survey (Visionner l’enquête) pour y connecter un autre module.
- Recherchez Email (Courrier électronique) et sélectionnez le module Email (Courrier électronique).
- Sélectionnez l’action Send an email (Envoyer un message électronique).
- Si vous utilisez ce module pour la première fois dans Make, cliquez sur Add (Ajouter) pour configurer une connexion dans votre compte de messagerie. Sélectionnez un type de connexion et connectez-vous à votre compte.
Vous n’aurez à le faire qu’une fois, car Make enregistre votre connexion en vue d’une utilisation ultérieure.
- Ajoutez l’adresse électronique d’un destinataire.
Il s’agit de l’adresse électronique à laquelle les messages seront envoyés.
- Cliquez dans la zone de texte « Objet ». Sélectionnez des champs de votre enquête pour construire l’objet du message électronique à l’aide du volet de paramètres du module qui apparaît.
- Cliquez dans la zone de texte « Contenu ». Sélectionnez des champs de votre enquête pour construire le contenu du message électronique à l’aide du volet de paramètres du module qui apparaît. Vous pouvez utiliser le format HTML pour le contenu.
- Cliquez sur OK.
Ce scénario doit envoyer le message électronique lorsqu’une réponse est apportée à une question d’une certaine façon, de sorte que vous fournirez un filtre.
- Cliquez sur le bouton d’outils entre les deux modules et sélectionnez Set up a filter (Configurer un filtre).
- Cliquez dans la zone de texte Condition et choisissez le champ dans votre enquête à utiliser dans le filtre.
- Choisissez l’opérateur pour la condition. Dans ce cas, choisissez la valeur par défaut, Equal to (Égal à).
- Entrez une valeur pour la condition et cliquez sur OK.
- Cliquez sur Save (Enregistrer) pour enregistrer votre scénario.
Vous pouvez également cliquer sur Run once (Exécuter une fois) pour tester votre webhook. Après avoir cliqué sur Run once (Exécuter une fois), ouvrez Survey123 et soumettez une enquête, en vérifiant que la réponse respecte les filtres appliqués. Vérifiez que le destinataire a reçu le message électronique.
- Utilisez le bouton bascule en bas à gauche de la page pour activer votre scénario. Réglez la planification sur Immediately (Immédiatement) pour que votre scénario s’exécute chaque fois qu’une réponse à l’enquête est soumise.
Pour découvrir de nouvelles façons d’utiliser Survey123 comme déclencheur dans vos scénarios Make, consultez les intégrations Survey123.
Configurer un webhook dans Microsoft Power Automate
Microsoft Power Automate est un service webhook disponible sur la plateforme Microsoft Office 365.
Remarque :
Les informations d’identification ArcGIS Online utilisées pour créer des flux dans Power Automate sont automatiquement déconnectées après deux semaines. Si vous ne parvenez pas à explorer les enquêtes attendues dans Power Automate, vérifiez que votre connexion aux données Survey123 est active. Pour plus d’informations, reportez-vous à l’article de blog Quick Tip: Keeping the ArcGIS Connectors for Power Automate Refresh Token Valid.
Pour configurer un flux dans Microsoft Power Automate à l’aide des connecteurs ArcGIS ou ArcGIS Enterprise, procédez comme suit. Si vous avez déjà créé des flux avec le connecteur Survey123, ils continueront de fonctionner, mais les nouvelles fonctions seront uniquement ajoutées aux connecteurs ArcGIS et ArcGIS Enterprise. Pour plus d’informations, reportez-vous à l’article de blog Survey123 triggers and actions in the ArcGIS connectors for Power Automate.
- Ouvrez Microsoft Power Automate.
- Sélectionnez Create (Créer) dans le menu latéral de la page.
- Sélectionnez Automated cloud flow (Flux cloud automatisé) à partir des options Start from blank (Commencer à partir de zéro).
La boîte de dialogue Build an automated cloud flow (Créer un flux cloud automatisé) apparaît.
- Donnez un nom au flux.
Vous allez ensuite sélectionner un déclencheur.
- Saisissez ArcGIS dans la barre de recherche, puis sélectionnez When a survey response is submitted (Quand une réponse à une enquête est envoyée).
Attention :
Sélectionnez l’option When a survey response is submitted (Quand une réponse à une enquête est envoyée) sous ArcGIS si le flux nécessite que vous vous connectiez à une organisation ArcGIS Online. Sélectionnez l’option When a survey response is submitted (Quand une réponse à une enquête est envoyée) sous ArcGIS Enterprise si le flux nécessite que vous vous connectiez à une organisation ArcGIS Enterprise.
- Cliquez sur Create (Créer).
- Si vous utilisez pour la première fois ce connecteur dans Microsoft Power Automate, cliquez sur Sign In (Se connecter) pour vous connecter avec vos identifiants de connexion d’organisation ArcGIS.
Vous n’aurez à vous connecter qu’une fois, car Microsoft Power Automate enregistre vos identifiants de connexion pour une utilisation ultérieure.
- Sélectionnez l’enquête que vous souhaitez utiliser avec le webhook dans la liste déroulante des enquêtes.
Vous avez maintenant configuré le déclencheur pour le webhook. Toutefois, pour que le webhook exécute des actions avec ce déclencheur, il reste à réaliser d’autres étapes.
Le flux doit envoyer un message électronique lorsqu’une réponse est apportée à une question d’une certaine façon de sorte que vous fournissiez une condition.
- Cliquez sur le bouton New Step (Nouvelle étape), puis sélectionnez Condition en haut de la section Actions.
- Cliquez sur la zone de texte la plus à gauche pour ouvrir une boîte de dialogue permettant de sélectionner une question ou une propriété à partir de l’enquête, et de sélectionner la question de l’enquête à utiliser pour qualifier l’enquête.
- Étant donné que vous voulez obtenir une réponse exacte, dans la zone du texte du milieu, sélectionnez la condition is equal to (est égal à) comme déclencheur dans le menu déroulant.
- Dans la zone de texte la plus à droite, saisissez la valeur de la question pour laquelle envoyer une notification.
Vous voulez que ce message électronique ne soit envoyé que si la condition est remplie.
- Cliquez sur Add an action (Ajouter une action) dans la zone If yes (Si oui).
La zone If no (Si non) reste vide.
De nombreux services de messagerie électronique disposent de connecteurs pouvant être utilisés dans ce flux.
- Sélectionnez Office 365 Outlook - Send an email (V2) (Office 365 Outlook - Envoyer un e-mail [V2]).
- Connectez-vous au service de messagerie électronique en saisissant vos identifiants de connexion, si ceux-ci ne sont pas déjà mémorisés.
- Renseignez les champs To (À), Subject (Objet) et Body (Corps) de votre courrier électronique.
Dans la boîte de dialogue Dynamic content (Contenu dynamique) qui s’affiche lorsque vous sélectionnez une zone de texte, vous pouvez insérer le contenu de la réponse à l’enquête comme il convient.
- Lorsque votre e-mail est terminé, cliquez sur Save (Enregistrer).
Le webhook est terminé, et activé par défaut. Le webhook va désormais s’exécuter chaque fois qu’une réponse d’enquête envoyée satisfait aux conditions données.
Conseil :
Vous pouvez utiliser l’action Create report (Créer un rapport) pour générer un rapport dans le cadre d’une réponse à l’enquête.
Configurer un webhook sur le site Web Survey123
Procédez comme suit pour configurer un webhook sur le site Web Survey123 :
- Sur la page My Surveys (Mes enquêtes), sélectionnez l’onglet Settings (Paramètres) dans le menu en bas à droite du volet de l’enquête.
- Sélectionnez la section Webhooks dans le menu de gauche.
Cette page vous permet de configurer des webhooks, et d’accéder aux webhooks que vous avez configurés. Si vous n’avez configuré aucun webhook dans Survey123, la page est vide.
- Cliquez sur Add Webhook (Ajouter un webhook).
Sur la nouvelle page qui s’affiche, vous pouvez configurer la manière dont le webhook va interagir avec l’enquête.
- Attribuez un nom à votre webhook. Ce nom servira à l’identifier à l’avenir.
- La payload URL correspond à l’endroit où les informations de l’enquête seront envoyées. Elle doit être fournie par un service de webhook externe.
Lorsque vous créez un webhook à l’aide d’un service tel que Microsoft Power Automate ou Make, la payload est indiquée automatiquement sur cette page. D’autres services, notamment Zapier ou FME Server, vous fournissent la payload URL à copier sur cette page. Avec certaines applications, vous pouvez avoir besoin de créer un service dédié pour écouter le webhook.
- L’événement déclencheur indique les actions spécifiques qui appelleront le webhook. Sélectionnez New record submitted (Nouvel enregistrement envoyé).
- Les données d’événement vous permettent de choisir les informations de votre enquête à inclure dans la payload : Survey info (Informations sur l’enquête), Server response (Réponse du serveur), Submitted record (Enregistrement envoyé), User info (Informations sur l’utilisateur) et Portal info (Informations sur le portail). Sélectionnez les options Survey info (Informations sur l’enquête) et Submitted record (Enregistrement envoyé).
- Le bouton bascule Status (Statut) détermine si ce webhook sera actif au moment de son enregistrement. Laissez-le défini sur On (Activé) (valeur par défaut).
- Cliquez sur Save (Enregistrer).
Le webhook est prêt à être utilisé. Il s’exécutera chaque fois qu’une réponse à une enquête est envoyée. Les règles définies dans le fournisseur de webhooks permettent de faire en sorte qu’un message électronique soit envoyé uniquement quand certains critères sont remplis.
Propriétés de la charge utile d’événement
Un événement de webhook envoie une charge utile de propriétés en tant qu’objet JSON. Le contenu de la charge utile est différent selon l’enquête. Le tableau suivant dresse la liste des propriétés communes de l’objet JSON :
| Propriété | Description |
|---|---|
| eventType | Type d’événement. Les valeurs peuvent être addData ou editData. |
| portalInfo | Informations relatives à l’organisation ArcGIS dans laquelle l’enquête est hébergée. Il contient les propriétés suivantes :
|
| surveyInfo | Informations relatives à l’enquête qui a généré le webhook. Il contient les propriétés suivantes :
|
| userInfo | Informations relatives au compte d’organisation ArcGIS de l’utilisateur qui a soumis l’enquête. Il contient les propriétés suivantes :
|
Les propriétés suivantes varient en fonction de l’enquête et du type d’événement :
| Propriété | Description |
|---|---|
| applyEdits | La charge utile Apply Edits (Appliquer les mises à jour) soumise par l’enquête. Si eventType est addData, elle contient adds. Si eventType est editData, elle contient updates. Si un nouvel enregistrement de répétition est ajouté, elle contient également adds. |
| response | La réponse de l’opération applyEdits. Elle inclut les ID globaux des entités créées par l’opération et précise si l’opération a abouti. |
| feature | L’enregistrement d’enquête qui a été soumis. Il contient les propriétés suivantes :
|
Vous avez un commentaire à formuler concernant cette rubrique ?