Zum Inhalt

Citunius API Commons

Was ist Citunius API Commons?

Citunius API Commons ist eine plattformunabhängige, allgemein verwendbare Klassenbibliothek für Business Chatbots die auf der Business Bot Plattform ausgeführt werden. Die Klassenbibliothek stellt grundlegenden Klassen zur Verfügung, um häufig wiederkehrende Aufgaben mit geringen Aufwand umzusetzen.

Verwenden der Citunius API Commons Bibliothek

Die Citunius API Commons Bibliothek wird im Chatbot-Projekt in das lib-Verzeichnis kopiert.

Language Service

Sobald der Chatbot mit Benutzern in verschiedenen Sprachen kommunizieren soll, müssen verschiedene Sprachlabels verwaltet werden. Dazu kann der Language-Service aus dem Citunius API Commons Bibliothek verwendet werden. Der passende Sprachlabel wird über einen eindeutigen Key und der Sprache identifiziert.

Die Sprachlabels werden nach Sprache in die verschiedenen Properties-Datei abgelegt, die sich unter resource → localization befinden.

Zum Beispiel:
  • string_de.properties für deutsche Sprachlabels
  • string_en.properties für englische Sprachlabels
  • string_it.properties für italienisch Sprachlabels
  • string_es.properties für spanische Sprachlabels
  • string_pt.properties für portugiesische Sprachlabels
  • string.properties für alle Sprachlabels, die keiner festgelegten Sprache zugeordnet werden können (fallback Sprache ist englisch)

Die UTF-8 kodierten Sprachdateien beinhalten nur die Sprachlabel der jeweiligen Sprache wie beispielsweise string_en.properties und string_de.properties:

1
Common.Hello=Hello

1
Common.Hello=Hallo

Um ein Sprachlabel zu laden, ruft man die Funktion getString("<Language Key>", "<Language code>") auf. Folgendes Beispiel verdeutlicht die Anwendung:

1
2
3
4
5
LocalisationService ls = new LocalisationService(pluginMap);
String languageLabelEnglish = ls.getString("Common.Hello", "en");
System.out.println(languageLabelEnglish+" John"); // Prints 'Hello John'
String languageLabelGerman = ls.getString("Common.Hello", "de");
System.out.println(languageLabelGerman+" John"); // Prints 'Hallo John'

Template Service

Im Chatbot können Vorlagen definiert werden, die Textdateien mit vordefinierten Textbausteinen sind, um die gewünschte Ausgabe zu erhalten. Mit Platzhaltern wie ${name} können dann vom Chatbot eigene Ausgaben eingefügt werden. Der Chatbot liefern dazu die tatsächlichen Werte für die Platzhalter und die endgültige Ausgabe wird auf der Basis der Vorlage + Platzhaltern generiert.

Die Eingabe von Templates ist eine Reihe von benannten Variablen, die Sie in der Regel als Map bereitstellen. Die Variablenwerte können einfache Strings, Zahlen aber auch Listen sein. Die Ausgabe von Templates wird in einen Writer geschrieben, den Sie bereitstellen. Sei die Citunius API Commons Bibliothek bereits alle benötigten Komponenten für den Template Service bereitstellt, ist das Laden und Verwenden von Template sehr einfach.

Alle Template-Dateien befinden sich im Verzeichnis resource → templates. Im folgenden Beispiel hat die Template-Datei den Namen list.ftl sowie die Platzhalter title und description.

Inhalt der list.ftl

1
2
3
${title}
--------------------------
${description}

Java-Beispiel:

1
2
3
4
5
6
7
8
9
TemplateService ts = new TemplateService(pluginMap);
Template templatePage = ts.getTemplate("list.ftl");
Map<String, Object> dataPage = new HashMap<String, Object>();
Writer outPage = new StringWriter();
dataPage.put("title", "The Headline of the day");
// dataPage.put("title", ls.getString("Generic.Results.PageTitle", defaultLanguage)); // If you want to load the title for another language
dataPage.put("description", "The body of the day");
templatePage.process(dataPage, outPage); 
String compiledPage = outPage.toString();

The Ausgabe befindet sich nun im String compiledPage und kann an die Business Bot Platform zurückgegeben werden, um die Ausgabe als Instant-Nachricht an den Benutzer zu senden.

1
2
PluginReturnMessage pluginReturnMessage = new PluginReturnMessage(null, outPage.toString(), null);
return pluginReturnMessage;

Filestore Service

Der Filestore Service erleichtert die Verwaltung von Dateien wie beispielsweise Bilder, Audio, Video und Dokumenten, die vom Benutzer empfangen und auch an den Benutzer gesendet werden. Eine Datei die im Filestore der Business Bot Plattform gespeichert wird, erhält eine Datei-UUID die jederzeit immer über diese UUID abgerufen werden kann. Die UUID (Universally Unique Identifier) ist eine eindeutige Ein UUID besteht aus einer 16-Byte-Zahl, welche die Datei im Filestore eindeutig kennzeichnet.

