Tutorial: Webforms / Webhooks

Einleitung

In diesem Tutorial zeige ich Dir, wie Du Webhooks verwendest, um Drittsysteme – in unserem Beispielfall die Meldeplattform der NPO Lebensbaum – mit funtrade zu verbinden. Mithilfe eines Webhooks sollen Meldungen (über gefundene neue Baumarten) vollautomatisch in funtrade eingelesen werden. Dabei wird für jeden neuen Melder eine Person angelegt, falls diese noch nicht existiert, und es wird ein Ereignis in der Kontakthistorie hinterlegt.

Szenario

NPO Lebensbaum: Betreibt eine Meldeplattform, über die Tiersichtungen gemeldet werden.
Ziel: Automatische Übertragung der Meldedaten in funtrade.
Verarbeitungsschritte:
- Anlage einer neuen Person (sofern noch nicht vorhanden).
- Hinterlegung eines Ereignisses in der Kontakthistorie.

Voraussetzungen

Datenstruktur kennen: Um das Setup vorzunehmen, ist es essenziell, die Datenstruktur des externen Systems zu kennen. Hierzu kannst Du ein Tool wie webhook.site verwenden.
Beispiel-Datenstruktur: Im Folgenden findest Du ein Beispiel der JSON-Payload, die von der Meldeplattform versendet wird:

{
    "id": 123343455349,
    "timestamp": 1740564744600,
    "event": "observation",
    "address": {
        "id": 3434534,
        "name": "Christian",
        "firstname": "Davatz",
        "street": "Freiestrasse 18",
        "city": "Zürich",
        "state": "ZH",
        "zip": "8000",
        "country": "CH"
    },
    "attributes": {
        "observation": "hedgehog"
    }
}

Schritte zur Einrichtung des Webhooks

Aufbau der Webhook-URL

Die URL für den Webhook setzt sich immer folgendermassen zusammen:

<KundenURL>/rest/webhook/v1.0/data/<WebformKey>/<WebFormId>/<ExternalId>

KundenURL
URL der funtrade installation (Browser-URL ohne das /funtrade)
WebformKey
oftmals der Name des Services/Drittsystems
WebFormId
Typ des "Models", oftmals Name einer gewissen Aktion/Events, im Plural
ExternalId
Id des Events im Quellsystem/Drittsystem

Bspw:

https://asp.arenae.ch/funtrade-playft/rest/webhook/v1.0/data/meldeplattform/observations/123343455348

Diese URL dient als Endpunkt, über den die Daten in funtrade übertragen werden.

1. Konfiguration der Adressfelder

Konfiguriere die Adressfelder, die als Grundlage für alle weiteren Verarbeitungsschritte dienen. Diese Felder ermöglichen es, die Daten aus der externen Quelle korrekt in funtrade zu importieren.

Spezielle Felder:

FTML Transaktion: Timestamp: hier kann als Feldwert: now eingetragen werden. Alternativ kann ein Feld aus der Payload verwendet werden: zur Zeit werden nur ISO-Datumsformate unterstützt.
FTML Transaktion: Source: muss das gleiche sein, wie WebformKey aus der URL
FTML Transaktion: Target: ist im Normalfall der Name der Installation, in unserem Fall playft
Webform: External-ID: um die External-ID aus der URL mit einem Wert aus der Payload zu überschreiben, kann dieses Feld verwendet werden

Neu vs. Bestehende Personen

funtrade sucht anhand der gefundenen Personen und Adressdaten die entsprechende Person in funtrade. Dabei kommt die Logik der "Dublettenprüfung" zum Einsatz.

Fall:

genauer Personentreffer: funtrade überspringt das erstellen der Person und geht in den Datenimport über
ungenauer Personentreffer: funtrade bereitet den Import der Daten vor, erstellt aber eine "Aufgabe" für den funtrade Benutzer, damit dieser die Zuordnung zur bestehenden Person kontrollieren kann, bevor der Datenimport für diesen Datensatz stattfindet
ohne Personentreffer: funtrade erstellt eine neue Person mit den gegebenen Daten und hinterlegt die definierten Daten

2. Ereignis vorbereiten (falls nicht bereits vorhanden)

Für unser Beispiel erstellen wir ein neues Ereignis Meldungen mit einer Ereignisposition, um den Igel separat zu zählen. Grundsätzlich kann aber mit einer generischen Position gearbeitet werden.

3. Definitionen und Verarbeitungsschritte

Nun wollen wir für den Fall, dass die Meldeplattform uns Daten schickt, definieren, dass funtrade ein Ereignis in der Kontakthistorie des entsprechenden Melders erstellt. Dieses Ereignis dient der Dokumentation der Meldung. Dazu müssen wir eine Definition sowie dazugehörende Verarbeitungsschritte erstellen.

Es können Bedingungen verwendet werden, um zu definieren, in welchem Fall welche Definition und entsprechend welche Verarbeitungsschritte gewählt wird. Die Verarbeitung geht die Definitionen anhand deren "Sortierung" durch. Wenn eine Definition zutrifft, werden die im unterste Teil des Bildschirms definierten Verarbeitungsschritte ausgeführt.

Sobald eine Definition die Bedingungen erfüllt, werden die Verarbeitungsschritte durchlaufen und der Event als "bearbeitet" markiert.

Um zu definieren, ob eine Definition verarbeitet werden soll, kann rechts eine Bedingung definiert werden. Dabei kann mit object/property auf das Feld property des JSON-Objektes object zugegriffen werden.

In unserem Fall erstellen wir eine globale ablehnen Position. In diesem Fall werden die Einträge final abgeschlossen, auch wenn keine Verarbeitungsschritte ausgeführt wurden.

Wenn wir eine abbrechen Verarbeitungsschritt definiert hätten stattdessen, hätte funtrade nach der nächsten Konfigurationsänderung bzw. dem ersten darauf folgenden Event versucht, auch diesen Datensatz erneut zu verarbeiten.

4. Test des Webhooks

Daten senden

Sende den Webhook mit folgender Payload (Beispiel mit curl).

Platzhalter ersetzen:

KundenURL
URL der funtrade installation (Browser-URL ohne das /funtrade)
BasicSecret
Benutzername und Passwort in Base64

curl --location '<KundenURL>/rest/webhook/v1.0/data/meldeplattform/observations/123343455349' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <BasicSecret>' \
--data '{
    "id": 123343455349,
    "timestamp": 1740564744600,
    "event": "observation",
    "address": {
        "id": 3434534,
        "name": "Christian",
        "firstname": "Davatz",
        "street": "Freiestrasse 18",
        "city": "Zürich",
        "state": "ZH",
        "zip": "8000",
        "country": "CH"
    },
    "attributes": {
        "observation": "hedgehog"
    }
}'

Überprüfung des Verarbeitungsstatus

Überprüfe in funtrade, ob die Daten angekommen sind. Der Status „bearbeitet“ zeigt an, dass eine FTML-Transaktion erstellt wurde. Schau Dir die FTML-Daten der Transaktion an, um den Verlauf und eventuelle Fehler zu überprüfen.

Fehlerbehandlung

Sollte die Verarbeitung nicht vollautomatisch abgeschlossen werden, prüfe die Fehlermeldung. Ein häufiger Fehler ist "Strasse / Ort Kombination": Diese Meldung weist darauf hin, dass die übermittelte Adressinformation nicht korrekt ist.

In diesem Fall kannst Du:

Die korrekte Kombination aus Strasse und Ort recherchieren.
Oder die Person manuell zuordnen, sofern sie bereits in der Datenbank vorhanden ist.