IBM WebSphere Adapter for PeopleSoft Enterprise 6.2.0 Quick Start Tutorials
Note: Before using this information and the product it supports, read the information in "Notices" on page 94. This edition applies to version 6, release 2, modification 0 of IBM WebSphere Adapter for PeopleSoft and to all subsequent releases and modifications until otherwise indicated in new editions.
Copyright International Business Machines Corporation 2008. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Table of contents Chapter 1. Introduction... 5 Learning Objectives...5 Audience...5 Software prerequisites...5 Chapter 2. Preparing to run through the tutorial... 7 Configuration prerequisites...7 Importing the sample projects into PeopleTools......7 Adding the trigger to WBI_CUSTOMER_COMP component...10 Generating the Java API for Component Interfaces......12 Creating a J2C Authentication Alias in WPS......14 Extracting the sample files...19 Chapter 3. Tutorial 1: Sending data to PeopleSoft Enterprise Application (outbound processing)... 21 Configuration prerequisites...21 Configuring the adapter for outbound processing...21 Setting connection properties for the external service wizard...27 Selecting the business objects and services to be used with the adapter...28 Generating business object definitions and related artifacts...30 Deploying the module to the test environment...35 Testing the assembled adapter application...37 Chapter 4. Tutorial 2: Receiving events from PeopleSoft Enterprise Application (inbound processing)... 43 Configuration prerequisites...43 Configuring the adapter for inbound processing...43 Setting properties for the external service wizard 48 Selecting the business objects and services to be used with the adapter...50 Generating business object definitions and related artifacts...52
Deploying the module to the test environment...60 Testing the assembled adapter application...62 Chapter 5. Tutorial 3: Effective Sequence number is not required for data insert (outbound processing)... 74 Configuration prerequisites...74 Configuring the adapter for outbound processing...74 Deploying the module to the test environment...83 Testing the assembled adapter application...83 Chapter 6. Troubleshooting... 93 Improve the WPS trace level......93 Connection issues with PeopleSoft Enterprise Application 93 Notices... 94
Chapter 1. Introduction WebSphere Adapter for PeopleSoft Enterprise is a J2EE component compliant with the JCA 1.5 specification. It will enable bidirectional connectivity to a PeopleSoft Enterprise application. The clients can send outbound messages to the resource adapter via the Common Client Interface (CCI) defined by the JCA specification. The resource adapter will perform the appropriate operation on the data based on the content and operation specified in the interaction specification. For inbound messages, the resource adapter uses the JCA message inflow contact. It will define a message listener interface and the endpoints or the message driven beans should implement this interface. This will enable the endpoints to receive any subscribed events from the resource adapter. To gain practical knowledge in setting up and deploying the adapter, complete one or more of the tutorials. Everything you need to complete a tutorial is contained in the tutorial. Perform the prerequisite tasks, before you attempt to complete the tutorials. Each tutorial takes less than an hour to complete. Learning Objectives After completing a tutorial, you should be able to perform the following tasks: Create an adapter project in WebSphere Integration Developer. Discover services and associated business objects from the enterprise information system (EIS) and make them part of the adapter project. Create a deployable module that you can install on WebSphere Process Server or WebSphere Enterprise Service Bus. Test the module and validate the results. Audience These tutorials are for integration developers who design, assemble, test, and deploy business integration solutions. Software prerequisites
To use these tutorials, you need the following software installed: WebSphere Integration Developer, version 6.2 WebSphere Process Server, version 6.2 PeopleTools, version 8.4x
Chapter 2. Preparing to run through the tutorial Configuration prerequisites Before performing tutorial testing, complete the following tasks: Import the sample projects into PeopleTools Add the trigger to WBI_CUSTOMER_COMP component Create the Java(TM) API for the Component Interfaces Create a J2C authentication alias in WebSphere Process Server The detailed steps for these tasks are provided in the following sections. Import the sample projects into PeopleTools Perform the following steps to import WBI_CUST_PROJ project into PeopleTools and build it. 1. Copy WBI_CUST_PROJ project from <WID_HOME>\ ResourceAdapters\PeopleSoft_6.2.0.0\Scripts to a temp directory (C:\Projects) on the machine where the PeopleTools runs. 2. Log on to the PeopleSoft application designer. 3. Select Tools> Copy Project > From File. 4. Browse to C:\Projects directory. From the Select Project from the List Below double-click WBI_CUST_PROJ. 5. In the Copy From File dialog, click Copy. Wait for the operation to complete. 6. Select WBI_CUST_PROJ in the left panel, and then select Build> Project from the main menu. 7. In the Build panel, select the following check boxes: a) Create Tables b) Create Views c) Create Trigger d) Run and build script
8. Click Build, to begin to build the project. 9. Click Close, to exit the Build Progress dialog. 10. In the Build Log view of the application designer, check the log messages to confirm that 3 records were processed correctly. 11. Select File> Save All to save the changes. Repeat the above steps to import IBM_EVENT_V600 project into PeopleTools and build it. Then you need to configure the user security for the Component Interfaces. 12. Log into PeopleSoft Web Client with the URL: http://localhost/psp/ps/?cmd=login 13. Go to PeopleTools >Security> Permissions & Roles> Permission Lists. 14. Input PTPT1200 in the edit box of begins with and click Search. 15. Go to the Component Interfaces tab, click to add the Component Interface WBI_CUSTOMER_COMP_INTERFACE. 16. Click Edit of WBI_CUSTOMER_COMP_INTERFACE.
17. Select Full Access for all methods and click OK. 18. Go back to the Component Interfaces tab, click to add the Component Interface IBM_EVENT_CI. 19. Click Edit of IBM_EVENT_CI.
20. Select Full Access for all methods and click OK. 21. Go back to the Component Interfaces tab and press Save button to save the changes. Add the trigger to WBI_CUSTOMER_COMP component For inbound operation, the adapter needs to retrieve the events from the IBM_EVENT_BC component. Add a trigger to WBI_CUSTOMER_COMP component, so that the events can be generated automatically when the data is created or modified against this component. Perform the following steps to add a trigger: 1. In PeopleSoft application designer, open WBI_CUST_PROJ project. 2. In the left panel, right-click on WBI_CUSTOMER_COMP and select View People- Code.
3. In the PeopleCode edit window, select SavePostChange in the right panel. 4. Input the following PeopleCode in the edit window.
Declare Function IBMPublishEvent PeopleCode IBM_FETCH_ID.IBM_NEXT_EVENT_ID FieldFormula; Component string &BONAME1; Component string &KEYLIST1; &BONAME1 = "WbiCustomerCompInterfaceBG"; &KEYLIST1 = "WBI_CUSTOMER.WBI_CUSTOMER_ID"; /* Check if Component Changed before calling function*/ If ComponentChanged() And %UserId <> "CW" Then /* Publish this event to the IBM Web- Sphere IBM_EVENT_TBL for polling */ IBMPublishEvent(&BONAME1, &KEYLIST1); End-If; 5. Select File->Save All to save the changes. Note: In the PeopleCode, the value of &BONAME1 should match the actual business object name that you generate in WebSphere Integration Developer while performing tutorial 2. In this sample document, the business object name is WbiCustomerCompInterfaceBG. If it is different in your scenario, modify the above PeopleSoftCode correspondingly. To ensure the trigger that was created above can work well, you need to do some initialization work. Connect to the database that the PeopleTools uses, and run the following SQL statement: $ insert into PS_IBM_FETCH_ID values(1000); $ commit; Create the Java API for Component Interface The Component Interface API provides access to all the objects and PeopleCode methods. You can manually generate these API using the application designer, and then compile them to a PSFTCI.jar file. 1. In PeopleSoft application designer, open IBM_EVENT_CI Component Interface.
2. Select Build->PeopleSoft API from the main menu. 3. In the Build PeopleSoft API Bindings dialog, make sure only the Build check box under Java Classes is selected. Set the Target Directory for storing the generated Java files. In the Select API to Build list, select the following items: CompIntfc.CompIntfcPropertyInfo CompIntfc.CompIntfcPropertyInfoCollection All beginning with CompIntfc.IBM_EVENT_CI All beginning with CompIntfc.WBI_CUSTOMER_COMP_INTERFACE 4. Click OK. Check the target directory to make sure the Java files are generated correctly. 5. Copy the generated Java files to C:\Temp directory, then copy psjoa.jar file from <PeopleTools_HOME>\web\psjoa to C:\Temp directory 6. Enter directory as C:\Temp and run the following commands to build the Java files. $ javac classpath.\psjoa.jar PeopleSoft\Generated\CompIntfc\*.java $ jar" -cvf PSFTCI.jar PeopleSoft\Generated\CompIntfc\*.class
These two JAR files psjoa.jar and PSFTCI.jar are used by the adapter to access the PeopleSoft Enterprise application later. Create a J2C Authentication Alias in WebSphere Process Server Perform the following steps to create a J2C authentication alias in WebSphere Process Server, which will be used by the adapter to access the PeopleSoft Enterprise application. 1. Open WebSphere Integration Developer and switch to Business Integration perspective. 2. Select Servers tab, right-click on WebSphere Process v6.2 Server and select Start. 3. After the server starts up, right-click on WebSphere Process v6.2 Server and select Run administrative console.
4. Log on to the administrative console. 5. Select Security-> Secure administration, application, and infrastructure.
6. In Secure administration, applications and infrastructure window, select Authentication > Java Authentication and Authorization Service >J2C authentication data. 7. Click New, to create a new alias.
8. Specify the properties with the following values. As shown in the following screen capture Property Alias User ID Password Value PSFT_Alias PS PS
9. Click Apply. 10. Click Save to save changes. 11. Then navigate to J2C authentication data to check the alias that was created. It will be used during the later tutorials.
Extract the sample files Replicas of the artifacts that you create when using the external service wizard are provided as sample files for your reference. Use these files to verify that the files you create with the external service wizard are correct. Some sample files are provided under Sample folder and their detailed contents are shown as below. You can create a temp folder and extract the archives: File name Description Samples\referencefiles\Tutorial1.zip TestOutbound\ PeopleSoftOutboundInterface.import Contains the SCA import for the resource adapter.
TestOutbound\ PeopleSoftOutboundInterface.wsdl TestOutbound\ WbiCustomerCompInterfa Container.xsd TestOutbound\ WbiCustomerCompInterfaceBG.xsd TestOutbound\ WbiCustomerCompInterfa TestOutbound\WbiAddress.xsd TestOutbound\WbiPhone.xsd Contains the SCA wsdl file for the resource adapter Business object definition for the business object container. Business object definition for the business object graph. Business object definition for the Customer business object. Business object definition for the Address business object. Business object definition for the Phone business object. Samples\referencefiles\Tutorial2.zip TestInbound\ PeopleSoftInboundInterface.export TestInbound\ PeopleSoftInboundInterface. TestInbound\ WbiCustomerCompInterfaceBG.xsd TestInbound\ WbiCustomerCompInterface TestInbound\WbiAddress.xsd TestInbound\WbiPhone.xsd Contains the SCA export for the resource adapter. Contains the SCA wsdl file for the resource adapter Business object definition for the business object graph. Business object definition for the Customer business object. Business object definition for the Address business object. Business object definition for the Phone business object.
Chapter 3. Tutorial 1: Sending data to PeopleSoft Enterprise application (outbound processing) This tutorial demonstrates how WebSphere Adapter for PeopleSoft Enterprise sends data to populate customer information into PeopleSoft Enterprise application. Configuration prerequisites Before starting this tutorial, perform the following tasks: Ensure the JAR files psjoa.jar and PSFTCI.jar created in section 2.1.3 are added to a directory, like E:\PS. Ensure the PeopleSoft Enterprise application is running. Configure the adapter for outbound processing Run the external service wizard to specify business objects, services, and configuration to be used in this tutorial. To generate the business objects and related artifacts, perform the following steps: 1. Open WebSphere Integration Developer and create a new workspace named PeopleSoft_Outbound.
2. Go to the Business Integration perspective and select File->New- >External Service. 3. In the External Service window, select Adapters-> PeopleSoft and click Next.
4. In the Select an Adapter window, select IBM WebSphere Adapter for PeopleSoft Enterprise and click Next.
5. In the Adapter Import window, click Next.
6. In the Required Files and Libraries window, use Browse to specify the location of psjoa.jar and PSFTCI.jar files and click Next.
7. In the Processing Direction window, select Outbound and click Next.
Set connection properties for the external service wizard 8. In the Discovery Configuration window, specify the connection properties for the external service wizard and click Next.
Select the business objects and services to be used with the adapter 9. In the Object Discovery and Selection window, select WBI_CUSTOMER_COMP_INTERFACE and add it to the Selected objects list. Click Next.
10. In the Configure Composite Properties window, accept the default settings and click Next.
Generate business object definitions and related artifacts 11. In the Service Generation and Deployment Configuration window, type widnode/psft_alias in the J2C Authentication Data Entry field and click Next.
12. In the Service Location Properties window click New.
13. In the Integration Project window, select Create a module project and click Next.
14. In the Module window, type TestOutbound in the Module Name field and click Finish.
15. Go back to the Service Location Properties window and click Finish.
16. Go back to the Business Integration perspective and select File->Save All to save the changes. Deploy the module to the test environment The result of running the external service wizard is an SCA module that contains an EIS import or export. Install this SCA module in WebSphere Integration Developer integration test client. 1. Add the module you created earlier to the server using the server panel in WebSphere Integration Developer. In the Servers tab, right-click on the WebSphere Process v6.2 Server, and select Add and Remove Projects.
2. Add the SCA module to the server. In the Add and Remove projects window, click Add to add TestOutboundApp project into the Configured projects list and click Finish.
Test the assembled adapter application Test the assembled adapter application using the WebSphere Integration Developer integration test client: 1. Select the service you want to test, right-click on TestOutbound module and select Test -> Test Module.
2. Populate the following values for input business objects. as shown in the following screen capture. Specify the input data as the following table shows: Property Name Component Interface Operation verb Property Value PeopleSoftOutboundInterface PeopleSoftOutboundInterface Create WbiCustomerId 99122 createwbicustomercompinterface WbiCustomerFname WbiCustomerLname Charlie Lee
WbiCustomer- Dob 1980-08-01 3. Run the service. Click Continue to run the service.
4. In the Select Deployment Location window, select the server instance you want to deploy the project to and click Finish.
5. Check the output of the service and check the data in the EIS to ensure it matches expected values.
Tutorial 2: Receiving events from PeopleSoft Enterprise application (inbound processing) Chapter 4. This tutorial demonstrates how WebSphere Adapter for PeopleSoft Enterprise polls the events from the PeopleSoft Enterprise application. Configuration prerequisites Before starting this tutorial, perform the following tasks: Ensure the JAR files psjoa.jar and PSFTCI.jar that are created in Chapter 2 are added to E:\PS directory. Ensure the PeopleSoft Enterprise application is running. Configure the adapter for inbound processing Run the external service wizard to specify business objects, services, and configuration to be used in this tutorial. To generate the business objects and related artifacts, perform the following steps: 1. Open WebSphere Integration Developer and create a new workspace named PeopleSoft_Inbound.
2. Go to the Business Integration perspective and select File->New- >External Service. 3. In the External Service window, select Adapters->PeopleSoft and click Next.
4. In the Select an Adapter window, select IBM WebSphere Adapter for PeopleSoft Enterprise and click Next.
5. In the Adapter Import window click Next.
6. In the Required Files and Libraries window, click Browse to specify the file path for psjoa.jar and PSFTCI.jar and click Next.
7. In the Processing Direction window, select Inbound and click next.
Set properties for the external service wizard 8. In the Discovery Configuration window, specify the connection properties for the external service wizard and click Next.
Select the business objects and services to be used with the adapter 9. In the Object Discovery and Selection window, select WBI_CUSTOMER_COMP_INTERFACE and add it to the Selected objects list. Click Next.
10. In the Configure Composite Properties window click Next.
Generate business object definitions and related artifacts 11. In the Service Generation and Deployment Configuration panel, type widnode/psft_alias in the J2C Authentication Data Entry field and click Next.
12. In the Service Location Properties window click New.
13. In the Integration Project window click Next.
14. In the Module window, type Test Inbound in the Module Name field and click Finish.
15. In the Service Location Properties window click Finish.
16. Go back to Business Integration perspective and drag the Java Component to the Assembly Diagram.
17. Add wire between PeopleSoftInboundInterface and Java Component1.
18. Select File->Save All to save the changes
Deploy the module to the test environment After running the external service wizard, you will have an SCA module that contains an EIS import or export. You must install this SCA module in the WebSphere Integration Developer integration test client. 1. Add the SCA module to the server using the server panel in WebSphere Integration Developer. In the Servers tab, right-click on the WebSphere Process v6.2 Server, and select Add and Remove Projects.
2. Add the SCA module to the server. In the Add and Remove Projects window, click Add to add TestInboundApp project to the Configured projects list. Click Finish.
Test the assembled adapter application Test the assembled adapter application using the WebSphere Integration Developer integration test client: 1. Attach the integration test client to the EIS export. a. In WebSphere Integration Developer, right-click on project TestInbound and select Test->Attach.
b. Switch to Configurations tab and click Add.
c. Select Component and Reference Emulator and click Next.
d. Select Module TestInbound and click Next.
e. Select Components and click the check box of Component1. Click Finish.
f. Switch back to Events tab and click Continue.
g. In the Select Deployment Location window, select the server instance you want to deploy the project to and click Finish.
2. Enter data in the EIS to trigger an inbound event. a. In the PeopleSoft application designer, open Component Interface WBI_CUSTOMER_COMP_INTERFACE and select Tools->Test Component Interface.
b. Specify WBI_CUSTOMER_ID to 99450 and click Create New.
c. Specify the property values as the following screen capture shows, then right-click on WBI_CUSTOMER_COMP_INTERFACE and select Save.
d. Click OK, when the Save() results dialog prompts.
3. Check the values in the object published to the WebSphere Integration Developer integration test client.
Tutorial 3: Effective Sequence number is not required for data insert (outbound processing) Chapter 5. This tutorial demonstrates how WebSphere Adapter for PeopleSoft Enterprise use IgnoreEffectiveSequence ASI to insert child data to the PeopleSoft Enterprise application. Configuration prerequisites Before starting this tutorial, perform the following tasks: Ensure the JAR files psjoa.jar and PSFTCI.jar that were created in section 2.1.3 are added to some directory, like E:\PS. Ensure the PeopleSoft Enterprise application is running. Configure the adapter for outbound processing Run the external service wizard to specify business objects, services, and configuration to be used in this tutorial. To generate the business objects and related artifacts, first perform step 1 to step 16 in section 3.2. Then perform the following steps to set the related ASI to ignore effective sequence number, including IgnoreEffectiveSequence, EffectiveDate, Effective- Sequence, KeepRelations, InsAtOldestEffDtPos. For details of the usage of these ASIs, refer to the PeopleSoft user guide. 1. In Business Integration perspective, expand Data Types under TestOutbound module and click WbiCustomerCompInterface. In the right panel, right-click WbiAddress->Show in Properties.
2. In Properties->Application Info tab, right-click PeopleSoftAttributeTypeMetadata->New->KeepRelations.
3. In TestOutbound > Data Types module click WbiAddress. In the right panel, right-click WbiAddress -> Show in Properties
4. In Properties->Application Info tab, right-click to add PeopleSoft- BusinessObjectTypeMetadata->New->IgnoreEffectiveSequence and PeopleSoftBusinessObjectTypeMetadata->New- >InsAtOldestEffDtPos
5. In WbiAddress tab, right-click Effdt -> Show in Properties
6. In Properties>Application Info tab, right-click PeopleSoftAttributeTypeMetadata>New>EffectiveDate
7. In WbiAddress tab, right-click WbiAddressId > Show in Properties
8. In Properties >Application Info tab, right-click PeopleSoftAttributeTypeMetadata >New >EffectiveSequence.
9. Select File >Save All to save the changes. Deploy the module to the test environment The result of running the external service wizard is an SCA module that contains an EIS import or export. Install this SCA module in WebSphere Integration Developer integration test client. Perform step 1 and step 2 in section 3.3. Test the assembled adapter application Test the assembled adapter application using the WebSphere Integration Developer integration test client:
1. Select the service you want to test, right-click TestOutbound module and select Test > Test Module. 2. Populate the following values for input business objects, as shown in the following screen capture. Specify the input data as shown in the following table: Property Name Component Interface Operation WbiCustomerId WbiCustomerFname WbiCustomerLname Property Value PeopleSoftOutboundInterface PeopleSoftOutboundInterface createwbicustomercompinterface 99123 Charlie Lee
WbiAddress[0] Effdt 2008-09-16 WbiAddressId 1 WbiAddressLine1 Line1 WbiAddress[1] Effdt 2008-09-17 WbiAddressId 2 WbiAddressLine1 Line2 WbiAddress[2] Effdt 2008-09-16 WbiAddressId 3 WbiAddressLine1 Line3
3. Run the service. Click Continue to run the service.
4. In the Select Deployment Location window, select the server instance you want to deploy the project to and click Finish.
5. Check the output of the service and check the data in the EIS to ensure it matches the expected values.
6. Populate the following values for input business objects, as shown in the following screen capture. Specify the input data as shown in the following table :
Property Name Component Interface Operation WbiCustomerId Property Value PeopleSoftOutboundInterface PeopleSoftOutboundInterface updatewbicustomercompinterface 99123 WbiCustomerFname WbiCustomerLname WbiAddress[0] Effdt 2008-09-16 WbiAddressId 4 WbiAddressLine1 Line4 GetHistoryItems true 7. Run the service. Click Continue to run the service.
8. Check the output of the serviceand check the data in the EIS to see the child data is added at the highest(oldest) index
In Step 4 of Section 5.2, if you add InsAtCurrentEffDtPos ASI instead of InsAtOldestEffDtPos, the child data will be added at the lowest (current) index in the previous step.
Chapter 6. Troubleshooting If you encounter any troubles while running the above tutorials, review the following tips for resolving some common problems. Improve the WebSphere Process Server trace level If you are not able to determine the cause of the error based on the exception message in the Component Test Client, you can perform the following steps to improve the WebSphere Process Server trace level to get more detailed adapter trace. a) Log on to WebSphere Process Server administrative console b) Go to Troubleshooting > Logs and Trace c) Select server1 d) Select Change Log Detail Levels e) In the Runtime tab, add setting string *=info: com.ibm.j2ca.*=all f) Click OK The trace file can be located at: <Profile Home>\logs\server1\trace.log Connection issues with PeopleSoft Enterprise application If the Adapter meets any problems when it tries to connect to the PeopleSoft Enterprise application, you can check the following things: a) Ensure the connection properties are correct, such as host name, port number, username, and password. b) Ensure the version of psjoa.jar that the Adapter uses is exactly the same as the version of the PeopleTools that the Adapter tries to connect to. For example, the Adapter will fail to connect to PeopleSoft Enterprise application if the psjoa.jar version is 8.48 but the PeopleTools version is 8.49.
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUB- LICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply to you.