Working With the JMS Connectors

Supported JMS Providers

To use the JMS connectors, you must add specific Java archive (JAR) files to the Java CLASSPATH. The JAR files that you add to the CLASSPATH depend on the JMS provider with which you're communicating. The following JMS providers are supported:

You can also add generic JMS providers for use with PeopleSoft Integration Broker.

See Adding Generic JMS Providers.

Integrations with Oracle SOA B2B Suite

The JMS target connector and JMS listening connector feature properties that enable you to integrate with Oracle SOA B2B Suite.

The Oracle SOA-B2B server supports several industry-standard e-commerce protocols as well as several transports for message delivery.

See Oracle B2B Documentation

PeopleSoft's integration to the Oracle SOA B2B Suite uses the JMS transport to deliver and receive messages, and as such the JMS target connector and JMS listening connector are used.

For outbound integrations with Oracle SOA B2B you set JMS target connector properties at the node-level. For inbound integrations with Oracle SOA B2B you set JMS listening connector properties in the integration gateway properties file. Setting these properties is discussed elsewhere in this section.

See Using the JMS Target Connector, Using the JMS Listening Connector

Receiving Messages

The JMS listening connector retrieves topics and queues that you have defined in integrationGateway.properties file. For each topic it starts a topic subscriber, and for each queue it starts a queue listener. When a message arrives either for a queue or topic, the JMS listening connector sends the message to the integration engine.

A parameter called ExternalMessageID is used to ensure that messages are received only once. When the JMS listening connector receives a message, it sets an external message ID in IBInfo and sends this information to the PeopleSoft Integration Broker with the message content. If the external message ID exists in IBInfo, the application server checks for duplicate messages. If a duplicate is found, an error is generated. The external message ID is optional. If specified, it must be unique and not exceed 70 characters.

Securing Messages to JMS Queues

PeopleSoft Integration Broker does not perform security validation checks on messages transmitted to JMS queues.

Error Handling

If an error occurs during message processing, the JMS listening connector publishes the message back to either an error topic or an error queue. All error messages feature a header called ErrorDescription which contains a description of the error.

To capture errors you must set error topic or error queue properties in the JMS Configuration Section of the integrationGateway.properties file. These properties are discussed later in this section. If both an error topic and an error queue are set up and configured, only the error queue will capture error messages.

JMS Queue Listener Properties

You can configure multiple queues in the section of the integrationGateway.properties file labeled JMS Configuration Section. To configure multiple queues, use the convention, ig.queue1, ig.queue2, ig.queue3, and so on.

JMS Topic Subscriber Properties

You can configure multiple topics, in the section of the integrationGateway.properties file labeled JMS configuration Section. To configure multiple topics, use the convention ig.topic1, ig.topic2, ig.topic3, and so on.

Error Queue Properties

To capture JMS listening connector errors in an error queue, set the following properties in the JMS Configuration Section of the integrationGateway.properties file.

Error Topic Properties

To capture JMS listening connector errors in an error topic, set the following properties in the JMS Configuration Section of the integrationGateway.properties file.

JMS Listening Connector Properties for Integrating with Oracle SOA B2B Suite

For inbound integrations from Oracle SOA B2B Suite, you must set the following property in the integrationGateway.properties file:

ig.AS2.<FROM_PARTY>.<TO_PARTY>.MessageName=

Set the values as follows:

• FROM_PARTY. Enter the sending node name.

• TO_PARTY. Enter the receiving node name.

• MessageName. Set this property equal to the message.version of the message.

For example:

ig.AS2.SOA_B2B.QE_LOCAL.MessageName=USER_PROFILE.VERSION1

In the example, SOA_B2B is the sending node, QE_LOCAL is the receiving node, and USER_PROFILE.VERSION1 is the message.version.

Information about setting properties for the JMS target connector for outbound integrations to Oracle SOA B2B is provided elsewhere in this section.

JMS Message Header Properties

For the JMS listening connector to process messages, you must set the following properties. You can set these properties in JMS message headers, the integrationGateway.properties file or in the body of the XML message.

You can specify JMS headers in the integrationGateway.properties file for both queues and topics. However you must be using separate queues or topics per requesting node/message combination.

You must supply the properties listed in the following table in the JMS message header when you publish messages from a JMS provider system to the integration gateway.

The following example shows specifying JMS header properties in the body of an XML message.

<?xml version="1.0" ?>
   <IBRequest>
      <ExternalOperationName>JMS_MessageName</ExternalOperationName>
      <OperationType>Async_or_Synch</OperationType>
         <From>
            <RequestingNode>JMS_RequestingNode</RequestingNode>
            <Password>JMS_NodePassword</Password>
            <OrigUser></OrigUser>
            <OrigNode></OrigNode>
            <OrigProcess></OrigProcess>
            <OrigTimeStamp></OrigTimeStamp >
         </From>
         <To>
            <FinalDestination>JMS_FinalDestination</FinalDestination>
            <DestinationNode>JMS_DestinationNode</DestinationNode>
         </To>
         <ContentSections>
            <ContentSection>
               <NonRepudiation></NonRepudiation>
                <Data></Data>
            </ContentSection>
        </ContentSections>
   </IBRequest>

When the message received specifies synchronous mode, a reference to the temporary queue or topic must be set in the JMS message header for the JMS listening connector to determination the destination of the message response. The JMS listening connector also sets the JMS correlation ID when it sends the response so the requestor can properly associate the response with its corresponding request.

