Creating Custom Listening Connectors using Integration Broker SDK

One of my customers recently had the need of allowing a third party web application to attach files into PeopleSoft. After trying a number of different approaches (the integration had to be done at the web application client level, which significantly reduces the options to manipulate the request to PeopleSoft before sending it, particularly when dealing with old web browsers), I gave up and came to the conclusion that I needed a custom listening connector in Integration Broker to implement such integration. 

The process of developing and installing a custom listening connector in Integration Broker is quite well described in PeopleBooks, however, I thought it would helpful to document the process I have followed.

Samples

PeopleSoft comes with some samples of connectors developed using the Integration Broker SDK. The most interesting one for listening connectors is ExampleServletListeningConnector.java located in the following folder:

$PIA_HOME/webserv/IFHRDEV/applications/peoplesoft/PSIGW.war/WEB-INF/SDK/src/samplelisteningconnectors.java

I've used this sample as the basis for my custom connector. In some cases, I also found quite handy to decompile the standard connectors such HttpListeningConnector. I could not find any exhaustive source of documentation of the Integration Broker SDK, so decompiling the existing connectors proved to be a good way to understand how to best use the SDK.

Note: For decompiling the Java class files I have used a very simple tool names cavaj. It is a very simple tool, but still helpful.

Development

Taking the previously mentioned sample as the basis, I have coded my own connector. If you are not interested in the details, you may want to skip to the next section.

What I needed to do in my connector was basically two things:

1. Encode the incoming file using Base64, as binary files could not be processed otherwise by the existing PeopleCode Message API.
2. Pass any parameters received in the HTTP Header or the URL as part of the IBInfo (Integration Broker information included in every internal Integration Broker message.

If you want to check the actual code, you can download the source code from this link:

https://drive.google.com/file/d/0B9Ts3FrN6NfhNWdaVnNhalAxRG8/view?usp=sharing

Compiling

Once your source code is ready, you need to compile it. The first step for Java compilation is to set the environment variables so they point to the Java SDK. In my case, I was using the PeopleSoft HCM 9.2 Update Image 11, and these were the commands I needed to use:

export JAVA_HOME=/opt/oracle/psft/pt/jdk1.7.0_71

export PATH=$PATH:$JAVA_HOME/bin

Then I went to the directory were my java file was placed and run the following command to compile the file:

javac -cp /home/psadm2/psft/pt/8.54/webserv/peoplesoft/applications/peoplesoft/PSIGW.war/WEB-INF/classes:/home/psadm2/psft/pt/8.54/webserv/peoplesoft/applications/peoplesoft/PSIGW.war/WEB-INF/lib/mail.jar:/opt/oracle/psft/pt/bea/wlserver/server/lib/weblogic.jar FileUploadListeningConnector.java 

The paths may obviously differ in your case, but the important thing is to include the following directories/jar files in your class path:

• $PIA_HOME/webserv/peoplesoft/applications/peoplesoft/PSIGW.war/WEB-INF/classes
• mail.jar
• weblogic.jar

Please note that weblogic.jar was needed because I was using WebLogic as my web server. In case you use WebSphere, you need to change this jar file.

Deployment

Once the file is compiled, you need to copy the resulting class file to the following directory:

$PIA_HOME/webserv/IFHRDEV/applications/peoplesoft/PSIGW.war/WEB-INF/classes/com/peoplesoft/pt/integrationgateway/listeningconnector

The next step is to let WebLogic know that there is a new servlet available. This can be done by editing the following file:

$PIA_HOME/webserv/IFHRDEV/applications/peoplesoft/PSIGW.war/WEB-INF/web.xml

All you need to do is to duplicate the sections referring to ExampleServletListeningConnector and replace those appearances with your connector name. In my case, I was using PeopleTools 8.54, and these were the lines I had to include:

(...)

<servlet>

<servlet-name>ExampleServletListeningConnector</servlet-name>

<servlet-class>com.peoplesoft.pt.integrationgateway.listeningconnector.ExampleServletListeningConnector</servlet-class>

</servlet>

<servlet>

<servlet-name>FileUploadListeningConnector</servlet-name>

<servlet-class>com.peoplesoft.pt.integrationgateway.listeningconnector.FileUploadListeningConnector</servlet-class>

</servlet>

(...)

<servlet-mapping>

<servlet-name>ExampleServletListeningConnector</servlet-name>

<url-pattern>/ExampleServletListeningConnector/*</url-pattern>

</servlet-mapping>

<servlet-mapping>

<servlet-name>FileUploadListeningConnector</servlet-name>

<url-pattern>/FileUploadListeningConnector/*</url-pattern>

</servlet-mapping>

(...)

Testing

In order to test the new connector, you need to reboot the web server so the changes made to register the new servlet are taken. Once this is done, you can check if the new listening connector is responding by using the declared URL:

http://webserver/PSIGW/FileUploadListeningConnector