Adding the PeopleSoft Adapter for Enterprise Applications to BizTalk Server 2010 + Adapter Configuration Information

There are numerous white papwrs on the BizTalk Enterprise Adapter for PeopleSoft. It is a wonderful tool, but unfortunately, none of these white papers thoroughly covers the challenges you may face in getting it up and running. I will try to explain some challenges you might face whilst using this Adapter in the next few posts, with the solutions I discovered.

Please follow up by also reading this post and this post for solutions to challenges you will most likely face if you are using a similar to environment to mine (i.e. BizTalk Server 2010 and Windows Server 2008 R2)

Once you have finished the process below, you can use the adapter by following the steps at this link: http://msdn.microsoft.com/en-us/library/aa995588.aspx. (I will try to find the time to create another post on the steps at some point)

At design time, the BizTalk Server 2010 PeopleSoft LOB adapter evaluates the PeopleSoft Component Interfaces on the PeopleSoft server and exposes a listing of these APIs which can then be consumed within BizTalk Server 2010. This adapter is a send adapter, and is used for initiating calls to PeopleSoft from BizTalk Server. However, note that while the PeopleSoft LOB adapter does not handle retrieving data from PeopleSoft directly, the send handler from BizTalk Server can be used to initiate a request for information using the Get or Find methods of the Component Interfaces exposed by the adapter, provided that the appropriate requesting parameters (keys, guids etc.) are made available

1. Install the Enterprise Applications Adapters
   1. Double-click ‘Setup.exe’ from your enterprise applications adapters installation pack
   2. Select ‘Install Microsoft BizTalk Adapters’
   3. Click on ‘Step 4: Install Microsoft BizTalk Adapters for Enterprise Applications’
   4. Use the default settings to install the adapters
   
   
2. Register the PeopleSoft Enterprise adapter with the BizTalk Server 2010 Instance
   1. Click Start, point to Programs, point to Microsoft BizTalk Server 2010 and then click BizTalk Server Administration
   2. Expand BizTalk Server Administration, expand BizTalk Group, expand Platform Settings, and then expand Adapters
   3. Right-click Adapters, point to New, and then click Adapter
   4. Enter a Name for the adapter. e.g, PeopleSoft
   5. From the Adapter list, select the adapter, and then click OK
   6. The prompt reads “This configuration changes requires host instance restart. Please restart the associated host instances for the changes to take effect." Click OK to finish the configuration.
   7. From the BizTalk Server 2006/2009 Administration console, navigate to BizTalk Server 2010 Administration -> BizTalk Group -> Platform Settings-> Host Instance
   8. Right-click BizTalkServerApplication, and then click Restart. BizTalkServerApplication is the typical default in-process host instance. If you assigned the adapter to a different host instance, you must restart that host instance instead.
   
   
3. Install the Sun Java JDK
1. Although BizTalk Server 2010 is built on the Microsoft .NET Framework, the connection of the PeopleSoft LOB adapter into the PeopleSoft application uses Java, and communicates with BizTalk Server using the PeopleSoft JOLT transaction protocol. This is especially evident when configuring the port because it is necessary to reference several JAR file locations in addition to the PeopleSoft connection information
     
   For this reason, the Java Development Kit (JDK) also needs to be installed
