Cloud Messaging

About Cloud Messaging

Messaging is one of the integration patterns used by the enterprise applications to solve integration challenges. Messaging systems allow independent applications to work together to accomplish some common tasks by means of exchanging messages without requiring direct connections. Messaging is also known as message-oriented middleware (MOM).

MOM uses a Messaging Provider to mediate messaging operations. MOM systems are composed of three basic components: clients, messages, and a MOM provider, including an API and administrative tools. The basic process of message exchange is as follows:

1. A client (publisher) sends a message using an API call to a destination managed by a Messaging Provider and the client continues to do other tasks while the message is processed.

2. The Messaging Provider routes and delivers the message to one or more clients (subscribers).

3. The client (subscribers) receives the message and acknowledges after processing it successfully.

The IBM webMethods Integration messaging solution allows you to implement the send/receive (publish/subscribe) or point-to-point messaging styles by bringing the JMS-based messaging capabilities . It provides the infrastructure for implementing message-based solutions that are built on the publish-and-subscribe model.

Terminology

• Publisher: A flowservice or a workflow that is configured to publish messages to the Messaging Provider. Other names for publisher are Sender or Producer.

• Subscriber: A flowservice or a workflow that is configured to receive messages from the Messaging Provider. Other names for subscriber are Receiver or Consumer.

• Destination: A virtual location through which the clients exchange messages. The publisher publishes messages to a destination that the messaging provider manages. The subscriber accesses that destination to consume the messages. There are two types of destinations:

  • Queue: A queue is used when a message is specified to be consumed by one subscriber. Messages are saved in the queue and delivered to subscribers. Thus, a queue guarantees that each message is delivered to one subscriber only. This type of messaging model is known as point-to-point messaging.

    

  • Topic: A topic is used when a message is specified to be consumed by more than one subscriber. When you send a message to a topic, all subscribers associated to that topic receive the message. This type of messaging model is know as publisher-subscriber.

    

• Message: A message is a data packet that sent to a destination. Data packet can contain simple text and documents. A message has three parts: Header, Properties, and Body. The header is the part of the message used for routing messages through the system. The properties include application-specific properties that are used to facilitate communication between applications. The body of a message is called the payload.

• Messaging Provider: The messaging provider is a communication platform that receives, stores, and delivers messages between applications. A messaging provider can be either Internal or External.

  • Internal Messaging Provider - This Messaging Provider is maintained by IBM. You can publish and consume messages only from workflows or flowservices in IBM webMethods Integration. The messaging destinations such as queues and topics can be managed from IBM webMethods Integration only. You can publish messages to the Internal Messaging Provider using the Messaging connector.
    

  • External Messaging Provider - This Messaging Provider is provided by an external vendor. It is hosted on an external system other than the IBM webMethods Integration for you to publish or consume messages. You can publish messages to an External Messaging Provider using the JMS (Java Messaging Service) connector.

• Messaging Provider Account – An account that enables the user to establish a connection to the Messaging Provider. Users can create accounts from the Connectors page. To connect to an Internal Messaging Provider, you must use a pre-configured default account.

• Messaging Service Trigger: A trigger for invoking the workflow when a message arrives (when a subscriber receives a message).

• Message Routes: A list of routing rules that can be added to a subscriber. An arriving message is evaluated against each rule in the specified order by the subsriber, and if the evaluation criteria is met, the invocation specified in the routing rule is initiated to perform further tasks.

• Routing Rule: A rule that defines how messages must be handled as they arrive at the destination. It consists of the following components:

  • Filter - The expression used for evaluating an incoming message.

  • Invocation - A subscriber-initiated workflow or flow service that performs additional tasks.

• Default Invocation: The default workflow or flow service that is initiated by the subscriber if no rules match.

Messaging Exchange Process in IBM webMethods Integration

1. The publisher publishes messages received to a destination (queue or topic) specified in the publisher’s workflow or flow service using the connectors - Messaging or JMS.

   • The Messaging connector is used to publish messages to the Internal Messaging Provider.

   • The JMS connector is used to publish messages to the External Messaging Provider.

2. The Messaging Provider (internal or external) sends the messages to the registered subscribers.

3. The subscriber evaluates the messages in accordance to the routing rules defined. If no rule satisfies the criteria, the default invocation is initiated. If default invocation is not specified, then the subscriber acknowledges the message and no invocation happens.

4. The initiated workflow or flow service performs the subsequent tasks as configured in IBM webMethods Integration.

The Messaging Provider delivers messages in the order they are received.

Message Restrictions in Cloud Messaging

The following sections lists the message limits that are supported in cloud messaging:

• Maximum Pending Messages

• Message Size Limits

Maximum Pending Messages

The Messaging Provider can hold up to 10000 messages per queue or topic. All messages arriving at the destinations are dropped if the hold capacity limit is reached, until the number of messages waiting to be delivered decreases. The dropped messages cannot be recovered. Delivered messages are no longer available for consumption by any other subscriber. If there are no subscribers, based on the destination type, the message retention is as follows for internal messaging providers:

• Queue: Messages are retained for 30 days.
  

• Topic: Messages are removed immediately. However, if there are registered subscribers that are not in the active state, then the message is retained for 30 days. During this period, if the subscriber returns to the active state, the message is delivered and removed from the topic.

Message Size Limits

The maximum message size is 50 MB. However, depending on the situation the size may vary as follows:

• If you are using the body/string and body/object fields, then the size limit is less than or equal to 50 MB.
  

• If you are using the body/data fields for complex messages, then the size limit is slightly less than 25 MB. This is because during encoding, metadata is included for each field or value in body/data and published. Thus, it is essential to pay attention to the cumulative size of all fields and values.

• If you want to run a workflow on receiving messages, then the maximum message size can be up to 10 MB. For more information about payload, see Webhook Payload and Log Data.

High-level Tasks for Configuring Messaging

Messaging Destinations

You can create messaging destinations that can be local to a project or shared across other projects.

Creating Queues

1. Go to Events > Messaging.

2. Click Messaging Destinations.

   

   By default, all the existing Queues created in the user tenant are listed.

3. Click Add Queue to create a new queue.

   

   The listing page shows the details under Name and Visibility, for example, whether a queue is Local or Shared and in the Actions columns. You can select a queue from the list to view the queue metrics.
   

4. Enter the following details:

   • Name: Provide the name of the queue.

   • Shared across all projects: Select Yes or No to set the queue as local or shared by using this option.

   

   Note

   The default setting for the Shared across all projects option is No, which means that the queue is project-specific and not accessible in other projects.

5. Click Save. The newly created Queue details page appears.

   

Creating Topics

1. Go to Events > Messaging.

2. Click Messaging Destinations. By default, the Queues landing page appears. Select Topics from the left navigation panel to view the topics listing page. All the existing topics created in the user tenant are listed.

   

3. Click Add Topic to create a new topic:

   

   The listing page shows the details under Name and Visibility, for example, whether a topic is Local or Shared and in the Actions columns. You can select a topic from the list to view its metrics.

4. Enter the following details:

   • Name - Provide the name of the topic.

   • Shared across all projects - Select Yes or No to set the topic as local or shared by using this option.

   

   Note

   The default setting for the Shared across all projects option is No, which means that the queue is project-specific and not accessible in other projects.

5. Click Save. The newly created Topic details page appears.

   

Metrics Associated with Queues and Topics

After you create a queue or a topic, the metrics available for a queue or a topic appear when you click the queue or the topic link to view the details.

• Name: Name of the queue or the topic.

• Capacity: The maximum number of messages the queue or topic can hold while waiting for subscribers to consume the pending messages.

• Rates:

  • Current Publish Rate: Rate in seconds at which messages are currently being published to the queue or to the topic.

  • Current Consumption Rate: Rate in seconds at which messages are currently being consumed from the queue or from the topic.

• Last Activity:

  • Last Published on: The date and time a message was last written to the queue or to the topic.

  • Last Consumed on: The date and time a message was last read from the queue or from the topic.

• Messages:

  • Published: Number of messages published to the queue or topic.

  • Consumed: Number of messages consumed from the queue or topic.

  • Pending: Number of messages pending in the queue or topic for consumption.

  • Last Message ID: Message ID of the last consumed message.

Subscribers

A subscriber receives messages published by a publisher. To receive published messages, you must create a subscription to that destination. After a subscription is created, a subscriber can view only messages published to that destination. As soon as a subscription receives an incoming message, it invokes a workflow or flow service defined in the subscription for processing the message.

