Webhook-Ereignisse aus externen Systemen integrieren

Wie integrieren Sie als Systemadministrator Ihr CRM, Monitoring-Tool oder Ticketing-Tool mit der Automation Engine? Mit der AWIkönnen Sie Webhook-Ereignisobjekte erstellen, mit denen Sie Ihre Webhooks des externen Systems in die Event Engine integrieren können. Das Webhook-Ereignisobjekt kann Webhook-Ereignis-Payloads von externen Systemen in Echtzeit überwachen und abrufen.

Das folgende Übersichtsdiagramm zeigt, wie eine Webhook-Ereignis-Payload von der Event Engine und der Automation Engine behandelt wird:

Dieses Beispiel demonstriert die Dienst-Orchestrierung unter Verwendung der Funktionen der Automic system. Die Dienst-Orchestrierung zeichnet sich durch einen automatisierten Prozess aus, der auf verschiedenen Plattformen, Domänen und Anwendungen ausgeführt wird, um einen IT-Dienst bereitzustellen. Weitere Informationen finden Sie unter Info zur Dienst-Orchestrierung.

Um die Funktion Webhook-Ereignis nutzen zu können, sind die folgenden Komponenten und Kenntnisse erforderlich:

• Eine Installation von Analyticsmit der Rule Engine Siehe: Installieren von Analytics und der Event Engine

• Stellen Sie sicher, dass die folgenden Action Packs installiert sind. Sie sollten sie im Ordner PACKAGES in der Seitenleiste des Explorers in der Process Assembly-Perspektive sehen.

  • PCK.AUTOMIC_ANAYLTICS (Analytics Action Pack)
    
  • PCK.AUTOMIC_RULE_SIMPLE (Event Engine Rule Simple)
    Dieses Action Pack enthält vordefinierte Objektvorlagen, um einfache Bedingungen (wie >, >=, =) für die eingehenden ereignisgesteuerten Regeln zu erstellen. Verwenden Sie die Regeln, um ein ausführbares AE-Objekt auszulösen.
  • PCK.AUTOMIC_RULE_STATECHANGE (Event Engine Rule State Change)
    Dieses Action Pack enthält vordefinierte Objektvorlagen, mit denen Sie Aktionen abhängig vom Status eines ausführbaren Objekts oder Dienstes auslösen können.

  Hinweis: Wenn sie nicht in der Seitenleiste des Explorers aufgelistet sind, müssen Sie sie von unserem Marketplace unter https://marketplace.automic.com/ herunterladen und installieren. Anweisungen zur Installation eines Action Packs finden Sie unter Packs installieren in Mit Packs und Plug-ins arbeiten.

• Vorkenntnisse in der Implementierung von Ereignis- und Variablen (VARA)-Objekten
• Ein gutes Verständnis für Webhooks und deren Umsetzung
• Zugriff auf ein externes System, das die Verwendung von Webhooks ermöglicht
• Kenntnisse der JSONPath-Syntax
• Kenntnisse über das JSON-Schema Ihres externen Systems
  

Weitere Informationen finden Sie unter: WEBHOOK-Ereignisse

Einen begrenzten API-Schlüsselerstellen

Für Webhook-Endpunkte ist ein begrenzter API-Schlüssel erforderlich. Der begrenzte Schlüssel muss für den Mandanten generiert werden, auf dem das Webhook-Objekt ausgeführt wird. Wenn die externe Webhook-API (zum Beispiel JIRA) den Berechtigungsschlüssel im HTTP-Header nicht senden kann, kann er auch als URL-Parameter bereitgestellt werden.

 

Beispiel:

http://host:port/analytics/api/v1/100/12345?authorization=1cb812db-6616-49da-af97-3719aeaddc24

 

Weitere Informationen finden Sie unter Analytics REST-API – Allgemeine Informationen

Eine IA-Ereignisdefinition erstellen

Die IA-Ereignisdefinition stellt eine Ereignisstruktur dar. Die Event Engine verwendet die Ereignisstruktur, um Regeln auszulösen und Jobs, Scripts und Workflows auszuführen etc.

Die folgenden Schritte zeigen Ihnen, wie Sie eine Ereignisdefinition mit Hilfe von Webhooks aus Ihrer externen System-Ereignis-Payload erstellen.

