PeopleTools 8.52: PeopleSoft Integration Broker Administration

Appendix: Using the Integration Broker Connector SDK

This appendix provides an overview of the PeopleSoft Integration Broker connector software development kit (SDK) and discusses how to:

Develop target connector classes.
Develop listening connector classes.
Install connector classes.
Register connectors.

Understanding the PeopleSoft Integration Broker Connector SDK

This section discusses:

The PeopleSoft Integration Broker Connector SDK.
SDK contents.
SDK location.
SDK connector example.

The PeopleSoft Integration Broker Connector SDK

Target connectors generate message requests, send them to integration participants, wait for responses from participants, and deliver the responses back to the gateway manager. Listening connectors receive message requests from integration participants, send them to the gateway manager, and deliver responses back to the integration participants.

PeopleSoft Integration Broker is bundled with connectors for use with PeopleSoft, HTTP, Java Messaging Service (JMS), PeopleSoft 8.1x, File Transfer Protocol (FTP), and Simple Mail Transfer Protocol (SMTP) communication formats. You can use the PeopleSoft Integration Broker Connector SDK to build and implement connectors for other communication formats and application requirements.

SDK Contents

The PeopleSoft Integration Broker Connector SDK includes:

Java classes that are required for creating connectors (including IBResponse and IBRequest objects).
Sample code for listening and target connector classes.
A Send Master utility to test connectors.
A Simple Post utility that enables third-party systems to post messages to the integration gateway.

SDK Location

The following table lists the location of the SDK and its contents.

Item	Location
SDK	<PIA_HOME>\webserv\<DOMAIN>\applications\ peoplesoft\PSIGW.war\SDK
Java classes	<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\ PSIGW.war\WEB-INF\classes
Sample code for listening and target connector classes	<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\ PSIGW.war\SDK\src
Send Master utility	Microsoft Windows: <PIA_HOME>\webserv\<DOMAIN>\piabin\StartSendMaster.bat UNIX: <PIA_HOME>\webserv\<DOMAIN>\piabin\StartSendMaster.sh
Simple Post utility	<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\ PSIGW.war\WEB-INF\classes\com\peoplesoft \pt\simplepost

SDK Connector Examples

Four sample connectors are provided as part of the SDK:

ExampleListeningConnector.java
ExampleServletListeningConnector.java
ExampleTargetConnector.java
SimpleFileTargetConnector.java

These connectors can be used as the basis for new development.

The ExampleListeningConnector and the ExampleServletListeningConnector highlight the differences between a minimalist listening connector and one intended to be run as a servlet.

The ExampleTargetConnector shows the basic requirements of a working target connector.

The SimpleFileTargetConnector is an example of a target connector written to perform a specific task: write outgoing message data to the file system.

To compile these connectors you must set the Java classpath to include the Integration Broker classes in:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEBINF\classes

and

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEBINF\lib\mail.jar

The Java class path must also be set to include the runtime Jar file for the installed web server, for example:

weblogic.jar for a WebLogic installation

Understanding the Code Examples in this Appendix

This appendix features pseudocode examples to help illustrate using the PeopleSoft Integration Broker SDK. The code examples are for illustrative purposes only and are not intended to be used in a production environment.

Understanding Connector Development and Implementation

This section discusses connector development and implementation.

Understanding Developing Connectors

You can produce new connectors in different ways, based on whether you want to create a listening connector or a target connector.

Listening connectors use standard connector interface and gateway services to link to the integration gateway. Although a Java interface object is not used for listening connectors, the listening connectors still must adhere to a standard scheme of logic to drive requests to, and to process responses from, the integration gateway.

Target connectors must implement a Java interface to become valid target connectors in the integration gateway. This ensures a standard interface for the gateway manager so that it can manage each target connector in a streamlined way.

To develop connectors, you:

Develop a connector class.
Install the connector class.
Register the connector.

Understanding General Connector Class Development Considerations

While implementations vary greatly, when you develop connector classes, you should incorporate specific functionality.

Input and Output Formats That Are Exchanged Through Connectors

For a target connector to handle input and output formats that are exchanged with its intended recipient, it must transform the PeopleSoft Integration Broker request (IBRequest) into a message that is formatted for the intended external system.

For instance, the HTTP target connector that is delivered with PeopleSoft Integration Broker gathers HTTP headers and cookies from the IBRequest and formulates the appropriate HTTP message, complete with the actual message content, so that it can be delivered to its destination. When the response comes back, the connector creates a PeopleSoft Integration Broker response (IBResponse) by using the response string.

For a listening connector to handle input and output formats that are exchanged with its requestor, it must transform the incoming message into an IBRequest. For example, the HTTP listening connector that is delivered with PeopleSoft Integration Broker recognizes SOAP messages and retrieves query string arguments, HTTP headers, and cookies. It then formats all of this information to create the IBRequest so that PeopleSoft Integration Broker can converse with it. When the response comes back, the HTTP listening connector reads the IBResponse and sends its output message content back to the requesting system.