Accessing Subscribers

1. Log on to the IBM webMethods Integration.

2. Go to Projects > Events > Messaging.
   By default, all existing subscribers created in the default project are listed. You can select a project from the Project drop-down list to view the subscribers for that selected project.

Creating Subscribers

Here the steps are explained to create a basic subscriber without any additional features.

1. Go to Events > Messaging.

2. Click Add new subscriber. The New subscriber page appears.
   The Add new subscriber button appears when you hover over the Messaging section. For readonly tenant users, the Add new subscriber button is in disabled mode.

3. Enter the following details:

   a. Name - Name of the subscriber.

   b. Description - Short explanation about the subscriber.

   c. Connector type - Type of connector you want to use. Select one of the following options:

   • Messaging for using an Internal Messaging Provider.

   • JMS for using an External Messaging Provider.

   d. Account - Account associated with the connector chosen in the previous step. If you have chosen:

   • Messaging - Use DefaultAccount.

   • JMS - Use one of the listed accounts. Alternatively, you can create a new account by clicking . For more information on creating an account, see Configuring JMS Connector Account in External Messaging Providers.

   e. Destination:

   • Destination type - Type of destination, either queue or topic.

   • Select destination - Select the destination from the Shared and Local categories.

   f. Default invocation:

   • Invocation type - Type of invocation, either workflow or flow service.

   • Select invocation - Name of the invocation. Alternatively, you can add a new invocation by clicking .

     Note

     For subscribers created prior to version 10.11, the Invocation type and Invocation name fields are grouped under the section Default invocation. Thus, the Invocation section that existed prior to version 10.11 from now is termed as Default invocation.

4. Click Save. The Subscriber details page appears. By default, the subscriber is in Enabled state.
   You can edit, enable, disable, or suspend a subscriber from the Subscriber details page. To customize the subscribers with additional features, click the Subscriber settings icon. For more information, see the sections: Subscriber Message Routing, Subscriber Error Management, Subscriber Message Acknowledgement, and Subscriber Message Processing.

   

   Note

   You can edit or delete a subscriber by clicking the Edit or Delete buttons available in the Actions column on the Events > Messaging page.

Subscriber Message Routing

The Message Routing feature enables you to define one or more routing rules for messages within a subscriber. Setting routing rules allow you to define the actions that must be taken after receiving a message.

A routing rule consists of two parts: an expression that specifies when the rule is applicable, and an action that must be completed. These processes can perform any processing, including extraction of the message and integration with back-end systems or a notification action. For example, a routing rule may initiate a business process that sends an alert notification to an administrator whenever a customer feedback message arrives in the mailbox.

Upon receiving a message, IBM webMethods Integration evaluates each routing rule. When the rule criteria match, the application initiates the business processes (invokes target) that is configured in the rule. If none of the rules satisfy the criteria, the application initiates the business process specified in Default invocation.

Subscribers evaluates the routing rules in the same order in which the rules appear in the editor. It is possible that a message could satisfy more than one routing rule. However, the subscriber runs only the workflow or flow service associated with the first satisfied routing rule and ignores the remaining routing rules. Therefore, the order in which you list routing rules on the editor is important.

For example, to process a purchase order, you might create services that:

1. adds a new customer record to a database.
2. adds a customer order.
3. bills the customer.

The service that adds a customer order can only run successfully if the new customer record has been added to the database. Likewise, the service that bills the customer can only run successfully if the order has been added. You can ensure that the services run in the necessary order by creating a subscriber that contains one routing rule for each expected message.

Subscriber Workflow with Message Routing

Adding Routing Rules to a Subsciber

1. Create a subscriber by following the instructions mentioned in Creating Subscribers, or, you can edit an existing subscriber.

2. Click Add routing rule. The New routing rule page appears.

3. Enter the following details:

   a. Name - Name for the routing rule. This name must be unique for each routing rule. It is used to identify the routing rule in other parts of the application.

   b. Filter - Expression that must be evaluated before running the invocation; can be empty for the default routing rule.

   c. Invocation type - Type of the invocation (workflow or a flow service) that must be invoked when a message arrives. See the section on Messaging Service Trigger for more information.

   d. Select Invocation- Name of the invocation that must be invoked. You can create a new invocation if none of the existing ones suffice by clicking .
   

   e. Click Add. The newly added rule appears under Routing rules.

   f. Repeat the sub steps in this step to add more routing rules.

   Tip

   • You can edit or delete a routing rule by clicking the Edit or Delete buttons djacent to the rule in the Subscriber details page.
   • Reordering Routing Rules: IBM webMethods Integration evaluates the routing rules in the same order in which the rules appear under Routing rules. However, you can reorder the rules as per your requirement by performing the following steps in the Subscriber details page: a. Select a routing rule. b. Move the selected rule up or down the list to the desired position.
     

4. Click Save. The subscriber details appear.

   

Subscriber Message Acknowledgement

The Acknowledgement mode property allows you to specify how the subscriber must acknowledge messages received from the Messaging Provider. The Acknowledgement mode can be configured in the General tab of the Subscriber settings dialog box.

You can set Acknowledgement mode with one of the following values:

• Client acknowledge: Acknowledges a message only after the invocation finishes.

• Auto acknowledge: Acknowledges the message automatically after the subscriber receives the message. That is the subscriber does not wait until the processing is completed. The subscriber cannot recover the message if the flow service execution fails or if Workflow invocation fails.

Subscriber Message Processing

Message processing determines how the subscribers processes the messages received by the Messaging Provider. The messages are processed in one of the following ways:

• Serial - Subscribers processes the messages sequentially in the order received from the Messaging Provider.

• Concurrent - Subscribers processes messages received from the Messaging Provider in parallel. That is, a subscriber processes as many messages as it can at the same time. The subscriber does not wait for the service specified in the routing rule to finish its processing before proceeding to the next message. You can specify the maximum number of messages a subscriber can process concurrently by using the Max concurrent processing property.
  
  Concurrent processing provides faster performance than serial processing because the subscriber processes more than one message at a time. However, the more messages are processed concurrently, the more memory the message processing consumes.
  
  Additionally, with concurrent processing, the subscriber does not guarantee that messages are processed in the order in which they are received.

Retrieving Multiple Messages for a Subscriber with Each Request

You can retrieve multiple messages from the Messaging Provider with each request by using the Max prefetch size property. Use of the prefetch size may improve performance of the subscriber because it reduces the time spent retrieving messages for the Messaging Provider. It can also reduce the burden on Messaging Provider as it reduces the number of requests to which the Messaging Provider needs to respond.

Using the prefetch size is most likely to improve performance for subscribers that process many small messages and have services that run quickly. For subscribers that fit this use case, prefetching messages can improve the overall performance of the application as subscriber saves time in retrieving messages one by one from the provider every time. If a subscriber receives large messages or has long-running services, using the prefetch size affects the overall performance of the application as all prefetched messages are processed serially.

Configuring Serial Message Processing

1. Create a subscriber by following the instructions mentioned in Creating Subscribers.
   

   Note

   • Ensure that the subscriber is subscribed to a topic.

   • For existing subscribers, click the Edit button in the Actions column of the corresponding subscriber you want to update in the Subscribers list table on the Events > Messaging page. The Update Subscriber page appears.

2. Click the Subscriber settings icon in the Subscribers page. The Subscriber settings dialog box appears.

3. Enter the following values in the Message processing tab:

   a. Select Serial as Processing mode. The Max concurrent processing value is set to 1 by default for serial processing.

   b. Max prefetch size: Number of messages you want the subscriber to retrieve from the Messaging Provider. The default value is 10.
   Specify zero if you do not want to prefetch messages from the Messaging Provider.

   

4. Click OK. The Subscribers page appears.

5. Click Save. The subscriber processes the messages serially.

Configuring Concurrent Message Processing

1. Create a subscriber by following the instructions mentioned in Creating Subscribers.

   Note

   For existing subscribers, click the Edit button in the Actions column of the corresponding subscriber you wish to update in the Subscribers list table on the Events > Messaging page. The Update Subscriber page appears.

2. Click the Subscriber settings icon in the Subscribers page. The Subscriber settings dialog box appears.

