SECTOR NORD AG Tipp des Monats

[Znuny] MS Teams Integration

Voraussetzungen

System: Znuny 6.1.x - Implementierung des Ticket-Invokers im ersten Znuny-Feature-Release
MS Teams: Eine Webhook URL - Offizielle Anleitung zur Erstellung eines Webhooks.

Funktion

Mit dieser Konfiguration wird ein Web-Service zu Znuny hinzugefügt mit dem Eventbasierte Nachrichten an MS Teams verschickt werden.
Zur Darstellung in Teams werden sogennante "Office 365 Connector Cards" verwendet:

Diese Karten basieren auf einer JSON-Struktur und werden später über das XSLT-Mapping generiert.

Erstellen des Webservices

Webservices werden über Admin-Oberfläche erstellt und verwaltet:
Admin → Webservices → Webservice hinzufügen

Hier kann über die Ready2Adopt-Webservices direkt eine MS Teams Konfiguration importiert werden:
MS Teams Notification auswählen → Button "Ready2Adopt-Webservices importieren"

Als nächstes wird der Netzwerktransport für "Znuny als Requester" konfiguriert. HTTP:REST ist hier schon vorausgewählt und enhält einige Voreinstellungen.
Für die weitere Konfiguration wird nun der Webhook benötigt:

Der Webhook wird in 2 Teile aufgeteilt. Der 2te Teil ist alles nach und inkl. des letzten "/".

Im Beispiel:

Webhook: https://sectornordag.webhook.office.com/webhookb2/04d23e1b-31d0-4d8e-88e5-d3b8549eef00@9c6e1dad-726e-42d6-8d62-aa0e205e6043/IncomingWebhook/847574eb4ec047cabd98e04b444b2606/7cb2c48f-1171-4356-a16f-1bc80fb8b1b9

1ster Teil: https://sectornordag.webhook.office.com/webhookb2/04d23e1b-31d0-4d8e-88e5-d3b8549eef00@9c6e1dad-726e-42d6-8d62-aa0e205e6043/IncomingWebhook/847574eb4ec047cabd98e04b444b2606

2ter Teil: /7cb2c48f-1171-4356-a16f-1bc80fb8b1b9

Es werden die die Einträge YOURHOOK_PART1 und /YOURHOOK_PART2 mit den entsprechenden Links ersetzt.

Danach kann die Konfiguration gespeichert werden.

Den Webservice ausführen

Das aufrufen des Webservices erfolgt eventbasiert.

Hierfür kann der vorher eingestellte Invoker "Escalate" ausgewählt und konfiguriert werden.

Es werden nun die entsprechenden Events ausgewählt, bei denen die Benachrichtigung ausgeführt werden soll. Die Darstellung, je nach Event kann später über das Mapping umgesetzt werden.
Dadurch spart man sich die Einrichtung eines neuen Web-Services für unterschiedliche Events

Anschließend wird das "Mapping für ausgehende Anfragedaten" in Form einer XSLT Datei konfiguriert.

XSLT-Mapping

<?xml version="1.0" encoding="UTF-8"?>
<xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:date="http://exslt.org/dates-and-times" extension-element-prefixes="date">
    <xsl:output method="xml" encoding="utf-8" indent="yes"/>
    <xsl:template match="RootElement">
        <xsl:copy>
            <themeColor>0076D7</themeColor>
            <Initialtype>MessageCard</Initialtype>
            <Initialcontext>http://schema.org/extensions</Initialcontext>
            <summary>Ticket <xsl:value-of select="//Ticket/TicketNumber" /> is escalated</summary>
            <sections>
                <activityTitle>Ticket #<xsl:value-of select="//Ticket/TicketNumber" /> is escalated</activityTitle>
                <markdown>true</markdown>
                <facts><Name>Owner</Name><Value><xsl:value-of select="//Ticket/OwnerData/UserFullname"/></Value></facts>
                <facts><Name>State</Name><Value><xsl:value-of select="//Ticket/State"/></Value></facts>
                <facts><Name>Type</Name><Value><xsl:value-of select="//Ticket/Type"/></Value></facts>
            </sections>
            <potentialAction>
                <potentialActiontype>ViewAction</potentialActiontype>
                <potentialActioncontext>http://schema.org</potentialActioncontext>
                <name>View ticket in Znuny</name>
                <target><OTRS_CONFIG_HttpType>://<OTRS_CONFIG_FQDN>/<OTRS_CONFIG_ScriptAlias>/index.pl?Action=AgentTicketZoom;TicketID=<xsl:value-of select="//Ticket/TicketID" /></target>
            </potentialAction>
        </xsl:copy>
    </xsl:template>
</xsl:transform>

Um genauer zu erfahren, wie die Struktur des Tickets aussieht, kann man in den Debugger des Webservices schauen. Das Debug-Level sollte dafür auf "Fehlersuche" stehen.

Danach werden die gemappten Daten so aufbereitet, dass Sie von Teams als MessageCard formatiert gelesen werden können.

Dabei werden zunächst die 3 Teile "sections target potentialAction" zu Arrays konvertiert.

