External Messaging Providers

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

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

• Message - 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.
    • Correlational - A unique identifier used to link messages together.
    • Nondelivery - Delivery mode used to send the message.
      Note: When sending a message, this value is obtained from the JMSMessage/header/deliveryMode input parameter.
    • Predestination - 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.
    • Timestamp - Time at which the message was given to the JMS provider.
    • JMistype - 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.
   1. Name - Name of the account.
   2. Description - Short description about the account.
   3. 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:
   1. 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.
   2. Connection client ID - Value that is used as JMS client identifier for connecting to Universal Messaging in IBM webMethods Cloud Container.
   3. 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:
   1. Security principal - IBM webMethods Cloud Container tenant username for accessing the JNDI directory.
   2. 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.
   3. 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.
   4. Keystore alias - Select the uploaded keystore that contains the client certificates for IBM webMethods Integration to use when connecting to the Universal Messaging provider.
   5. 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:
    1. 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.
    2. 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).
    3. 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.
    4. 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.
    5. Maximum session sool size - Maximum number of session objects in the session pool. The default value is 30.
    6. 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:
    1. 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 Accounts - 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.
   1. Name - Name of the account.
   2. Description - Short description about the account.
   3. 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:
   1. 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
   2. Clustered UM – Turn the switch to one of the following states:
      • Yes - If the realm specified in 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.
   3. Do the following steps if the realm specified in the Provider URL is part of a cluster setup:
      1. Click Add realm node to add more realm URL that are part of the cluster other than specified in the Provider URL.
      2. Repeat the previous step to add remaining realm URLs. You must add all realm URLs belonging to the cluster.
      3. Follow the master - This setting affects producer and consumer connections created using this account. Do one of the following:

         Option	Description
         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.

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

         Option	Description
         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.

   4. Do the following steps if the realm specified in the Provider URL is not part of a cluster setup:
      1. Click Add failover node to add a failover Universal Messaging URL that IBM webMethods Integration must connect to if the existing connection is lost.
      2. 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.

   5. Connection client ID - Specify a value that is used as JMS client identifier for making connection with Universal Messaging.
   6. 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:
   1. Security principal - Username for connecting to Universal Messaging to retrieve JNDI objects.
   2. Security credentials - Password for connecting to Universal Messaging to retrieve JNDI objects.
   3. 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.
   4. 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.
   5. 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:
    1. 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.
    2. 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).
    3. 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.
    4. 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.
    5. Maximum session sool size - Maximum number of session objects in the session pool. The default value is 30.
    6. 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:
    1. 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. See Subscriber State Management in For more information on subscriber state management, see Subscribers. Additionally, any flow services or workflows that use a disabled account to publish messages fails.