1. Melden Sie sich auf einem Automation Engine-Mandanten an, dem ein IA-Agent zugewiesen ist. Siehe: Mandanten den Agenten zuordnen
   

2. Klicken Sie auf Process Assembly in AWI
   .

   • Klicken Sie in der Symbolleiste auf Objekt hinzufügen
   • Wählen Sie die VariablenstrukturAdministration-Perspektive, und erweitern Sie sie.
   • Wählen Sie XML-Variablen und erweitern Sie sie. Wählen Sie anschließend IA > EVENT_DEFINITION-Variable
     

3. Um eine IA-Ereignisdefinition aus Ihrer Webhook-Ereignis-Payload zu erstellen, müssen Sie über Vorkenntnisse über den Inhalt der Payload verfügen. Laden Sie eine Test-Ereignis-Payload mit einem zuvor definierten Endpunkt herunter oder verwenden Sie Ihren Systemführer, um das Schema zu verstehen.

   Hinweis:Die Ereignis-Payload befindet sich im JSON-Format. Um die Schlüsselattribute abzubilden, müssen Sie über Vorkenntnisse in der JSONPath-Syntax verfügen.

   Beispiel:
   Das folgende Beispiel zeigt die Seite "Ereignisdefinition" (links) und eine Webhook-Ereignis-Payload in JSON (rechts). Diese Informationen helfen Ihnen herauszufinden, wie Sie Ihre Ereignisdefinition erstellen können.

   Wichtig!

   • Bei der Definition Ihrer Schlüsselattribute wird Ihre Ereignis-Payload in einem strukturierten Schema angezeigt. Sie müssen Ihre Attributschlüssel in einem flachen Schema definieren.
   • Obwohl es keine Regel für die Benennung von Schlüsselattributen gibt, empfehlen wir Ihnen, diese so zu benennen, wie sie im JSON erscheinen. Diese Vorgehensweise ermöglicht es Ihnen, sie beim Erstellen eines Webhook-Ereignisobjekts einfach zuzuordnen.

   
   Geben Sie die folgenden Details in das Blatt "Ereignisdefinition" ein und beachten Sie, was Sie erzielen wollen, wenn externe Ereignisse empfangen werden:

   • Attributschlüssel: Schlüssel-Wert-Paar (zum Beispiel Anwendungsnachricht, Statusereignis, Bestätigung usw.)
   • Beschreibung: Optional
   • Typ: Sie können in Bezug auf Ihren Attributschlüssel zwischen den Optionen "String", "Zahl" oder "Boolean" wählen.
     
     
4. Klicken Sie auf Speichern, nachdem Sie Ihre Ereignisdefinition vervollständigt haben.

Weitere Informationen zur Ereignisdefinition finden Sie unter: IA-Ereignis-VARA-Objekte

Ein Webhook-Ereignis erstellen, zuordnen und filtern

Ein Webhook-Ereignis erzeugt einen Endpunkt für einen externen Webhook, um Payloads zur Verarbeitung an die Event Engine zu senden. Die folgende Schritt-für-Schritt-Anleitung zeigt Ihnen, wie Sie Werte mit JSONPath erstellen, zuordnen und empfangene Payloads filtern.

1. Klicken Sie im AWI auf Process Assembly.
   

   • Klicken Sie in der Symbolleiste auf Objekt hinzufügen
   • Ereignisbaum (EVNT) auswählen und erweitern
   • IA-Variablen auswählen und erweitern und WEBHOOK Ereignis auswählen

   Hinweis: Informationen zum Sichern des Webhook-Endpunkts finden Sie unter "Sichern des Backends" unter Installieren von Analytics und der Event Engine. Der Webhook läuft auf dem IA-Agenten und verwendet die gleichen SSL-Einstellungen. Wenn Sie für jeden Webhook unterschiedliche Zertifikate verwenden möchten, installieren Sie mehrere IA-Agenten und verwenden Sie das Zertifikat für jeden Agenten.
   
   Im Objektblatt "Webhook-Ereignisobjekt" befinden sich zwei Abschnitte:
   

   • Endpunktinformation
     • Pfad
   • Empfangene Daten zu Ereignisdefinitionen zuordnen
     
     • Ereignisdefinition
     • Empfangenen Daten mit bedingten Operatoren filtern
     • Werte über JSONPath zuordnen
       
