IBM Developer

Tutorial

Integrating ActiveMQ with Sterling Order Management system

Integrate ActiveMQ with IBM Sterling Order Management system for efficient message processing and task management

By Mohamed Jawahar Hussain, Ashima Singhal

On this page

In the rapidly evolving landscape of modern business, efficient communication and seamless integration between different systems are important. One such integration critical to many organizations is between Apache ActiveMQ, a powerful message broker, and the IBM Sterling Order Management System (OMS), a robust platform for managing orders and fulfillment. This tutorial explores how to integrate ActiveMQ with Sterling OMS, providing step-by-step instructions and insights for seamless deployment.

Installing Apache ActiveMQ

The experimentation was conducted on CentOS 9, using ActiveMQ version 5.15.15. This version aligns with the compatibility requirements of IBM Sterling Order Management (OMS) version 10.0.2403.0, ensuring seamless integration and optimal performance. For the most up-to-date information on compatible versions, see the IBM product compatibility report.

Note: Java is a prerequisite for running ActiveMQ.

Installing IBM JDK for ActiveMQ runtime

  1. You must perform this installation as a root user.
  2. Create a new directory named "demo" within the root directory using the command:
     mkdir /root/demo
  3. Navigate to the demo directory using:
     cd /root/demo
  4. Now, use the following curl command to download the JDK:
     curl https://public.dhe.ibm.com/ibmdl/export/pub/systems/cloud/runtimes/java/8.0.8.21/linux/x86_64/ibm-java-sdk-8.0-8.21-linux-x86_64.tgz --output ibm-java-sdk-8.0-8.21-linux-x86_64.tgz
    Note: You can also access the IBM JDK through the following link: IBM Java SDK Downloads - Version 8.0
  5. Extract the downloaded file ibm-java-sdk-8.0-8.21-linux-x86_64.tgz using the following command:
     tar -xvf ibm-java-sdk-8.0-8.21-linux-x86_64.tgz
  6. Rename the directory ibm-java-x86_64-80 to ibmjdk.
  7. Set the Java path as follows:
     export JAVA_HOME="/root/demo/ibmjdk"
 export PATH=$PATH:$JAVA_HOME/bin
  8. Now, check the installed Java version by running the following command:
     java -version
    alt Figure 1: Java version

Installing Apache ActiveMQ

  1. Create a subdirectory named activemq in the demo directory /root/demo/activemq.
  2. Navigate to the activemq directory using the command:
     cd /root/demo/activemq.
  3. Now, use the following curl command to download ActiveMQ version 5.15.15:
     curl https://archive.apache.org/dist/activemq/5.15.15/apache-activemq-5.15.15-bin.tar.gz --output apache-activemq-5.15.15-bin.tar.gz
  4. Extract the downloaded file apache-activemq-5.15.15-bin.tar.gz using the following command:
     tar -xvf apache-activemq-5.15.15-bin.tar.gz
  5. Once extracted, you should find a folder named apache-activemq-5.15.15.
  6. Now, navigate to the bin directory under apache-activemq-5.15.15 by running the following command:
     cd /root/demo/activemq/apache-activemq-5.15.15/bin
  7. Run the following command to start ActiveMQ Console:
      ./activemq console
    If the startup is successful, the following message is displayed: alt Figure 2: Staring ActiveMQ server

  8. Verify the connection to ActiveMQ by accessing the ActiveMQ console.

    • URL: http://<host or ip>:8161/admin/
    • Username: admin
    • Password: admin

    Note: If you are unable to log in to the ActiveMQ console, you can also check the following configurations:

    • Open the jetty.xml file by navigating to /root/demo/activemq/apache-activemq-5.15.15/conf/jetty.xml.

    • Change the host value to 0.0.0.0. By default, the value for the host is localhost.

      <bean id="jettyPort"
   class="org.apache.activemq.web.WebConsolePort"
  init-method="start">
  <!-- the default port number for the web console -->
  <property name="host" value="0.0.0.0"/>
  <property name="port" value="8161"/>
</bean>

      alt Figure 3: ActiveMQ console

Creating Queue in ActiveMQ Console

Click on the Queue icon to create a new queue named omsqueue. Similarly, you can create other queues such as omssyncqueue, omsintqueue, and omsagentqueue.

alt Figure 4: Queues in ActiveMQ

Creating Topic in ActiveMQ

Click on the Topic icon. Create a new topic named omssynctopic. Similarly, you can create another topic named omsinttopic.

alt Figure 5: Topics in ActiveMQ

Sending and receiving message in ActiveMQ Queue using standalone client

To connect a Java client application to ActiveMQ for sending and receiving messages, you will need the following libraries:

  • activemq-all-5.16.0.jar
  • org.apache.aries.jndi-1.0.0.jar

The following sample code snippet shows how to send and receive messages to and from the Queue:

The sendMessage() method is used to create and send a message to the ActiveMQ Queue named omsqueue, while the receiveMessage() method is used to consume messages from the omsqueue destination queue.