3. Enter the following values in the Message processing tab:

   a. Processing mode: Select as Concurrent.

   b. Max concurrent processing: Maximum number of messages that must be processed concurrently. You can specify a value between 1 to 10. Value of 1 is same as serial processing.
   For example, if this value is set to 10 and if 10 messages are received from Messaging Provider then the subscriber processes all 10 messages at the same time depending on Max prefetch size setting..

   c. Connection Count – Number of connections a subscriber must make to receive messages from the Messaging Provider. You can specify a value between 1 to 10. The default vale is 1.

   Note

   The Connection count property is applicable for subscribers associated with JMS connector. Also, as part of the creation of the JMS connector account, you have to set the Allow new connection per subscriber value to True in order to set the Connection count property to be applicable.

   d. Max prefetch size: Number of messages you want the subscriber to retrieve from the Messaging Provider in a single request. The default value is 10.
   Specify zero if you do not want to use the prefetch messages from the Messaging Provider.

   Note

   Increasing the prefetch size value greater than one can have an impact on concurrent processing. For more information, see Retrieving Multiple Messages for a Subscriber with Each Request.

   

4. Click OK. The Subscribers page appears.

5. Click Save. The subscriber processes the messages in concurrently.

Subscriber Error Management

During message processing, a subscriber may encounter errors that can generally be categorized as follows:

• Transient errors: Recoverable errors caused by temporary conditions such as network failures or unavailability of resources.
  

• Fatal errors: Non-recoverable errors caused by faulty business logic.

A subscriber acknowledges the message when an error occurs by default. However, subscribers can be configured to retry messages depending on the type of the errors encountered. You can set a subscriber’s behavior for managing errors from the Subscriber settings dialog box.

Transient Errors

Transient errors occur because of a temporary situation that might be resolved quickly, for example, the inaccessibility of a resource due to network failure or an inability to connect to a database, or whenever the invoked flow service calls the throwExceptionForRetry service causing it to fail with transient error. As the condition that caused the Subscriber to fail is temporary, it is possible for the Subscriber to invoke flow service successfully if it waits and then re-runs. Hence, you can configure the retry mechanism.

When a Subscriber fails because of a transient error, IBM webMethods Integration does the following:

1. Verifies if the retry limit is reached.

   • Yes: Verifies if the subscriber is configured to suspend on error:

     • Yes: Suspends the subscriber temporarily and recovers the message. This indicates that the required resources are not ready to process the message and makes the message available for processing later.

       Note

       Subscriber remains in suspended state until one of conditions specified in the Subscriber State section is met. After the subscriber is enabled, the messaging provider redelivers the same message, and the subscriber processes the message.

     • No: Acknowledges the message and the flow service invocation is marked as failed. In this scenario, if you have configured the subscriber to suspend on fatal error, then the subscriber suspends
       

   • No: Retries to process the message at configured retry intervals.

Fatal Errors

Fatal error occurs because of an exceptional situation that cannot be resolved. As the subscriber cannot resolve the condition that caused the operation to fail, the subscriber aborts the operation with a failure exception.

When a Subscriber fails because of a fatal error, IBM webMethods Integration does the following:

1. Verifies if the subscriber is configured to suspend on error.

   • Yes - Suspends the subscriber temporarily and sends an acknowledgment.

   • No - Sends an acknowledgment for the message.

In both the scenarios, the message processing ends with an error. The subscriber is ready to process the next message.

Configuring Subscriber Error Handling Mechanisms

1. Create a subscriber by following the instructions mentioned in Creating Subscribers.

   Note

   For existing subscribers, click the Edit button in the Actions column of the corresponding subscriber you wish to update in the Subscribers list table on the Events > Messaging page. The Update Subscriber page appears.

2. Click the Subscriber settings icon. The Subscriber settings dialog box appears.

3. Click the Error handling tab. The error handling options appear.

   

4. To configure Fatal Errors - Set the Do not suspend the subscriber option with one of the following values:

   • ON - if you want to suspend the subscriber when an error occurs.

   • OFF - if you do not want to suspend the subscriber when an error occurs. The default value is OFF .

5. To configure Transient Errors - Enter the following values under the Transient Error Handling section:

   • Max retry attempts - Number of times that a flow service (invoked by the subscriber) must retry to process a message if it fails because of a transient error. The default value is Five. Setting it to Zero indicates that the flow service does not retry to process the message. You can specify a value in the range from Zero to 100.

   • Retry interval - Duration that the system waits before retrying to run the flow service again. The default value is 10 seconds . You can specify a value in the range from Four to 3600 (Four seconds to One hour).

   • On retry failure - Action to be taken after the retry count limit is reached. You can specify one of the actions:

     • Throw exception - Flow service stops processing the current message with an exception. The current message is acknowledged, and the subscriber starts processing the new messages.

     • Suspend and retry later- Recovers the message to the messaging provider and suspends the subscriber.

6. Click OK. The subscriber performs the actions as configured whenever an error occurs.

Subscriber State Management

The state of a subscriber indicates whether a subscriber is active or inactive. IBM webMethods Integration allows you to view, change, and manage the state of a subscriber.

The states that can be set for a subscriber are: Enable, Disable, and Suspend. You may want to change the state of a subscriber in the following scenarios:

• The Messaging Provider system is functioning under an unusually heavy load.

• The back-end system to which subscribers interact needs maintenance or is becoming unresponsive.

• The error occurs during message processing and the subscribers who are listening to the message are suspended automatically by the Messaging Provider system.

You can view the current state of a subscriber in the Subscribers list table on the Events > Messaging page.

Alternatively, you can view the subscriber state by going to the details page of a particular subscriber.

Subscriber State Behavior

Subscriber State	Behavior
Enabled	The subscriber is active to receive and process messages.
Enabled but not running	The subscriber is unable to connect to the Messaging Provider either because the account has been disabled or because the system is unable to reach the messaging provider.
Disabled	The subscriber is unavailable and cannot receive and process any message. Note Subscribers that are disabled can be enabled only using the user interface.
Suspended	The subscriber is partially available. This means, the subscriber can process only existing messages but cannot receive any new messages. Note Subscribers can enter the Suspended state due to one of the reasons: A user has suspended a subscriber explicitly using the user interface. The system suspends a subscriber for reasons like message processing error, server overload, and back-end system failure. In such cases, the subscriber is automatically enabled after the cause is addressed.
Not Configured	The subscriber is not configured, that is, it does not have any routing rules defined and is marked with an orange warning icon. You can configure the subscriber using the Edit option either from the Subscribers page or from the corresponding workflow.

Changing Subscriber State

1. Go to Events > Messaging. The existing subacribers are listed. If subscribers are not yet created, you does not see the list.

2. Click the corresponding vertical ellipsis icon for the subscriber you want to change the state. A menu appears.

3. Select the state you want to set for the subscriber from the list of options that appear. When you change the state of a subscriber, IBM webMethods Integration takes some time to update the change. During this time, new messages are retrieved and processed.

   

   Or, click the checkbox next to the Name in header row to change the subscriber states at once

   

   Tip

   You can alternatively change the state of a subscriber by going to the details page of a particular subscriber.
   Note

   • When you disable an enabled subscriber, IBM webMethods Integration checks for existing and new messages. The existing messages that are currently being processed are allowed to complete, whereas messages that are awaiting to be processed are dropped and cannot be retrieved again. New messages are not retrieved.
   • When you suspend an enabled subscriber, IBM webMethods Integration allows existing messages that are currently being processed and messages that are awaiting to be processed to continue their normal course of execution. New messages are not retrieved.
   • If you disable an enabled subscriber that is associated with a queue, IBM webMethods Integration allows you to create a new subscriber on the same queue. This means, you can have only one active subscriber for a queue but can have multiple disabled subscribers for the same queue. This is applicable only for internal Messaging Providers.
   • If you want to enable a disabled subscriber that is associated with a queue, ensure that the queue is not associated with any other active subscriber. This is because there can only be one active subscriber for a queue.
   • You cannot suspend a disabled subscriber directly. If you want to suspend a disabled subscriber, you must enable it and suspend.

Messaging Service Trigger

You can subscribe for messages through workflows using the Messaging Service Trigger option instead of Messaging.

The workflow is run whenever messages are published to the associated destination. In other words, this is the same as creating a subscriber from Messaging and then associating it with the workflow under Default invocation. As a result, a Messaging Service Trigger is automatically created and attached to the workflow.

The process is as follows:

Prerequisite: Ensure that destination (queue or topic) exists. Otherwise, create a destination from Messaging before starting with the workflow creation.

1. Create a workflow.

2. Add a Messaging Service Trigger.

3. Associate a destination, either queue or topic.