Interaction Between Local and External Systems

A target connector interacts with an external system by sending it information and by retrieving the response.

For example, to accomplish this interaction, the HTTP target connector that is delivered with PeopleSoft Integration Broker uses various HTTP-specific classes to send messages through HTTP and to handle the external system being down, security (through HTTPS), and so forth.

A listening connector interacts with an external system by receiving requests from the external system and returning responses that the external system understands. For example, to accomplish this interaction, the HTTP listening connector that is delivered with PeopleSoft Integration Broker uses a servlet to receive and reply to incoming HTTP messages.

Developing Target Connector Classes

This section discusses target connector class development and discusses how to:

Use the target connector interface.
Build introspection into target connectors.
Build error handling and logging into target connectors.

Using the Target Connector Interface

As with PeopleSoft-provided target connectors, the integration gateway dynamically invokes custom target connectors through the gateway manager. Target connectors must adhere to a standard structure as defined in the target connector interface.

public interface TargetConnector {
   IBResponse send(IBRequest request) throws 
                     GeneralFrameworkException, 
                     DuplicateMessageException, 
                     InvalidMessageException, 
                     ExternalSystemContactException, 
                     ExternalApplicationException, 
                     MessageMarshallingException, 
                     MessageUnmarshallingException;

   IBResponse ping(IBRequest request) throws
                     GeneralFrameworkException, 
                     DuplicateMessageException, 
                     InvalidMessageException, 
                     ExternalSystemContactException, 
                     ExternalApplicationException, 
                     MessageMarshallingException, 
                     MessageUnmarshallingException;

ConnectorDataCollection introspectConnector();

Use the Send method to send a request to an external system and to retrieve its response. The gateway manager passes the request to this method and expects a response to be returned.

The Ping method enables PeopleSoft Integration Broker to verify the availability of a site. The Integration Broker Monitor can also invoke the Ping method explicitly.

The following diagram shows how the Send method connector code generates and sends message requests to integration participants and returns responses:

Message send scenario

The following diagram shows how the Ping method connector code pings external systems.

Ping scenario

ConnectorDataCollection invokes introspection and the introspectConnector method is used by the application server to discover the connector properties that are used with the given target connector.

Building Introspection into Target Connectors

PeopleSoft Integration Broker can introspect (query) the capabilities of target connectors that are installed on a local or remote integration gateway by using introspection. Load all target connectors that are delivered with PeopleSoft Integration Broker by clicking the Load button on the Connectors page in the Gateways component.

You can build introspection into custom-built connectors. When you do so, you can load the connector and its properties with the click of a button.

For the introspection process to gather information about a custom target connector, you must implement the IntrospectConnector method.

The following example shows the connector properties that are available for use with the SMTP target connector:

public ConnectorDataCollection introspectConnector() {
   //Creates the ConnectorDataCollection that will be returned 
   //by this method. This object will contain all the 
   //necessary information about this Connector's properties.

      ConnectorDataCollection conCollection = new ConnectorDataCollection();

      //Create ConnectorData Object and stipulating the name of 
      //the connector as seen from the Gateway Component.

      ConnectorData conData = new ConnectorData("SMTPTARGET");

      conData.addConnectorField("DestEmailAddress", true, "", "");
      conData.addConnectorField("SourceEmailAddress", true, "", "");
      conData.addConnectorField("CC", false, "", "");
      conData.addConnectorField("BCC", false, "", "");
      conData.addConnectorField("HEADER", Content-type”, false, 
         "", "text/plain|text/html");
      conData.addConnectorField("HEADER","sendUncompressed",true,
         "Y","Y|N");

      //Add the ConnectorData to your ConnectorDataCollection 
      //Object. Typically, you would only
      //add one ConnectorData into your ConnectorDataCollection.
      conCollection.addConnectorData(conData);

   return conCollection;
}

Use the addConnectorField method to add connector fields:

addConnectorField ([PropertyID] PropertyName, 
Required, DefaultValue, PossibleValues)

Use the following parameters for this method:

Parameter	Description
Property ID	Identifies different property types, such as HEADER for HTTP or SMTP. PeopleSoft software also uses the HEADER property ID to allow a message to be sent in either compressed or clear format through the sendUncompressed property. If this parameter is not supplied, the property ID is the connector name.
Property Name	Identifies the name of the connector property.
Required	Determines whether the information is required for the target connector to deliver its message. Values are: Y: True N:False
Default Value	Identifies the default value for the property. Typically, you set the Required parameter to True when you specify a default value so that this information carries to the node configuration in the integration engine.
Possible Values	Identifies a list of the possible values that the property can take, separated by the \| character.

The following definition shows how these properties function:

conData.addConnectorField("HEADER","sendUncompressed",true,"Y, "Y|N");

In this case, the property name is sendUncompressed and its property ID is HEADER. The sendUncompressed property is required (the third parameter is set to true), so that whenever you create a node in the node definition component and specify SMTPTARGET as the target connector, this property appears on the page automatically. Further, because the default value is set to Y, this is the default value. Possible values have been identified as Y or N. If you click the list box (search box) for this property on the Connectors tab in the Node Definition component, you can select from those two values.

The following diagram shows how connector code accomplishes introspection.

Introspection scenario

Building Error Handling and Logging into Target Connectors

The following code example demonstrates how to build error handling and logging into target connectors:

package com.peoplesoft.pt.integrationgateway.targetconnector;

import ...

public class SampleTargetConnector implements TargetConnector {
         public IBResponse ping(IBRequest request)

         public IBResponse send(IBRequest request)throws 
                     GeneralFrameworkException,
                     InvalidMessageException,
                     ExternalSystemContactException,
                     ExternalApplicationException,
                     MessageMarshallingException,
                     MessageUnmarshallingException,
                     DuplicateMessageException  {

      PSHttp httpObj = null;
      try {

      // Get handle on rootnode
      XmlNode root = dom.GetDocumentElement();

      // Cast the IBRequest back to an InternalIBRequest
      InternalIBRequest request = (InternalIBRequest)requestOrig;

      // Populate App Msg XML  Dom Object from IBRequest

      ...

      // Get the URL from either the IBRequest or from the 
      //prop file (default)

      String URL = request.getConnectorInfo().getFieldValue("URL");

      // Log the request
      Logger.logMessage("SampleTargetConnector: 
      Application Message Request", dom.GenerateXmlString(),
      Logger.STANDARD_INFORMATION);

      // Send the request DOM Document
      httpObj.setRequestProperty("content-type", "text/plain");
      httpObj.send(dom.GenerateXmlString().getBytes());

      // Get the response and convert to a String
      responseString = new String(httpObj.getContent());

      // Log the response
      Logger.logMessage("SampleTargetConnector: 
      Application Message Response", responseString, 
      Logger.STANDARD_INFORMATION);

      // Construct the IBResponse
      response = new IBResponse();

      ...

      // Return the successful IBResponse
      return response;

   } catch (XmlException xe) {
      httpObj.disconnect();
      throw new GeneralFrameworkException ("SampleTargetConnector:Failed
         while parsing XML");

   } catch (org.w3c.www.protocol.http.HttpException httpe) {
      throw new ("SampleTargetConnector:HTTP Protocol 
         exception",httpe);

   } catch (java.io.IOException ioe) {
      throw new ExternalSystemContactException 
         ("SampleTargetConnector:I/O Exception",ioe);

   } finally {
      httpObj.disconnect();
   }
   } // end send()
}

Developing Listening Connector Classes

This section discusses listening connector class development and discusses how to:

Build servlet-based and nonservlet-based listening connectors.
Invoke listening connectors.
Control message routing.
Build error handling and logging into listening connectors.

Building Servlet-Based and Nonservlet-Based Listening Connectors

If you require a listening connector that services HTTP requests, build a servlet-based listening connector. A servlet-based listening connector runs in the Servlet container on the web server.

See SDK Connector Examples.

This PeopleBook does not discuss how to install servlets on web servers.

See The servlet documentation for your web server.

Invoking Listening Connectors

Listening connectors must invoke PeopleSoft Integration Broker through the gateway manager Connect method.

IBResponse connect(IBRequest) throws GeneralFrameworkException DuplicateMessageException InvalidMessageException MessageMarshallingException MessageUnmarshallingException ExternalSystemContactException ExternalApplicationException

Controlling Message Routing

By accessing and modifying key information on the IBRequest, you can control the behavior of transactions as they flow through the integration gateway.

This section describes several dispatching features that you can use to control message routing by modifying the IBRequest from the listening connector, including routing messages to:

Other (remote) integration gateways.
Specific target connectors.
Other PeopleSoft systems.

You can control the routing of a message to another integration gateway by specifying the uniform resource locator (URL) of the gateway in the IBRequest. You might need to forward messages to another gateway so that they can be processed by a remote PeopleSoft Integration Broker system. To do so, specify the URL of this integration gateway as follows:

. . .
IBRequest ibRequest = new IBRequest();
IbRequest.setOperationName("RemoteRoutingTest");
IbRequest.setRequestingNode("SourceSystem");
IbRequest.setPassword("myPassword");
. . .

//Specify the processing of the message to occur from 
//anotherIntegration Gateway.
ibRequest.setRemoteFrameworkURL("https://hostName/PSIGW/
PeopleSoftListeningConnector");

You can also route a message to a specific target connector by modifying the request's ConnectorInfo object as follows:

. . .  
IBRequest ibRequest = new IBRequest();
. . .

// Send a message through the HttpTargetConnector for example.
ConnectorInfo connectorInfo = ibRequest.getConnectorInfo();

connectorInfo.setConnectorClassName("HttpTargetConnector");
connectorInfo.setField("URL","http://www.externalsite.com");
connectorInfo.setField("Method","POST");
. . .

Building Error Handling and Logging into Listening Connectors

This is sample code for building error handling and logging into listening connectors:

package com.peoplesoft.pt.integrationgateway.listeningconnector;

import ...

public class HttpListeningConnector extends HttpServlet {
      public void doGet(HttpServletRequest req, 
      HttpServletResponse resp) throws ServletException, IOException {
      }

      public void doPost(HttpServletRequest req,
      HttpServletResponse resp) throws ServletException, IOException {

         String actualResponse ="";
         IBRequest request = null;
         IBResponse response = null;

      try {

         String inputString = MiscUtil.readerToString(new 
         InputStreamReader(req.getInputStream()));

         // Log the actual Input String
         Logger.logMessage("HttpListeningConnector: HTTP
         Request", inputString, Logger.STANDARD_INFORMATION);

         HttpListeningConnectorUtility util = new
         HttpListeningConnectorUtility();
         request = util.createIBRequest("XML", req, inputString);

         // Use the GatewayManager to invoke the Integration 
         // Server and return its response.
         GatewayManager conMgr = new GatewayManager();
         response = conMgr.connect(request);

         // Need to get the actual response from the 
         //IBResponse
         actualResponse = response.getContentSectionAt(0);

   } catch (InvalidMessageException ime) {
         ime.printStackTrace();
         actualResponse = getErrorXml(ime);
         Logger.logError("HTTPListeningConnector:
         InvalidMessageException", request, response,
         Logger.STANDARD_GATEWAY_EXCEPTION, ime);

   } catch (ExternalSystemContactException esce) {
         esce.printStackTrace();
         actualResponse = getErrorXml(esce);
         Logger.logError("HTTPListeningConnector: 
         ExternalSystemContactException", request, response,    
         Logger.STANDARD_GATEWAY_EXCEPTION, esce);

   } catch (ExternalApplicationException esee) {
      esee.printStackTrace();
      actualResponse = getErrorXml(esee);
      Logger.logError("HTTPListeningConnector:
      ExternalApplicationException", request, response,
      Logger.STANDARD_GATEWAY_EXCEPTION, esee);

   } catch (MessageMarshallingException mme) {
      mme.printStackTrace();
      actualResponse = getErrorXml(mme);
      Logger.logError("HTTPListeningConnector: 
      MessageMarshallingException", request, response,
      Logger.STANDARD_GATEWAY_EXCEPTION, mme);

   } catch (MessageUnmarshallingException mue) {
      mue.printStackTrace();
      actualResponse = getErrorXml(mue);
      Logger.logError("HTTPListeningConnector: 
      MessageUnmarshallingException", request, response,
      Logger.STANDARD_GATEWAY_EXCEPTION, mue);

   } catch (GeneralFrameworkException gfe)  {
      gfe.printStackTrace();
      actualResponse = getErrorXml(gfe);
      Logger.logError("HTTPListeningConnector: 
      GeneralFrameworkException", request, response,
      Logger.STANDARD_GATEWAY_EXCEPTION, gfe);
   }

   // Return the message to the original requestor that
   //invoked the Servlet
   HttpListeningConnectorUtility.
         sendResponseBackToRequestor(actualResponse, resp);

   // Log the actual output String
   Logger.logMessage("HttpListeningConnector: 
      HTTP Response", actualResponse, Logger.STANDARD_INFORMATION);

   }   // end doPost()
}

Installing Connector Classes

Install connector classes on the local web server.

Installing Target Connector Classes

To install a target connector class, copy the class from the Java Classes directory to the following location on the local web server:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF\classes\com\peoplesoft\pt\integrationgateway\targetconnector

Installing Listening Connector Classes

To install a listening connector class, copy the class to the following location on the local web server:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF\classes\com\peoplesoft\pt\integrationgateway\listeningconnector

Registering Connectors

Before you can use a target connector, you must register it on the integration engine. To register a connector, load the connector information in the Gateways component by using the Load button. Loading the connector makes its capabilities known to PeopleSoft Integration Broker.

Then, assign the connector to the intended node on the Connector page in the Node Definition component. Enter the connector ID that corresponds to the new connector and edit the properties, as needed.

Servlet based listening connectors need to be registered with the web server. The mechanism for doing so is web server-specific. For Weblogic, this involves adding entries for the servlet and mapping to the web.xml file found in the following location:

<PIA_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW.war\WEB-INF