Webhooks—ArcGIS Survey123

Les webhooks permettent à plusieurs applications d’interagir 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 Survey123, il est possible de configurer et d’activer les webhooks lorsqu’un enregistrement est créé dans une couche d’entités ou supprimé d’une couche d’entités, ou 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.

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.

Outre le fournisseur de webhooks attitré de votre lieu de travail, divers services de processus tiers sont disponibles, parmi lesquels Microsoft Power Automate, Make, Zapier et tray.io. Tous ces services peuvent servir à incorporer Survey123 comme déclencheur pour un processus automatisé.

Microsoft Power Automate et Make incluent également des composants de processus pour faciliter la création de webhooks à utiliser avec Survey123.

Types de webhooks pris en charge par Survey123

Survey123 prend en charge deux types de webhooks :

Webhooks de couche d’entités : ces webhooks sont stockés dans la couche d’entités ou vue de couche d’entités de l’enquête et déclenchés par celle-ci.
Webhooks Survey123 : ces webhooks sont stockés dans l’élément de formulaire de l’enquête et déclenchés par l’application de terrain ou l’application Web.

Microsoft Power Automate inclut un connecteur ArcGIS qui permet de configurer les webhooks de couche d’entités ou les webhooks Survey123. Pour en savoir plus, reportez-vous à la rubrique Connecteurs ArcGIS. Les composants de processus suivants qui permettent de configurer un webkook Survey123 restent disponibles, mais ne sont plus mis à jour :

Microsoft Power Automate : connecteur Survey123
Make : module Survey123

Exemples de configuration d’un webhook

Il existe de nombreuses façons d’utiliser Survey123 comme déclencheur dans vos processus. Les trois premiers exemples de cette section utilisent le même scénario (envoyer un courrier électronique de notification quand une réponse reçue à une question contient une certaine valeur), mais chaque exemple utilise un composant de processus tiers ou type de webhook différent. Pour le dernier exemple, vous devez avoir créé un webhook personnalisé (ne pas utiliser de connecteur Microsoft Power Automate ou de module Make). Cet exemple décrit la procédure d’ajout du webhook à Survey123.

Consultez les exemples ci-dessous :

Configurer un webhook de couche d’entités dans Microsoft Power Automate

Pour configurer un webhook de couche d’entités dans Microsoft Power Automate, procédez comme suit :

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 record is created in a feature layer (Lorsqu’un enregistrement est créé dans une couche d’entités) comme déclencheur de ce processus.
Cliquez sur Create (Créer).
Connectez-vous avec les informations d’identification de votre organisation ArcGIS, puis sélectionnez la couche d’entités à surveiller.
Vous devez sélectionner la couche d’entités ou vue de couche d’entités cible des envois.
Ajoutez l’action Fetch updates, changes, or deletions from feature layer (Récupérer les modifications, mises à jour ou suppressions d’une couche d’entités) dans ce processus.
1. Définissez Change URL (Modifier l’URL) comme entrée de l’option Get changes from (Obtenir les modifications auprès de).
2. Définissez layerId comme entrée de l’option feature layer ID (ID de la couche d’entités).
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 est désormais exécuté toutes les 30 secondes.

Configurer un webhook Survey123 dans Microsoft Power Automate

Pour configurer un webhook Survey123 dans Microsoft Power Automate, procédez comme suit :

Remarque :

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).
Cliquez sur Create (Créer).
Connectez-vous avec les informations d’identification de votre organisation ArcGIS.
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 manière 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 Survey123 dans Make

Pour configurer un webhook Survey123 dans Make, procédez comme suit :

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. Sous Connection (Connexion), cliquez sur Add (Ajouter) et nommez la connexion à ArcGIS.
Vous n’aurez à le faire qu’une fois, car Make enregistre vos informations pour une utilisation ultérieure.
- 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 manière, de sorte que vous fournissez 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.

Ajouter un webhook sur le site Web Survey123

Il est possible d’ajouter un webhook Survey123 ou un webhook de couche d’entités sur le site Web. La procédure ci-après illustre la configuration d’un webhook de couche d’entités. Un webhook Survey123 est identique, mais avec des options Event data (Données d’événement) supplémentaires répertoriées dans Event payload properties (Propriétés de la charge utile d’événement).

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), puis sélectionnez Add feature layer webhook (Ajouter un webhook de couche d’entités).
Dans le nouveau panneau qui s’affiche, vous pouvez configurer la manière dont le webhook interagit 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é).

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 le type de webhook utilisé et l’enquête.

Les webhooks de couche d’entités contiennent uniquement des événements addData ou editData. Pour plus d’informations, reportez-vous à la rubrique Charges utiles des webhooks de couche d’entités.

Les webhooks Survey123 contiennent le type d’événement et des propriétés supplémentaires. Le tableau suivant dresse la liste des propriétés communes de l’objet JSON d’un webhook Survey123 :


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 : url token
surveyInfo	Informations relatives à l’enquête qui a généré le webhook. Il contient les propriétés suivantes : formItemId formTitle serviceItemId serviceUrl
userInfo	Informations relatives au compte d’organisation ArcGIS de l’utilisateur qui a soumis l’enquête. Il contient les propriétés suivantes : username firstName lastName fullName email

Les propriétés suivantes des webhooks Survey123 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 : attributes geometry layerInfo result repeats Remarque : Chaque objet à l’intérieur de la matrice repeats est une feature qui possède des attributes, une geometry, des layerInfo, un result, des repeats et des attachments. attachments id globalId name contentType size keywords url parentObjectId

Vous avez un commentaire à formuler concernant cette rubrique ?