4. Associate with an existing subscriber.

   Note

   These filters are called as the routing rules filters which initiate to run the workflow if any of them match. If none of the existing subscribers meet the requirement you can also create a new subscriber and associate with the workflow from Messaging Service Trigger itself.

5. Define filter conditions.

   Note

   These filters are called as the routing rules in Messaging. All routing rules defined for a subscriber (either from workflow or Subscriber) are listed in the respective Subscriber details page under the Routing rules section.

6. Save the workflow. This workflow is ready to receive the published messages.

Subscribers created either from workflows or directly from Messaging are all listed in the Subscribers list table on the Events > Messaging page. If you modify or add more routing rules to a subscriber from the Subscribers details page in Messaging, the corresponding Messaging Service Trigger is automatically updated with these changes. The newly added routing rules are listed under Filters for a Messaging Service Trigger. Similarly, if you modify any values or add more filters to a Messaging Service Trigger, then those details are automatically updated and listed in the Subscriber details page. Since only the filters that trigger this workflow are listed here, the message evaluation might not always follow the order that you see here. To know the actual order, check the Routing rules section in the Subscriber details page.

For instance, there is a subscriber S1 associated to a workflow. You have added filter F1 from workflow, then add routing rule R1 from the Subscribers details page for S1. Upon viewing the Routing rules section, F1 is followed by R1 as the rules. Later, you added another filter, F2. Now if you look at the Routing rules section, you see that there are three rules listed: F1, R1, and F2. On the other hand, in workflows under Add Filters, the order is shown as F1 and F2. Subscribers evaluate the routing rules as listed under the Routing rules section. Hence, the message evaluation might not always follow the order in which the rules are listed for a workflow.

Configuring Messaging Service Trigger for Subscribing Messages

1. Go to Integrations > Workflows. The Workflows page appears.

2. Click Add. The Start Building your Workflow page appears.

3. Click Create New Workflow to start creating a workflow. The workflow canvas appears.

4. Click the Settings icon on the Start step . The Trigger page appears.

5. Search and select the Messaging Service trigger.

   

   Note

   Version: 1 Messaging Service triggers cannot be modified.

6. Click Next. The Messaging Service page appears.

7. Perform the following steps to add a subscriber:

   1. Click . The Add subscriber page appears.

   2. Enter the following details:

      a. Subscriber Name - Name of the subscriber.

      b. Description - Short explanation about the subscriber.

      c. Destination type- Type of destination, either Queue or Topic.

      d. Destination - Name of the destination.

      

   3. Click Save. The subscriber is created.

      

8. Perform the following to add filters:

   1. Click Add Filters. The filter fields appear.

   2. Enter the following details:

      a. Name - Name for the filter. This name must be unique for each filter. It is used to identify the routing rule in other parts of the application.

      b. Filter Expression - Expression that must be evaluated before running the invocation; can be empty for default routing rule.

   3. Repeat the sub steps in this step to add more filters.

      

9. Click Save. The Test trigger page appears.

   Note

   If you want to test the trigger for a subscriber, you must first publish a message and then click the Test button to see whether the message is received.

10. Click Skip. The Trigger output datapage appears.

11. Click Done. The workflow canvas appears.

12. Drag and drop the Logger connector on to the canvas from the Search pane.

13. Click the warning icon on the Logger. The Logger page appears.

14. Click Next. The Logger connector fields appear.

15. Drag and drop string to the Log Data field.

    

16. Click Next. The Test this action page appears.

17. Click Done. The workflow canvas appears.

18. Connect Logger to the Stop step.

    

19. Provide a name and description for the workflow.

    

20. Save the workflow. Now the workflow is ready to receive messages and process further steps based on the filters specified.

    Note

    • You can edit a subscriber’s filters by clicking the Edit button of the Messaging Service trigger from a workflow.
    • If a workflow is associated with only one subscriber and you have deleted the trigger, then the subscriber is also deleted.
      

Messaging Connector Parameters

Input Parameters

• JMSMessage: A document representing the JMS message you want to send.

  • properties: A document containing optional fields added to the message header. IBM webMethods Integration adds the following properties to JMS messages it sends:

    • uuid: A universally unique identifier for the message.

  • body: A document containing the JMS message body. IBM webMethods Integration supports the following formats for the JMS message body.

    • string: Message body in the form of a string.

    • object: Message body in the form of a serializable object.

    • data: Message body in the form of a document.

    Note

    • Only one of the mentioned formats can be used to send data.
    • In Workflows, the string and data formats can be used. In flow services, all mentioned formats can be used.
      

Output Parameters

• JMSMessage: A document containing the message sent to the JMS provider.

  • properties: A Document containing optional fields added to the message header. IBM webMethods Integration adds the following properties to JMS messages it sends:

    • uuid: A universally unique identifier for the message assigned by the sender.
      

  • body: A document containing the JMS message body. IBM webMethods Integration supports the following formats for the JMS message body.

    • string: Message body in the form of a string.

    • object: Message body in the form of a serializable object.

    • data: Message body in the form of a document.

    Note

    This message format can only be used when exchanging JMS messages between IBM webMethods Integration and On-premise IBM webMethods Integration Server.

Publish and Subscribe Messages using Flow services

Summary

To publish and subscribe messages using queues and flow services.

Basic Flow

Publishing and subscribing messages using queues and flow services involves the following high-level tasks:

1. Create Queue: Create a queue Q1 to store messages received from publisher.

2. Create Publisher: Create a flow service, say Q1_publish_flowservice, to publish the messages to Q1.

3. Create Subscriber: Create a subscriber, say Q1_subscriber, which subscribes to Q1 and runs a flow service, Q1_consume_flowservice, to consume the messages.

4. Publish Messages: Run the publisher and view the consumer flow service execution logs.

Create Queue

1. Log in to IBM webMethods Integration and create a project, for example, Messaging_Ops. You can also select an existing project.

2. Go to Events > Messaging.

3. Click Messaging destinations. The Queues page appears.

4. Click Add Queue. The New Queue page appears.

5. Enter the queue name as Q1.

   

6. Click Save. The newly created queue details appear.

   

Create Publisher

1. Click Integrations > Flow services. The Flow services page appears.

2. Click . The Start creating the Flow service page appears.

3. Enter the Flow service name as Q1_publisher_flowservice.

4. [Optional] Enter a short description of the flow service under Flow service name.

5. Type Messaging in the flow service step 1 and select Messaging from the list that appears. The fields associated with the Messaging application appears.

6. Select the following options:

   a. Action: publish

   b. Destination type: Queue

   c. Destination: Q1

   Note

   You can also add a new destination by clicking the Add Destination option.

   d. Account - Default account

   

7. Click to map the input and output fields. The Pipeline panel appears.

8. Double-click on the string field. The Set Value page appears.

9. Enter the message I want to publish a message!.

   

10. Click Save. The Pipeline panel appears.

11. Close the Pipeline panel. The Flow service page appears.

12. Click Save. The flow service is ready to publish messages.

Create Subscriber

You can create the consumer flow service in one of the following ways:

• Create a flow service from the Flow services page, then assign that flow service to a subscriber during subscriber creation.

• Create the Flow service when creating a subscriber.

Here, the steps are explained to create Q1_subscriber containing Q1_consume_flowservice from the Subscribers page.

1. Go to Events > Messaging.

2. Click Add new subscriber. The New subscriber page appears.

3. Enter the following details:

   a. Subscriber Name: Q1_subscriber

   b. Description: Consumes messages from Q1

   c. Connector Type: Messaging

   d. Account: Account that must be used to connect to the messaging provider. It is the DefaultAccount.

   e. Destination type: Queue

   f. Select destination: Q1

4. Perform the following to set the Default invocation:

   a. Invocation type: Flow service

   b. Select invocation: Click and enter the name as Q1_consumer_flowservice in the New Flow service page.

   

   c. Click Save.

5. Perform the following to add routing rules:

   a. Click Add routing rules. The New routing rule page appears.

   b. Enter the following details:

   i. Name: Rule 1

   ii. Filter: %body/string%==”Hello”

   iii. Invocation type: Flow service

   iv. Select Invocation: Click and enter the name as Rule1_invocation_flowservice in the New Flow service page.

   v. Click Save. The selected flow service is added and is invoked if the incoming message criteria is satisfied.

   

   Note

   You can choose an existing flow service too. Only flow services that have JMS trigger specifications are listed in the Select Invocation field.

   c. Click Add. The new rule is created and listed under Routing rules.

   d. Repeat the sub steps in this step to add more rules if required.