If any of the message header properties are missing, an error is logged and an error is published to an error topic or error queue. The message that the connector publishes to the error topic has a property call error and is set to True. The error message that is published contains the following information: default message, message ID, message set, message parameters, and body of the message sent.

Starting and Shutting Down the JMS Listening Connector

Use the JMS Listening Connector Administration page to start or shut down the JMS listening connector.

See Administering JMS Listening Connectors

Performing Administrative Tasks on JMS Listening Connectors

The JMS Listening Connector Administration page enables you to perform administrative tasks on JMS listener queues and subscriber topics, such as start, stop, and pause queues and topics. Using the JMS Listening Connector Administration page to administer JMS listening connectors is discussed elsewhere in the product documentation.

See Administering JMS Listening Connectors

Asynchronous and Synchronous Communication

The JMS target connector provides both synchronous and asynchronous modes of communication. When the node level property ReplyTo is set to False, communication is asynchronous. When it is set to True, communication is synchronous.

For asynchronous communication, the JMS target connector publishes messages to MOM or drops messages into a queue and commits the session. It does not wait for a response from the destination system. For synchronous communication, after the connector publishes messages or drops them into a queue, it waits for the temporary topic or queue to respond.

For synchronous communication, the exchanges involve only the publisher and a single subscriber. When a JMS-compliant remote node receives a synchronous request message from PeopleSoft, it must use the value of the JMSCorrelationID of the request message to populate the correlation ID of its response message. When the response is received by the PeopleSoft JMS target connector, it compares the JMSCorrelationID of the response message with the JMSCorrelationID of the request. The message is not accepted if these two IDs do not match.

When sending messages either synchronously or asynchronously, the connector sets different string properties in the JMS message header. The properties are used as metadata about the message. The JMS target connector also sets a reference to the temporary queue or topic from which it requires the response.

JMS Target Connector and Message Segments

The JMS target connect is segment-aware and you may use it to send message segments to integration partners.

See Working With Message Segments.

IBInfo Data Contained in JMS Headers

A message has two parts—the transaction data and the IBInfo header that is the routing envelope used by PeopleSoft Integration Broker. In the event that a receiving system wants to make use of the IBInfo data, IBInfo header information is included when publishing messages to non-PeopleSoft systems when using the JMS target connector or the HTTP target connector.

When using the JMS target connector to send messages to non-PeopleSoft systems, the following IBInfo data is contained in the JMS headers. The content of the message (message body) is not impacted.

• RequestingNode

• FinalDestinationNode

• DestinationNodes

• MessageName

• MessageType

• OrigTimeStamp

• NonRepudiation

Gateway-Level Connector Properties

There are no gateway-level JMS target connector properties that you must set.

Node-Level Connector Properties

You must set either a JMS queue or JMS topic for a given node definition. If both are set or are missing the PeopleSoft Integration Broker generates an invalid message exception.

JMS message types can be Text, Map Message, Stream, or Object. However, PeopleSoft provides only text messages. If you need to use other message types, you can write a class that implements the com.peoplesoft.pt.integrationgateway.common.jms.ProcessJMSMessage interface, and you set the class name as a value for JMSMessageTypeClass.

The provider name that you specify for the JMSProvider in the node definition must match the JMSProvider.JNDIFactory property that you specify in the integrationGateway.properties file.

The following table describes the node-level connector properties:

JMS Target Connector Properties for Integrations with Oracle SOA B2B

The following table lists node-level properties that you must set for the JMS target connector for outbound integrations with Oracle SOA B2B.

Set these properties on the Nodes – Connector page. To access the page select PeopleTools > Integration Broker > Integration Setup > Node Definitions and click the Connectors tab.

For all properties except for AS2MODE, you must add a new row to the properties grid and manually enter property ID, property name, and property values.

Information about setting properties for the JMS listening connector for inbound integrations from Oracle SOA B2B is provided earlier in this topic.

Additional Setup Steps

Before using the JMS target connector, verify that:

1. The JMS messaging system is running.

2. All JMS connection factories, topics, and queues are registered for JNDI lookup.

3. A username and a password are created in the JMS system for use as values for the properties JMSUserName and JMSPassword.

JMS Target Connector Errors and Exceptions

The JMS target connector may generate the following exceptions:

Configuring the JMS Listening Connector for Generic JMS Providers

To configure the JMS listening connector for a generic JMS provider:

• Obtain the following information from the provider:

  • JMS jar file.

  • JNDIFactory information

• Determine if messaging will be in topics or queues.

• Determine if error handling will be in topics or queues.

• Update JMS properties in the integrationGateway.properties file:

  • Update the JNDIFactory entry.

    For example if the provider were Tibco the entry might be:

     ig.jms.JMSProvider.JNDIFactory.Tibco=com.tibco.JMSFactory

  • Populate the appropriate messaging topic and queue entries based on how messaging will be handled.

  • Populate the appropriate error topic and queue entries based on how messaging will be handled.

In addition to the information provided in this section, review the JMS Headers Properties section of this topic which discusses the required information that must be in the headers of each message processed by the JMS listening connector.

Configuring the JMS Target Connector for Generic JMS Providers

To configure the JMS target connector for a generic JMS provider:

• Define a node for the provider.

• Assign the JMS target connector to the provider node and specify the target connector properties.