• Download the latest JDK rom Sun microsystems (current version is JDK 7, but I only got a successful connection with jdk 6 in my case at first. I later realised this was because I needed the 32 bit version of the JDK 7 even though I am running on a 64-bit OS - Windows 2008 R2. I installed the 32-bit version of the JDK 7 and got it to work)
• Double-click the downloaded JDK file (jdk-6-windows-i586.exe and thewn jdk-7-windows-i586.exe in my case) executable. You must have administrative permissions in order to install the JDK on Microsoft Windows)
• Install the components you need – note the location of the installation (typically something like C:\Program Files (x86)\Java\jdk1.7.0)
• Set the PATH environment Variable.(You can run the JDK without setting the PATH environment variable, or you can optionally set it so that you can conveniently run the JDK executable files (javac.exe, java.exe, javadoc.exe, and so forth) from any directory without having to type the full path of the command. If you do not set the PATH variable, - I didn't - you need to specify the full path to the executable file every time you run it, in the port configurations)
1. To set the PATH environment variable, Click Start, then Control Panel, then System
2. Click Advanced System Settings, then Environment Variables
3. Under ‘System Variables’, scroll to PATH and Add the location of the bin folder of the JDK installation at the end of the PATH variable. The PATH environment variable is a series of directories separated by semicolons (;) and is not case-sensitive
   
   The following is a typical value for the PATH variable: C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Java\jdk1.7.0_01
4. Configure the adapter
   
   
   1. The PeopleSoft adapter requires that the send and receive pipelines use the default XML pipelines of XML Transmit and XML Receive respectively
   2. The adapter uses transport properties (see Tables 1 and 2) to connect to PeopleSoft. One important characteristic to note about these transport settings is that the values are case sensitive. Take care when specifying the properties
                                                    
      
      Figure 1 – Adapter Properties
   
   

   Transport Property	Description / Example
   Application Server Path	The name of the computer and port on which the PeopleSoft application server is running and listening. The syntax of the URL path to the PeopleSoft 8 application is //<machine_name>:<port> The <port> value is the JOLT protocol Listener port, not the App Server port. The default JOLT port is 9000.
   JAVA_HOME	The location where the JDK was installed. For example: C:\Program Files (x86)\Java\jdk1.7.0. (Not required if you set up the environment PATH variable as described in step 3d above
   Password	The user’s password used to access the PeopleSoft system. The characters do not appear but are represented by asterisks (*). This is required only if you are not using Enterprise Single Sign-On (SSO).
   PeopleSoft 8x JAR Files	The location of the psjao.jar file on the PeopleSoft server.. (I copied the psao.jar file from the PeopleSoft server onto the BizTalk server in my case, so I ecreated a folder for it and entered it as C:\PSJarLoc\psjoa.jar) For example: C:\PeopleSoft\psjoa.jar or \\<PeopleSoft Server>\web\psjoa\psjoa.jar The psjoa.jar file is unique to each version and installation of PeopleSoft. This file is typically located at <PeopleSoft_Home>\web\PSJOA\psjoa.jar.
   User Name	The user’s login name used to access the PeopleSoft system. This is required only if you are not using SSO

   
   Table 1 – Required Transport Properties
   
   

   Transport Property	Description / Example
   Database date format	The default format is YYYY-MM-DD - When a date is used as a key value, it may have a different format which needs to tally with the format on the PeopleSoft database.
   Max Concurrent Calls	Default is 5 - This value specifies the maximum number of concurrent calls that can be made on this send port. If the number of calls exceeds this value, the additional requests will become dehydrated until processing threads become available. –1 indicates an unlimited number of calls
   Maximum number of sessions	Default is 40 - This determines the maximum number of sessions that can be connected to the server at one time - Sessions relate to the way in which a client connects to the server. For example, if the login credentials are the same, they use the same session. Concurrent calls relate to the number of simultaneous connections that can be made to a server at a time. You may need to limit the number of sessions based on the number of client licenses, whereas the number of concurrent calls impacts performance and is determined by back-end processing capabilities
   Event Log Level	Error - This is the level of events that are to be recorded as they are encountered. The default value is Error. Possible values are Info (includes warnings and errors), Warning (includes errors), and Error.
   Refresh Agent	Yes - When Yes is selected, the runtimeagent.exeand the browsingagent.exe processes will be restarted automatically as required. They are processes that the BizTalk Server runtime and Visual Studio.Net respectively invoke on the LOB adapters for metadata generation
   Affiliate application	This value is created by Enterprise Single Sign-On tools and is used to represent an external application. The user credentials are stored in the SSO Credential database Use SSO – This value determines whether SSO is to be used or not

   
   Table 2 – Additional Transport Properties

Appendix: References and more reading:

http://msdn.microsoft.com/en-us/library/bb820917(v=bts.10).aspx
http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=16310
http://download.oracle.com/javase/7/docs/webnotes/install/windows/jdk-installation-windows.html
http://go.microsoft.com/fwlink/?LinkId=96136
http://hosteddocs.ittoolbox.com/KK022704.pdf
http://download.microsoft.com/download/1/6/9/16968441-c6c8-4bd0-9410-5f4014bc61f0/peoplesoft.doc