Business Bot Components

Package Structure

The Java project has a directory structure for clear structuring of the various contents. A default is to separate the directory with the source code and the compiled class files. Usually, the folder names for Java EE projects are src and bin.

Note

Notice for Eclipse: Development environments such as Eclipse translate Java types from mod:src folder into bin folder, and copy resources such as images and NLS files to the mod:src folder on each build. Eclipse supports this structure by default if option mod:Create separate folders for source and class files is activated in the dialog for a new Java project under mod:Project layout.

Note

Notice for NetBeans: Under NetBeans the default structure is somewhat different and is closely linked to the build tool Ant. The folder mod:src contains the default classes and resources, a second folder test the test classes and resources. The compiled Java classes are stored in the folder build/classes. The result of the build, a jar file in the case of a simple Java project, is located in the dist folder.

The directory structure also has a mod:lib and mod:resource folder. The libraries used by the Business Bot is stored in folder mod:lib. The mod:resource folder is divided into mod:localization for language files, mod:media for multimedial files, and mod:templates for message templates. The project structure looks as follows:

BusinessBot<Projectname>
|- src
   |- Package <country.company.businessbot.<application name>
   |- Package <country.company.businessbot.<common>
   |- Package <country.company.businessbot.<database> (optional)
   |- Package <country.company.businessbot.plugin (required)
      |- PluginClient.java (required) (Schnittstelle)
   |- Package <country.company.businessbot.<services>
|- classes
   |- extension.idx (Extension Point for the class loader)
   |- MANIFEST.MF (META Informationen)
|- lib (Bibliotheken)
   |- de.citunius.businessbot.api-1.0.0.jar (Common API for the Business Bot Platform)
   |- de.citunius.businessbot.api.messenger-1.0.0.jar (Generic Messenger API for the Business Bot Platform)
   |- de.citunius.businessbot.api.sfb-1.0.0.jar (Skype for Business API for the Business Bot Platform)
   |- de.citunius.businessbot.api.telegram-1.0.0.jar (Telegram Messenger API for the Business Bot Platform)
|- resources
   |- localization
      |- string_de.properties (Language labels for German)
      |- string_en.properties (Language labels for English)
      |- string.properties (Detault language labels)
   |- media
      |- images
         |- icon.png (Business Bot Icon)
   |- templates
      |- list.ftl (Template for Instant Messages - Template: List)
   build.xml (Apache Ant Build configuration)
       MANIFEST.MF (Default project META information)
       plugin.properties (META information for the plugin)

Warning

Important: A Business Bot can use either the library mod:Skype for Business API OR mod:Telegram Messenger API, but NOT both libraries may be present in the mod:lib directory of the project.

Plugin Manager

The Plugin Manager searches for the META information of the plugin which is defined in the manifest file mod:classes/MANIFEST.MF. The mod:MANIFEST.MF file contains the entries as shown in the following example:

Manifest-Version: 1.0
Implementation-Title: calculator Plugin #1
Implementation-Version: 1.2.0-SNAPSHOT
Plugin-Id: de.citunius.telegram.calculator
Built-By: ME
Created-By: Apache Maven 3.3.9
Plugin-Version: 1.0.0
Plugin-Provider: Citunius GmbH
Plugin-Class: de.citunius.businessbot.plugin.PluginClient
Plugin-Dependencies:
Implementation-Vendor-Id: de.citunius.plugins
Build-Jdk: 1.7.0_67
Specification-Title: calculator Plugin #1
Specification-Version: 1.2.0-SNAPSHOT
Archiver-Version: Plexus Archiver

In the sample manifest, a plugin with the Id de.citunius.telegram.calculator was defined with the class de.citunius.businessbot.plugin.PluginClient and version 0.0.1. The plugin Id must be unique and correspond to the conventions <Country>.<Company>.<Instant Messenger>.<Application Name>, otherwise the registration of the plugin will be rejected. In addition, the plugin version must be compatible with Semantic Versioning (The Business Bot Platform uses jsemver as implementation for SemVer because it supports comparison of versions).

Another internal component of the Plugin Manager is the ExtensionFinder, which describes how the Plugin Manager finds the extension via the Extension Point. The DefaultExtensionFinder looks for the extension with an extension annotation in file META-INF/extensions.idx. The Business Bot Platform uses Java Annotation Processing to compile all classes of the extension at runtime, which are annotated with @Extension and create for this the corresponding Extension Index file.

