Connect
Unter der Produktlinie Connect bieten wir Ihnen einzeln zu erwerbende Add-ons für KIX Pro an. Die Add-ons ermöglichen Ihnen den Datenaustausch mit Fremdsystemen und die Nutzung externer Datenbankverbindungen als Datenquelle zur weiteren Verwendung in KIX.
Typische Anwendungsfälle für Connect sind bspw.
Import von Organisations-, Kontakt- oder Assetdaten aus CRM- oder ERP-Systemen wie Navision, Axapta, Sugar CRM etc.
Anzeige von Kundendaten, Controlling Informationen aus CRM- oder ERP-Systemen wie Navision, Axapta, Sugar CRM etc.
Import von Assetdaten aus Endpoint-Management-/Inventarisierungs-/Discovery-Systemen wie Baramundi, i-doit, opsi, etc.
Anzeige von Warenbeständen zu Artikelnummern ("Warehouse Integration")
Übernahme von Ticketdaten aus anderen Systemen
Bereitstellung von Auswahlwerten in Formularfeldern an Tickets, Organisationen, Kontakten oder FAQ-Einträgen aus CRM- oder ERP-Systemen wie Navision, Axapta, Sugar CRM etc.
Den Agenten stehen somit die aktuellen Daten aus anderen Datenbankquellen für die Nutzung in KIX zur Verfügung. Die Daten werden bspw.
in Dynamischen Feldern an Tickets, Kontakten, Organisationen oder FAQ-Einträgen referenziert
in Detailansichten oder Dashboards kontextbezogen dargestellt
als Grundlage für Datenimporte in das KIX-Asset-Management (CMDB) verwendet
zur Erstellung von Tickets verwendet.
Installation
Gemeinsamer Funktionsumfang der Connect Add-ons
Die Add-ons der Connect-Linie greifen auf teilweise gemeinsame Kernfunktionen zurück, wie der Feldtyp "Data Source" für Dynamische Felder sowie erweiterte Macro Actions.
Feldtyp "Data Source"
Der Feldtyp Data Source wird mit Add-ons der Connect-Linie ausgeliefert und wird initial in Connect Database und Connect Webservice genutzt.
Mit Dynamischen Feldern vom Typ Data Source können Formularfelder eingebunden werden, deren Wertebereich in Connect-Datenquellen definiert ist. Sie ermöglichen, Inhalte aus externen Datenquellen an allen Objekten zu hinterlegen, welche Dynamische Felder unterstützen.
Sie lösen die in KIX Pro Version 17 existierenden Feldtypen RemoteDB und Invoker ab.
Die Funktionsweise entspricht der des Feldtyps Asset Reference. So können Einzel- und Mehrfachwerte in einem Formularfeld hinterlegt und die Informationen in einem Overlay eingeblendet werden.
Die Bereitstellung und Verwendung dieser Dynamischen Felder in Vorlagen und Aktionen für das Self Service Portal ist ebenfalls möglich. Beachten Sie jedoch die hinterlegten Zugriffsbeschränkungen (Rollenzuordnung) an der dem jeweiligen Feld zugeordneten Datenquelle. Die gewünschten Kundennutzerrollen z.B. "Customer", benötigen dann ebenfalls Zugriffsberechtigung auf die Datenquelle.
Abb.: Dynamisches Feld Typ "Data Source" im Dialog
Abb.: Dynamisches Feld Typ "Data Source" in den Ticketdetails
Konfigurationsparameter
Parameter | Beschreibung |
|---|---|
CacheTTL | Definiert, für wieviel Sekunden ein einmal an der Datenquelle angefragter Datensatz im KIX-Cache gehalten wird, bevor eine neue Anfrage an die Datenquelle gesendet wird. Z. B.: 3600 |
Data Source | Die anzufragende Datenquelle Z. B.: "Servicequotas (DB)" |
Default Display Column | Array von Spalte-Anzeige-Paaren. Definiert den Inhalt des Overlays bei der Darstellung des Dynamischen Feldes in den Detailansichten.
Zum Beispiel: Spalte: quota - Anzeige: Quota Spalte: cname - Anzeige: Org.-name Spalte: startdate - Anzeige: From Spalte: enddate - Anzeige: Until |
Display Pattern | Definiert, welche Attribute der Listenanfrage für die Darstellung eines Einzeleintrags (View-Mode und Auswahlliste) genutzt werden. Die Attributnamen (DB-Spaltennamen bzw. -Aliase) werden mittels Z. B.: <quota> (<cname>) |
Hinweis
Einige Macro Actions der Connect-Linie enthalten eine Debug-Option.
Wenn Sie das Debugging aktivieren, muss im SysConfig-Schlüssel der Wert debug gesetzt sein. Anderenfalls werden nur die von der Macro Action gelieferten Fehlermeldungen erfasst und in der Job Historie angezeigt, alle anderen Debug-Informationen jedoch nicht.
XSL Transformation (kurz XSLT) ist eine Sprache zur Transformation von XML-Dokumenten.
Die Macro Action XSL Transformation wird mit Add-ons der Connect-Linie ausgeliefert. Sie erlaubt die Umwandlung einer eingehenden Datenstruktur in eine andere Datenstruktur und damit die Erstellung komplexer Datenstrukturen. Somit können Wertübersetzungen, Wertextraktionen und Strukturveränderungen vorgenommen werden. KIX verwendet XSLT in Version 1.1.
Zweck der Macro Action ist es, Daten für die Verwendung in anderen Macro Actions vor- oder aufzubereiten, z. B. für Webhook Extended. Sie kann das Ergebnis von XSL-Transformationen als Inhalt im Request verwenden.
Gleichermaßen können Ergebnisse von Webanfragen (Responses) für die weitere Verwendung in anderen Macro Actions vorbereitet werden, z. B. für Asset erstellen oder aktualisieren.
Beim Einsatz der XSL-Transformation stehen KIX-eigene Funktionen bereit, um die Möglichkeiten von XSLT zu erweitern.
Die Macro Action übernimmt eine als Macro Variable oder Zeichenkette definierte Datenstruktur, wandelt diese in XML um und wendet darauf die XSL-Transformation auf Basis eines XSLT-Templates an. Das Ergebnis dieser Umwandlung steht dann zur weiteren Verwendung zur Verfügung.
Praktische Anwendungsfälle sind bspw.:
die Hinterlegung von Fremdsystem-IDs zu Tickets nach deren Übermittlung (Redmine, Confluence, Jira, etc.)
die Aufbereitung von Asset-Informationen zur Ablage in der KIX-CMDB (Inventarisierung)
oder die Fehlerbehandlung von Webhook Extended-Aufrufen.
Siehe auch: Beispiel: Redmine Issue erstellen
Abb.: Schema einer XSL Transformation
Parameter | Beschreibung |
|---|---|
Data | Das Ausgangsobjekt oder der JSON-String, der transformiert werden soll. Wird ein JSON-String angegeben, werden KIX-Platzhalter unterstützt. Beispiel: ${SomeMacroVariable}
oder JSON-String, z.B.:
{
"issue": {
"subject": "<KIX_TICKET_Title>",
"description": "Lorem ipsum..."
}
} |
Debug | Debug-Ausgaben de-/aktivieren. Mögliche Werte: yes | no Wenn aktiviert, werden die von der Macro Action gelieferten Debug-Informationen in der Job Historie angezeigt. Voraussetzung: Der SysConfig-Schlüssel Automation::MinimumLogLevel muss auf den Wert |
XSL Template | Das XSL Template für die vorzunehmende Transformation. Das Ergebnis einer Transformation muss zur weiteren Verwendung im root-Pfad des Dokuments enthalten sein. In Verbindung mit Macro Action ??? kann eine Fehlerbehandlung eingerichtet werden. Das nachfolgende Beispiel beinhaltet eine Auswertung des HTTP-Statuscodes und Aufbereitung des HTTP-Response-Inhalts. <?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:KIX="urn:KIX">
<xsl:output method="xml" encoding="utf-8" indent="yes"/>
<xsl:template match="RootElement">
<root>
<xsl:variable name="HTTPCode" select="HTTPCode"/>
<xsl:choose>
<xsl:when test="$HTTPCode='201'">
<RMIssueID><xsl:value-of select="Result/issue/id"/></RMIssueID>
</xsl:when>
<xsl:otherwise>
<RMIssueID><xsl:text>Not transfered to Redmine.</xsl:text></RMIssueID>
</xsl:otherwise>
</xsl:choose>
</root>
</xsl:template>
</xsl:stylesheet> |
Tags, die Array-Struktur erzwingen (ForceArray) | Tags, welche in den transformierten Daten nur einmal vorkommen, enthalten den Inhalt als String oder Hash. Wenn in der Datenstruktur zwingend ein Array-Inhalt für einen Tag benötigt wird, egal ob dieser nur einmal, oder mehrfach verwendet wird, kann dieser Tag hier angegeben werden. Mehrere Tags können mit Komma getrennt eingetragen werden. |
Leereinträge unterdrücken (SuppressEmpty) | Wenn ein Tag in den transformierten Daten keinen Inhalt hat, dann wird ein Fallback angewendet. Mögliche Optionen:
|
XSL TransformedData | Variablenname für die Ergebnisstruktur der Umwandlung Z. B.: |
KIX stellt einige spezifische Funktionen zur Auflösung von Identifikatoren (Ermittlung von Contact-, Organisation-, Asset-IDs aus Namen, Login-Kennern oder Nummern von Objekten) sowie für ergänzende Möglichkeiten in XSLT-Mappings bereit.
Der Aufruf der Aktionen bei Anwendung eines XSL-Templates führt zur Ersetzung des Funktionsaufrufs mit dem Ergebnis der Funktion.
Folgende Funktionen werden bereitgestellt; der Rückgabewert ist jeweils ein String:
AccessTokenLookup (String)
Liefert einen OAuth2-Access- Token für das per Parameter benannte OAuth2 Profil.
Mögliche Werte:
Office365Rückgabewerte: String
AssetGetIDByName (String)
ID des Assets basierend auf Asset-Name
Mögliche Werte:
ddsrv009Rückgabewerte: String
AssetGetIDByClassAndAttributeValue (String, String, String, String)
ID des Assets, basierend auf Assetklasse und einem beliebigen klassenspezifischen Attribut ('AssetClass, 'AttributeKey' , 'SearchValue', 'JoinSeparator', 'SplitSeparator')
Mögliche Werte: 'Computer', 'FQDN', 'chnb001.example.com', ',', ','
Rückgabewerte: String
AssetGetIDByClassAndName (String, String)
ID des Assets basierend auf Assetklasse und -name ( 'AssetClass', 'AssetName')
Mögliche Werte: 'Computer', 'chnb001'
Rückgabewerte: String
AssetClassGetIDByName (String)
ID der Assetklasse
Mögliche Werte: 'Computer'
Rückgabewerte: String
AssetGetIDByNumber (String)
ID des Assets basierend auf Assetnummer
Mögliche Werte: '634000001'
Rückgabewerte: String
Base64Decode (String)
Base64-Decodierung der übergebenen Zeichenkette
Mögliche Werte: 'U29tZUJhc2U2NFN0cmluZw=='
Rückgabewerte: String
Base64Encode (String)
Base64-Codierung der übergebenen Daten/Zeichenkette
Mögliche Werte: 'SomeDataString'
Rückgabewerte: String
ConfigGet (String)
Wert des durch "String" bezeichneten SysConfig-Eintrags vom Typ "String"
Mögliche Werte: 'SysConfigKey'
Rückgabewerte: String
ContactGetIDByEmail (String)
ID des Kontakts mit der gegebenen E-Mail
Mögliche Werte: 'max@example.com'
Rückgabewerte: String
ContactGetIDByUserLogin (String)
ID des Kontakts mit dem angegebenen USer-Login (nur wenn es einen Nutzer gibt)
Mögliche Werte: 'contact075'
Rückgabewerte: String
DeploymentStateGetIDByName (String)
ID des Verwendungsstatus
Mögliche Werte: 'ITSM::ConfigItem::Computer::Type', 'Desktop'
GeneralCatalogGetIDByClassAndName (String, String)
ID des General Catalog-Eintrags zur General Catalog-Klasse und Anzeigewert ('GC-Class', 'GC-Name')
Mögliche Werte: 'ITSM::ConfigItem::Computer::Type', 'Desktop'
Rückgabewerte: String
GenerateTOTP (String, String, String, String, String)
Generiert ein "Timebased One Time Password" (TOTP) aus den übergebenen Parametern.
Dieses kann via Macro-Variable im Header des WebhookExtended verwendet werden, um TOTPMFA- Authentifizierungen in Webhook-Aufrufen zu verwenden.
Mögliche Werte: 'KRUGKU3FMNZGK5CTORZG S3TH','30','6','SHA1','0'
Rückgabewerte: String
Parameter 1: Base32Secret
Das Shared Secret in Base32- Enkodierung
Parameter 2: TimeStep
Angabe für die Gültigkeitsdauer eines Token.
Standardwert: 30.
Erwartet eine natürliche Zahl.
Parameter 3: Digits
Länge des Tokens.
Standardwert: 6.
Erlaubt sind: 6, 7 oder 8.
Parameter 4: Algorithm
Verschlüsselungs-Algorithmus für den Token.
Standardwert: SHA1.
Erlaubt sind:
SHA1,SHA256undSHA512(Großschreibung ist relevant)
Parameter 5: Previous
Erzeugt ein vorheriges/ zukünftigen OTP.
Standardwert: 0
IncidentStateGetIDByName (String)
ID des Vorfallsstatus
Mögliche Werte:
OperationalRückgabewerte: String
MD5Sum (String)
MD5-Summe zu übergebener Zeichenkette
Mögliche Werte:
SomeStringRückgabewerte: String
OrganisationGetIDByName (String)
ID der Organisation mit gegebenem Namen
Mögliche Werte:
Harmony Shoal Inc.Rückgabewerte: String
OrganisationGetIDByNumber (String)
ID der Organisation mit der gegebenen Nummer
Mögliche Werte:
CN007Rückgabewerte: String
PatternMatch (String, String)
Gibt 1 zurück, wenn in der übergebenen Zeichenkette das Muster RegEx enthalten ist.
Es werden reguläre Ausdrücke in Perl verwendet.
Mögliche Werte: String, REGEX
Rückgabewerte: String
PatternRemove (String, String)
Entfernt aus der übergebenen Zeichenketten den auf RegEx zutreffenden Teil.
Es werden reguläre Ausdrücke in Perl verwendet.
Mögliche Werte: String, REGEX
Rückgabewerte: String
PatternReplace (String, String, String)
Ersetzt aus der übergebenen Zeichenketten den auf RegEx zutreffenden Teil.
Es werden reguläre Ausdrücke in Perl verwendet.
Mögliche Werte: String, REGEX, replacement
Rückgabewerte: String
SystemDataDelete (String)
Entfernt den vollständigen Eintrag zu einem übergebenen Schlüssel aus KIX, z. B. für Auth-Token
Mögliche Werte:
N2GBearerTokenRückgabewerte: String
SystemDataGet (String)
Gibt einen permanent in KIX hinterlegten und durch den Schlüssel identifizierten Wert zurück.
Ermöglicht, einen bpsw. in einem früheren "WebhookExtended"-Aufruf erhaltenen Auth-Token in weiteren Aufrufen zu verwenden.
Mögliche Werte:
N2GBearerTokenRückgabewerte: String
SystemDataSet (String, String)
Speichert einen Wert zu einem übergebenen Schlüssel permanent in KIX (z. B. Auth-Token), welcher durch eine Nutzer-Passwort-Anfrage generiert wird.
Ermöglicht bspw. einen per "WebhookExtended" erhaltenen Auth-Token im System zu speichern.
Mögliche Werte:
N2GBearerToken,__eyJ0eXAiOiJKV1QiLC...Rückgabewerte: String
TimeStamp ([String])
Optional: Gibt einen Zeitstempel zurück (jetzt+Offset Sekunden) im Format 'YYYY-MM-DD hh:mm:ss'
Mögliche Werte:
3600Rückgabewerte: String
TimeString (String, [String])
Wie "TimeStamp (OffsetInSeconds)", jedoch kann das Format entsprechend strftime definiert werden.
Mögliche Werte:
Format,3600Rückgabewerte: String
UserGetIDByLogin (String)
Ermittelt die ID des Nutzers, der durch den übergeben Loginnamen identifiziert wird.
Mögliche Werte:
mamuRückgabewerte: String
UserGetLoginByID (String)
Ermittelt das Login des Nutzers, der durch die übergeben ID identifiziert wird.
Mögliche Werte: 1
Rückgabewerte: String
Rückgabewerte aus XSL-Funktionen
In der Regel geben XSLT-Funktionen Zeichenketten (Strings) zurück. Diese können direkt innerhalb des XSLT wiederverwendet werden.
Werden spezifische XSLT-Funktionen aufgerufen, die komplexe Datenstrukturen zurück geben, kann auf die Einzelelemente der Strukturen zugegriffen werden.
Im nachfolgenden Beispiel wird eine hypothetische Funktion MyTicketGet() aufgerufen, die einen Ticket-Hash zurück gibt. Das Beispiel verwendet spezifische Angaben aus dem Hash für die weitere Verarbeitung.
Aufruf im XSLT-Template:
<xsl:variable name="Ticket" select="KIX:MyTicketGet(123)"/>
<Ticket>
<ContactID><xsl:value-of select="$Ticket//ContactID"/></ContactID>
<StateName><xsl:value-of select="$Ticket//State"/></StateName>
</Ticket>Ergebnis der JSON-Struktur nach XLS-Transformation:
"Ticket": {
"ContactID": "1701",
"StateName": "open"
}XML-inkompatible Parameter-Namen
XSLT ist eine Ausprägung von XML. Daher gelten Beschränkungen hinsichtlich der Zeichen, welche als Namen für Tags verwendet werden können. JSON unterliegt nicht den gleichen Beschränkungen. So sind bspw. in JSON Key-Strings wie " @name " möglich. Soll ein Präfix verwendet werden, ist das dem jeweiligen XML-Tag als Attribut " prefix " mitzugeben.
So erzeugt bspw. <id prefix="@">SomeIdentifierString</id> die JSON-Struktur "@id": "SomeIdentifierString",.
Typisierung von ausgehenden Daten
Sollen in ausgehenden Anfragen/Webrequests und dem darin enthaltenen JSON bestimmte Datentypen erzwungen werden, weil bspw. die anzusprechende Schnittstelle eine starke Typisierung fordert (z.B. Boolean oder Number), kann auch dies via XSLT gesteuert werden.
<eventSequenceNumber convert="number"> <xsl:text>1701</xsl:text> </eventSequenceNumber> <someBooleanValue convert="boolean"> <xsl:text>0</xsl:text> </someBooleanValue> <someOtherBooleanValue convert="boolean"> <xsl:text>1</xsl:text> </someOtherBooleanValue>
Folgende JSON-Struktur wird erzeugt:
"eventSequenceNumber": 1701, "someBooleanValue": false, "someOtherBooleanValue": true,
Gezieltes erzwingen von Array-Strukturen
Wird in den ausgehenden Daten an bestimmten Stellen zwingend eine Array-Struktur benötigt, während der gleiche Tag an einer anderen Stelle kein Array sein darf, weil das Datenschema dies fordert, kann auch dies via XSLT gesteuert werden. Dies wird beispielsweise in den Asset-Versionsdaten von KIX benötigt.
<SectionNetwork forceArray="1">
<NIC forceArray="1">
<NIC><xsl:text>lo</xsl:text></NIC>
<IPoverDHCP><xsl:text>No</xsl:text></IPoverDHCP>
<IPAddress forceArray="1"><xsl:text>127.0.0.1</xsl:text></IPAddress>
</NIC>
</SectionNetwork>Folgende JSON-Struktur wird erzeugt:
{
"SectionNetwork": [
"NIC": [
{
"NIC": "lo",
"IPoverDHCP": "No",
"IPAddress": [
"127.0.0.1"
]
}
]
]
}Die Macro Action Get Object Data ermittelt den bedarfsgerechten Inhalt von KIX Business Objekten, z. B. Tickets mit Artikeln und Anhängen, Assets mit Versionsdaten, Organisations- und Kontaktdaten
Sie führt eine KIX-interne Abfrage durch und gibt das ermittelte Objekt mit allen Details zur weiteren Bearbeitung an weitere Automatisierungsschritte zurück.
Das kann bspw. in Ticket-Jobs genutzt werden, um alle Ticketdaten - inklusive der zugehörigen Artikel - zu beziehen und zur weiteren Verarbeitung in XSL Transformationen bereit zu stellen. Ein anderer Anwendungsfall ist der Bezug der an einem Ticket referenzierten Daten (Organisation, Kontakt oder Assets).
Auf diesem Weg stehen mehr Angaben zur Verfügung, als über die aus Textbausteinen und Antwortvorlagen bekannten Platzhalter möglich sind.
Parameter | Beschreibung |
|---|---|
Beinhaltet | zu inkludierende Unterobjekte oder aufzulösende IDs Siehe Backend-REST-API Dokumentation: KIX API Dokumentation Z. B.: DynamicFields, Priority, Articles, Queue, State, Links |
Expands | zu erweiternde Unterobjekte Siehe Backend-REST-API Dokumentation: KIX API Dokumentation Z. B.: Links |
Item List | Bezeichner der Macro-Variable für weitere Verarbeitung der Rückgabe Z. B.: CompanyList |
ObjectID | ID des zu beziehenden Objekts Z. B.: 123 | ${SomeMAcroVariable} |
Object Typ | zu beziehender Businessobjekttyp Z. B.: Asset | Ticket | Organisation | Contact |
Die Macro Action Get Item From Data Source führt eine Detailanfrage an eine Connect Datenquelle durch.
Die Rückgabestruktur ist ein Hash, wobei die Attribut-/Spaltennamen bzw. Aliase der Detailanfrage die Schlüssel bilden.
Ein komplexes Beispiel ist in der Dokumentation für Connect Database enthalten.
{
"ID": 18,
"cname": "Hypokrates Medical Services",
"cno": "HMS",
"quota": 95,
"comments": "Some generic comment here.",
"startdate": "2021-01-01 00:00:00+00",
"enddate": "2022-01-01 00:00:00+00"
}Parameter | Beschreibung |
|---|---|
Data Source | Die anzufragende Datenquelle Z. B.: "Servicequotas (DB)" |
Item | Bezeichner der Macro-Variable für die weitere Verarbeitung der Rückgabe Z. B.: CurrCompanyData |
Item ID | ID des abzurufenden Datensatzes. Es werden KIX-Platzhalter und Macro Variablen unterstützt. Wird die Macro Action innerhalb einer Loop nach einem Get Item List From Data Source aufgerufen, kann per Punkt- Notation auf den ID-Wert innerhalb des Hashes der aktuellen Schleifenvariable zugegriffen werden. Beispiele:
|
Die Macro Action Get Item List From Data Source" führt eine Listenanfrage an eine Connect Datenquelle durch. Dabei können freie Suchkriterien und Werte für fixierte Suchattribute angegeben werden.
Die Rückgabestruktur ist ein "Array of Hashes", wobei die Attribut-/Spaltennamen bzw. Aliase der Listenanfrage die Schlüssel bilden.
Ein komplexes Beispiel finden Sie in der Dokumentation für Connect Database.
[
{"ID":11,"cno":"EMA","cname":"EM Automotive GmbH & Co. KG","quota":24},
{"ID":18,"cno":"HMS","cname":"Hypokrates Medical Services","quota":95}
]Verwendung Rückgabewert
In der Regel wird der Rückgabewert in einer weiteren Macro Action Schleife eingesetzt. Da diese ein Array erwartet, ist keine Aufbereitung des Rückgabewertes erforderlich.
Innerhalb dieser Schleife kann auf ID-Werte mittels der Punkt-Notation ${LoopVariable.ID} zugegriffen werden.
Parameter | Beschreibung |
|---|---|
Data Source | Die anzufragende Datenquelle Z. B.: "Servicequotas (DB)" |
Item List | Bezeichner der Macro-Variable für weitere Verarbeitung der Rückgabe Z. B.: CompanyList |
Parameters | JSON-Struktur der in der Datenquelle anzuwendenden fixierten Parameter, z. B.: {
"Param1":123,
"Param2": "Text Pattern",
"Param3": [123]
} |
Search | JSON-Struktur der in der Datenquelle anzuwendenden Suchkriterien. Der Aufbau entspricht dem von Filterkriterien in der KIX REST-API {
"Item": {
"AND": [
{
"Field": "id",
"Operator": "GT",
"Type": "NUMERIC",
"Value": "5"
},
{
"Field": "id",
"Operator": "LT",
"Type": "NUMERIC",
"Value": "9"
}
]
}
} |