All of the IB definitions must be defined and configured using PeopleSoft's powerful PeopleTools Development Environment. Portions of PeopleTools are accessible via the PeopleSoft Internet screens (dubbed "PIA screens"), while other portions can only be accessed via the separate Application Designer client program. Gateway, node, transaction, and relationship definitions must be defined and configured via the PIA screens, while messages, message channels, and any custom PeopleSoft programs (written in a language called PeopleCode) must be created and maintained via the Application Designer.

An Example: Integration via JMS
The following example will reinforce the concepts presented above. In this example, an integration scenario between WebLogic Server 7.0 hosted components and a single local PeopleSoft 8.4 instance using JMS will be explored.

One of the first steps in implementing an IB integration is to define the messages that will be exchanged between the participating systems. Two messages will be defined: one for messages emanating from WLS 7.0 to PeopleSoft, and another for messages traveling back. For the sake of simplicity, this example will use nonrowset messages with XML content.

Since any given message must belong to an existing message channel, the channel must be created first. After the message channel has been created, its configuration properties can be browsed. Figure 3 is an example of a message channel configuration dialog displayed in the Application Designer.

The JKK_TX_MESSAGE_CHANNEL channel dialog displays the list of messages associated with the channel. In this example, the JKK_TX_REQUEST_MESSAGE and JKK_TX_RESPONSE_MESSAGE definitions represent the application data messages exchanged between WLS 7.0 and PeopleSoft. Typically, structured rowset messages will be defined in the Application Designer, along with a record-based content schema. However, for this simplified example, the message definitions are simply monikers acting as proxies for the unstructured content they represent.

In this example, synchronous messaging will be used for both inbound and outbound traffic. Once messages arrive in PeopleSoft, they will be written to a disk file before an empty response message is created and then returned to the WLS-hosted caller. After this, the original message will be routed back to WLS (over JMS) via a feedback loop.

In order to accomplish this, you must first write a PeopleCode request handler and attach it to the JKK_TX_REQUEST_MESSAGE definition in the Application Designer. As in other development environments, such as Visual Basic, PeopleCode message objects can respond to various events. A message's OnRequest event can specify a custom PeopleCode routine to handle the synchronous arrival of the message. The PeopleCode routine can perform the appropriate actions before creating and returning a status message.

The PeopleCode request handler for the inbound JKK_TX_REQUEST_MESSAGE is shown in Listing 1(listings for this article can be found at www.sys.con.com/weblogic/sourcec. cfm). As illustrated, the first programmatic instruction uses the special IB function, getMessageXmlDoc(), to retrieve the incoming XML message. After this, the message contents are converted into an XML string before being appended to a file named IncomingRequests.log. Finally, CreateMessage and ReturnToServer are special functions used to generate and then return an empty status message through IB back to the caller.

The next major step is to define and configure the necessary integration nodes, transactions, and relationships using the PeopleTools PIA screens.

Two nodes, JKK_SOURCENODE and JKK_TARGETNODE, will be created to represent the WLS instance participating in the integration. This instance will be the ultimate receiver of the messages it originally transmitted. The JKK_SOURCENODE definition is fairly straightforward. However, the JKK_TARGETNODE node definition is more involved because it must ultimately transmit messages to an external destination (the WLS instance) via JMS. Figure 4 provides a look at the target connector information attached to JKK_TARGETNODE. Although there are several properties associated with the connector, we will focus on only the most important ones: JMSUserName, JMSPassword, JMSUrl, JMSTopic, and JMSFactory.

JMSUrl specifies the host and listening port of the target JMS server. In this case, the server is WLS 7.0-based and resides at http://wls01:7001. JMSUserName and JMSPassword are valid user ID/password combinations on the target WLS 7.0 instance. JMSFactory and JMSTopic reference the factory and topic defined within the target JMS server's config.xml file. A JMS listener or message-driven bean (MDB) listening to the same combination of JMSFactory, JMSTopic, and JMSServer will rendezvous with the IB and receive any messages transmitted by the broker via JKK_TARGETNODE.

The next step is to define the necessary inbound and outbound transactions and associated relationships. IB transaction mappings must be made from the perspective of the PeopleSoft instance's default local node. Hence, an inSync transaction conveying JKK_TX_REQUEST_MESSAGE and returning JKK_TX_RESPONSE_MESSAGE must be defined at JKK_SOURCENODE, while an outSync transaction with identical message characteristics must be defined at JKK_TARGETNODE.