Plugin Lifecycle

Each plugin passes through a pre-defined set of states. The PluginState defines all possible states. The primary plugin states are:

• CREATED
• DISABLED
• STARTED
• STOPPED

The DefaultPluginManager contains the following logic:

• All plugins are resolved and loaded
• DISABLED plugins are NOT automatically STARTED by the Business Bot Platform, BUT you may manually start (and therefore enable) a DISABLED plugin by calling startPlugin on the Business Bot Platform instead of enablePlugin() + startPlugin()
• Only STARTED plugins may contribute extensions. Any other state should not be considered ready to contribute an extension to the running system.

The differences between a DISABLED plugin and a STARTED plugin are:

• A STARTED plugin has executed Plugin.start(), a DISABLED plugin has not.
• A STARTED plugin may contribute extension instances to the Business Bot Platform, a DISABLED plugin may not.

DISABLED plugins still have valid class loaders and their classes can be manually loaded and explored, but the resource loading - which is important for inspection - has been handicapped by the DISABLED check.

Note

Notice for Eclipse: If you use Eclipse than make sure annotation processing is enabled at least for any projects registering objects using annotations. In the properties for your new project go to Java Compiler > Annotation Processing, check the Enable Project Specific Settings and make sure Enable annotation processing is checked.

Interface

The interconnection point of the Plugin Manager between the Business Bot Platform and the Business Bot takes place in class PluginClient located in package de.citunius.businessbot.plugin. The class contains the methods start(), stop() and class BusinessBot that implements the interface BusinessBotInterface. This class defines the method handleIncomingMessage() for incoming messages from mobile user and method sendMessage() for outgoing messages from the business system. Parameters are passed using the HashMap pluginMap.

Business Bot Library

The following Business Bot libraries are delivered:

• de.citunius.businessbot.api-1.0.0.jar (Common API for the Business Bot Platform)
• de.citunius.businessbot.api.messenger-1.0.0.jar (Generic Messenger for the Business Bot Platform)
• de.citunius.businessbot.api.sfb-1.0.0.jar (Skype for Business API for the Business Bot Platform)
• de.citunius.businessbot.api.telegram-1.0.0.jar (Telegram Messenger API for the Business Bot Platform)

Only one messenger library (file de.citunius.businessbot.api.<messenger>-<version>.jar) can be used per Business Bot otherwise you will face issues with the class loader. The messenger library contains specific functions that are valid only for the particular messenger such as menu structure.

Menu Structure

If you want to create a menu for the Business Bot, you can use the prefabricated functions from the messenger library. The Business Bot must store the UserState to remember the menu or submenu of the user. This can be realized via a database function, which stores the UserState for all the users.

A menu is composed with the object ReplyKeyboardMarkup. Therefore, the object ReplyKeyboardMarkup is instantiated, some properties are given and the buttons are defined. The following programming example is provided for illustration purposes:

/**
 *
 * @return
 */
 private ReplyKeyboardMarkup getKeyboardPreferencesMainMenu() {
     ReplyKeyboardMarkup replyKeyboardMarkup = new ReplyKeyboardMarkup();
     replyKeyboardMarkup.setSelective(true);
     replyKeyboardMarkup.setResizeKeyboard(true);
     replyKeyboardMarkup.setOneTimeKeyboad(false);

     List<List<String>> keyboard = new ArrayList<>();
     List<String> keyboardFirstRow = new ArrayList<>();
     keyboardFirstRow.add(getCommandLanguages(language));
     keyboardFirstRow.add(getCommandAbout());
     keyboard.add(keyboardFirstRow);
     replyKeyboardMarkup.setKeyboard(keyboard);
     return replyKeyboardMarkup;
 }

In the above example, a Preferences menu is created, which has the buttons Languages and About.

Database Access

Business Bots need to implement data management either file-based or using a database. The database-based approach must be implemented individually for each Business Bot. Therefore, you must copy the appropriate library for the access database to the lib directory. For further information regarding implementation, please refer to the documentation of the respective manufacturers.

National Language Processing (NLP)

Business Bots can be expanded by the ability of National Language Processing (NLP) and AI (Artificial Intelligence) through appropriate libraries. For example, libraries such as Apache OpenNLP and IBM Watson are suitable for this purpose. For more information, please refer to manufacturer’s documentation.