2. Endpunkt-Information – Pfad:
   Wenn ein neues Webhook-Ereignisobjekt im AWI erstellt wird, wird eine URL mit einem eindeutigen Pfad generiert. Der eindeutige Pfad wird mit dem Automation Engine-Login über den ID des Mandanten und einer eindeutigen Nummer generiert. Diese gesamte URL (einschließlich des Pfades) wird in der Konfiguration der Webhook-URL Ihres externen Systems verwendet.
   
   Die URL hat die folgende Struktur:
   
   Adresse des IA Automation-Agenten/ + "analytics/api/" + Version der API (derzeit "v1") + Mandanten-Nr ./ + eindeutige Nr.
   
   Beispiel:
   Das folgende Beispiel zeigt die Endpunktstruktur (URL+Pfad).
   
   
   Beispiel:
   Das folgende Beispiel zeigt die Endpunktstruktur (URL+Pfad), wie sie in AWI
   
   
   
   
   erscheint
3. Empfangene Daten zur Ereignisdefinitionen zuordnen – Auswahl der Ereignisdefinition:
   Wählen Sie im Webhook-Ereignisobjektblatt die Ereignisdefinition aus, um mit der JSONPath-Zuordnung und dem Filterprozess zu beginnen. Die Ereignisdefinition enthält Ihre definierten Attributschlüssel.
   
   Beispiel:
   
   
   
4. Empfangene Daten zu Ereignisdefinitionen zuordnen –Empfangene Daten filtern
   Mit dieser Funktion können Sie empfangene Ereignis-Payloads mithilfe grundlegender bedingter Operatoren filtern. Wenn die Filterbedingungen erfüllt sind, werden sie verwendet, um Regeln für eingehende Ereignisse auszulösen.
   
   Hinweis: Die Operatoren für den Filter sind auf der Seite Einfache Regel definiert.
   
   Um einen Filter anzuwenden, müssen Sie zuerst einen JSONPath aus der empfangenen Payload auswählen. Sie können den JSONPath auswählen, indem Sie den Pfad manuell unter Verwendung der automatischen Empfehlung eingeben. Oder Sie treffen die Auswahl über den JSONPath Builder und die Schaltfläche Ausdruck erstellen.
   
   Automatische Empfehlung
   Wenn Sie den JSONPath manuell eingeben, müssen Sie Kenntnisse über das Schema der empfangenen Payload und JSONPath besitzen. Die Funktionalität der automatischen Empfehlung kann Ihnen dabei helfen, einen JSONPath-Ausdruck zu erstellen, sie kann diesen jedoch nicht auswerten.
   
   JSONPath Builder
   Mit dem JSONPath Builder können Sie folgende Operationen ausführen:
   
   • Ein JSONPath-Beispiel kopieren und in den Editor einfügen
   • Einen Ausdruck manuell eingeben und diesen mit Hilfe des Felds Ausdruck auswerten
   • Empfangene Daten filtern, indem Sie eine Zeile im Editor auswählen und auf die Schaltfläche Ausdruck erstellen klicken, um einen Ausdruck und das Ergebnis automatisch zu generieren
   • Werte zuordnen, indem Sie eine Zeile im Editor auswählen und auf die Schaltfläche Ausdruck erstellen klicken, um einen Ausdruck und ein Ergebnis automatisch zu generieren
     

   Beispiele:
   Im folgenden Beispiel ist die Zeile phoneNumbers ausgewählt. Nachdem Sie auf die Schaltfläche Ausdruck erstellen geklickt haben, wird das phoneNumbers-Array ausgewertet, und es werden ein Ausdruck und ein Ergebnis generiert.
   
   

   Filter erstellen

   Wenn Sie den JSONPath Builder im Abschnitt Empfangene Daten filtern verwenden, können Sie die generierten Ausdrücke verwenden, um schnell Filter zu erstellen.

   
   

    

   
   
   Beispiel:
   Der folgende Beispielfilter basiert auf einem Webhook-Ereignis in der JIRA-Anwendung namens Issue_created. Wenn eine JIRA-Ereignis-Payload mit dem Ereignisnamen issue_created empfangen wird, löst sie eine Regel in der Event Engine aus.
   
   
   
   Hinweis: Der Deep-Scan-Operator "..." wird für Filterausdrücke nicht unterstützt. Weitere Informationen finden Sie hier.
   
   Es ist auch möglich, mehrere externe Systemereignistypen über die Funktion Zuordnung hinzufügen zuzuordnen. Daher können Sie die gleiche Webhook-URL (Endpunkt) in Ihrem externen System für mehrere Ereignistypen registrieren.
   
   Beispiel:
   Das folgende Beispiel zeigt eine externe Repository-Anwendung, die konfiguriert ist, um zwei Ereignis-Payloads (Push und Modified) an eine URL (Endpunkt) zu senden.
   
   
   
