Skip to content

System-Integration

Die Art und der Verwendungszweck einer Business Logic entscheidet darüber, ob eine Systemintegration notwendig ist. Eine autonom agierende Business Logic benötigt in der Regel kein Zugriff auf ein dahinterliegendes Geschäftssystem und greift auf Daten und Bibliotheken innerhalb des Business Logic Kontexts zurück oder verwendet einen bereitgestellten Webservice eines Anbieters.

Business Logics die als Schnittstelle für ein Geschäftssystem eingesetzt werden, müssen auch mit dem entsprechenden Geschäftssystem kommunizieren, um Daten abzufragen und zu speichern. Dafür ist eine Systemintegration erforderlich. Die Systemintegration erfolgt an drei Stellen:

  • Im Geschäftssystem (Administration und Durchführung von Abfragen)
  • In der Business Logic (Logik, z.B. Abfrage und Speichern von Informationen)
  • Auf der Business Bot Plattform (Systemintegrationsmodul)

System-Integration im Geschäftssystem

Die Systemintegration des Geschäftssystems gestaltet sich je nach Systemtyp individuell, da verschiedene Programmiersprachen zum Einsatz kommen können. Abhängig vom Geschäftssystem kann die Integration über Java, PHP, Perl oder über eine andere Sprache erfolgen, sofern diese vom Geschäftssystem unterstützt wird. Wichtig ist dabei, das die Technologie REST und JSON unterstützt wird, die zur Kommunikation mit der Business Bot Plattform notwendig ist.

Die Kommunikation mit der Business Bot Plattform erfolgt über HTTPS (HyperText Transfer Protocol Secure), um Daten sicher zu übertragen. Als Datenaustauschformat kommt JSON zum Einsatz. Citunius stellt hierzu die Bibliothek für Systemintegrationen mit Java zur Verfügung. Die Bibliothek (de.citunius.bbpi-businesssystem.apiconnector-1.0.0.jar) enthält bereits die notwendigen Objekte und Methode, um Updates von der Business Bot Plattform abzuholen und zusenden.

Die Java-Bibliothek beinhaltet verschiedene Möglichkeiten zur Einbindung im Geschäftssystem.

  • Client Console (geeignet für System-Scripts)
  • Client ADK (geeignet für Standalone Java-Programme)
  • Servlet Context Listener (geeignet für die direkte Integration in ein Geschäftssystem)

Console Client

Der Console Client als Utility kann direkt auf der Commandline ausgeführt werden. Folgende Parameter werden vom Console Client erwartet.

 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

Beispiel zu Abrufen von Nachrichten von Business Bot Plattform

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

Beispiel zu Senden einer Nachricht zur 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

Der Client ADK dient zur Java-basierten Integration einer Applikation. Folgendes Programmbeispiel zum Senden und Empfangen von Nachrichten dient zur Veranschaulichung:

 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

Der Servlet Context Listener wird im Deployment Descriptor der Webapplikation des Application Server (z.B. Tomcat) eingebunden. Dazu wird die web.xml Datei der Web-Applikation um folgende Werte ergänzt:

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

Achten Sie darauf, dass alle erforderlichen Bibliothek im Web-Projekt unter WebContent/WEB-INF/lib/ vorhanden sind.

System-Integration in der Business Logic

Wenn eine Business Logic mit dem Geschäftssystem kommunizieren möchte, erfolgt dies über die bereitgestellten Messenger API Bibliotheken (Datei de.citunius.businesslogic.api.<Messenger>-<Version>.jar). Es ist daher nicht erforderlich, die Bibliothek des Geschäftssystems direkt in die Business Logic zu integrieren.

Der Business Logic muss zur Kommunikation mit dem Geschäftsystems einen RMI-Aufruf durchführen, um einen neuen SystemEvent auszulösen. Der SystemEvent wird von der Business Bot Plattform automatisch generiert. Dazu muss die Business Logic einen neuen MessageEvent erzeugen. Folgendes Programmierbeispiel dient zur Veranschaulichung:

 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
}

Im obigen Beispiel wird zunächst ein Filter-Objekt erzeugt, um die vom Geschäftssystem zurückgegebenen Ergebnisse durch die Angabe von Eigenschaften zu reduzieren. Zudem wird die VIEW angegeben, die für zurückgegebene Geschäftsobjekte in der Instant-Nachricht verwendet werden soll. Die VIEW wird verwendet, um eine vordefinierte Vorlage für die zurückgegebenen Geschäftsobjekte zu verwenden (z.B. Vorlage für eine Liste von Objekten oder Objektdetails).

Das Geschäftsobjekt kann für ihr Geschäftssystem individuell implementiert werden, muss jedoch die Möglichkeit zur Konvertierung zu JSON unterstützen. Durch das Einkapseln des Geschäftsobjekte in das Data-Objekt wird die Übertragung des systemspezifischen Objektes gewährleistet. Nachdem das Filter-Objekt und Geschäftsobjekt (BusinessSystemObject) erzeugt wurden, werden beide Objekte in das Data-Objekt eingekapselt und das Data-Objekt anschließend zu JSON konvertiert.

In nächsten Schritt wird ein neuer MessageEvent mit der Referenz zum Data-Objekt erzeugt und an den RMI Client übergeben. Die Business Bot Plattform erzeugt daraufhin einen neuen Job und SystemEvent, der der Warteschlange hinzugefügt wird. Sobald die Systemintegration des Geschäftssystems mit der Business Bot Plattform verbindet, wird der Job abgeholt und von der Systemintegration des Geschäftssystems verarbeitet. Die abgefragten Informationen bzw. Geschäftssystemobjekte werden dann von der Systemintegration durch einen neuen Job an die Business Bot Plattform übermittelt und der Business Logic als eingehender SystemEvent mitgeteilt.

System-Integrationsmodul auf der Business Bot Plattform

Das Systemintegrationsmodul gibt an, welche Geschäftssysteme sich mit der Business Bot Plattform verbinden und mit der Business Logic kommunizieren dürfen. Diesbezüglich ist der Systemtype, Name und das Release des zu verbindenen Geschäftssystems wichtig. Das Systemintegrationsmodul wird mit der Business Logic ausgeliefert und während der Installation der Plattform hinzugefügt. Damit ein Geschäftssystem mit der Business Bot Plattform kommunizieren kann, muss eine neue Instanz des Systemintegrationsmoduls erstellt werden. Dazu geht man auf der Business Bot Plattform auf System-Integration → Integrierte Systeme → Systemintegrationsmodul hinzufügen.

Damit die Verbindung erfolgreich zwischen der Geschäftssystemintegration und der Business Bot Plattform hergestellt werden kann, müssen die META-Information bestehend aus dem Systemtyp, Name und das Release übereinstimmen. Die META-Informationen werden in der Geschäftssystemintegration bei der Erzeugung der Objektstruktur angegeben. Dazu dient folgendes Programmierbeispiel zur Veranschaulichung:

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