JMS Real-Time integration with SAP Data Services

Purpose

This how-to guide shows how to integrate a Java  Messaging Services (JMS) Provider with SAP Data Services. This is a common Enterprise Application Integration scenario where a service is called asynchronously via request/response messages.  SAP Data Services’ role here is to provide a simple Real-Time service. Configuration includes quite a few steps to get everything up and running. This step-by-step configuration example covers all components that need to be touched including the JMS provider.

Overview

We want an external information resource (IR) – our JMS provider – to initiate a request by putting a request message into a request queue.  SAP Data Services is the JMS client that waits for request messages, executes a service and puts a correlated response message into a response queue.  We’re using the pre-built JMS adapter in SAP Data Services 4.2 and use Active MQ as JMS provider. Since we focus on Real-Time integration we’re not using an adapter datastore in this scenario. All incoming and outgoing data is received/sent back via messages. We will configure a Real-Time Job, check the settings of the Job Server and Access Server, configure a Real-Time Service, install Active MQ and configure the message queues, configure the JMS adapter and its operation and finally send test messages from the Active MQ console.

Real-Time Job
For our service we’re using a “Hello Word”-Real-Time Job named Job_TestConnectivity. For details, please refer to the  SAP Data Services 4.2 tutorial Chapter 14 . SAP Data Services comes with all the ATL, DTD and XML files in <DS_LINK_DIR>/ConnectivityTest to create  Job_TestConnectivity. The job reads an input message that has one input string…

…and returns an output message that has one output string with the first two words of the input string in reverse order:

Job Server

We need to make sure that one JobServer supports adapters. Using Data Services Server Manager utility, we switch on  “support adapter, message broker communication” and “Use SSL protocol for adapter, message broker communication”. We associate the Job Server with the repository that has the Real-Time Job Job_TestConnectivity. Finally we restart SAP Data Services by clicking “close and restart” or we restart it later using the Control Panel  => Administrative Tools => Services => SAP Data Services (right mouse click) => restart.

Access Server

We need to have an Access Server up and running. The Access Server  will receive the input messages from the JMS adapter and dispatch them to an instance of the Real-Time Service RS_TestConnectivity. In SAP Data Services Management Console choose Administrator => Management => Access Server and check if an Access Server is configured and add one if necessary. By default, the AccessServer uses port 4000.

Real-Time Service

We configure a Real-Time Service “RS_TestConnectivity” for our Real-Time Job Job_TestConnectivity. In SAP Data Services Management Console navigate to Administrator => Real-Time => <hostname>:4000 => Real-Time Services => Real-Time Service Configuration. Configure a new Real-Time Service “RS_TestConnectivity” and select Job_TestConnectivity with the Browse-Button:

Add the JobServer as Service Provider and click “Apply”. Start the Real-Time Service via Administrator => Real-Time => <hostname>:4000 => Real-Time Services => Real-Time Service Status, and click “Start”:

Active MQ – Installation

We could use any JMS provider but in this case we’re using Active MQ since it can be quickly installed and configured. Download and unzip Active MQ from http://activemq.apache.org/. In this scenario we use version 5.9.0 and we install it in C:\local\ActiveMQ on the same machine as SAP Data Services. At the command line change to directory C:\local\ActiveMQ\bin and execute activemq.bat:

Active MQ console

Now, we have our JMS provider up and running and we can access the Active MQ console at http://<hostname>:8161/admin . We’re using admin / admin to login.

The browser should now display the homepage of the Active MQ console:

We click on the “Queues” menu to add 3 queues named “FailedQueue”, “RequestQueue” and “ResponseQueue”:

Active MQ JMS client

The SAP Data Services JMS Adapter will access the JMS client provided by Active MQ to communicate with the JMS provider. The JMS client is in activemq-all-5.9.0.jar. We will add this jar file to the ClassPath of the JMS adapter later. According to the JNDI documentation of Active MQ we need to create a jndi.properties file and either add it to the ClassPath or put it into activemq-all-5.9.0.jar. The jndi.properties file maps the JNDI names of the queues to their physical names. Create jndi.properties as shown below. You can add it to activemq-all-5.9.0.jar e.g. by using WinZip.

JMS Adapter

Now we are ready to configure our JMS Adapter in SAP Data Services. In SAP Data Services Management Console, choose Administrator => Adapter Instances => Adapter Configuration…

Choose JMSAdapter…

Enter the configuration information as shown below:

• set the adapter name; here: MyJMSAdapter
• set the Access Server hostname and port; here: localhost, 4000

Remove the default entry of the ClassPath and add the following files to the ClassPath. All necessary jar files – except the JMS client jar file – are located in <DS_LINK_DIR>\lib\ or <DS_LINK_DIR>\ext\lib\. Replace <DS_LINK_DIR> with the respective directory of your installation.