5. Empfangene Daten zu Ereignisdefinitionen zuordnen - Werte mit JSONPath Builder zuordnen:
   Nachdem Sie die Ereignisdefinition ausgewählt haben, werden Ihre zuvor erstellten Attributschlüssel aufgelistet. Die nächste Aufgabe ist die Zuordnung der Attributschlüssel zum JSONPath der eingehenden Ereignis-Payload. Die Zuordnung ist notwendig, da die Regellogik der Event Engine nur bei Ereignissen im Format der Ereignisdefinition funktioniert.
   
   Werte mit dem JSONPath-Builder zuordnen
   
   Wenn Sie den JSONPath-Builder im Abschnitt Werte über JSONPath zuordnen verwenden, können Sie ein Ereignisdefinitionsattribut schnell einem JSONPath zuordnen.
   
   
   
   Beispiel:
   Im folgenden Beispiel wurde jeder Ereignisdefinitionsattributschlüssel dem entsprechenden JSONPath zugeordnet.
   
   
6. Wählen Sie die Registerkarte Attribute und wählen Sie den IA-Agenten aus
   
   .
7. Speichern und dann das Webhook-Ereignis ausführen.
   

Eine Regel erstellen

Regeln sind Bausteine, die auf Regellogik basieren. Unter Regellogik kann man sich einen Satz Anweisungen (oder eine Formel) vorstellen, der bzw. die bestimmte Folgerungen anwendet. Beispiel: IF eine Bedingung erfüllt ist, THEN führen Sie eine Aktion aus.

Zwei Regeltypen können verwendet werden, um ein Ereignis auszulösen:

• Einfache Regel
• Statusänderungsregel

Hinweis: Informationen zum Installieren der Analytics Action Pack-Regeln finden Sie unter:Eine Event Engine-Regel installieren.

Alle Regeln weisen folgende Merkmale auf:

• Sie führen ein Automation Engine-Objekt aus, wenn die Regel auslöst.
• Ein Regeltyp wird durch einen Parametersatz definiert, der den PromptSet-Werten des ausgewählten AE-Objekts einfach zugewiesen werden kann.
• Ein Regeltyp bietet einen festgelegten Satz an Output-Parametern

1. Wählen Sie den Regeltyp aus der Liste aus und fügen Sie ihn hinzu.



2. Konfigurieren Sie die Regel (basierend auf dem ausgewählten Regeltyp). Die Konfiguration wird anhand von Anwendungsfällen in anderen Kapiteln genauer beschrieben. Siehe: RULE-Ereignisse

   Beispiel:
   Fortsetzung des UI-Meldungsbeispiels. Wenn der Ereignistyp gleich "repo: msg_change" ist, wird die Regel ausgelöst und führt einen Job aus, der ein Ticket für das Übersetzungsteamerstellt.

   

3. Speichern Sie die erstellte Regel

4. Führen Sie die Regel aus und überprüfen Sie, ob die Regel ausgeführt wird, indem Sie die Registerkarte Ausführungen öffnen

5. Wenn eine Regel ausgelöst wird, wird eine neue Child-Ausführung generiert. Sie können eine Child-Ausführungsaufgabe öffnen, um das AE-Objekt, das durch den Auslöser ausgeführt wird, anzuzeigen
6. Die Anzahl der Ereignisse erhöht sich jedes Mal, wenn die Regel ausgelöst wird

Hinweis: Die Anzahl der Ereignisse erhöht sich nicht für jedes Ereignis, das die Regel eventuell mitverfolgt.