6. Click Save. The flow service is added to the subscriber and the Subscriber details page appears.

   

   Further, as you have created the consumer flow service from the Subscribers page, the trigger specification reference appears automatically.

7. Click Save. The subscriber is created with the Q1_consumer_flowservice that consumes messages arriving in Q1.

Publish Messages

1. Open the Q1_publisher_flowservice.

2. Click . If the Q1_publisher_flowservice runs successfully, the Q1_consumer_flowservice runs automatically. The Q1_publisher_flowservice sends the message to the queue Q1 and as the Q1_Subscriber is listening to Q1, it runs the Q1_consumer_flowservice created in the Q1_Subscriber.

3. Go to Monitor > Execution results > Flow service execution. The flow service execution statistics appear.

4. Go to the Executions section. You can observe that the Execution source column for the:
   

   • Q1_consumer_flowService is Messaging Subscriber.

   • Q1_publisher_flowService is User Interface.

   

In this way, you can publish and subscribe messages using flow services.

Publish and Subscribe Messages Using Workflows

Summary

To publish and subscribe messages using topic and Workflows.

Basic Flow

Publishing and subscribing messages using topics and workflows involves the following high-level tasks:

1. Create Publisher: Create a workflow, say T1_publish_workflow, to publish the messages to topic T1.

2. Create Subscriber: Create a Subscriber, say T1_subscriber, which subscribes to T1 and runs a workflow, T1_subscriber_workflow, to consume the messages.

3. Publish Messages: Run the publisher and view the consumer workflow execution logs.

Create Publisher

1. Log in to IBM webMethods Integration and create a project, for example, Messaging_Ops. You can also select an existing project.

2. Click Integrations > Workflows. The Workflows page appears.

3. Click . The Start Building your Workflow page appears.

4. Click Create New Workflow to start creating a workflow to publish the message. The Workflow canvas appears.

5. Drag and drop the Messaging connector on to the canvas from the right-side Search pane.

6. Click the warning icon on the Messaging connector. The Messaging page appears.

   

7. Provide the following details to configure the Messaging connector:

   a. Select action: publish

   b. Name: T1_publisher

   c. Destination Type: Topic

   d. Destination: T1 (You can also add a new destination by clicking )

   e. Connect to Messaging: DefaultAccount
   

   

   f. Click Next. The T1_publisher page appears.

   g. Type the message, Hello! I’m publishing a message, in the string field.
   

   

   h. Click Next. The Test this action page appears.
   

   

   i. Click Test. The Output tab shows that the message has been posted.
   

   

   j. Click Done. The workflow canvas page appears.

8. Connect the Messaging step to the Stop button.

9. Provide a name for the workflow, T1_publisher_workflow.

   

10. Click Done. The workflow name is updated.

11. Save the workflow.

Create Subscriber

1. Click Integrations > Workflows. The Workflows page appears.

2. Click . The Start Building your Workflow page appears.

3. Click Create New Workflow to start creating a workflow for subscribing messages. The workflow canvas appears.

4. Click the Settings icon on the Start step . The Trigger page appears.

5. Search and select the Messaging Service trigger.

   

6. Click Next. The Messaging Service page appears.

7. Perform the following steps to add a subscriber:

   a. Click . The Add subscriber page appears.

   b. Subscriber Name: T1_subscriber

   c. Description: Consumes messages received from T1

   d. Destination type: Topic

   e. Destination: T1
   

   

   f. Click Save. The subscriber is created.

8. Perform the following to add filters:

   a. Click Add Filters. The filter fields appear.

   b. Enter the following details:

   i. Name: F1.

   ii. Filter Expression: %body/string%==”Hello”.

   iii. Repeat the previous two steps to add more filters.

   

9. Click Save. The Test trigger page appears.
   

   If you want to test the trigger, you must first publish a message and then click the Test button to see whether the message is received.

10. Click Skip. The Trigger output data page appears.

11. Click Done. The workflow canvas appears.

12. Search for the Logger connector and drag and drop the Logger connector on to the canvas.

    

13. Click the warning icon on the Logger. The Logger page appears.

    

14. Click Next. The Logger fields appear.

15. Drag and drop string to the Log Data field.

    

16. Click Next. The Test this action page appears.

    

17. Click Done. The workflow canvas appears.

18. Connect Logger to the Stop step.

    

19. Provide a name and description for the workflow.

    

20. Save the workflow. Now the workflow is ready to receive messages and process further steps based on the filters specified.

Publish Messages

1. Open the T1_publish_workflow from the Workflows page.

2. Click .

3. Go to Monitor > Execution results > Workflow execution. The workflow execution statistics appear. You can observe that the Execution source column for the:

   • T1_subscriber_workflow is Trigger.

   • T1_publisher_workflow is Manual.

   

In this way, you can publish and subscribe messages using workflows.

Publish and Consume a Document

Summary

To publish and consume a document.

Basic Flow

Publishing and consuming messages using documents involves the following high-level tasks: 1. Create a topic, todays_quote.

1. Create a document type, doc_quote from scratch to publish.

2. Create a publisher flow service, publish_doc_quote, to publish a document.

3. Create a consumer flow service, consume_doc_quote, that logs the same data sent in the published document.

4. Create a subscriber, todays_quote_subscriber, to consume messages published to topic.

5. Create a consumer workflow, todays_quote_subscriber2, that logs the same data sent in the published document.

6. Run the publisher flow service and check if both the consumers have executed successfully.

Create Topic

1. Log in to IBM webMethods Integration and create a project, for example, Messaging_Ops. You can also select an existing project.

2. Go to Events > Messaging.

3. Click Messaging destinations. The Queues page appears.

4. Click Topics. The Topics page appears.

5. Click Add Topic. The New topic page appears.

6. Enter the topic name as, todays_quote.

   

7. Save the topic. The newly created topic details appear.

Create Document Type

1. Go to Configurations > Flow service > Document Types > Add Document Type. The Add new Document type dialog box appears.

2. Select Build from scratch.

3. Click OK. The Add new Document type page appears.

4. Click Load JSON. The Type or paste JSON content text box appears.

5. Paste the content.

   

6. Click Load JSON. The Add new Document type page appears.

   

7. Click Save. The newly created document type appears under Document Types.

   

Create Publisher

1. Click Integrations > Flow services. The Flow services page appears.

2. Click . The Start creating the Flow service page appears.

3. Enter the flow service name as publish_doc_quote.

4. [Optional] Enter a short description of the flow service under Flow service name.

5. Type Messaging in the flow service step 1 and select Messaging from the list that appears. The fields associated with the Messaging application appears.

6. Select the following options:

   a. Action: publish

   b. Destination type: Topic

   c. Destination: todays_quote

   d. Account: Default account

   

7. Click Define I/O. The Define input and output fields page appears.

8. Select the Add a new set option. The data fields appear.

9. Enter the following details:

   a. Name: quote

   b. Type: Document Reference

   c. Document reference: doc_quote

   

10. Click Done. The Flow service page appears.

11. Click to map the input and output fields. The Pipeline panel appears.

12. Map the quote document reference from the input pipeline to the data field in the JMS message body.

    

13. Click Save.

14. Close the Pipeline panel. The Flow service page appears.

15. Click Save. The flow service is ready to publish messages.

Create Consumer Flow service

1. Click Integrations > Flow services. The Flow services page appears.

2. Click . The Start creating the Flow service page appears.

3. Enter the flow service name as consume_doc_quote.

4. [Optional] Enter a short description of the flow service under Flow service name.

5. Click Define I/O. The Define input and output fields page appears.

6. Select Specification Reference.

7. Select the Messaging Service.

   

8. Click Done. The Flow service page appears.

9. Do the following steps in order to retrieve fields of the published quote document, you must first map the data to doc_quote in the transform pipeline step.

   a. Type Transform in the flow service step 1 and select Transform Pipeline from the list that appears.

   b. Click to map the input and output fields. The Pipeline panel appears.

   c. Click in the Pipeline Output. The Pipeline output page appears.

   d. Enter the following details:

   i. Name: doc_quote

   ii. Type: Document Reference

   iii. Document reference: doc_quote

   

   e. Click Save. The Pipeline panel appears.

   f. Map the data field under the JMSMessage body to the newly created doc_quote field.

   

   g. Close the Pipeline panel. The flow service page appears.