• <DS_LINK_DIR>\lib\acta_adapter_sdk.jar
• <DS_LINK_DIR>\lib\acta_broker_client.jar
• <DS_LINK_DIR>\lib\acta_jms_adapter.jar
• <DS_LINK_DIR>\lib\acta_tool.jar
• <DS_LINK_DIR>\ext\lib\ssljFIPS.jar
• <DS_LINK_DIR>\ext\lib\cryptojFIPS.jar
• <DS_LINK_DIR>\ext\lib\bcm.jar
• <DS_LINK_DIR>\ext\lib\xercesImpl.jar
• C:\local\ActiveMQ\activemq-all-5.9.0.jar (make sure it contains jndi.properties)

Note: The template file JMSadapter.xml that has the default ClassPath and all other default values and choices, is located in <DS_COMMON_DIR>\adapters\config\templates. You might want to adjust this file to have other defaults when configuring a new JMS adapter. Once an adapter is configured you need to change its configuration file located in <DS_COMMON_DIR>\adapters\config. On Windows <DS_COMMON_DIR> is %ALLUSERSPROFILE%\SAP BusinessObjects\Data Services by default.

JMS Adapter – JNDI configuration

We use the Java Naming and Directory Interface (JNDI)  to configure the JMS adapter. So we chose:

   Configuration Type:  JNDI

Next we set the Active MQ JNDI Name Server URL:

     Server URL: tcp://localhost:61616

For Active MQ we need to set the JNDI context factory to org.apache.activemq.jndi.ActiveMQInitialContextFactory (see ActiveMQ documentation section JNDI support). By default this string is not offered in the drop down box in the JNDI configuration section, so we need to edit <DS_COMMON_DIR>\adapters\config\templates\JMSAdapter.xml and add the string to the pipe-delimited list in the jndiFactory entry.

Note: If MyJMSAdapter already exists, we need to edit <DS_COMMON_DIR>\adapters\config\MyJMSAdapter.xml instead.

     <jndiFactory Choices=”org.apache.activemq.jndi.ActiveMQInitialContextFactory|     …   >

After navigating to Administrator => Adapter Instances => Adapter Instances  => My JMSAdapter  we choose the right string from the drop-down-list and set:

     Initial Naming Factory: org.apache.activemq.jndi.ActiveMQInitialContextFactory

Finally we set the Queue Connection Factory and Topic Connection Factory as described in the Active MQ documentation:

     Queue Connection Factory: QueueConnectionFactory

     Topic Connection Factory: TopicConnectionFactory

Click “Apply” to save all settings.

JMS Adapter – start

We are ready to check if the JMS adapter starts now. We still have to configure an operation for the adapter yet (see below) but we want to check first if our configuration works fine. There are many reasons that the adapter doesn’t start at first  – e.g. missing or wrong files in ClassPath, typos in JNDI configuration, etc. You will not find any entry in the error file and trace file in this case – these files are for messages created by the adapter when it is up and running. To find the reason for the adapter in case it doesn’t start, switch on Trace Mode=True in the JMS Adapter Configuration and restart the JMS Adapter. Then Check the Job Server’s log file in <DS_COMMON_DIR>/log/<jobserver>.log. Search for the java call the Job Server executes to launch the JMS Adapter. Copy the whole command, execute it from the command line and try to fix the problem by adjusting the command.If the JMS adapter starts properly the Adapter Instance Status will look like this:

JMS Adapter – operation configuration

Now we need to configure the  JMS operation. We’ll configure an operation of type “Get: Request/Reply” since we want our adapter to dequeue requests from the RequestQueue, pass it to the Real-Time Service, wait for the response and enqueue the response into the ResponseQueue.In DS Management Console navigate to Administrator =>  Adapter Instances => <jobserver>@<hostname>:<port> => Adapter Configuration => MyJMSAdapter => Operations and click “Add”. Select Operation Type “Get: Request/Reply and Request/Acknowledge using Queues” and click “Apply”.

Set the operation details as displayed below. Since our Real-Time Service will respond to requests quickly, we reduce the polling interval to 50 ms.

Click “Apply” to save the changes and restart the adapter. The adapter instance status should look like this:

JMS Adapter – test

Of course we want to see if the adapter works as expected. To do this we put a request message into the request queue and see what happens. We open the Active MQ console again (URL http://<hostname>:8161/admin, Login: admin/admin) and select “Send”. We create the request message as shown below:

After we have clicked “Send” the message is enqueued into RequestQueue, dequeued from there by the JMS adapter that passes the request to the Real-Time Service and receives the response from it. The JMS adapter finally puts the response message into ResponseQueue.

The Active MQ console should look like this after some seconds:

We have one message in the response queue. To display it we click on ResponseQueue and then on the message ID…

…and have a look at the repsonse message.  You should see the “World Hello” string in the message details.