# Adaptive Cards

Neben der Möglichkeit, die Darstellung von Antwort-Elementen im Editor zu pflegen (vgl. Formatierung im Editor ) unterstützt die Kauz-NLU auch die Darstellung mithilfe von Adaptive Cards.

Adaptive Cards ist ein von Microsoft entwickeltes Framework für die einfache Darstellung komplexer Inhalte und wird z. B. in Microsoft Produkten wie Teams oder Outlook eingesetzt. Die Darstellung mit Adaptive Cards ist insbesondere für Kunden interessant, die komplexe Datenstrukturen im Chat abfragen, übermitteln oder darstellen wollen. Das können z. B. Suchergebnisse aus Chat-&-Search , Formulardaten, Tabellen oder Produktübersichten sein.

Es gibt zwei Arten von Adaptive Cards:

• Statische Adaptive Cards sind besonders geeignet für die Darstellung von nicht-veränderlichen Inhalten, wie z. B. Antworttexten. Hinweis: In Antworttexten können Platzhalter aus dem Platzhaltermanagement im Editor genutzt werden.
• Dynamische Adaptive Cards bestehen aus zwei Komponenten: einer Vorlage (payload) und Daten (data). Die Daten werden bei der Darstellung anstelle von Variablen in der Vorlage eingesetzt. Damit sind dynamische Darstellungen komplexer Datenstrukturen möglich. Die Daten können aus anderen Kauz-NLU-Modulen bezogen werden, z. B. dem Chatverlauf oder Dialogplanparametern (vgl. hierzu Parameter-Abfrage ). Daten können aber auch aus externen API-Schnittstellen von Kunden abgerufen werden.

Adaptive Cards werden aus JSON-Daten erzeugt.

Die Vorentwicklung der JSON-Daten für Adaptive Cards findet mit dem Adaptive Cards Designer statt. Im Designer finden Sie auch Beispiele für mögliche Anwendungsszenarien von Adaptive Cards.

Wenn Sie mit dem Design zufrieden sind, schicken Sie den JSON-Payload Ihrer Karte an Ihre Kauz-Projektleitung. Diese hinterlegt die Karte für Sie im Chatbot.

Eine Referenz auf die Karte ist im Editor bereits an Dialogplan-Reaktionen möglich. Schreiben Sie dafür adaptiveCard={Name der Karte} in das Actions-Feld einer Reaktion.

Wenn Ihr Design die dynamische Auflösung von Variablen erfordert, müssen diese im Gesprächsverlauf zusammen mit dem Payload übergeben werden. Bitte besprechen Sie mit Ihrer Kauz-Projektleitung, ob dies für Ihren Anwendungsfall gegeben ist.

Adaptive Cards können sog. Actions enthalten, welche das Ausführen von Aktionen definieren. Aktionen werden standardmäßig als Button dargestellt, können aber auch als Selection Action an ein Element in der Adaptive Card gehängt werden. In letzterem Fall wird die Aktion ausgeführt, wenn das entsprechende Element angeklickt wird.

Eine Beschreibung der vom Kauz-Standard-Frontend unterstützten Aktionen finden Sie nachfolgend.

Diese Aktion öffnet eine spezifizierte URL. Information zur Spezifikation finden Sie hier: Action.Url.

Diese Universal-Aktion sammelt Informationen aus Input-Feldern, führt diese bei Bedarf mit Daten-Feldern zusammen und führt die im verb spezifizierte Aktion aus. Information zur allgemeinen Spezifikation finden Sie hier: Action.Execute.

Diese Aktion sendet einen HTTP-Request an eine definierte URL ab. Minimal angegeben werden muss der type, das verb sowie die url. In der Adaptive-Card gesammelte Daten werden automatisch an den Request angehängt.

"actions": [
	{
    "type": "Action.Execute",
    "verb": "sendHttpRequest",
    "style": "positive",
    "title": "Formular absenden",
    "data": {
      "url": "http://127.0.0.1:1880/ping",
      "method": "POST",
      "contentType": "urlencoded",
      "headers": {
           "Authorization": "",
           "Cookie": "",
           "Content-Type": "application/x-www-form-urlencoded"
         }
      }
    }
  ]

Es empfiehlt sich, in der Antwort auf den HTTP-Request eine Ergebniskarte zu übermitteln, welche die ursprüngilche Karte bei erfolgreicher Übermittlung ersetzt. Wird keine Ergebniskarte übermittelt, verbleibt die ursprüngliche Karte und kann erneut abgesendet werden.

Die ursprüngliche Karte kann durch die Ergebniskarte ersetzt werden, wenn:

• die HTTP-Antwort einen Body enthält
• und der Body einen JSON-Wert enthält
• und der JSON-Wert ein Feld type enthält
• und dieses den Typ AdaptiveCard hat.

msg.payload = {
    "type": "AdaptiveCard",
    "body": [
        {
            "type": "TextBlock",
            "text": "Vielen Dank für das Ausfüllen des Formulars.",
            "wrap": true
        },
        {
            "type": "FactSet",
            "facts": facts
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5"
}

Diese Aktion öffnet ähnlich wie Action.OpenUrl eine spezifizierte URL. In diesem Fall handelt es sich um einen Mailto-Link, welcher den konfigurierten E-Mail-Client des*der Chatbotnutzer*in öffnet.

Die Action erlaubt die Spezifikation der Empfänger-E-Mail-Adresse, eines Betreffs und des Inhalts. Daten, die in der Adaptive Card eingesammelt werden, können dynamisch ersetzt werden. Verwenden Sie hierzu das Mark-Up {{Variablenname}} im Text. Zeilenumbrüche können mit \n eingefügt werden.

"actions": [
    {
      "type": "Action.Execute",
      "verb": "sendMailClient",
      "title": "E-Mail-Client öffnen",
      "data": {
          "address": "service@kauz.ai",
          "subject": "Betreff der Mail",
          "body": "Sehr geehrte Damen und Herren,\n Bitte berücksichtigen Sie meine Auswahl: {{choice}}.\n Viele Grüße"
      }
    }
  ]

Diese Aktion erlaubt das Versenden einer Mail mit strukturiertem Inhalt an eine konfigurierte Mail-Adresse und einen bereitgestellten E-Mail-Host.

Die Action erlaubt die Spezifikation eines Betreffs und des Inhalts. Daten, die in der Adaptive Card eingesammelt werden, können dynamisch ersetzt werden. Verwenden Sie hierzu als Mark-Up doppelte geschweifte Klammern {{ im Text, z. B. {{Variablenname}}. Zeilenumbrüche können mit \n eingefügt werden.

"actions": [
    {
        "type": "Action.Execute",
        "title": "Absenden",
        "id": "sendenbutton",
        "verb": "sendMailAPI",
        "data": {
            "subject": "Kontaktanfrage von {{name}}",
            "body": "Sehr geehrte Damen und Herren,\n\n hier sind meine Kontaktdaten:\n\n Name: {{name}} \n\n E-Mail: {{mailAddress}} \n\n Rückruf erwünscht: {{callbackWanted}} \n\nTelefonnummer: {{phoneNumber}} \n\n Rückruf erwünscht am: {{callbackDate}} \n\n um: {{callbackTime}}.\n\n\n Viele Grüße \n\n {{name}}"
        }
    }
]