Skip to content

System Integration

The type and purpose of the Business Logic determines whether a system integration is necessary or not. An autonomously operating Business Logic usually does not need access to a business system, but instead accesses data and libraries within the Business Logic context or use a web service provided via REST.

Business Logics, which are used as interfaces for a business system, must also communicate with the appropriate business system in order to query and store data. This requires a system integration and takes place in three places:

  • In the business system (administration and execution of queries)
  • In the Business Logic (logic for querying and storing information)
  • On the Business Bot Platform (System Integration Module)

System Integration into Business System

Depending on the system type, the system integration of the business system is individual, since different programming languages can be used for the implementation. Depending on the business system, the integration can take place via Java, PHP, Perl or other languages, provided the language is supported by the business system. However, it is important that the programming language supports the technology REST and JSON, which is necessary for the communication with the Business Bot Platform.

The communication with the Business Bot Platform takes place over HTTPS (HyperText Transfer Protocol Secure) to transfer data securely. JSON is used as data exchange format. Citunius provides the library for system integrations with Java. The library (de.citunius.bbpi-businesssystem.apiconnector-1.0.0.jar) already contains the necessary objects and method to retrieve and send updates for a Business Logic from/to the Business Bot Platform.

The Java library contains various possibilities for integration into the business system.

  • Client Console (Suitable for system scripts)
  • Client ADK (Suitable for standalone Java programs)
  • Servlet Context Listener (Suitable for direct integration into a business system)

Console Client

The Console Client as Utility can be used on the command line. The following parameters are expected by the Console Client:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
C:\BBP_Builder\staging\BBPI-BUSINESSSYSTEM.ApiConnector\bin>java -cp de.citunius.bbpi-businesssystem.apiconnector-1.0.0.jar;C:\BBP_Builder\staging\BBPI-BUSINESSSYSTEM.ApiConnector\jars\* de.citunius.bbpi.businesssystem.console.ConsoleClient                                                              

----------------------------------------------------------------                                    
Copyright (c) 2016-2017 Citunius GmbH.                                                               
All Rights Reserved.                                                                                
Business Bot Platform Integration                                                                   
Version 1.0.0 R2017 (Build date: 24.01.2017) on Windows Server 2012 R2                              
----------------------------------------------------------------                                    

usage: bbpi                                                                                         
 -c,--config <arg>             the configuration file                                               
 -f,--fromUser <arg>           from username (sender of this instant                                
                               message)                                                             
 -help                         print this message                                                   
 -l,--listener                 starts the listener on this console                                  
 -m,--message <arg>            the formatted instant message text                                   
 -n,--notificationName <arg>   the notification name                                                
 -s,--sendMessage              send a message                                                       
 -t,--toUser <arg>             to username (receiver of this instant                                
                               message)                                                             
 -v,--version                  print the version information and exit

Example to retrieve messages from Business Bot Platform

1
2
Example - Receive messages:
java -cp de.citunius.bbpi-businesssystem.apiconnector-1.0.0.jar;C:\BBPI-BUSINESSSYSTEM.ApiConnector\jars\* de.citunius.bbpi.businesssystem.console.ConsoleClient -c c:\temp\bbpi.conf -s -l

Example to send a message to the Business Bot Plattform

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Example - Send message:
java -cp de.citunius.bbpi-businesssystem.apiconnector-1.0.0.jar;C:\BBPI-BUSINESSSYSTEM.ApiConnector\jars\* de.citunius.bbpi.businesssystem.console.ConsoleClient -c c:\temp\bbpi.conf -s -n "MyNotification" -m "MyMessage" -f john -t erika

----- Content of c:\temp\bbpi.conf <Begin> --------
#########################################################################
# Business Bot Platform Integration - Configuration Properties
#########################################################################

# Production
BBPI.Gateway.Url=https://<TENANT ID>.bbp.local/bbp/rest/api/1.0/
BBPI.Gateway.SystemIdentifier=<SYSTEM IDENTIFIER>
BBPI.Gateway.Token=<tenantId>:<API ID>:<API KEY>
BBPI.System.UpdateManager.InitTime=1000

-------------------<End> ------------------------

Client ADK

The Client ADK is used for Java-based integration of an application. For this purpose, following sample program for sending and receiving messages is provided for illustration purposes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
/*
 * Copyright: (c) 2015-2017, Citunius GmbH. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * Licence: This program contains proprietary and trade secret information of Citunius GmbH.
 *          Copyright notice is precautionary only and does not evidence any actual or intended 
 *          publication of such program
 *          See: https://www.citunius.de/en/legal
 *
 * Requires: JDK 1.8+
 *
 */