Notes:

  • The WIRE_LEVEL_ENDPOINT URL is defined in the code, which is required for establishing a connection factory where the JMS Server operates. tcp://9.30.223.187:61616 denotes that ActiveMQ is hosted on 9.30.223.187, with the default port set to 61616.
  • The code initiates and starts a session.
  • The code creates a producer, consumer, and queue.
package com.activemqclient;
import org.apache.activemq.ActiveMQConnectionFactory;
public class ActiveMQProducer
    {
        private final static String WIRE_LEVEL_ENDPOINT = "tcp://9.30.223.187:61616";
        public static void main(String[] args) throws JMSException
        {
            sendMessage();
            receiveMessage();
        }
        public static void sendMessage() throws JMSException
        {
                ActiveMQConnectionFactory connectionFactory = new
                                    ActiveMQConnectionFactory(WIRE_LEVEL_ENDPOINT);
                Connection connection = connectionFactory.createConnection();
                connection.start();
                Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
                Destination destination = session.createQueue("omsqueue");
                MessageProducer producer = session.createProducer(destination);
                producer.setDeliveryMode(DeliveryMode.NON_PERSISTENT);
                // Create a messages
                String text = "Hello world! ";
                TextMessage message = session.createTextMessage(text);
                System.out.println("Sent message: "+ message.getText());
                producer.send(message);
                session.close();
                connection.close();
        }
     public static void receiveMessage() throws JMSException
        {
                ActiveMQConnectionFactory connectionFactory = new
                            ActiveMQConnectionFactory(WIRE_LEVEL_ENDPOINT);
                Connection connection = connectionFactory.createConnection();
                connection.start();
                Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
                Destination destination = session.createQueue("omsqueue");
                MessageConsumer consumer = session.createConsumer(destination);
                Message message = consumer.receive(1000);
                if (message instanceof TextMessage)
                {
                        TextMessage textMessage = (TextMessage) message;
                        String text = textMessage.getText();
                        System.out.println("Received: " + text);
                }
                else
                {
                        System.out.println("Received: " + message);
                }
                consumer.close();
                session.close();
                connection.close();
         }
      }