10. Do the following step to log the quote that is received:

    a. Type logCustomMessage in the flow service step 1.

    

    b. Click to map the input and output fields. The Pipeline panel appears.

    c. Double-click message under the Input column. The Set Value page appears.

    d. Add the custom message: Today’s quote is “%/doc_quote/content%“, by “%/doc_quote/author%.

    e. Select Perform pipeline variable substitution.

    

    f. Click Save. The Pipeline panel appears.

11. Close the Pipeline panel. The Flow service page appears.

12. Click Save.

Create Subscriber

Create a subscriber, todays_quote_subscriber, for consuming the messages sent to the topic todays_quote.

1. Go to Events > Messaging.

2. Click Add new subscriber. The New subscriber page appears.

3. Enter the following details:

   a. Subscriber Name: todays_quote_subscriber

   b. Description: Consumes messages from todays_quote

   c. Connector Type: Messaging

   d. Account: Account that must be used to connect to the messaging provider. It is the DefaultAccount.

   e. Destination type: Topic

   f. Select destination: todays_quote

   g. Invocation type: Flow service

   h. Select invocation: consume_doc_quote

   

4. Click Save. The subscriber is created.

Create Consumer Workflow

Create another subscriber, todays_quote_subscriber2, for consuming the messages sent to the topic, todays_quote.

1. Click Integrations > Workflows. The Workflows page appears.

2. Click . The Start Building your Workflow page appears.

3. Click Create New Workflow to start creating a Workflow for subscribing messages. The Workflow canvas appears.

4. Click the Settings icon on the Start step . The Trigger page appears.

5. Search and select the Messaging Service trigger.

6. Click Next. The Messaging Service page appears.

7. Perform the following steps to add a subscriber:

   a. Click . The Add subscriber page appears.

   b. Subscriber Name: todays_quote_subscriber2

   c. Description: Consumes messages received from todays_quote

   d. Destination type: Topic

   e. Destination: todays_quote
   

   

   f. Click Save. The subscriber is created.

8. Click Save. The Test trigger page appears.

   Note

   If you want to test the trigger, you must first publish a message and then click the Test button to see whether the message is received.

9. Open the publisher flow service publish_doc_quote in a separate tab.

10. Click . The Input values page appears.

11. Add the input values as shown:

    

12. Click Run. The Run Successful message appears if the flow service runs successfully.

    

13. Go to the previous tab where the consume_doc_quote_workflow is open.

14. Click Test. The OUTPUT tab contains the document that was published in the earlier step.

    

15. Click Done. The Workflow canvas appears.

16. Search for the Logger connector and drag and drop the Logger connector on to the canvas.

17. Click the warning icon on the Logger. The Logger page appears.

18. Click Next. The Logger fields appear. Note that the quote document is available in the JMS message body data fields.

    

19. Paste the following text in the log data box: Today’s quote is “{{$trigger.JMSMessage.body.data.content}}” by {{$trigger.JMSMessage.body.data.author}}.

    

20. Click Next. The Test this action page appears.

21. Click Done. The Workflow canvas appears.

22. Connect Logger to the Stop step.

23. Provide a name and description for the Workflow.

    

24. Save the Workflow.

Publish Messages

1. Open the publish_doc_quote flowservice.

2. Click . The Input values page appears.

3. Add the input values as shown:

   

4. Click Run. The Run Successful message appears if the flow service runs successfully. The document is published to topic.

   

5. Go to Monitor > Execution results > Flow service execution. The flow service execution statistics appear. You can observe that status is success.

   

   Also, the message is logged.

   

6. Go to Monitor > Execution results > Workflow execution. The Workflow execution statistics appear.

   

7. Select the logger step to see the log message

   

External Messaging Providers

The External Messaging Providers are those messaging providers that are hosted on an external system other than IBM webMethods Integration for you to publish or consume messages.

The functioning of external messaging provider is same as that of the internal messaging provider. The only difference is that the external messaging provider is managed by your organization and not by IBM. As it is external to IBM webMethods Integration, you need to create a JMS Account to connect to the external provider.

Currently, IBM webMethods Integration supports the following external messaging providers:

• Universal Messaging in the IBM webMethods Cloud Container - This option allows users to connect to Universal Messaging in IBM webMethods Cloud Container to integrate with IBM webMethods Integration. The IBM webMethods Cloud Container uses Universal Messaging (provided by IBM) as the messaging provider.

• Self-hosted Universal Messaging - This option allows users to leverage their existing Universal Messaging system-based solutions to integrate with IBM webMethods Integration. Universal Messaging is maintained by the user and must be publicly accessible.

  Note

  In order to connect to Universal Messaging in IBM webMethods Cloud Container, you must enable the Allow External Access to Messaging option.
  

JMS Connector Parameters

Input Parameters

• destinationName: Name or lookup name of the Destination to which you want to send the message. Specify the lookup name of the Destination object when the JMS connection alias uses JNDI to retrieve administered objects.

• destinationType: Type of destination to which you want to send the message. Specify one of the following values:

  • QUEUE to send the message to a particular queue. This is the default.

  • TOPIC to send the message to a topic.

• JMSMessage: A document representing the JMS message you want to send.

  • header: A document containing the header of the JMS message.

    • deliveryMode: Specifies the message delivery mode for the message. Specify one of the following:

      • PERSISTENT: Default. Provide once-and-only-once delivery for the message. The message is not lost if a JMS provider failure occurs.

      • NON_PERSISTENT: Provide at-most-once delivery for the message. The message has no guarantee of being saved if a JMS provider failure occurs.

    • timeToLive: Length of time, in milliseconds, that the JMS provider retains the message. The default value is Zero, meaning that the message does not expire.

    • JMSType: Message type identifier for the message.

  • properties: A document containing optional fields added to the message header. IBM webMethods Integration adds the following properties to JMS messages it sends:

    • uuid: A universally unique identifier for the message.

  • body: A document containing the JMS message body. IBM webMethods Integration supports the following formats for the JMS message body.

    • string: Message body in the form of a string.

    • bytes: Message body in the form of a one-dimensional byte array.

    • object: Message body in the form of a serializable object.

    • data: Message body in the form of a document.

    Note

    • Only one of the mentioned formats can be used to send data.
    • In workflows, the string and data formats can be used. In flow services, all mentioned formats can be used.
      

Output Parameters

• JMSMessage: A document containing the message sent to the JMS provider.

  • header: A document containing the header fields for the sent message. The JMS provider populates these fields after it has successfully received the message from IBM webMethods Integration.

    • JMSCorrelationID: A unique identifier used to link messages together.

    • JMSDeliveryMode: Delivery mode used to send the message.
      

      Note

      When sending a message, this value is obtained from the JMSMessage/header/deliveryMode input parameter.

    • JMSDestination: Destination (queue or topic) to which the message was sent.

    • JMSExpiration: Time at which this message expires. If the message producer did not specify a time-to-live, the JMSExpiration value is zero, indicating the message does not expire.

      Note

      When sending a message, this value is obtained from the JMSMessage/header/timeToLive input parameter.

    • JMSMessageID: Unique identifier assigned to this message by the JMS provider.

    • JMSTimestamp: Time at which the message was given to the JMS provider.

    • JMSType: Message type identifier specified by the client when sending the message.

  • properties: A document containing optional fields added to the message header. IBM webMethods Integration adds the following properties to JMS messages it sends:

    • uuid: A universally unique identifier for the message assigned by the sender.
      

  • body: A document containing the JMS message body. IBM webMethods Integration supports the following formats for the JMS message body.

    • string: Message body in the form of a string.

    • bytes: Message body in the form of a one-dimensional byte array.

    • object: Message body in the form of a serializable object.

    • data: Message body in the form of a document.

    This message format can only be used when exchanging JMS messages between IBM webMethods Integration and On-premise webMethods Integration Server.

JMS Connector Account Parameters

• Name: Name of the account for easy identification.

• Description: Short description about the account.

• Messaging provider template: Messaging Provider that IBM webMethods Integration must connect with to send or receive messages.

• Provider URL: Primary URL of the initial context for sessions with the JNDI provider. The URL specifies the JNDI directory in which the JNDI provider stores JMS administered objects.

• Clustered UM: Option to specify if the realm specified in the Provider URL is part of a cluster.
  Server clustering refers to a group of servers working together as one system to provide users with higher availability. These clusters are used to reduce downtime and outages by allowing another server to take over in the event of an outage. This option is applicable only if the provider is Universal Messaging and is clustered.

• Follow the Master: Whether connections created from this account must always connect to the master realm server in the cluster. This setting affects producer and consumer connections created using this account. If selected, IBM webMethods Integration always connects to the master realm server in a Universal Messaging cluster to send or receive messages. Otherwise, IBM webMethods Integration connects to one of the servers listed by following the order specified in Connection retry mode. This option is applicable only if the provider is Universal Messaging and is clustered.