package test.de.citunius.bbpi.businesssystem;

import java.util.Properties;

import org.apache.log4j.Logger;

import de.citunius.bbpi.api.listener.Initiater;
import de.citunius.bbpi.api.listener.MessageUpdateListener;
import de.citunius.bbpi.api.objects.Message;
import de.citunius.bbpi.api.objects.Update;
import de.citunius.bbpi.businesssystem.Client;
import de.citunius.bbpi.businesssystem.Constants;
import de.citunius.bbpi.helpers.Utilities;

public class TestClientADK {
    private static Logger logger = Logger.getLogger("BBPI");

    public static void main(String[] args) {

        // Set properties       
        logger.info("Set properties for connection");
        Properties libProperties = new Properties();
        // BBP properties
        libProperties.setProperty(Constants.APPPROPERTIES_BBPI_GATEWAY_URL, "https://<Tenant Id>.bbp.local/bbp/rest/api/1.0/");
        libProperties.setProperty(Constants.APPPROPERTIES_BBPI_GATEWAY_SYSTEMIDENTIFIER, "<System-Integration Identifier>");
        libProperties.setProperty(Constants.APPPROPERTIES_BBPI_GATEWAY_TOKEN, "<Tenant Id>:<API Id>:<API Key>");
        libProperties.setProperty(Constants.APPPROPERTIES_BBPI_SYSTEM_UPDATEMANAGER_INITTIME, "1000");
        // Client properties (for send message)
        libProperties.setProperty(Constants.SYSTEM_TYPE, "<System Type>"); // e.g. Nagios
        libProperties.setProperty(Constants.SYSTEM_RELEASE, "<System Release>"); // e.g. 4.x
        libProperties.setProperty(Constants.VIEW_INSTANTMESSANGE, Constants.VIEW_GENERICOBJECT_PUSHEVENT_DETAILS);

        // Creates a new client
        Client client = new Client(libProperties);

        // Send a push message to the Business Bot Platform 
        String notificationName = "nagios";
        if (client.sendPushMessage(notificationName, "<myTestMessage>", "<from User>", "<to User>")) {
            logger.info("Message has been sent successfully to the Business Bot Platform");
        } else {
            logger.error("Failed to sent message to the Business Bot Platform");
        }

        // Register message receiver to get notification about message updates
        logger.info("Register message receiver to get notification about message updates");
        Initiater initiater = new Initiater();
        MessageReceiver messageReceiver = new MessageReceiver();
        initiater.addListener(messageReceiver);
        Utilities.setInitiater(initiater); // Make listener public to library (Generic Updater Handlers)

        // Retrieve messages from the Business Bot Platform
        logger.info("Retrieve messages from the Business Bot Platform");
        client.retrieveMessages();  
    }

}

/**
 * This class is called on new message updates
 *  
 * @author me
 *
 */
class MessageReceiver implements MessageUpdateListener {
    private static Logger logger = Logger.getLogger("BBPI");

    @Override
    public void onMessageUpdateReceived(Update update) {
        logger.info("New message received");

        // Handle incoming message
        Message message = update.getMessage();
            if (message != null) {
                logger.info("TestClientADK: Message received: ["+message+"]");
            }
     }
}

Servlet Context Listener

The Servlet Context Listener is included in the deployment descriptor of the web application in the application server (e.g., Tomcat). To do this, the web.xml file of the web application is supplemented with following values:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<!-- Business Bot Platform Integration (BBPI-BUSINESSSYSTEM) - Citunius GmbH - BEGIN -->
<listener>
    <listener-class>de.citunius.bbpi.businesssystem.servletcontext.BBPContextListener</listener-class>
</listener>
<context-param>
    <param-name>BBPI.System.UpdateManager.InitTime</param-name>
    <param-value>10000</param-value>
</context-param>
<context-param>
    <param-name>BBPI.Gateway.Url</param-name>
    <param-value>https://[Tenant Id].bbp.local:450/bbp/rest/api/1.0/</param-value>
</context-param>
<context-param>
    <param-name>BBPI.Gateway.Token</param-name>
    <param-value>[Tenant Id]:[API Id]:[API Key]</param-value>
</context-param>
<context-param>
    <param-name>BBPI.Gateway.SystemIdentifier</param-name>
    <param-value>[System-Integration Identifier]</param-value>