Configuring IBM Sterling DTK to use ActiveMQ

  1. Assume that the IBM Sterling OMS DTK is installed in the directory /root/demo/devtoolkit_docker.
  2. You need to install the following third-party JARs in the IBM Sterling OMS DTK:
    • activemq-all-5.16.0.jar: You can find this JAR in the directory /root/demo/activemq/apache-activemq-5.15.1.
    • org.apache.aries.jndi-1.0.0.jar: You can download it from the Apache website.
  3. Create a directory called 3rdpartyjars under /root/demo/ and place the two ActiveMQ client JARs in it.
  4. Create a subdirectory called activemqjndi under /root/demo/3rdpartyjars and create a file named jndi.properties with the following content:
     connectionFactoryNames=connectionFactory,queueConnectionFactory
 queue.omssyncqueue=omssyncqueue
 queue.omsintqueue=omsintqueue
 queue.omsagentqueue=omsagentqueue
 topic.omssynctopic=omssynctopic
 topic.omsinttopic=omsinttopic
  5. Now package the jndi.properties file into a JAR using the following command (navigate to /root/demo/3rdpartyjars):
     jar cf activemqjndi.jar jndi.properties
  6. Once the activemqjndi.jar is packaged, you can remove the jndi.properties file
  7. Navigate to /root/demo/devtoolkit_docker/runtime/bin and execute the following command to install the client JARs mentioned in Step 1.
     ./install3rdParty.sh yfsextn 1_0 -j /root/demo/3rdpartyjars/* -targetJVM EVERY
  8. Navigate to /root/demo/devtoolkit_docker/runtime/jar/yfsextn/1_0 and verify if all three JARs are present.
  9. Now, navigate to the /root/demo/devtoolkit_docker directory and execute the following command to create the extensions.jar.
     ./runtime/bin/sci_ant.sh -f ./runtime/devtoolkit/devtoolkit_extensions.xml export
  10. Update the existing developer toolkit environment with the generated extensions.jar by running the following command:
    ./om-compose.sh update-extn /root/demo/devtoolkit_docker/extensions.jar

Configuring ActiveMQ in IBM Sterling Order Management

  1. In the Application Manager, navigate to Application Platform -> System Administration -> Initial Context Factory Codes. Create a new entry with the following details:

    • Short Description: ActiveMQ
    • Long Description: ActiveMQ

    • Initial Context Factory: org.apache.activemq.jndi.ActiveMQInitialContextFactory

      alt Figure 6: Initial Context Factory configuration

  2. Add the yfs.flow.override.icf property via the property management tool in SMA. Set the value to org.apache.activemq.jndi.ActiveMQInitialContextFactory.

    alt Figure 7: SMA configuration

  3. Navigate to the /root/demo/devtoolkit_docker/compose directory and run the following command to restart the application server:

     ./om-compose.sh restart appserver

Sending message to an ActiveMQ queue via a synchronous service

  1. In the Application Manager, navigate to Application Platform -> Process Modeling. Select the Order Tab -> Sales Order -> Order Fulfillment.
  2. Now, at the bottom left of Order Fulfillment, click on the Service Definition tab.
  3. Click on the + icon and create a synchronous service named ActiveMQQueueSender.
  4. After the service is created, drag the JMS Queue transport type from the left side and drop it to the right, connecting it with the start and end points of the service.

  5. Provide the following details for a new entry in the Runtime section:

    Note: The following configuration can be applied to all other use cases mentioned below.

    • Destination Name: Queue or Topic based on the chosen component name defined in the jndi.properties file.
    • Connection Factory: ConnectionFactoryName defined in the jndi.properties file.
    • Initial Context Factory: ActiveMQ

    • Provider URL: <tcp://<ip>:61616 >

      Note: The default port for ActiveMQ is 61616, and the IP address corresponds to your Sterling DTK where ActiveMQ is running.

      alt Figure 8: Synchronous service to send message to ActiveMQ queue.

  6. You can now use the API tester to invoke this service and pass the message. To verify whether the data sent has reached the queue, navigate to the Queue tab in the ActiveMQ Console and click on the queue name to check the message content.

Sending message to an ActiveMQ topic via a synchronous service

  1. In the Application Manager, Navigate to Application Platform -> Process Modeling. You can select Order Tab -> Sales Order -> Order Fulfillment.
  2. Now, at the Left bottom side of Order Fulfilment -> Click on service Definition tab.
  3. Click on the + icon and create a synchronous service named ActiveMQTopicSender.

  4. Once the service is created, drag the JMS Topic transport type from left side and drop it to right connecting with start and end point of service.

    alt Figure 9: Synchronous Service to send message to topic

  5. You can now use API tester to invoke this service and pass the message.

  6. Verify whether the data sent has reached the queue by navigating to the Topic tab in ActiveMQ Console and click on the topic name to verify the message content.

Receiving message from an ActiveMQ Queue via asynchronous service

  1. In the Application Manager, navigate to Application Platform -> Process Modeling. You can choose Order Tab -> Sales Order -> Order Fulfillment.
  2. Now, at the bottom left of Order Fulfillment, click on the Service Definition tab.
  3. Click on the + icon and create an Asynchronous service named ActiveMQQueueReceiver.
  4. After the service is created, drag the JMS Queue transport type and API component from the left side and drop them on the right side, connecting them with the start and end points of the service.

  5. In this process, messages already present in the queue will be picked up by an integration server. The integration server will consume the messages from the queue and invoke the createOrder API to generate an order in Sterling OMS.

    alt Figure 10: Receive message via an asynchronous service using queue

  6. Click on the Server tab and generate a new integration server named ActiveMQQueueReceiver.

  7. Select the API component and choose the API named createOrder.

  8. Start the integration server from the Sterling OMS runtime/bin directory:

     ./agentserver.sh ActiveMQQueueReceiver

    The following message is displayed:

    main: Successfully started all services for Server: ActiveMQQueueReceiver

Receiving message from an ActiveMQ Topic via asynchronous service

  1. In the Application Manager, navigate to Application Platform -> Process Modeling. You can select Order Tab -> Sales Order -> Order Fulfillment.
  2. Now, at the bottom left of Order Fulfillment, click on the Service Definition tab.
  3. Click on the + icon and create an Asynchronous service named ActiveMQTopicReceiver.
  4. After the service is created, drag the JMS Topic transport type and API component from the left side and drop them on the right side, connecting them with the start and end points of the service.

  5. In this scenario, messages arriving into the topic will be captured by an integration server. The integration server will then consume the messages from the topic and invoke the createOrder API to generate an order in Sterling OMS.

    alt Figure 11: Receive message via an asynchronous service using topic

  6. Click on the Server tab and create a new integration server named ActiveMQTopicReceiver.

  7. Select the API component and choose the API named createOrder.

  8. Start the integration server from the Sterling OMS runtime/bin directory:

     ./agentserver.sh ActiveMQTopicReceiver

    The following message is displayed:

    main: Successfully started all services for Server: ActiveMQQueueReceiver

Configuring ActiveMQ as JMS runtime for Sterling OMS agents

  1. The agent configuration for ScheduleOrder follows:

    alt Figure 12: ScheduleOrder agent configuration

  2. Start the agent server from the Sterling OMS runtime/bin directory:

     ./agentserver.sh ScheduleOrder

    The following message is displayed:

    main: Successfully started all services for Server: ScheduleOrder

  3. Next, the ScheduleOrder agent server will search for potential transactions from the YFS_TASK_Q table and run the subsequent transaction on the order.
  4. The ScheduleOrder agent server will schedule the order after it is created.

Summary

This tutorial provided comprehensive instructions on integrating ActiveMQ with IBM Sterling Order Management System (OMS). It covered installation steps for ActiveMQ, configuration of queues and topics, and implementation of both synchronous and asynchronous message handling. Additionally, the tutorial provided instructions for setting up integration servers to consume messages from queues and topics, and agent server configuration for task scheduling within Sterling OMS.