Webhooks sind weit verbreitet und ermöglichen eine Interaktion zwischen mehreren Anwendungen. Hierbei werden Rückrufe mithilfe von HTTP/POST-Anforderungen zwischen den Anwendungen übergeben. Weitere Informationen finden Sie im Wikipedia-Eintrag zu Webhooks. Die häufigsten Verwendungsmöglichkeiten von Webhooks sind: Senden von Benachrichtigungen per E-Mail oder SMS, Veröffentlichen von Nachrichten in sozialen Medien, automatisches Schreiben von Datensätzen in eine Tabelle und Aktualisieren von Enterprise-Datenbanken.
In ArcGIS Survey123 können Webhooks beim Senden von Survey-Antworten eingerichtet und aktiviert werden. Ein Webhook kann nach dem erfolgreichen Versand von Informationen an den Feature-Layer aufgerufen werden, um dann eine andere Aktion auszulösen, z. B. das Versenden einer E-Mail, das Anhängen des Survey-Inhalts an eine Tabelle oder das Versenden einer Warnung.
Möglicherweise nutzt Ihre Organisation bereits einen Webhook-Anbieter; andernfalls können Sie auf die Angebote von Dritten zurückgreifen, z. B. Microsoft Power Automate, Make (vormals Integromat), Zapier und tray.io. Mit diesen Services können Sie Survey123 als Trigger integrieren und so Ihren Prozess automatisieren. Insbesondere sind Microsoft Power Automate und Make mit einem Survey123-Konnektor ausgestattet, über den Sie Survey123 mit geringem Aufwand, ohne Konfiguration des Webhooks in der Survey123-Website und ohne Eingabe einer Payload-URL in Ihren Webhook-Workflow integrieren können.
Vorsicht:
Wenn Sie einen Webhook für einen Survey erstellen oder ändern, muss der Survey in der mobilen Survey123-App aktualisiert werden, damit die Änderungen wirksam werden.
Es gibt zahlreiche Möglichkeiten, Survey123 in Ihren Workflows als Trigger zu verwenden. In den folgenden drei Abschnitten erfahren Sie, wie Sie einen Webhook zum Senden von Benachrichtigungen einrichten. Dieser veranlasst den Versand einer E-Mail, sobald eine Antwort gesendet wird, die eine mit einem bestimmten Wert beantwortete Frage enthält.
Am Ende dieses Themas werden alle Eigenschaften, die in der Webhook-Ereignisnutzlast verfügbar sind, als Referenz aufgeführt.
Einrichten eines Webhooks in Make
Make (früher Integromat) ist eine Online-Automatisierungsplattform. Registrieren Sie sich für ein kostenfreies Konto, um mit der Plattform arbeiten zu können. In Make stehen Vorlagen zur Verfügung, die Sie als Ausgangspunkt verwenden können, um beispielsweise Anlagen in E-Mail-Benachrichtigungen einzubinden, Datensätze zu Arbeitsblättern hinzuzufügen und Kalenderelemente zu erstellen.
- Melden Sie sich unter https://www.make.com/ an.
- Klicken Sie auf der Seite Scenarios auf die Schaltfläche Create a new scenario.
- Klicken Sie auf das Symbol für das Modul in der Mitte des Bildschirms. Suchen Sie nach Survey123, und wählen Sie den Eintrag aus.
- Wählen Sie das Trigger-Modul Watch survey aus.
In diesem Modul wird das Szenario bei jeder Übermittlung einer Antwort auf den Survey ausgeführt.
Ein Pop-up wird angezeigt, das Sie beim Konfigurieren des Moduls Watch survey unterstützt.
Tipp:
Mit dem Modul Create report können Sie einen Bericht für eine Survey-Antwort generieren.
- Klicken Sie auf Add, und geben Sie einen Namen für den Webhook an.
Dieser sollte für den Survey, für den Sie den Webhook konfigurieren, eindeutig sein.
- Richten Sie eine Verbindung zu Ihrer ArcGIS-Organisation ein, wenn Sie das Modul Survey123 in Make zum ersten Mal verwenden. Dies müssen Sie nur einmal tun; Ihre Daten werden für die künftige Verwendung in Make gespeichert. Klicken Sie unter Connection auf Add, und geben Sie einen Namen für die Verbindung zu ArcGIS ein.
- Klicken Sie zum Herstellen der Verbindung mit ArcGIS Online auf Save, um sich bei Ihrer ArcGIS-Organisation anzumelden.
- Um sich bei ArcGIS Enterprise anzumelden, müssen Sie Make bei Ihrem Portal registrieren. Weitere Informationen finden Sie im Blogbeitrag Survey123 Tricks of the Trade: Make.
- Wählen Sie einen Survey in der ArcGIS-Organisation aus, zu dem Sie eine Verbindung herstellen möchten.
- Wählen Sie die Optionen aus, die Ihr Webhook enthalten soll, und klicken Sie auf Save.
Es empfiehlt sich, für alle erweiterten Einstellungen den Standardwert Yes beizubehalten; dadurch erhalten Sie die größtmögliche Flexibilität bei der Anpassung Ihres Webhooks.
- Klicken Sie auf OK.
Der Webhook wird erstellt und das Watch Survey-Modul konfiguriert.
- Klicken Sie auf die Schaltfläche Add another module auf der rechten Seite des Moduls Watch survey, um ein anderes Modul mit ihm zu verbinden.
- Suchen Sie nach Email, und wählen Sie das Email-Modul aus.
- Wählen Sie die Aktion Send an email aus.
- Wenn Sie dieses Modul in Make zum ersten Mal verwenden, klicken Sie auf Add, um eine Verbindung zu Ihrem E-Mail-Konto einzurichten. Wählen Sie einen Verbindungstyp aus, und melden Sie sich bei Ihrem Konto an.
Dies müssen Sie nur einmal tun; Ihre Verbindung wird für die künftige Verwendung in Make gespeichert.
- Fügen Sie die E-Mail-Adresse eines Empfängers hinzu.
An diese Adresse werden E-Mails gesendet, die durch bestimmte Aktionen ausgelöst werden.
- Klicken Sie in das Textfeld für den Betreff. Wählen Sie Felder aus Ihrem Survey aus, um den E-Mail-Betreff über das angezeigte Fenster mit den Moduleinstellungen zu erstellen.
- Klicken Sie in das Textfeld für den Inhalt. Wählen Sie Felder aus Ihrem Survey aus, um den Inhalt der E-Mail über das angezeigte Fenster mit den Moduleinstellungen zu erstellen. Sie können den Inhalt mithilfe von HTML formatieren.
- Klicken Sie auf OK.
Dieses Szenario sieht vor, dass die E-Mail gesendet werden soll, wenn auf eine Frage eine bestimmte Antwort gegeben wurde. Also muss ein Filter eingerichtet werden.
- Klicken Sie auf die Werkzeugschaltfläche zwischen den beiden Modulen, und wählen Sie Set up a filter aus.
- Klicken Sie auf das Textfeld Condition, und wählen Sie das Feld aus dem Survey aus, das Sie im Filter verwenden möchten.
- Wählen Sie einen Operator für die Bedingung aus. Wählen Sie in diesem Fall den Standardoperator Equal to aus.
- Geben Sie einen Wert für die Bedingung ein, und klicken Sie auf OK.
- Klicken Sie auf Save, um das Szenario zu speichern.
Optional können Sie auch auf Run once klicken, um den Webhook zu testen. Nach dem Sie auf Run once geklickt haben, sollten Sie Survey123 öffnen und einen Survey einsenden, um sicherzustellen, dass die Survey-Antwort der Filterbedingung entspricht. Vergewissern Sie sich, dass der Empfänger die E-Mail erhält.
- Mit der Umschaltfläche links unten auf der Seite können Sie das Szenario aktivieren. Legen Sie den Zeitplan auf Immediately fest, um sicherzustellen, dass das Szenario bei jeder eingesendeten Survey-Antwort ausgeführt wird.
Informationen zu weiteren Möglichkeiten der Verwendung von Survey123 als Trigger in den Make-Szenarien finden Sie unter Survey123-Integrationen.
Einrichten eines Webhooks in Microsoft Power Automate
Microsoft Power Automate ist ein Webhook-Service, der auf der Microsoft Office 365-Plattform verfügbar ist.
Hinweis:
ArcGIS Online-Anmeldeinformationen, die zum Erstellen von Flows in Power Automate verwendet wurden, werden nach zwei Wochen automatisch abgemeldet. Wenn Sie erwartete Surveys in Power Automate nicht durchsuchen können, vergewissern Sie sich, ob Ihre Survey123-Datenverbindung aktiv ist. Weitere Informationen finden Sie im Blogartikel Quick Tip: Keeping the ArcGIS Connectors for Power Automate Refresh Token Valid.
Führen Sie zum Einrichten eines Flows in Microsoft Power Automate mit den ArcGIS- oder ArcGIS Enterprise-Konnektoren die folgenden Schritte aus. Wenn Sie zuvor schon Flows mit dem Survey123-Konnektor erstellt haben, funktionieren diese weiterhin, aber neue Funktionalität wird nur den ArcGIS- und ArcGIS Enterprise-Konnektoren hinzugefügt. Weitere Informationen finden Sie im Blogartikel Survey123 triggers and actions in the ArcGIS connectors for Power Automate.
- Öffnen Sie Microsoft Power Automate.
- Wählen Sie im Seitenmenü Create aus.
- Wählen Sie Automated cloud flow in den Optionen unter Start from blank aus.
Das Dialogfeld Build an automated cloud flow wird angezeigt.
- Geben Sie einen Namen für den Flow an.
Als Nächstes wählen Sie einen Trigger aus.
- Geben Sie ArcGIS in die Suchleiste ein, und wählen Sie Beim Senden einer Survey-Antwort aus.
Vorsicht:
Wählen Sie die Option Beim Senden einer Survey-Antwort unter ArcGIS aus, wenn für den Flow die Anmeldung bei einer ArcGIS Online-Organisation erforderlich ist. Wählen Sie die Option Beim Senden einer Survey-Antwort unter ArcGIS Enterprise aus, wenn für den Flow die Anmeldung bei einer ArcGIS Enterprise-Organisation erforderlich ist.
- Klicken Sie auf Erstellen.
- Wenn Sie diesen Konnektor erstmalig in Microsoft Power Automate verwenden, klicken Sie auf Anmelden, und melden Sie sich mit den Anmeldeinformationen Ihrer ArcGIS-Organisation an.
Sie müssen sich nur einmal anmelden; Ihre Anmeldeinformationen werden für die künftige Verwendung in Microsoft Power Automate gespeichert.
- Wählen Sie aus der Dropdown-Liste der Surveys den Survey aus, den Sie für den Webhook verwenden möchten.
Sie haben nun den Trigger für den Webhook eingerichtet. Damit der Webhook mit diesem Trigger Aktionen durchführen kann, sind jedoch weitere Schritte erforderlich.
Der Flow sieht vor, dass eine E-Mail gesendet wird, wenn auf eine Frage eine bestimmte Antwort gegeben wurde. Also muss eine Bedingung eingerichtet werden.
- Klicken Sie auf die Schaltfläche Neuer Schritt, und wählen Sie Bedingung im oberen Bereich des Abschnitts Aktionen aus.
- Klicken Sie auf das Textfeld ganz links, um ein Dialogfeld zu öffnen, in dem Sie eine Frage oder Eigenschaft aus dem Survey auswählen können, und wählen Sie die Survey-Frage aus, die Sie zur Qualifizierung des Survey verwenden möchten.
- Wählen Sie im mittleren Textfeld im Dropdown-Menu die Bedingung ist gleich als Trigger aus, da Sie nach einer exakten Antwort suchen.
- Geben Sie im Textfeld ganz rechts den Wert für die Frage ein, bei der eine Benachrichtigung gesendet werden soll.
Sie möchten, dass die E-Mail nur versendet wird, wenn die Bedingung erfüllt ist.
- Klicken Sie im Feld Wenn ja auf Eine Aktion hinzufügen.
Das Feld Wenn nein bleibt in diesem Fall leer.
Viele E-Mail-Services bieten Konnektoren, die für diesen Flow verwendet werden können.
- Wählen Sie Office 365 Outlook – E-Mail senden (V2) aus.
- Melden Sie sich beim Mail-Service an, sofern Ihre Anmeldeinformationen noch nicht gespeichert wurden.
- Füllen Sie die Felder An, Betreff und Text Ihrer E-Mail aus.
Fügen Sie im Dialogfeld Dynamischer Inhalt, das bei Auswahl eines Textfeldes angezeigt wird, ggf. den Inhalt aus der Survey-Antwort ein.
- Klicken Sie auf Speichern, wenn Sie mit der E-Mail fertig sind.
Die Erstellung des Webhooks ist abgeschlossen, und er ist standardmäßig aktiviert. Der Webhook wird nun immer dann ausgeführt, wenn eine Survey-Antwort gesendet wird, die den angegebenen Bedingungen entspricht.
Tipp:
Mit der Aktion Create report können Sie einen Bericht für eine Survey-Antwort generieren.
Konfigurieren eines Webhooks in der Survey123-Website
Gehen Sie wie folgt vor, um einen Webhook auf der Survey123-Website einzurichten:
- Wählen Sie auf der Seite Eigene Surveys die Registerkarte Einstellungen aus, die sich im Menü rechts unten im Survey-Fenster befindet.
- Wählen Sie im Menü links den Bereich Webhooks aus.
Auf dieser Seite können Sie Webhooks einrichten und auf vorhandene Webhooks zugreifen. Wenn Sie noch keine Webhooks in Survey123 eingerichtet haben, ist die Seite leer.
- Klicken Sie auf Webhook hinzufügen.
Eine neue Seite wird angezeigt, auf der Sie die Art und Weise der Interaktion des Webhooks mit Ihrem Survey festlegen können.
- Geben Sie zur künftigen Identifizierung einen Namen für den Webhook an.
- An die Nutzdaten-URL werden die Survey-Informationen gesendet. Diese muss von einem externen Webhook-Service bereitgestellt werden.
Wenn Sie einen Webhook mit einem Service wie Microsoft Power Automate oder Make erstellen, wird die Payload-URL auf dieser Seite automatisch angegeben. Andere Services wie Zapier oder FME Server stellen die Payload-URL bereit, damit Sie sie in diese Seite kopieren können. Für andere Anwendungen müssen Sie möglicherweise einen eigenen Service erstellen, der auf den Webhook wartet.
- Die Trigger-Ereignisse beschreiben, durch welche Aktionen der Webhook ausgelöst wird. Wählen Sie Neuer Datensatz wurde gesendet aus.
- Anhand von Ereignisdaten können Sie auswählen, welche Informationen aus Ihrem Survey in den Nutzdaten enthalten sein sollen: Survey-Info, Serverantwort, Gesendeter Datensatz, Benutzerinformationen und Portalinformationen.. Aktivieren Sie die Optionen Survey-Info und Gesendeter Datensatz.
- Mit der Umschaltfläche Status legen Sie fest, ob der Webhook beim Speichern aktiviert wird. Behalten Sie die Standardeinstellung Ein bei.
- Klicken Sie auf Speichern.
Der Webhook ist verwendungsbereit und wird bei jedem Senden einer Survey-Antwort ausgeführt. Anhand von Regeln auf Seiten des Webhook-Anbieters kann festgelegt werden, dass eine E-Mail nur gesendet wird, wenn bestimmte Kriterien erfüllt werden.
Eigenschaften der Ereignisnutzlast
Ein Webhook-Ereignis sendet eine Nutzlast mit Eigenschaften in Form eines JSON-Objekts. Der Inhalt der Nutzlast hängt von dem jeweiligen Survey ab. In der folgenden Tabelle sind die allgemeinen Eigenschaften aufgeführt, die im JSON-Objekt enthalten sind:
| Eigenschaft | Beschreibung |
|---|---|
| eventType | Der Typ des Ereignisses. Werte können addData oder editData sein. |
| portalInfo | Informationen über die ArcGIS-Organisation, in der der Survey gehostet wird. Sie enthält die folgenden Eigenschaften:
|
| surveyInfo | Informationen über den Survey, der den Webhook erzeugt hat. Sie enthält die folgenden Eigenschaften:
|
| userInfo | Informationen über das ArcGIS-Organisationskonto des Benutzers, der den Survey gesendet hat. Sie enthält die folgenden Eigenschaften:
|
Die folgenden Eigenschaften hängen vom Typ des Survey und des Ereignisses ab:
| Eigenschaft | Beschreibung |
|---|---|
| applyEdits | Die vom Survey übermittelte Nutzlast Änderungen übernehmen. Wenn eventType addData ist, enthält sie adds. Wenn eventType editData ist, enthält sie updates. Beim Hinzufügen eines neuen Wiederholungsdatensatzes enthält sie auch adds. |
| response | Die Antwort vom applyEdits-Vorgang. Sie enthält die Global-IDs für die Features, die durch den Vorgang erstellt wurden, und gibt an, ob der Vorgang erfolgreich war. |
| feature | Der Survey-Datensatz, der gesendet wurde. Sie enthält die folgenden Eigenschaften:
|