</context-param>
<context-param>
    <param-name>BBPI.Gateway.SystemType</param-name>
    <param-value>[System Type]</param-value>
</context-param>
<context-param>
    <param-name>BBPI.Gateway.SystemRelease</param-name>
    <param-value>[System Release]</param-value>
</context-param>
<!-- Business Bot Platform Integration (BBPI-BUSINESSSYSTEM) - Citunius GmbH - END -->

Make sure that all the necessary libraries are present in the web project at WebContent/WEB-INF/lib/.

System Integration into Business Logic

The Business Logic communicate with the business system using the provided messenger API libraries (file de.citunius.businesslogic.api.<Messenger>-<Version>.jar). Therefore, it is not necessary to integrate the business system library directly into the Business Logic.

The Business Logic must perform an RMI call to communicate with the business system in order to trigger a new SystemEvent. The SystemEvent is automatically generated by the Business Bot Platform. Therefore, the Business Logic must create a new MessageEvent. The following programming snippet serves as an example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// Define object filter and VIEW for returned objects
Filter filter = new Filter();
filter.setObjectType(myBusinessSystemType);
filter.setObjectName(myBusinessSystemObject);
filter.setLimit(1);
filter.setView(VIEW_LIST_BUSINESSSYSTEM_OBJECTS);

// Create business system specific object 
BusinessSystemObject busSysObj = new BusinessSystemObject();
busSysObj.setType(myBusinessSystemType);
busSysObj.setSubject(myBusinessSystemObjectMessageText);
busSysObj.setOwner(mobileUserAccountUsername);

// Convert business system object to json
String busSysObjAsJson = objectToJson(busSysObj);

// Create data object to encapsulate the filter object and business system object
Data data = new Data();
data.setFilter(filter);
data.setResult(busSysObjAsJson);

// Convert data object to json
String messageText = objectToJson(data);

// Create Message Event with reference to the data object
MsgEvent messageEvent = new MsgEvent(tenantId, accountId, 0, null, "Received", mobileUserAccountPhoneNumber, 
null, new Date(), null, new Date(), null, messageText, mobileUserAccountMobileApp, null, null, sysEventType, sysEventName, botInstance);

// Create new RMI client
RMIClient rmiClient = new RMIClient();
if ( rmiClient.createMessageEventAndJob(apiId, apiKey, messageEvent.toJson().toString(), defaultLanguage) ) {
   // Data stored successfully
} else {
   // Could not store data
}

In the above example, a Filter object is created to reduce the results returned by the business system by specifying properties. Moreover, the VIEW is specifies in the request and applied for returned business objects in the instant message. The VIEW is used to apply a predefined template for returned business objects (e.g., template for a list of objects or object details).

The business object can be implemented individually for your business system, but it must support the possibility to convert to JSON. The business object is encapsulated into the Data object to ensure the transfer of the system-specific object. Once the Filter object and business object (BusinessSystemObject) is created, both objects are encapsulated into the Data object, and subsequently the Data object is converted to JSON.

In a further step, a new MessageEvent with reference to the Data object is created and passed to the RMI Client. Subsequently, the Business Bot Platform creates a new Job and SystemEvent, which is added to the queue. As soon as the system integration of the business system connects to the Business Bot Platform, the Job is retrieved and processed by the system integration of the business system. The queried information or business system objects are then transmitted by the system integration to the Business Bot Platform by a new Job and pushed to the Business Logic as incoming SystemEvent.

System Integration Module in the Business Bot Platform

The system integration module specifies which business systems is allowed to connect to the Business Bot Platform and communicate with the Business Logic. In this regard, the system type, name, and release of the business system is important. The system integration module is delivered with the Business Logic and added to the platform during the installation. A new instance of the system integration module must be created, so that a Business Logic can communicate with the Business Bot Platform. Therefore, login to the Business Bot Platform and navigate to System Integration → Integrated Systems → Add System Integration Module.

The META information must match the criteria consisting of the system type, name, and release to establish the connection between the business system integration and the Business Bot Platform. The META information is specified in the business system integration when creating the object structure. The following programming example serves as an example:

1
2
3
4
5
6
// Create META object
Meta meta = new Meta();
meta.setEventType("GetResult");
meta.setEventName("Objects");
meta.setSystemType("<BusinessSystem>"); // e.g. ICINGA
meta.setSystemRelease("<Version>"); // e.g. 2.x