Die Registrierung einer Datei im BBP-Filestore erfolgt wie im folgenden Beispiel:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
// Upload and register local file to BBP FileStore
String filePath = pluginMap.get(ConstantsPlugin.PLUGIN_WORKDIR)+"/image.jpg";
try {
    WebService ws = new WebService(pluginMap);
    String fileUUID = ws.registerFileToBBPFileStore(filePath);
    logger.info("Local WorkDirFile ["+filePath+"] has been registered to BBP FileStore successfully: UUID: ["+fileUUID+"]");
} catch (Exception e) {
    System.out.println("Unable to register local WorkDirFile ["+filePath+"] to BBP FileStore: "+e.getMessage());
    return null;
}

Soll eine Datei an einem Benutzer gesendet werden, so muss die Rückgabenachricht die FileUUID enthalten. Die FileUUID wird im Format <FileUUID:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX> angegeben.

1
2
3
String fileUUID = "550e8400-e29b-11d4-a716-446655440000";
String replyMessage = "<FileUUID:"+fileUUID+">";
return replyMessage;

Callback Service

Die Callback-Funktionalität wurde mit dem BBP-Release R2018 FP1832 eingeführt, um die Ausführung von zeitgesteuerten Tasks zu ermöglichen. Wenn das Ziel eine Callback-Funktionalität für einen Chatbot ist, die auf der Plattform läuft, kann dies einfach über die vorhandene API der Business Bot Plattform passieren.

Im Chatbot muss dazu ein Callback von der Business Bot Plattform mit der folgenden Funktion registriert werden:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
public boolean registerCallback(MobileUserAccount mobileUserAccount) {
    String cronSchedule = "0 0/1 * * * ? *";
    String callbackMessage = "reminder-xy";
    ChatbotCallback chatbotCallback = new ChatbotCallback(Integer.parseInt(pluginMap.get(ConstantsPlugin.BOTID)), Integer.parseInt(pluginMap.get(ConstantsPlugin.PLUGIN_ID)), mobileUserAccount.getId(), cronSchedule, callbackMessage);

    // Register chatbot callback to BBP webservices
    String receiptId = null;
    try {
        WebService ws = new WebService(pluginMap);
        receiptId = ws.registerChatbotCallback(chatbotCallback);
    } catch (Exception e) {
        logger.error("Unable to register chatbot callback ["+chatbotCallback.getCallbackMessage()+"] to BBP webservices: "+e.getMessage());
        return false;
    }
    if (receiptId != null && receiptId.length() != 0) {
        logger.info("Chatbot callback ["+chatbotCallback.getCallbackMessage()+"] has been registered to BBP webservices successfully. Receipt Id: ["+receiptId+"]");
    } else {
        logger.error("Failed to register chatbot callback ["+chatbotCallback.getCallbackMessage()+"] to BBP webservices");
        return false;
    }
    return true;
}

Wenn der Callback über die Webservices registriert wurde, ruft die Business Bot Plattform den Chatbot wie definiert auf. Die folgende Funktion im Chatbot wird dann aufgerufen, damit der Chatbot weitere Aktivitäten durchführen kann:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
public String handleIncomingCallback(String tenantId, String accountId, String message, String jsonMobileUserAccount) {
    logger.info("handleIncomingCallback() called");

    JSONObject jsonObjectMobileUserAccount = new JSONObject(jsonMobileUserAccount);
    MobileUserAccount mobileUserAccount = new MobileUserAccount(jsonObjectMobileUserAccount);

    String userId = Utilities.getMobileAppSettingValue(Utilities.getMobileAppSettingParameterNameUserId(tenantId, accountId, pluginMap), mobileUserAccount.getPrimaryMobileDevice().getPrimaryMobileApp().getMobileAppSettings());
    if (null != userId) {
        logger.info("User identification ["+Utilities.getMobileAppSettingParameterNameUserId(tenantId, accountId, pluginMap)+"] has been found: ["+userId+"]");            
    } else {
        logger.error("User identification ["+Utilities.getMobileAppSettingParameterNameUserId(tenantId, accountId, pluginMap)+"] not found for mobile user ["+mobileUserAccount.getUsername()+"]");
        return null;
    }

    PluginReturnMessage pluginReturnMessage = new PluginReturnMessage(null, "Callback message: ["+message+"]", null);
    return pluginReturnMessage.toJson().toString();
}

Wenn der geplanten Chatbot-Callback gestoppt werden soll, muss der Callback bei der Business Bot Plattform über Webservices abgemeldet werden:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
public boolean unregisterCallback(int id) {
    // Unregister chatbot callback from BBP webservices
    try {
        WebService ws = new WebService(pluginMap);
        if (ws.unregisterChatbotCallback(id)) {
            logger.info("Chatbot callback id ["+id+"] has been unregistered from BBP webservices successfully.");
        } else {
            logger.error("Failed to unregister chatbot callback id ["+id+"] from BBP webservices");
            return false;
        }
    } catch (Exception e) {
        logger.error("Unable to unregister chatbot callback id ["+id+"] from BBP webservices: "+e.getMessage());
        return false;
    }
    return true;
}

BusinessLogicApi.Commons JavaDoc

Eine detaillierte Beschreibung der Klassen und Interfaces finden Sie in der JavaDoc-Dokumentation.