Webhooks—ArcGIS Survey123

Webhooks 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 Survey123 können Webhooks eingerichtet und aktiviert werden, wenn ein Datensatz in einem Feature-Layer erstellt oder daraus gelöscht wird oder wenn eine Survey-Antwort übermittelt wird. 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.

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.

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, Zapier und tray.io. Mit diesen Services können Sie Survey123 als Trigger integrieren und so Ihren Prozess automatisieren.

Microsoft Power Automate und Make bieten auch Workflow-Komponenten, die die Erstellung von Webhooks zur Nutzung mit Survey123 unterstützen.

Typen von Webhooks, die von Survey123 unterstützt werden

Survey123 unterstützt zwei Typen von Webhooks:

Feature-Layer-Webhooks: Sie werden im Feature-Layer oder in der Feature-Layer-Sicht des Survey gespeichert und von dort aus ausgelöst.
Survey123-Webhooks: Diese werden im Formularelement des Survey gespeichert und über die mobile App oder die Web-App ausgelöst.

Zu Microsoft Power Automate gehört ein ArcGIS-Connector, der die Einrichtung von Feature-Layer-Webhooks oder Survey123-Webhooks unterstützt. Weitere Informationen finden Sie unter ArcGIS-Connectors. Die folgenden Workflow-Komponenten, die bei der Einrichtung eines Survey123-Webhooks helfen, sind weiterhin verfügbar, werden aber nicht mehr aktualisiert.

Microsoft Power Automate: Survey123-Connector
Make: Survey123-Modul

Beispiele für das Einrichten eines Webhooks

Es gibt zahlreiche Möglichkeiten, Survey123 in Ihren Workflows als Trigger zu verwenden. In den ersten drei Beispielen in diesem Abschnitt wird dasselbe Szenario verwendet: Eine Benachrichtigungs-E-Mail wurde gesendet, die eine mit einem bestimmten Wert beantwortete Frage enthält. Es wird aber jeweils eine andere Workflow-Komponente eines Drittanbieters oder ein anderer Webhook-Typ verwendet. Das letzte Beispiel setzt voraus, dass Sie einen benutzerdefinierten Webhook (ohne einen Microsoft Power Automate-Connector oder ein Make-Modul) erstellt haben, und es beschreibt, wie der Webhook zu Survey123 hinzugefügt wird.

Beispiele:

Einrichten eines Feature-Layer-Webhooks in Microsoft Power Automate

Führen Sie die folgenden Schritte aus, um einen Feature-Layer-Webhook in Microsoft Power Automate einzurichten:

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 das Suchfeld ein, und wählen Sie Wenn ein Datensatz in einem Feature-Layer erstellt wird als Trigger in diesem Workflow aus.
Klicken Sie auf Erstellen.
Melden Sie sich mit den Anmeldeinformationen Ihrer ArcGIS-Organisation an, und wählen Sie den Feature-Layer aus, den Sie überwachen möchten.
Sie müssen den Feature-Layer oder die Feature-Layer-Sicht für die Übermittlung auswählen.
Fügen Sie in diesem Workflow die Aktion Änderungen, Aktualisierungen oder Löschungen in einem Feature-Layer abrufen hinzu.
1. Legen Sie URL ändern als Eingabe von Änderungen abrufen von fest.
2. Legen Sie layerId als Eingabe von Feature-Layer-ID fest.
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 jetzt alle 30 Sekunden ausgeführt.

Einrichten eines Survey123-Webhooks in Microsoft Power Automate

Führen Sie die folgenden Schritte aus, um einen Survey123-Webhook in Microsoft Power Automate einzurichten:

Hinweis:

Ö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.
Klicken Sie auf Erstellen.
Melden Sie sich mit den Anmeldeinformationen Ihrer ArcGIS-Organisation an.
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.

Einrichten eines Survey123-Webhooks in Make

Führen Sie die folgenden Schritte aus, um einen Survey123-Webhook in Make einzurichten:

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. Klicken Sie unter Connection auf Add, und geben Sie einen Namen für die Verbindung zu ArcGIS ein.
Dies müssen Sie nur einmal tun; Ihre Daten werden für die künftige Verwendung in Make gespeichert.
- 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 Blogartikel Survey123Tricks 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.

Hinzufügen eines Webhooks auf der Survey123-Website

Ein Survey123-Webhook oder ein Feature-Layer-Webhook kann auf der Website hinzugefügt werden. Die folgenden Schritte veranschaulichen, wie ein Feature-Layer-Webhook eingerichtet wird. Ein Survey123-Webhook ist identisch, es werden jedoch weitere Optionen für Ereignisdaten in den Eigenschaften der Ereignisnutzlast aufgeführt.

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, und wählen Sie Feature-Layer-Webhook hinzufügen aus.
Ein neuer Bereich wird angezeigt, in dem 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.

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 vom verwendeten Webhook-Typ und vom Survey ab.

Feature-Layer-Webhooks enthalten nur addData- oder editData-Ereignisse. Weitere Informationen finden Sie unter Payloads für Feature-Layer-Webhooks.

Survey123-Webhooks enthalten den Typ des Ereignisses sowie weitere Eigenschaften. In der folgenden Tabelle sind die allgemeinen Eigenschaften aufgeführt, die im JSON-Objekt eines Survey123-Webhooks 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: url token
surveyInfo	Informationen über den Survey, der den Webhook erzeugt hat. Sie enthält die folgenden Eigenschaften: formItemId formTitle serviceItemId serviceUrl
userInfo	Informationen über das ArcGIS-Organisationskonto des Benutzers, der den Survey gesendet hat. Sie enthält die folgenden Eigenschaften: username firstName lastName fullName email

Die folgenden Eigenschaften von Survey123-Webhooks 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: attributes geometry layerInfo result repeats Hinweis: Jedes Objekt innerhalb des repeats-Arrays ist ein feature mit attributes, geometry, layerInfo, result, repeats und attachments. attachments id globalId name contentType size keywords url parentObjectId

Feedback zu diesem Thema?