• Clustered Realm URLs: Remaining URLs of the cluster. This option is applicable only if the provider is Universal Messaging and is clustered. This option is applicable only if the provider is Universal Messaging is clustered and the Follow the Master option is disabled.

• Connection retry mode: Method by which IBM webMethods Integration must attempt to connect to one of the servers in the cluster when the existing connection is lost. In sequential mode, IBM webMethods Integration retries to establish connections with the servers in the order specified in the list. In random mode, IBM webMethods Integration retries to establish connection at random to any of the servers specified in the list.

• Provider URL Failover List: JNDI URLs that IBM webMethods Integration must connect to if the existing connection is lost. This option is applicable only if the provider is not a clustered Universal Messaging setup.
  Failover support enables recovery from failures that occur during processing, making your applications more robust. For example, by having more than one messaging servers, you protect your application from failure in case one of the servers becomes unavailable. If the IBM webMethods Integration connection with the server fails, IBM webMethods Integration automatically reconnects to another server provided in the list.

• Connection ClientID: JMS client identifier associated with the connections established by this account.

• JMS connection factory lookup name: Lookup name for the connection factory that you want to use to establish a connection with the Messaging provider specified in this JMS Connector Account.

• Security principal: Username that IBM webMethods Integration provides to the JNDI provider for accessing the JNDI directory.

• Security credentials: Password that IBM webMethods Integration provides to the JNDI provider for accessing the JNDI directory.

• Use SSL: Option to establish a secure communication between IBM webMethods Integration and the JNDI provider.

• Truststore Alias: Alias for the truststore that contains the certificates of the Certificate Authority (CA) for the JNDI provider.

• Keystore alias: Alias for the keystore that contains the client certificates for IBM webMethods Integration to use when connecting to the JNDI provider using two-way SSL.

• Key alias: Alias to the key that contains the private key for connecting to the JNDI provider using two-way SSL.

• Max retry attempts: Option to specify if the IBM webMethods Integration must retry to connect to the Messaging Provider when a transient error occurs, such as, connectivity loss with Messaging Provider.

• Retry interval: Duration (in seconds) that the publisher waits before retrying the publish action again.
  When you configure the Max retry attempts and Retry interval options, the publisher flow service or workflow does not end the publish action right away when a transient error occurs. IBM webMethods Integration retires to publish the message for the configured number of times based on the specified Retry interval. IBM webMethods Integration throws an exception if the error persists even after retrying.

• Cache JMS Sessions: Whether JMS sessions and related session objects created by the producer must be cached between publishing calls.
  When sending a message, IBM webMethods Integration creates and closes a new JMS session for each message. When a cached session pool is defined for a JMS account, IBM webMethods Integration draws from a pool of open JMS sessions for sending a message instead of opening and closing a session for each JMS message.
  You can specify the minimum and maximum sizes for the session pools as well as the idle time after which an idle session object can be removed from the pool.

• Create new connection per subscriber: Whether to create a new connection for each subscriber to receive messages in parallel using this account. Otherwise, all subscribers use the same connection. The number of connections a subscriber can make can be set in the Connection Count property under Message Processing in Subscriber settings.

Configuring JMS Connector Account - Universal Messaging in IBM webMethods Cloud Container

1. Go to Projects > Connectors. All predefined connectors are listed in the right pane.

2. Type JMS in the Search text box of the right pane. The matching connectors are listed.

   

3. Click JMS. The Add account wizard appears.

   

4. Enter the following details under General Settings:

   a. Name - Name of the account.

   b. Description - Short description about the account.

   c. Messaging provider template - Select IBM webMethods Cloud Container UM for using Universal Messaging in IBM webMethods Cloud Container solution as the messaging provider.

   Note

   To connect to Universal Messaging in IBM webMethods Cloud Container, you must enable the Allow External Access to Messaging option under Messaging Access Settings in IBM webMethods Cloud Container.

5. Click Next. The Connection Settings tab appears.

6. Enter the following details:

   a. Provider URL - Universal Messaging URL configured in IBM webMethods Cloud Container. The URL is defined in Access URL under Messaging Access Settings of the IBM webMethods Cloud Container solution.

   

   Note

   You must specify Two-way SSL URL if you want to enable two-way SSL communication under the Security Settings tab.

   b. Connection client ID - Value that is used as JMS client identifier for connecting to Universal Messaging in IBM webMethods Cloud Container.

   c. JMS connection factory lookup name - Lookup name for the connection factory that you want to use to create a connection to Universal Messaging specified in this account.

7. Click Next. The Security Settings tab appears.

8. Enter the following details:

   a. Security principal - IBM webMethods Cloud Container tenant username for accessing the JNDI directory.

   b. Security credentials - IBM webMethods Cloud Container tenant password for accessing the JNDI directory.

   Note

   If you want to enable two-way SSL communication, then follow the instructions mentioned in sub steps c, d, and e. Otherwise, ignore the sub steps and go to step 9.

   c. Use Two-Way SSL - Drag the switch to right to enable two-way SSL if you want to establish a two-way secure communication between IBM webMethods Integration and the Universal Messaging in IBM webMethods Cloud Container. By default, the option is disabled.

   Note

   To configure two-way SSL, you need the certificate details of IBM webMethods Cloud Container. It involves the following steps:
   i. Download the Keystore from IBM webMethods Cloud Container. For more information on how to generate client certificate, see the Adding Client Certificate section in the Settings topic of IBM webMethods Cloud Container help.
   ii. Upload the downloaded keystore to IBM webMethods Integration. For more information on how to upload certificates, see Certificates.

   d. Keystore alias - Select the uploaded keystore that contains the client certificates for IBM webMethods Integration to use when connecting to the Universal Messaging provider.

   e. Key alias – Select the alias for the key that contains the private key for connecting to the Universal Messaging provider.

9. Click Next. The Producer Settings tab appears.

10. Enter the following details:

    a. Max retry attempts – Number of times a publisher must retry to publish messages when transient errors are encountered. The default value is five. Setting it to zero indicates that the publisher does not retry to publish the message. You can specify a value in the range from 0 (zero) to 100.

    b. Retry interval (in seconds) – Duration that the publisher waits before retrying the publish action again. The default value is 10 seconds. You can specify a value in the range of 4 to 3600 (four seconds to one hour).

    c. Cache JMS sessions – Drag the switch to right to enable caching for JMS sessions. By default, the option is disabled. If you have enabled caching then follow the sub steps d, e, and f.

    d. Minimum session pool size - Minimum number of session objects in the session pool. The default value is One. Zero indicates that the caching is disabled.

    e. Maximum session sool size - Maximum number of session objects in the session pool. The default value is 30.

    f. Idle timeout (in seconds) - Duration after which IBM webMethods Integration removes an inactive session object. A value of zero indicates that pool entries never expire. The default value is 60 seconds.

11. Click Next. The Advanced Settings tab appears.

12. Enter the following details:

    a. Create new connection per subscriber – Drag the button to right to create a new connection for each subscriber. You can increase the number of connections a subscriber can make by setting the Connection Count property under Message Processing in Subscriber settings.

13. Click Save. The JMS account is configured and the IBM webMethods Integration and webMethods Cloud Container’s Universal Messaging systems can publish and receive messages.

Configuring JMS Connector Account - Self-hosted Universal Messaging

1. Go to Projects > Connectors. All predefined connectors are listed in the right pane.

2. Type JMS in the Search text box of the right pane. The matching connectors are listed.

   

3. Click JMS. The Add account wizard appears.

   

4. Enter the following details under General Settings:

   a. Name - Name of the account.

   b. Description - Short description about the account.

   c. Messaging provider template - Select Universal Messaging for connecting to a self-hosted Universal Messaging server which is publicly accessible.

5. Click Next. The Connection Settings tab appears.

