Integrations

Dieses Dokument behandelt das Konzept der Integrationen.

Einleitung

Unter Integrations lassen sich Verbindungen zu externen Systemen einrichten, ohne programmieren zu müssen. Integrationen stehen in Workflow als Trigger oder als Schritt zur Verfügung.

Bei Inbound und Outbound Integrations unterscheidet man die Richtung des Aufrufs.

• Bei einer Outbound-Integration ruft die Mercury.ai Plattform ein externes Tool auf.
• Bei einer Inbound-Integration ruft ein externes Tool einen von der Mercury.ai Plattform bereitgestellten Webhook auf.

Inbound Integrations

Eine Inbound-Integration ermöglicht es externen Systemen, die Mercury.ai Plattform anzusprechen, um Informationen zu setzen oder zu aktualisieren oder Aktionen wie das Senden einer WhatsApp-Template-Nachricht auszulösen. Inbound-Integrationen können nur von aussen angesprochen werden, wenn sie als Trigger eines Workflows verwendet werden. Die Integration kann eingehende Informationen mittels JSON Path aus dem Request extrahieren und an den verbundenen Workflow weiterreichen. Der Workflow kann diese Informationen verarbeiten und ein Ergebnis an den Aufrufer der API als Response zurückgeben.

Jede Inbound-Integration besteht aus mehreren Blöcken in denen Einstellungen vorgenommen werden können.

Your webhook

Unter Your webhook stellt die Inbound-Integration einen Webhook zur Verfügung, der von anderen Systemen aufgerufen werden kann. Dieser wird beim Anlegen der Integration automatisch erstellt. Der Webhook kann dann mit einem zuvor angelegten Secret über standard Authentifizierung abgesichert werden:

Captured payload

Mit einem Aufruf des Webhooks durch ein externes System werden Informationen (der Payload des API-Aufrufs) zumeist als JSON mitgesendet. Der letzte auf dem bereitgestellten Webhook empfangene Payload wird unter Captured payload dargestellt um die Datenextraktion zu erleichtern. Da diese Informationen in der Regel personenbezogene Daten enthalten können, werden sie nur kurz nach dem eingegangenen Aufruf angezeigt und nach einiger Zeit automatisch gelöscht:

Workflow input

Unter Workflow input wird festgelegt wie der Workflow Informationen aus dem eingehenden Request extrahieren soll:

Jeder eingehende HTTP Request bietet Zugriff auf die Request-Header und den mitgesendeten Body:

{
  "headers": [
    {
      "content-type" : "application/json"
    }
  ],
  "body": {
    "parameter" : "Hello World",
    "userId" : "123456"
  }
}

Um in diesem Beispiel die userId aus dem Body zu extrahieren wird ein neuer Input angelegt. Der Key ist frei wählbar und dient in einem verbundenen Workflow zur Referenzierung des Wertes. Der Wert selbst wird per JSON Path extrahiert; eine Sprache, die entwickelt wurde, um Daten in JSON-Dokumenten einfach filtern und navigieren zu können. In den Integrationen wird JSON Path verwendet, um Informationen aus API Antworten zu extrahieren. Hier erfahren Sie mehr. Zum Beispiel: $.body.userId.

Workflow output

Jede Integration kann einen oder mehrere Workflow-Outputs zur Verfügung stellen. Diese Key-Value-Paare werden unter Workflow Output angelegt und werden nach der Ausführung des Workflows beschrieben werden beschrieben und an die Integration zurückgegeben. Die definierten Keys können im Response Body verwendet werden und werden gegen ihre Werte beim Absenden des Repsonses ersetzt. Wird ein definierter Wert nicht vom Workflow gesetzt, ist es möglich hier einen Default-Wert anzugeben, welcher stattdessen verwendet wird:

Der Example-Wert wird momentan nicht verwendet.

Response body

Der Response body definiert den Wert welcher an den aufrufenden Service zurückgegeben wird. An dieser Stelle kann auf nur auf Variablen aus dem Workflow Output zugegriffen werden.

Outbound Integrations

Eine Outbound-Integration dient dazu, externe Services innerhalb eines Workflows anzusprechen. Nachdem eine Outbound-Integration erstellt worden ist, kann sie als Step in einen Workflow integriert werden.

Jede Outbound-Integration besteht aus mehreren Blöcken in denen Einstellungen vorgenommen werden können.

Input definition

Unter Input Definition können Variablen angelegt werden, die die Integration benötigt, um einen API-Call auszuführen. Diese Variablen werden im Workflow, der diese Integration verwendet, entsprechend mit Werten gefüllt.
Input-Variablen sind daher immer sind Key-Value Paare wobei der Key im API Call als Platzhalter für die Werte verwendet wird. Wird über den Workflow ein Key nicht beschrieben, kann ein Default-Wert angegeben werden, der verwendet wird falls der Wert leer bleibt:

Der Example-Value wird ausschließlich und immer beim Ausführen der Tests-Funktionalität verwendet!

Authentication

Wähle ein zuvor angelegtes Secret aus, um Deinen API-Call abzusichern. Wird ein Token ausgewählt, wird es automatisch dem Header unter Your API Call hinzugefügt.

Your API call

Hierbei wird der anzusprechende API-Endpunkt hinterlegt und die Header (z.B. die Authentifizierung) für den API-Call gesetzt.

Es muss immer mindestens der Header Content-Type gesetzt werden. Aktuell erlauben wir die folgenden Content-Types, mit den folgenden Bedeutungen:

• application/json: Der angegeben Response-Body wird als JSON interpretiert versendet.
• none: Der angegeben Response-Body wird uninterpretiert versendet.
• application/x-www-form-urlencoded: Ermöglicht das Hinzufügen von beliebigen Key-Value-Paaren.
• multipart/form-data: Ermöglicht das Versenden von Binärdateien, wie z.B. Media-Assets welche über das Media Core-Behavior im Context als Assert-Id gespeichert wurden.

Test

Klicke auf den send-Button um einen API-Call mit den eingestellten Example-Values auszuführen. Nach Ausführung erscheint ein detailliertes Execution-Log:

Output definition

Jede Output-Integration kann einen oder mehrere Outputs in Form von Key-Value Paaren zur Verfügung stellen. In der Output-Definition werden die Namen für die Keys vergeben und per JSON Path aus der Response des API-Calls extrahiert und beschrieben:

Diese Werte stehen dann dem Workflow an entsprechender Stelle zur Verfügung: