Citunius API Commons¶

What is Citunius API Commons?¶

Citunius API Commons is a platform-independent, general-purpose class library for business chatbots running on the business bot platform. The class library provides basic classes to implement frequently recurring tasks with little effort.

Use Citunius API Commons library¶

The Citunius API Commons library is copied to the lib directory in the Chatbot project.

Language Service¶

Whenever the chatbot has to communicate with users in other languages, different language labels have to be managed within your chatbot application. The language service from the Citunius API Commons library can be used for this purpose. The appropriate language label is identified by a unique key and the language code.

The language labels are stored by language in the various properties file located at resource → localization.

For example:

string_de.properties for German language labels
string_en.properties for English language labels
string_it.properties for Italian language labels
string_es.properties for Spanish language labels
string_pt.properties for Portuguese language labels
string.properties for all language labels that cannot be assigned to a specific language (fallback language is English)

The UTF-8 encoded language files only contain the language labels of the respective language such as string_en.properties and string_de.properties:

1	Common.Hello=Hello

1	Common.Hello=Hallo

To load a language label, you have to call the function getString("<Language Key>", "<Language code>"). The following example illustrates the usage:

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¶

The chatbot application can use templates, which are text files with predefined text fragments to get the desired output. With placeholders like ${name}, you can add own outputs to the text fragments. The chatbot provides the actual values of these placeholders and the final output is generated based on the template + all placeholders.

The input of templates is a series of named variables that you usually provide as Map. The variable values can be simple strings, numbers or lists. The output of templates is written into a Writer that you provide. The Citunius API Commons library already provides all required components for the template service, so that loading and using templates for you chatbot is very easy.

All template files are located in the resource → templates directory. In the following example, the template file is named list.ftl and has the placeholders title and description.

Content of list.ftl

1
2
3

${title}
--------------------------
${description}

Java-Example:

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 output is now in string compiledPage and can be returned to the Business Bot Platform to send the output as an instant message to the user.

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

Filestore Service¶

The Filestore service facilitates the management of files such as images, audio, video and documents that are received by the user but also sent to the user. A file which is stored in the file store of the Business Bot Platform receives always a file UUID that can be used to retrieve the file again at a later stage. The UUID (Universally Unique Identifier) is a unique UUID consisting of a 16-byte number that uniquely identifies the file in the filestore.

The registration of a file in the BBP-Filestore is performed as illustrated in the following example:

// 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;
}

In case that you want to send a file to a user, the return message must contain the FileUUID. The FileUUID is specified in format <FileUUID:XXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXXXXX>.

1
2
3

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

Callback Service¶

The callback functionality was introduced with BBP release R2018 FP1832 to allow the execution of scheduled tasks. In case you want a callback functionality for your chatbot running on the platform, you can simply use the existing API of the business bot platform.

In the chatbot, a callback from the business bot platform must be registered with the following function:

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;
}

Once you have registered the callback via web service, the Business Bot platform calls the chatbot as defined. The following function in the chatbot is then called to allow the chatbot to perform further activities:

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();
}

If you want to stop the scheduled chatbot callback, the callback must be unregistered from the business bot platform via web services:

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¶

For a detailed description of the classes and interfaces, see the JavaDoc documentation.