6. Enter the following details:

   a. Provider URL - Universal Messaging realm URL that IBM webMethods Integration uses for looking up JMS objects (destinations and connection factories) in the JNDI directory.

   Note

   To connect to IBM Universal Messaging, provide Universal Messaging realm URL in one of the following formats:
   - nsp://UM_host:UM_port
   - nsps://UM_host:UM_port
   - nhp://UM_host:UM_port
   - nhps://UM_host:UM_port
   

   b. Clustered UM – Turn the switch to one of the following states:

   • Yes: If the realm specified in the Provider URL is part of a cluster setup. A minimum of two URLs is mandatory. Follow the instruction in sub step c and ignore sub step d.

   • No: If the realm specified in the Provider URL is not part of a cluster setup. Follow the instructions mentioned in sub step d that follows and ignore sub step c.

   c. Do the following steps if the realm specified in the Provider URL is part of a cluster setup:

   i. Click Add realm node to add more realm URL that are part of the cluster other than specified in the Provider URL.

   ii. Repeat the previous step to add remaining realm URLs. You must add all realm URLs belonging to the cluster.

   iii. Follow the master - This setting affects producer and consumer connections created using this account. Do one of the following:

   • Enabled - IBM webMethods Integration always connects to the master realm server in a cluster to send or receive messages. This is the default option.

   • Disabled – IBM webMethods Integration connects to one of the servers listed to send or receive messages. You can specify the server order in the Connection retry mode option.

   iv. Connection retry mode – Select one of the following values:

   • Retry sequentially - IBM webMethods Integration retries to establish connection with the servers in the order specified in the list.

   • Retry randomly - IBM webMethods Integration retries to establish connection at random to any of the specified servers.

   d. Do the following steps if the realm specified in the Provider URL is not part of a cluster setup:

   i. Click Add failover node to add a failover Universal Messaging URL that IBM webMethods Integration must connect to if the existing connection is lost.

   ii. Repeat the previous step to add multiple failover nodes.
   In case of a failover setup, all objects such as queues, topics, and connection factories must be present in all failover nodes. You cannot recover messages if connectivity fails.

   e. Connection client ID - Specify a value that is used as JMS client identifier for making connection with Universal Messaging.

   f. JMS connection factory lookup name - Lookup name for the connection factory that you want to use to establish a connection with the Universal Messaging provider specified in this account.

7. Click Next. The Security Settings tab appears.

8. Enter the following details:

   a. Security principal - Username for connecting to Universal Messaging to retrieve JNDI objects.

   b. Security credentials - Password for connecting to Universal Messaging to retrieve JNDI objects.

   c. Select the Same as JNDI credentials check box if the same username and password mentioned under JNDI authentication must be used for Universal Messaging authentication to publish and consume messages. Otherwise, provide the following details:

   • User - Username required for authenticating with Universal Messaging to publish or consume messages.

   • Password - Password required for authenticating with Universal Messaging to publish or consume messages.

   d. Use SSL – Drag the switch to right to enable a secure communication between IBM webMethods Integration and Universal Messaging. By default, the option is disabled.

   e. Specify the following details if you have enabled SSL in the previous sub step:

   • Truststore alias - Select the truststore that contains the certificate authority (CA) of the certificates for Universal Messaging.

   • Keystore alias - Select the keystore that contains the client certificates used by IBM webMethods Integration to connect with Universal Messaging.

   • Key alias - Select the alias for the key that contains the private key for connecting to Universal Messaging securely.

9. Click Next. The Producer Settings tab appears.

10. Enter the following details:

    a. Max retry attempts – Number of times a publisher must retry to publish messages when transient errors are encountered. The default value is five. Setting it to zero indicates that the publisher does not retry to publish the message. You can specify a value in the range from 0 (zero) to 100.

    b. Retry interval (in seconds) – Duration that the publisher waits before retrying the publish action again. The default value is 10 seconds. You can specify a value in the range of 4 to 3600 (four seconds to one hour).

    c. Cache JMS sessions – Drag the switch to right to enable caching for JMS sessions. By default, the option is disabled. If you have enabled caching then follow the sub steps d, e, and f.

    d. Minimum session pool size - Minimum number of session objects in the session pool. The default value is One. Zero indicates that the caching is disabled.

    e. Maximum session sool size - Maximum number of session objects in the session pool. The default value is 30.

    f. Idle timeout (in seconds) - Duration after which IBM webMethods Integration removes an inactive session object. A value of zero indicates that pool entries never expire. The default value is 60 seconds.

11. Click Next. The Advanced Settings tab appears.

12. Enter the following details:

    a. Create new connection per subscriber – Drag the button to right to create a new connection for each subscriber. You can increase the number of connections a subscriber can make by setting the Connection Count property under Message Processing in Subscriber settings.

13. Click Save. The JMS connector account is configured and the IBM webMethods Integration and Self-hosted Universal Messaging systems can publish and receive messages.

Enabling and Disabling JMS Accounts

You can either enable or disable the accounts from the Connectors page. For more information on how to enable and disable JMS accounts, see Enabling invalid/disabled accounts and Disabling Accounts.

If you have disabled the JMS account, then IBM webMethods Integration suspends all subscribers that use this account. For more information on subscriber state management, see Subscriber State Management. Additionally, any flow services or workflows that use a disabled account to publish messages fails.

Publish and Subscribe Messages Using External Messaging Provider - JMS Connector

Summary

To publish and subscribe messages using the JMS connector.

1. Create Publisher - Create a flow service, say publish_flowservice, to publish the messages to topic, JMSTopic.

2. Create Subscriber - Create a subscriber, say JMSsubscriber, which subscribes to JMSTopic and runs a flow service, JMSTopic_consumer_flowService , to consume the messages.

3. Publish Messages - Run the publisher and view the consumer flow service execution logs.

Basic Flow

Prerequisites

• Access to Universal Messaging.

• Universal Messaging must have connection factory in the JNDI context.

• If you want to use Two-Way SSL, then the appropriate client certificate generated from IBM webMethods Cloud Container must be uploaded in IBM webMethods Integration under Configurations > Certificates.
  For more information about client certificate, see Two-Way SSL and Messaging in IBM webMethods Cloud Container documentation.

Create Publisher

1. Click Integrations > Flow services. The Flow services page appears.

2. Click . The Start creating the Flow service page appears.

3. Enter the flow service name as publisher_flowservice.

4. [Optional] Enter a short description of the flow service under Flow service name.

5. Type JMS in flow service step1 and select JMS from the list that appears. The fields associated with the JMS connector appears.

6. Select the following options:

   1. Action - send

   2. Account - account that must be used to connect to the JMS connector. You can configure a new account if an account is not available. For more information, see Configuring JMS Connector Account.

   

7. Click to map the input and output fields. The Pipeline panel appears.

8. Double-click destinationName to specify the destination to which the messages must be published. The Set Value - destinationName dialog box appears.

9. Enter the name of the destination. For example, JMSTopic.

   

10. Double-click on the string field. The Set Value - string page appears.

11. Enter the message I want to publish a message!

    

12. Click Save. The Pipeline panel appears.

13. Close the Pipeline panel. The Flow service page appears.

14. Click Save. The flow service details are saved.

Create Subscriber

You can create the consumer flow service in one of the following ways:

• Directly from the Flow services page.

• Create the flow service when creating a subscriber. The subscriber listens to messages that the topic receives. If the topic receives messages, then the consumer flow service in the subscriber runs automatically.

Here, the steps are explained to create the JMSTopic_consumer_flowService using Messaging.

1. Go to Events > Messaging.

2. Click Add new subscriber. The New subscriber page appears.

3. Enter the following details:

   1. Subscriber Name - JMSSubscriber

   2. Description - Subscribes for messages published to JMSTopic

   3. Connector Type - JMS

   4. Account - Account that must be used to connect to JMS provider

   5. Destination type- Topic

   6. Select destination- JMSTopic

4. Perform the following to set the Default invocation:

   1. Invocation type - Flow service

   2. Select invocation :

      1. Click . The New Flow service page appears.

      2. Enter the name as JMSTopic_consumer_flowservice.

         

      3. Click Save.

5. Click Save. The JMSSubscriber is created with the JMSTopic_consumer_flowService that consumes messages arriving in JMSTopic.

Publish Messages

1. Open the publisher_flowservice.

2. Click . If the publisher_flowservice runs successfully, the JMSTopic_consumer_flowService runs automatically. The publisher_flowservice sends the message to the topic JMSTopic and as the JMSSubscriber is listening to topic, it runs the JMSTopic_consumer_flowService created in the JMSSubscriber.

3. To verify if the consumer Flow service ran:

   1. Go to Monitor > Execution results > Flow service execution. The Flow service execution statistics appear.

   2. Go to the Executions section. You can observe that the Execution source column for the:

      • JMSTopic_consumer_flowService is Messaging Subscriber.

      • publisher_flowService is User Interface.

      

In this way, you can publish and subscribe messages using the JMS connector.