Integrating IBM MQ with Orkes Conductor

This developer guide includes the steps to integrate IBM MQ with Orkes Conductor. This integration lets you connect your IBM MQ server to Conductor to publish and subscribe messages to/from IBM MQ.

Get Configuration Credentials from IBM MQ

Before beginning the integration process, you must obtain certain configuration parameters from the IBM MQ console, such as hostname, port, queue manager, channel, etc.

You can get the host name & port while setting up IBM MQ.

Refer to the official IBM documentation for more configuration details.

Integrating with IBM MQ as a Message Broker

Once you have the required configuration parameters from IBM MQ, let’s integrate with Orkes Conductor.

1. Navigate to Integrations from the left menu on the Orkes Conductor cluster.
2. Click + New integration from the top-right corner.
3. Under the Message Broker section, choose IBM MQ.
4. Click +Add and provide the following parameters:

Parameters	Description
Integration Name	A name to identify your integration.
Host Name	The hostname or IP address of the IBM MQ server.
Port	The port number on which the IBM MQ server is configured to listen for incoming connections. The default port for IBM MQ is 1414, but it usually varies with the required connection.
Queue Manager	The queue manager to which Orkes Conductor will connect. The queue manager should already be configured in your IBM MQ environment. Check out IBM MQ’s official documentation on configuring queue manager.
Channel	IBM MQ uses channels to establish connections between clients and queue managers. Specify the channel name the Conductor will use to communicate with IBM MQ.
Connection Security	Choose the required connection security type. It can take the following values: With Username/Password Passwordless
User	The username to authenticate the connection with the IBM MQ server. Note: This field is applicable only if Connection Security is chosen as With Username/Password.
Password	The password associated with the username to authenticate the connection with the IBM MQ server. Note: This field is applicable only if Connection Security is chosen as With Username/Password.
Select the preferred messaging method	Choose the messaging approach that suits your communication needs. It can be of the following types: Topic-based Messaging - Allows messages to be broadcasted to multiple subscribers based on the topics of interest, fostering a publish/subscribe model. Queue-based Messaging - Allows point-to-point messaging, where messages are sent directly to individual queues for consumption by specific recipients.
Topic String	Used to define the criteria for selecting topics in the messaging system. Allows you to specify patterns that match topics of interest. For example, entering ‘finance/’ would subscribe you to all topics under the ‘finance’ category. Note: This field is applicable for Topic-based Messaging.
Authentication type	Choose the required authentication type. It can take the following values: NONE JKS
Choose Trust Store file	If the authentication is chosen as JKS, upload the Java JKS trust store file with CAs.
Trust Store Password	The password for the trust store.
Transport Layer Security	Choose the TLS connection security. Supported values: NONE Using Cipher Suite
Cipher Suite	Select an appropriate Cipher Suite from the following options if TLS with Cipher Suite is chosen: TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 TLS_RSA_WITH_AES_256_GCM_SHA384 ANY_TLS12
Description	A description of the integration.

5. You can toggle on the Active button to activate the integration instantly.
6. Click Save.

Creating Event Handlers in Orkes Conductor

The integration is created successfully now. The next step is to create an event handler in Orkes Conductor.

To do this:

1. Navigate to Definitions > Event Handler from the left menu on your Orkes Conductor cluster.
2. Click the + Define event handler option from the top-right corner.
3. Create an event handler with the following configurations:

Event Handler Parameters	Description
Name	A name to identify your event handler definition.
Event	The event integration you have created in the following format: Type : Config Name : Queue Name Example: ibm_mq:ibm-mq:queue-name Notes: The drop-down automatically lists the integration you’ve added to the Conductor cluster. You can choose that and add the queue name to which you want to publish/receive messages.
Condition	The ECMAScript to control the message processing if required. Check out the event handler documentation for more details.
Actions	Choose the required actions to be carried out when sending/receiving the events from IBM MQ. It can take the following values: Complete Task Terminate Workflow Update Variables Fail Task Start Workflow Each type of action requires and supports a certain set of input parameters. Check out the event handler documentation for more details.
Active	Set this to true or false. It determines if the event handler is running or not.

A sample JSON for the event handler is as follows:

{
 "name": "event-handler-ibm",
 "event": "ibm_mq:ibm-mq:queue_name",
 "evaluatorType": "javascript",
 "condition": "true",
 "actions": [
   {
     "action": "start_workflow",
     "start_workflow": {
       "name": "http-test",
       "version": "1"
     },
     "expandInlineJSON": false
   }
 ]
}

note

The IBM MQ event handler now supports custom headers, allowing users to pass custom string properties/headers in _headers.

RBAC - Governance on who can use Integrations

Once the integration is added, the next step is determining who can access these integrations.

The permissions can be granted to applications/groups within the Orkes Conductor cluster.

To provide explicit permission to Groups:

1. From the left menu on your Orkes Conductor cluster, navigate to Access Control > Groups.
2. Create a new group or choose an existing group.
3. Under the Permissions section, click +Add Permission.
4. From the Integrations sub-tab, choose the integration with required permissions.
5. Click Add Permissions. This ensures that all the group members can access these integration models in their workflows.

Similarly, you can also provide permissions to applications.

Creating Workflow in Orkes Conductor

This step involves creating a workflow with an event task in Orkes Conductor. Here, we are utilizing the IBM MQ queue as a sink for the event.

You can quickly build a workflow from UI in Orkes Conductor.

For this,

1. Navigate to Definitions > Workflow, and click the + Define Workflow button.
2. Create a workflow and add an event task at the required point with the Sink in the format ibm_mq:ibm-mq:queue-name, where “ibm-mq” is the integration name and “queue-name” is the queue to which Conductor should send/receive messages.

Executing Workflow in Orkes Conductor

The workflow can be run using different methods. You can use the Run Workflow button for quick testing, as shown in the image below:

Upon successful execution, you can verify the message's delivery through the IBM MQ console.

The action added in the event handler definition was to start the workflow http-test. You can verify this from the Executions > Workflow page.