Als letztes werden noch einige Teile über RegEx ausgetauscht, da für die JSON-Struktur bestimmte Abschnitte mit "@..." angegeben werden müssen. Diese Einträge kann man aber nicht
in der XSLT vornehmen.

Dynamisches Mapping

Möchte man einen Webservice bei verschiedenen Events ausführen, möchte aber ebenfalls unterschiedlichen Text an Teams übergeben, so kann dies dynamisch über das XSLT-Mapping gelöst
werden. Anstatt einen neuen Webservice anlegen zu müssen, wird hier innerhalb des Mappings auf den Eventtypen gefiltert und je nach Eventtyp ein anderes Template erstellt.

Im Beispiel:

Dynamisches XSLT-Mapping Quelle reduzieren

<?xml version="1.0" encoding="UTF-8"?>
<xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:date="http://exslt.org/dates-and-times" extension-element-prefixes="date">
    <xsl:output method="xml" encoding="utf-8" indent="yes"/>
    
    <!--Defining a variable with the event-type-->
    <xsl:variable name="Event">
        <xsl:value-of select="//Event/Event"/>
    </xsl:variable>
    
    <!--Creating template-mode based on Eventtype-->
    <xsl:template match="/">
        <xsl:choose>
            <xsl:when test="$Event='TicketPriorityUpdate'">
                <xsl:apply-templates select="//Ticket" mode="PriorityUpdate" />
            </xsl:when>
            <xsl:otherwise>
                <xsl:apply-templates select="//Ticket" mode="TicketQueueUpdate" />
            </xsl:otherwise>
        </xsl:choose>
    </xsl:template>
    
    <!--Creating template for the connector card based on template-mode-->
    <xsl:template match="Ticket" mode="PriorityUpdate">
        <xsl:copy>
            <themeColor>0076D7></themeColor>
            <Initialtype>MessageCard</Initialtype>
            <Initialcontext>http://schema.org/extensions</Initialcontext>
            <summary>Ticket <xsl:value-of select="//Ticket/TicketNumber" /> hat die Priorität verändert</summary>
            <sections>
                <activityTitle>Ticket #<xsl:value-of select="//Ticket/TicketNumber" /> hat die Priorität auf "<xsl:value-of select="//Ticket/Priority"/>"  geändert</activityTitle>
                <markdown>true</markdown>
                <facts><Name>Besitzer</Name><Value><xsl:value-of select="//Ticket/OwnerData/UserFullname"/></Value></facts>
                <facts><Name>Queue</Name><Value><xsl:value-of select="//Ticket/Queue"/></Value></facts>
                <facts><Name>Betreff</Name><Value><xsl:value-of select="//Ticket/Articles[last()]/Subject"/></Value></facts>
                <facts><Name>Text</Name><Value><xsl:value-of select="//Ticket/Articles[last()]/Body"/></Value></facts>
            </sections>
            <potentialAction>
                <potentialActiontype>ViewAction</potentialActiontype>
                <potentialActioncontext>http://schema.org</potentialActioncontext>
                <name>View ticket in Znuny</name>
                <target><OTRS_CONFIG_HttpType>://<OTRS_CONFIG_FQDN>/<OTRS_CONFIG_ScriptAlias>index.pl?Action=AgentTicketZoom;TicketID=<xsl:value-of select="//Ticket/TicketID"/></target>
            </potentialAction>
        </xsl:copy>
    </xsl:template>
    <!--Creating template for the connector card based on template-mode-->
    <xsl:template match="Ticket" mode="TicketQueueUpdate">
        <xsl:copy>
            <themeColor>0076D7></themeColor>
            <Initialtype>MessageCard</Initialtype>
            <Initialcontext>http://schema.org/extensions</Initialcontext>
            <summary>Ticket <xsl:value-of select="//Ticket/TicketNumber" /> wurde verschoben</summary>
            <sections>
                <activityTitle>Ticket #<xsl:value-of select="//Ticket/TicketNumber" />  wurde verschoben</activityTitle>
                <markdown>true</markdown>
                <facts><Name>Besitzer</Name><Value><xsl:value-of select="//Ticket/OwnerData/UserFullname"/></Value></facts>
                <facts><Name>Queue</Name><Value><xsl:value-of select="//Ticket/Queue"/></Value></facts>
                <facts><Name>Priorität</Name><Value><xsl:value-of select="//Ticket/Priority"/></Value></facts>
                <facts><Name>Betreff</Name><Value><xsl:value-of select="//Ticket/Articles/Subject"/></Value></facts>
                <facts><Name>Text</Name><Value><xsl:value-of select="//Ticket/Articles/Body"/></Value></facts>
            </sections>
            <potentialAction>
                <potentialActiontype>ViewAction</potentialActiontype>
                <potentialActioncontext>http://schema.org</potentialActioncontext>
                <name>In Znuny öffnen</name>
                <target><OTRS_CONFIG_HttpType>://<OTRS_CONFIG_FQDN>/<OTRS_CONFIG_ScriptAlias>/index.pl?Action=AgentTicketZoom;TicketID=<xsl:value-of select="//Ticket/TicketID"/></target>
            </potentialAction>
        </xsl:copy>
    </xsl:template>
</xsl:transform>

Zurück