In addition, a relationship, shown in Figure 5, will be created to tether the two nodes together so inbound message traffic is routed to the target node and ultimately back to the WLS instance via the JMS target connector. Relationships, like many PeopleSoft objects, can be activated or deactivated, and can even become applicable upon a given effective date. All of this provides considerable flexibility, as multiple relationships can be defined across a set of node and date combinations.

In addition, relationships can be used to reconcile differences in the data formats exchanged between a combination of source and target nodes. For example, the data emanating from JKK_SOURCENODE may need to be transformed, translated, or even filtered en route to JKK_TARGETODE. A relationship can perform these data manipulations using PeopleSoft batch programs called application engine programs. These programs can use a combination of PeopleCode, Extensible Stylesheet Language Transforms (XSLT), or SQL actions to perform the required data manipulations between a given combination of nodes. Such programs would be specified in the Transformations section of Figure 5.

The next step is to configure the Integration Gateway to use the appropriate inbound JMS topics and queues. This configuration information is stored in the integrationGateway.properties text file, which is located under the Integration Gateway subdirectory of the installation tree. The gateway can listen to any combination of JMS topics and queues, and can use different JMS providers. For this example, the WebLogic JMS provider will be used, along with a single inbound JMS topic and a special gateway error topic. The gateway will publish processing errors to this topic, in addition to writing the errors to a cumulative error log file. This design would accommodate a custom error topic subscriber that could handle gateway errors programmatically.

Listing 2 shows the portions of an integrationGateway.properties file relevant to the integration example. The ig.isc.serverURL, ig.isc.userid, ig.isc.password, and ig.isc.toolsRel properties specify the Jolt address, along with a valid user ID/password combination for the target application server. These properties effectively connect the gateway, which resides on the Web server, to the appropriate application server. Messages that enter the gateway will, under normal conditions, be routed to the target application server for processing by PeopleCode message subscriptions and OnRequest handler programs.

The ig.jms.JMSProvider.JNDIFactory.WebLogic property setting instructs the gateway to use WebLogic as the JMS provider. Next, the ig.jms.Topics, and ig.jms.Topic1 lines define the total number of JMS listening topics and specific topic connection information, respectively. The subsequent ig.jms.ErrorTopic lines specify the JMS error topic to which gateway errors should be published. The JMS connection properties shown in Listing 2 will cause the gateway to rendezvous with topic publishers and subscribers on the WLS instance server.

The final step of this example is to create the actual JMS topic publishers and subscribers that will rendezvous with the gateway via the topics defined in the integrationGateway.properties file. Specifically, a JMS subscriber will be needed to cover both the error topic and the PostingStatusMessage topic specified in the JMS target connector. These JMS subscribers can be standard JMS message listeners or even MDBs. A standard JMS topic publisher can be used to send JMS TextMessage instances into the gateway.

Listing 3 shows three message properties that must be set prior to publishing JMS TextMessage instances to the gateway. The first property, MessageName, specifies the message associated with the textual message being published. The DestinationNodes property specifies the default local node for the target PeopleSoft system. Finally, the RequestingNode indicates the IB node sending the published messages. Since the MessageName and RequestingNode shown in the listing match the inSync transaction previously defined at JKK_SOURCENODE, the broker will accept and route the published messages to the JKK_TARGETNODE node.

Conclusion
The concepts, definitions, and procedures outlined in this article enable J2EE and PeopleSoft 8.4 applications to be seamlessly integrated using JMS. The benefits of taking this approach are clear: standards-based protocols and data (e.g., JMS and XML), transactional integrity, assured message delivery (both within PeopleSoft IB and WebLogic JMS), and high scalability using a combination of mechanisms such as message channels and pools of MBDs. Another benefit is that it can be used to integrate J2EE with any PeopleSoft 8.4-based product, including Financials, HRMS, SCM, and CRM.

It's important to remember that this article provides an outline, not an exhaustive treatment of this topic. Important issues such as security have not been discussed. Others, such as transaction management, are only implied by virtue of using JMS, but have not been covered. Both J2EE and PeopleSoft's Integration Broker are vast, complex technologies that cannot be covered in any appreciable detail within the constraints of this article. However, this outline can become the first step in the journey toward mastery of these technologies. The next article in this series will explore the integration of J2EE and PeopleSoft 8.4 applications using Web services.