Connect Webservice
KIX als Provider - Spezifische Endpunkte
Neben der universellen REST-API von KIX können mit dem Add-on Connect Webservice spezifische Endpunkte mit konkreten Funktionen oder, im Gegensatz zur REST-API, mit erweiterten Funktionen eingerichtet werden. Dies erfolgt im Menü .
Anwendungsszenarien können sein:
Schnittstelle für die Aktualisierung von Kontakt-/Organisationen
Das auslösende System hat keine Kenntnis über die KIX-internen Identifikatoren oder darf nur ausgewählte Informationen bereit stellen. So kann beispielsweise nur die E-Mail-Adresse eines Kontaktes oder die Nummer der Organisation bekannt sein, jedoch soll eine geänderte Anschrift, Telefonnummer oder Nachname erfasst werden.
Die Aufgabe des Endpunktes ist es, zum übermittelten Kenner den passenden Eintrag zu ermitteln und zu aktualisieren.
Schnittstelle für die Aktualisierung von Asset-Daten
Die Meldung von freiem Speicher oder dem zuletzt angemeldeten Benutzer kann direkt an KIX erfolgen, ohne dass auf eine Synchronisation der Daten durch KIX gewartet werden muss. Kritische Informationen können damit schneller und einfach am Asset bereit gestellt werden.
Schnittstelle für das Monitoring von Meldungen
IT-Monitoring-Services können Störungen direkt an KIX melden. Die Meldung beinhaltet bspw. einen Geräte-Identifikator und den aktuellen Fehlerzustand.
Mit den erweiterten Makro Actions von Connect Webservice kann nicht nur ein Ticket erstellt, sondern bei wiederholten Meldungen auch aktuelle Informationen zu einem bestehenden, offenen Ticket ergänzt werden. Eine Anbindung per Mail ist nicht erforderlich.
Schnittstelle für Gerätedaten bzw. Erstellung von Tickets aus unvollständigen Eingaben
Technische Monitoring-Tools oder Geräte können Fehlerzustände an eine definierte URL melden. Übermittelt werden in der Regel nur die Gerätenummer und ein Fehlercode.
Die Aufgabe des Endpunktes ist es, die übermittelten Daten zu vervollständigen, sodass ein Ticket mit allen notwendigen Informationen erstellt oder ein bereits bestehender Vorgang zum Gerät aktualisiert werden kann.
Ergänzung von Informationen an Tickets
Mittels einer einfachen URL kann direkt eine Information ("Flag") an einem Ticket gesetzt werden. Der Klick auf die URL setzt ohne Aufruf des Self Service oder Agentenportals eine Rückmeldung ab.
Ein konkretes Beispiel sind niedrigschwellige Genehmigungen oder Ablehnungen. Der Empfänger einer E-Mail mit einer solchen URL kann diese anklicken und somit einen Antrag direkt ablehnen oder freigeben.
Achtung
Der Versand der URL in einer E-Mail birgt Unsicherheiten. Jeder mit Zugriff auf die URL könnte eine Zustimmung auslösen. Daher sollte dieses Verfahren nur bei begrenzten Risiken eingesetzt werden.
Eine Übersicht aller konfigurierten Endpunkte finden Sie im Admin Modul unter . Die Übersicht enthält zudem den Zugriff auf das jeweilige endpunktspezifische Log.
Abb.: Übersicht der in KIX Connect eingerichteten Endpunkte
Das Log kann in der Oberfläche eingesehen oder heruntergeladen werden:
Abb.: Geöffnete Ansicht des Logfiles für einen Endpunkt
Eigene Endpunkte können Sie im Admin Modul unter einrichten. Die Einrichtung erfolgt schrittweise:
Definition des Endpunktes
Definition der auszuführenden Aktionen
Zugriff auf die erhaltenen Parameter
Hinweis
Nachfolgend wird anhand eines vereinfachten Beispiels ein Endpunkt eingerichtet.
Im Anwendungsszenario wird ein Ticket aus unvollständigen Angaben erstellt. Die von einem Monitoring-Tool oder Gerät übermittelten Informationen wie Gerätenummer und Fehlercode werden genutzt, um aus diesen unvollständigen Angaben ein Ticket zu generieren und dabei die fehlenden Angaben zu ergänzen.
Das Beispiel dient lediglich der Veranschaulichung und erhebt keinen Anspruch auf produktive Einsatzfähigkeit.
Abb.: Definition des Beispiel-Endpunkts "Simple Ticket Creation"
Folgende Angaben werden in der Definition des Endpunktes hinterlegt:
Parameter | Beschreibung |
|---|---|
Name | Name des Endpunkts Z. B.: Simple Ticket Creation |
Route | Der Endpunkt als Unterpunkt zur REST-API /api/v1/ webservices/<EndpointRoute> Z. B.: simpleticket/:DeviceName Mittels des Platzhalters Im Beispiel wird der Parameter |
Authentication | Definiert, ob der Endpunkt eine Authentifizierung verlangt (aktuell noch keine verfügbar). z. B.: none Als Workaround kann dies über Parameterauswertung in der Macro-Verarbeitung realisiert werden. |
Request Methode | Soll ein Proxy-Server angesprochen werden? Wenn ja, mit welcher Methode? Mögliche Werte: GET | POST | PUT | PATCH | DELETE | OPTIONS | HEAD |
Log Level | Detailtiefe des Logs Mögliche Werte: error | notice | info | debug |
Comment | Kurzbeschreibung des Endpunktes z.B. Verwendungszweck, Prozesszuordnung oder relevante Gegenseite. |
Gültigkeit | De-/Aktivieren des Endpunktes |
Endpunktaktionen sind grundsätzlich wie Macros in Jobs aufgebaut und offerieren die gleichen Möglichkeiten.
Um auf die Inhalte eines Requests wie URL-Parameter oder den Inhalt eines POST-Requests zuzugreifen, wird die Macro-Variable ${Request} bereit gestellt. Diese beinhaltet alle Angaben des erhaltenen Requests.
Ein einfacher Endpunkt ist ein (erweitertes) Echo. Dazu verwendet das Endpunkt-Macro ausschließlich die Aktion Set Response. Diese Macro Action erlaubt die Definition des HTTP-Status Codes, der HTTP-Header sowie des zu übermittelnden Inhaltes. Die einfachste Ausprägung ist, mit einen Statuscode ohne weitere Angaben zu antworten.
Abb.: Konfiguration des "Simple Ticket Creation"-Endpunkts als Echo
Bei Verwendung des Endpunkts wird somit die vollständige Anfrage als Antwort zurück geliefert:
shell>$ curl --request GET \
--url 'http://yourkix-api.kix.cloud/api/v1/webservices/simpleticket/0815ABC?ErrorCode=3001701' \
--header 'Content-Type: application/json' \
| jq
{
"Parameters": {
"ErrorCode": "3001701;",
"DeviceName": "0815ABC"
},
"RequestMethod": "GET",
"ContentType": "application/json",
"HttpUserAgent": "curl/8.1.2",
"RequestUri": "/webservices/simpleticket/0815ABC?ErrorCode=3001701",
"ContentLength": null,
"Headers": {
"Accept": "*/*"
},
"RemoteAddr": "::ffff:10.255.0.2",
"RemotePort": "63873",
"QueryString": "ErrorCode=3001701%3B"
}Auf die Inhalte des Requests kann mit der Macro-Variable ${Request} zugegriffen werden. Ist in der Anfrage ein Parameter XYZ enthalten, so wird dieser mittels ${Request.Parameters.XYZ} abgerufen. Gleiches gilt für Inhalte des Bodys eines POST-/PUT-/PATCH-Requests.
Im folgenden Beispiel soll ein Ticket erstellt und dabei die Angaben aus dem Request genutzt werden. Dazu wird die Macro-Definition angepasst. Die erste Action ist nun der Aufruf eines Macros vom Typ Ticket, welches wiederum die TicketCreate-Aktion benutzt und deren Rückgabewert als Antwort auf den Endpunkt-Aufruf liefert.
Konfiguration der Macro:
Aktion: Execute Macro
Macro: Ticket
1. Aktion: Ticket erstellen
NewTicketID: NewSimpleTicketID
Title:
Fehler Bericht für ${Request.Parameters.DeviceName} ${Request.Parameters.ErrorCode})
Artikeltext:
Geräte Name: ${Request.Parameters.DeviceName} Fehler Code: ${Request.Parameters.ErrorCode}
Kontakt: admin
Kanal: note
Sender Typ: external
Priorität: 2 high
Team: Service Desk
Typ: Incident
Aktion: Set Response
Status Code: 200
Headers: Content-Type: application/json
Content: {"ID": ${NewSimpleTicketID}}
Abb.: Konfiguration Endpunkt-Makro mit Parameterzugriff (Teil 1)
(Für eine bessere Übersicht wurden nicht relevante Parameter der Macro-Action "Ticket Create" ausgeblendet.)
Abb.: Konfiguration Endpunkt-Makro mit Parameterzugriff (Teil 2)
Ein zuvor eingerichteter Endpunkt kann über die REST-API unter /api/v1/webservices/<EndpointRoute> aufgerufen werden.
Ist die REST-API bspw. unter https://yourkix-api.kix.cloud erreichbar und wurde ein Endpunkt mit der Route /simpleticket eingerichtet, so kann dieser unter der URL https://yourkixapi.kix.cloud/api/v1/webservices/simpleticket aufgerufen werden. Dabei muss die HTTP-Methode verwendet werden, die der Endpunkt-Konfiguration entspricht.
Tipp
In Verbindung mit den Möglichkeiten weiterer Macro Actions wie ObjectGet, XSLTransform, Set Dynamic Field, CreateOrUpdateAsset, CreateOrUpdateContact, CreateOrUpdateOrganisation, usw. können Sie die Funktionen der Schnittstelle weiter spezialisieren und auf den konkreten Anwendungsfall anpassen.
Beispiel: Aufruf des Simple-Ticket-Endpunkts (Verwendung jq für Formatierung)
Der Aufruf GET https://yourkix-api.kix.cloud/api/v1/webservices/simpleticket/0815ABC?ErrorCode=3001701 soll ein Ticket zum Gerät "0815ABC" mit dem Fehlercode "3001701" erstellen.
shell> curl --request GET \
--url 'http://yourkix-api.kix.cloud/api/v1/webservices/simpleticket/0815ABC?ErrorCode=3001701' \
--header 'Content-Type: application/json' \
| jq
{
"ID": 3
}Das Ergebnis ist des Aufrufs ist ein neues Ticket:
Abb.: Neues Ticket, welches durch den Endpunkt erstellt wurde
KIX als Requester - Verwendung von Webhooks
Das Add-on Connect Webservice ermöglicht die Einbindung, d. h. Nutzung von HTTP/s-Webservices in KIX. Dabei können die Webservices sowohl Datenquelle als auch Ziel für die aktive Datenübermittlung sein.
Gängige Synonyme für diese Funktionen sind auch "ausgehende Webhooks" oder "Invoker".
In Unterscheidung zu Connect Database wird kein direkter Datenbankzugriff genutzt, sondern der Zugriff auf eine Webschnittstelle via HTTP/s. Darüber hinaus kann Connect Webservice auch Informationen an die angebundenen Webservices übermitteln, statt diese nur zu konsumieren. Typische Szenarien sind:
Übermittlung von Informationen an dritte Vorgangs-/Ticketsysteme, wie bspw. Jira, Redmine, Trello, BMC, etc.
Auslösen von Softwareauslieferungen durch Endpoint-Managementsysteme wie Baramundi, ido-IT, OPSI, etc.
Übermittlung von Abrechnungsdaten aus Tickets an CRP- oder ERP-Systeme wie Navision, Axapta, Sugar CRM etc.
Die technische Voraussetzung ist das Vorhandensein einer HTTP/S-Verbindung vom KIX-Backend zum Zielsystem einschließlich der Zugangsdaten (falls erforderlich) mit entsprechenden Berechtigungen.
Das Add-on Connect Webservice enthält zusätzliche Macro Actions für die Kommunikation mit anderen Webservices.
Die Macro Action ermöglicht die aktive Kommunikation mit einem anderem Webservice.
Mögliche Auslöser der Macro Action können spezifische Änderungen an einem Ticket oder Asset sein. Mittels periodischer Jobs können auch Listen von Einträgen abgerufen und verarbeitet werden.
Konkrete Anwendungen sind bspw. die Inventarisierung der Asset-Datenbank von KIX oder die proaktive Erstellung von Tickets.
Die Macro Action funktioniert ähnlich der im Basisprodukt enthaltenen Macro Action Webhook. Sie unterscheidet sich darin, dass komplexe, mehrstufige Datenstrukturen als Nutzlast im Aufruf (Request) übergeben werden können. Zudem kann die Antwort (Response) des aufgerufenen Webservices entgegen genommen und für weitere Macro Actions (z. B. XSL Transformation oder Get Object Data) weiterverwendet werden.
Achtung
Die Parameter Client Certificate, Client Key, Client Key Password, CA Certificate und CA Directory dienen der Authentifizierung mittels SSL-Zertifikaten.
Die Angaben für Client Certificate, Client Key, CA Certificate und CA Directory sind Pfandangaben auf dem Backend-Container.
Nur verwenden, wenn Know-How zu diesem Authentifizierungsverfahren besteht!
Alle relevanten Zertifikate sind vom Administrator auf dem Backend-Container einzubinden und zu pflegen! Keine Pflege über das Frontend!
Parameter | Beschreibung |
|---|---|
Response | Variablenname für die Ergebnisstruktur des Webrequests. Es wird ein strukturiertes Objekt zurückgegeben, welches HTTPCode, Status, Content, Header (Key-Value-Paare) und Result mit dem Ergebnis als JSON-Objekt enthält. |
URL | Die aufzurufende URL. Es werden KIX- Platzhalter unterstützt. |
Method | die Aufrufmethode (HTTP-Verb) Mögliche Werte: GET | POST | PUT | PATCH | DELETE | OPTIONS | HEAD |
Use Proxy | Soll ein Proxy-Server angesprochen werden? Mögliche Werte: yes | no |
Proxy | Welcher Proxy Server soll angesprochen werden? Z. B.: http://proxy.example.com:3128 Ist nichts angegeben, wird die allgemeine Proxy-Einstellung aus dem SysConfig-Schlüssel verwendet. |
Headers | zu übermittelnde HTTP-Header Z. B.: Content-Type: application/json |
Content | Der zu übermittelnde Inhalt ("payload"). Kann als JSON-Zeichenkette oder als Macro-Variable angegeben werden. Es werden KIX-Platzhalter unterstützt. Beispielsweise: {
"issue": {
"project_id": 1,
"subject": "<KIX_TICKET_Title>",
"description": "Lorem ipsum..."
}
}oder ${SomeMacroVariable}JSON-Quotierung bei PlatzhalterinhaltenBei der Verwendung von Platzhaltern im Content ist darauf zu achten, dass deren Inhalte bereits JSON-quotiert vorliegen. Das ist insbesondere bei mehrzeiligen Inhalten nicht der Fall. Sollte solch ein Platzhalter benutzt werden, kann dieser zunächst einer Macro-Variablen zugewiesen und diese nachgehend JSON-quotiert eingefügt werden.
|
Client Certificate | Vollständiger Pfad und Name der SSL-Client-Zertifikatsdatei. Unterstützte Formate: PEM, DER, PKCS#12 |
Client Key | Vollständiger Pfad und Name der SSL-Key-Zertifikatsdatei |
Client Key Password | Das Passwort der SSL-Key-Zertifikatsdatei, falls diese verschlüsselt ist |
CA Certificate | Vollständiger Pfad und Name der Certification-Authority-Zertifikatsdatei zur Validierung der SSL-Zertifikatsdatei |
CA Directory | Vollständiger Pfad zum Ordner in dem die relevanten Certification-Authority-Zertifikatsdateien im System abgelegt sind |
Disable SSL-Verification | Deaktiviert die Prüfung von SSL-Zertifikaten bei HTTPS-Verbindungen |
debug | Erweitertes Logging für den Aufruf de-/ aktivieren. Mögliche Werte: yes | no Tipp: Debug-Informationen können auch der Job-Historie entnommen werden. |
Beispiele für die Verwendung der Macro Action finden Sie unter:
Diese Macro Action ermöglicht das Übermitteln von Anhängen an andere Webservices, die Multipart/FormData empfangen können.
Beispielsweise, um aus einem Ticket oder bei Anlage eines Tickets ein Jira-Issue zu erstellen, welches auch die Anhänge enthält, die am Artikel hinterlegt sind.
Parameter | Beschreibung |
|---|---|
Response | Variablenname für die Ergebnisstruktur des Webrequests. Z. B.: MyAttachmentResponse Es wird ein strukturiertes Objekt zurückgegeben, welches HTTPCode, Status, Content, Header (Key-Value-Paare) und Result mit dem Ergebnis als JSON- Objekt enthält. |
URL | Die aufzurufende URL. Es werden KIX- Platzhalter unterstützt. Z. B.: http://192.168.188.48:3001/rest/ api/2/issue/KIX-123/attachments |
Use Proxy | Soll ein Proxy-Server angesprochen werden? Mögliche Werte: yes | no |
Proxy | Welcher Proxy Server soll angesprochen werden? Z. B.: http://proxy.example.com:3128 Ist nichts angegeben, wird die allgemeine Proxy-Einstellung aus dem SysConfig-Schlüssel verwendet. |
Headers | zu übermittelnde HTTP-Header Beispielsweise:
|
Attachment Data | Der zu übermittelnde Inhalt. Z. B.: ${SomeMacroVariableWithStructure} Hier wird i.d.R. eine Macro Variable verwendet, die ein Objekt mit den Strukturen Content, ContentType und Filename enthalten muss, z.B.: SomeMacroVariableWithStructure = {
"Content": "<base64 encoded content here>",
"ContentType": "image/png",
"Filename": "sample.png"
}Weiterführende Hinweise siehe Macro Actions: |
Debug | Erweitertes Logging für den Aufruf de-/ aktivieren. Mögliche Werte: yes | no Tipp: Debug-Informationen können auch der Job-Historie entnommen werden. |
Beispiel:
Es wird ein spezifischer Endpoint konfiguriert, der ein Array von Assets, Kontakten, Organisationen oder Ticketdaten entgegen nimmt. Diese Daten werden in einer Macro Action Schleife verarbeitet um daraus jeweils das betreffende KIX-Objekt zu erstellen (Asset, Kontakt, Organisation oder Ticket).
Die IDs der innerhalb der Schleife zu erstellenden Objekte sollen gesammelt werden, um nach der Abarbeitung eine Sammelantwort/Response mit allen erzeugten IDs zurück zu geben. Zum Sammeln der IDs wird ein Array benötigt.
Anwendung in Macros
Macro-Variablen können mehrere Werte aufnehmen und somit nein Array bilden. Die einzelnen Werte werden dabei durch Komma getrennt (s. auch Variablen):
${Variable1,Variable2}Ist einer der übergebenen Parameter bereits ein Array, so werden die beiden Arrays konkateniert:
Variable1 := ['Test1.1','Test1.2']
Variable2 := ['Test2.1','Test2.2']
${Variable1,Variable2} == ['Test1.1','Test1.2','Test2.1','Test2.2']Erweiterte Operationen/Filter
Für erweiterte Array-Operationen werden mit KIX Connect Webservice zusätzliche Variablen-Filter bereit gestellt.
Hinweis
Die Funktionen verändern nicht die eigentliche Variable, sondern gelten nur für den entsprechenden Aufruf.
Soll das Ergebnis persistent sein, muss die Macro Action Variable setzen verwendet werden.
Parameter | Beschreibung |
|---|---|
VariableUtil.Push | Wandelt die Variablen in ein Array (falls es noch keines ist) Der übergebene Wert wird am Ende des Arrays angefügt. Beispiel: Variable1 := ['Test1.1','Test1.2']
Variable2 := ['Test2.1','Test2.2']
${Variable1|VariableUtil.Push(${Variable2})} == ['Test1.1','Test1.2',['Test2.1','Test2.2']] |
VariableUtil.Pop | Wandelt die Variablen in ein Array (falls es noch keines ist) Der übergebene Wert wird am Ende des Arrays entfernt. Beispiel: Variable1 := ['Test1.1','Test1.2']
${Variable1|VariableUtil.Pop} == ['Test1.1'] |
VariableUtil.Shift | Wandelt die Variablen in ein Array (falls es noch keines ist) Der übergebene Wert wird am Anfang des Arrays entfernt. Beispiel: Variable1 := ['Test1.1','Test1.2']
${Variable1|VariableUtil.Shift} == ['Test1.2'] |
VariableUtil.Unshift | Wandelt die Variablen in ein Array (falls es noch keines ist) Der übergebene Wert wird am Anfang des Arrays angefügt. Beispiel: Variable1 := ['Test1.1','Test1.2']
Variable1 := ['Test2.1','Test2.2']
${Variable1|VariableUtil.Unshift(${Variable2})} == [['Test2.1','Test2.2'],'Test1.1','Test1.2'] |
VariableUtil.InitialPush | Wandelt den Wert einer Variable in ein Array (falls es noch keines ist) Ist der Variablenwert der leere String, wird ein leeres Array initialisiert Der übergebene Wert wird am Ende des Arrays angefügt. Beispiel: Variable1 := ''
Variable2 := 'Test1'
${Variable1|VariableUtil.InitialPush(${Variable2})} == ['Test1'] |
VariableUtil.AsArray | Wandelt den Wert einer Variable in ein Array (falls es noch keines ist) Beispiel: Variable1 := 'Test1'
${Variable1|VariableUtil.AsArray} == ['Test1'] |