You are on page 1of 736

Integration Tools

April 2004 INS-1022-844A

Instructor Guide

PeopleSoft PeopleTools 8.44

Integration Tools INS-1022-844A Contributors: Cathy DeFeo, Shyam Rangaratnam, Robert Taylor, Jason Franco, Tushar Chury, Mahesh Deshpande, Monique Dawson, Andrew Rothstein, Kathryn Kazmierski Restricted Rights Copyright 2004 PeopleSoft, Inc. All rights reserved. All material contained in this document is proprietary and confidential to PeopleSoft, Inc. and is protected by copyright laws. No part of this document may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, including, but not limited to, electronic, graphic, mechanical, photocopying, recording, or otherwise without the prior written permission of PeopleSoft, Inc. This document is subject to change without notice, and PeopleSoft, Inc. does not warrant that the material contained in this document is free of errors. Any errors found in this document should be reported to PeopleSoft, Inc. in writing. PeopleTalk and People power the internet. are trademarks; and PeopleSoft, the PeopleSoft logo, PeopleTools, PS/nVision, PeopleCode, PeopleBooks, Vantive, Vantive Enterprise and Red Pepper are registered trademarks of PeopleSoft, Inc. All other trademarks mentioned in this document are the property of their respective owners.

CONTENTS
Preface Integration Tools ..............................................................................................................ix Typographical Conventions and Visual Cues ....................................................................ix Related Documentation .......................................................................................................x Course Overview ...............................................................................................................1 Technology Overview......................................................................................................11 PeopleSoft Integration Technologies ................................................................................12 PeopleSoft Integration Broker...........................................................................................15 Component Interfaces........................................................................................................21 WSDL Integrations ...........................................................................................................23 File Interfaces ....................................................................................................................24 Finding Information About PeopleSoft Integration Tools in PeopleBooks ......................27 Introducing PeopleSoft Component Interfaces ............................................................37 Describing PeopleSoft Component Interfaces...................................................................38 Describing the PeopleSoft Component Interface Architecture .........................................44 Listing the Elements of a Component Interface Definition...............................................46 Describing Component Interface Keys .............................................................................48 Describing Component Interface Properties and Collections............................................50 Describing Component Interface Methods........................................................................56 Creating and Testing Component Interfaces................................................................59 Listing the Steps for Creating Applications That Use Component Interfaces ..................60 Designing Component Interface Applications ..................................................................61 Creating or Modifying Supporting Definitions .................................................................63 Creating Component Interfaces.........................................................................................64 Activity 1: Creating Component Interfaces ...................................................................74 Setting Component Interface Security...............................................................................78 Testing Component Interfaces...........................................................................................80 Activity 2: Testing a Component Interface....................................................................83 Implementing Component Interfaces ............................................................................87 Describing Component Interface Instantiation..................................................................88 Adding Component Interface PeopleCode to an Application ...........................................92 Modifying Component Interface PeopleCode...................................................................99 Activity 3: Activating a Component Interface.............................................................106 Working with Component Interface Collections........................................................115 Describing Component Interface Collections .................................................................116 Writing PeopleCode for Component Interface Collections.............................................120

Lesson 1 Lesson 2

Lesson 3

Lesson 4

Lesson 5

Lesson 6

PeopleSoft Proprietary and Confidential

iii

Integration Tools

Contents

Working with Effective-Dated Data................................................................................123 Activity 4: Using Component Interfaces with Collections ..........................................125 Lesson 7 Building Component Interface APIs ...........................................................................135 Describing Component Interface APIs............................................................................136 Building Component Interface APIs ...............................................................................137 Generating Runtime Code Templates .............................................................................139 Establishing a PeopleSoft Session...................................................................................142 Deploying Component Interfaces....................................................................................144 Testing the Java SDK Sample .........................................................................................148 Activity 5: Testing SDK Java API Sample..................................................................154 Creating a Java API.........................................................................................................160 Activity 6: Creating a Java Component Interface API ................................................164 Using the Excel to Component Interface Utility .........................................................171 Describing the Excel to Component Interface Utility .....................................................172 Assigning Public Access .................................................................................................176 Connecting to PeopleSoft................................................................................................178 Creating a Template ........................................................................................................181 Entering Data...................................................................................................................186 Submitting Data...............................................................................................................188 Activity 7: Creating ExcelToCI Template...................................................................190 Deploying the Excel Workbook ......................................................................................194 Activity 8: Deploying Workbooks...............................................................................195 Introducing PeopleSoft Integration Broker Architecture .........................................199 Describing the PeopleSoft Integration Broker Architecture............................................200 Describing the PeopleSoft Integration Gateway .............................................................202 Describing Connectors ....................................................................................................204 Describing the Gateway Services....................................................................................210 Describing the Integration Broker Engine Components .................................................213 Explaining the Flow of Inbound Requests to PeopleSoft Integration Broker .................215 Explaining the Flow of Outbound Requests from PeopleSoft Integration Broker..........217 Configuring PeopleSoft Integration Broker ...............................................................221 Configuring PeopleSoft Integration Broker ....................................................................222 Configuring an Integration Gateway ...............................................................................227 Activity 9: Configuring the Gateway...........................................................................236 Describing Nodes ............................................................................................................238 Renaming the Default Local Node ..................................................................................245 Activity 10: Renaming the Default Local Node........................................................247 Creating and Pinging Remote Nodes ..............................................................................249 Activity 11: Configuring Remote PeopleSoft Nodes ................................................251 Creating Message Channels and Message Definitions ...............................................257 Listing the Development Elements Used with PeopleSoft Integration Broker ...............258

Lesson 8

Lesson 9

Lesson 10

Lesson 11

iv

PeopleSoft Proprietary and Confidential

Contents

Integration Tools

Describing Message Channels.........................................................................................262 Securing Message Channels............................................................................................270 Describing Message Definitions .....................................................................................272 Creating Message Definitions .........................................................................................279 Creating Test Messages...................................................................................................281 Activity 12: Creating a Message Definition ..............................................................283 Lesson 12 Describing the PeopleSoft Message Format................................................................287 Describing the Message Formats Used with PeopleSoft Integration Broker ..................288 Viewing Message Structure in Integration Broker Monitor............................................290 Describing the PeopleSoft Structured Message Format ..................................................294 Describing the PSCAMA record .....................................................................................297 Editing Message XML ....................................................................................................302 Activity 13: Viewing and Editing a Structured XML Message ................................303 Sending and Receiving Messages .................................................................................307 Listing PeopleSoft Integration Broker Transaction Types ..............................................308 Describing PeopleCode Used with Structured Messages................................................310 Publishing Asynchronous Messages ...............................................................................319 Activity 14: Publishing a Message ............................................................................321 Subscribing to Asynchronous Messages .........................................................................322 Testing Subscription PeopleCode ...................................................................................327 Activity 15: Writing and Testing Subscription PeopleCode .....................................328 Sending and Receiving Synchronous Messages..............................................................331 Assigning Transactions to Nodes ....................................................................................338 Activity 16: Adding Asynchronous Transactions .....................................................341 Activity 17: Sending and Receiving a Synchronous Message ..................................344 Describing Message Routing...........................................................................................348 Monitoring Messaging System Performance Using Integration Broker Monitor...355 Describing Integration Broker Monitor...........................................................................356 Describing Asynchronous Message Flow .......................................................................359 Listing the Message Statuses...........................................................................................363 Using Integration Broker Monitor...................................................................................365 Activity 18: Monitoring Messages ............................................................................380 Viewing Message System Performance Statistics...........................................................386 Archiving Messages ........................................................................................................395 Performing Error Notification .........................................................................................397 Activity 19: Sending and Receiving Messages .........................................................399 Applying Transformations ...........................................................................................403 Describing Transform Programs .....................................................................................404 Developing Transformation Programs ............................................................................409 Writing the XSLT to Transform a Message ....................................................................414 Testing Transform Programs...........................................................................................423

Lesson 13

Lesson 14

Lesson 15

PeopleSoft Proprietary and Confidential

Integration Tools

Contents

Activity 20: Reviewing, Writing and Testing Transform Programs .........................425 Transforming a Message to a SOAP Request .................................................................431 Activity 21: Testing Transform Program from a SOAP Document ..........................439 Lesson 16 Working with Relationships .........................................................................................443 Describing Relationships.................................................................................................444 Creating Integration Points Using the Integration Point Wizard.....................................446 Viewing the Integration Point .........................................................................................454 Activity 22: Creating Integrations Using the Integration Point Wizard ....................456 Maintaining Relationships...............................................................................................464 Activity 23: Adding a Relationship Using the Relationship Component..................468 Applying Translations and Filtering ...........................................................................471 Describing Data Translation............................................................................................472 Describing Codesets ........................................................................................................474 Creating a Codeset Group ...............................................................................................477 Creating Codesets............................................................................................................483 Creating Codeset Values .................................................................................................485 Activity 24: Creating Codeset Groups, Codesets and Codeset Values .....................487 Writing a Transform Program for Data Translation........................................................492 Activity 25: Writing a Transform Program for Data Translation..............................495 Describing Filtering.........................................................................................................497 Writing a Transform Program for Filtering.....................................................................499 Activity 26: Applying Filtering .................................................................................501 Testing Connector and Message Processing Using Send Master ..............................507 Testing FILEOUTPUT Connector ..................................................................................508 Activity 27: Testing FILEOUTPUT Connector ........................................................510 Describing Send Master ..................................................................................................513 Identifying Send Master Workspaces..............................................................................516 Identifying Send Master Project Types ...........................................................................517 Creating an Input File Project .........................................................................................519 Activity 28: Creating Send Master Projects ..............................................................520 Creating an Integration Broker Project............................................................................524 Activity 29: Creating Integration Broker Projects in Send Master ...........................526 Creating Third-Party Integrations Using WSDL.......................................................533 Describing Web Services ................................................................................................534 Describing the Actional SOAPswitch .............................................................................538 Describing the Actional SOAPswitch Administration Console ......................................545 Adding Systems...............................................................................................................548 Adding a Web Service.....................................................................................................552 Creating Routing Data.....................................................................................................555 Completing the Integration..............................................................................................558 Activity 30: Creating a Web Service using Actional SOAPswitch...........................561

Lesson 17

Lesson 18

Lesson 19

vi

PeopleSoft Proprietary and Confidential

Contents

Integration Tools

Importing WSDL.............................................................................................................571 Lesson 20 Using PeopleSoft Published EIPs .................................................................................579 Describing PeopleSoft Published EIPs............................................................................580 Generating WSDL From Component Interfaces and Messages......................................581 Listing the Definitions Used with Component Interface WSDL Bindings .....................586 Defining the Third-Party Node........................................................................................588 Generating WSDL for Component Interfaces.................................................................590 Sending a SOAP Message to PeopleSoft ........................................................................592 Activity 31: Testing Component Interface WSDL Binding......................................595 Importing Data into the PeopleSoft System Using Flat Files ....................................601 Describing File Layouts ..................................................................................................602 Creating File Layouts ......................................................................................................608 Importing Data Using File Layouts.................................................................................614 Describing the Generated Application Engine PeopleCode............................................620 Running the Application Engine Program ......................................................................631 Activity 32: Using a File Layout to Import Data.......................................................634 Adding Field Attributes to a File Layout ........................................................................641 Activity 33: Importing a File with Field Attributes...................................................643 Writing Data to Flat Files .............................................................................................647 Listing the Methods Used to Read From and Write to Plain Text Files .........................648 Writing to Files Defined by a File Layout.......................................................................651 Creating Application Engine Programs to Export Data to Flat Files ..............................656 Activity 34: Writing Data to a File............................................................................657 Creating Multilevel File Layouts ....................................................................................660 Using PeopleCode with Multilevel File Layouts ............................................................665 Activity 35: Creating a Multilevel File Layout .........................................................668 Creating and Using Segments in File Layouts ................................................................672 Activity 36: Importing Data Using Segments ...........................................................677 Final Activity .................................................................................................................683 Activity 37: Using a Component Interface in Subscription PeopleCode ..................684 Course Review ...............................................................................................................693 Sample Code ..................................................................................................................695 STUDENT_PROFILE Component Interface Template..................................................696 STUDENT_PROFILE Component Interface Visual Basic Template ............................699 STUDENT_PROFILE Component Interface Java Template..........................................703 STUDENT_PROFILE.java.............................................................................................707 PO_TRANSFORM XSLT ..............................................................................................711 Integration Broker Troubleshooting Guide................................................................713 Publication Process Problems: ........................................................................................714 Subscription Process Problems .......................................................................................716

Lesson 21

Lesson 22

Lesson 23 Lesson 24 Appendix A

Appendix B

PeopleSoft Proprietary and Confidential

vii

Integration Tools

Contents

Other Possible Problems .................................................................................................718 Appendix C Appendix D Accessing CTE ...............................................................................................................721 Curriculum Map ...........................................................................................................725

viii

PeopleSoft Proprietary and Confidential

Preface

Integration Tools
Typographical Conventions and Visual Cues
This section discusses: Typographical conventions. Visual cues.

Typographical Conventions
This table contains the typographical conventions that are used in this guide:
Typographical Convention Bold Description Indicates PeopleCode function names, method names, language constructs, and PeopleCode reserved words that must be included literally in the function call. Indicates field values, emphasis, and PeopleSoft or other booklength publication titles. In PeopleCode syntax, italic items are placeholders for arguments that your program must supply. We also use italics when we refer to words as words or letters as letters, as in the following: Enter the letter O. KEY+KEY Indicates a key combination action. For example, a plus sign (+) between keys means that you must hold down the first key while you press the second key. For ALT+W, hold down the ALT key while you press the W key. Indicates a PeopleCode program or other code example. Indicate lesson and chapter titles in cross-references and words that are used differently from their intended meanings. Indicate that the preceding item or series can be repeated any number of times in PeopleCode syntax. Indicate a choice between two options in PeopleCode syntax. Options are separated by a pipe ( | ). Indicate optional items in PeopleCode syntax. When placed before a parameter in PeopleCode syntax, an ampersand indicates that the parameter is an already instantiated object. Ampersands also precede all PeopleCode variables.

Italics

Monospace font (quotation marks) . . . (ellipses) { } (curly braces) [ ] (square brackets) & (ampersand)

PeopleSoft Proprietary and Confidential

ix

Integration Tools

Preface

Visual Cues
Training courses contain the following visual cues. Notes Notes indicate information that you should pay particular attention to as you work with the PeopleSoft system. Note. Example of a note. If the note is preceded by Important!, the note is crucial and includes information that concerns what you must do for the system to function properly. Important! Example of an important note. Warnings Warnings indicate crucial configuration considerations. Pay close attention to warning messages. Warning! Example of a warning. Cross-References Training guides provide cross-references either under the heading See Also or on a separate line preceded by the word See. Cross-references lead to other documents, such as PeopleBooks, that are pertinent to the immediately preceding documentation. Example:

Example of cross-reference to a PeopleBook

Related Documentation
PeopleSoft applications are documented in PeopleBooks, which are delivered on the PeopleBooks CD-ROM. You can also order printed, bound versions of PeopleBooks through the Documentation section of the PeopleSoft Customer Connection website. You can find updates and additional documentation for each release on the PeopleSoft Customer Connection website. See Also PeopleSoft Customer Connection, http://www.peoplesoft.com/corp/en/login.asp

PeopleSoft Proprietary and Confidential

Lesson 1

Course Overview
Objectives
By the end of this course, you will be able to: Describe the PeopleSoft integration technologies. Integrate data with PeopleSoft and third-party systems using component interfaces. Configure PeopleSoft Integration Broker. Send and receive messages using PeopleSoft Integration Broker. Create integrations requiring transformations, translations and filtering. Test connector and message processing using the Send Master utility. Integrate with third-party systems using Web Services Definition Language (WSDL) files. Use flat files to integrate PeopleSoft data with PeopleSoft and third-party systems.

Slide 3 ________________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

Course Overview

Lesson 1

Agenda: Day One


On day one, we will provide an overview of customization and present these topics: Introducing PeopleSoft Component Interface. Creating and Testing Component Interfaces. Implementing Component Interfaces. Working with Component Interface Collections.

Slide 4 ________________________________________________________________________________________________________

Instructor Notes
This section describes: CTE Instructions for Integration Tools Course Manual Instructions for Training Database. Activity Dependencies

CTE Instructions for Integration Tools Course


Instructions for students to access the CTE are in Appendix A. In this course there are two databases, Training and Financials. Students have their own Training database, however there is only one shared Financials database. All files for the Integration tools course are located in the students folder under \tools\1022_IntTools. There is only one copy of the java servlet JavaCustomerServer.jar and it is located in the root of the z: drive. Instructor Logins
Login Type Instructor 1 Instructor 2 User name: TCA101 TCA201 Password: (upper case) TCA101 TCA201

Getting Assistance If you have not received your class ID and password, speak with your Education Center contact. If you have problems accessing Your Training environment assigned to your class, contact the Technical Support Operations at 925-694-2222.

PeopleSoft Proprietary and Confidential

Lesson 1

Course Overview

Integration Tools Course Environment There is a bat programs that are run as part of the refresh for this course 1022_Integration Tools.bat it is located in Instructor Tools folder. You do NOT have to run these, they will have already been done for you, this information is only to help you understand the environment and to use if you need to test a CTE that is shared by other course. This bat files are used to do the following necessary for this course: Enable pub/sub for all the training databases and FSCM 88 database. Start app engines configured in process scheduler. Start the Training databases and FSCM app server and process scheduler. Set PS_HOME environment variable.

Note. Do not run these bat files in the test environment (swim lanes for testing) or you will affect others using the CTE.

Manual Instructions for Testing


When you are testing in the CTE or you run into problems, here are the manual instructions for setting up the environment. Enabling Pub/Sub To enable pub/sub for a domain: 1. Double-click on the PeopleTools folder. 2. Double-click on PSADMIN icon. 3. Enter 1 for 1) Application Server then click ENTER. 4. Enter 1 for 1) Administer a Domain then click ENTER. 5. Select the number for your database then click ENTER. 6. Enter 4 for 4) Configure this domain then click ENTER. 7. Enter Y to shut down the domain and then click ENTER. 8. Enter 1 to change the Pub/Sub to Yes and then click ENTER. 9. Enter 11 for 11) Load configuration as shown and then click ENTER. You will see a message Domain configuration complete. 10. Enter 1 for 1) Boot this domain then click ENTER. You will see a message indicating the processes have started. 11. Enter Q and then click ENTER. 12. Enter Q and then click ENTER.

PeopleSoft Proprietary and Confidential

Course Overview

Lesson 1

Configuring Process Scheduler for AE If you just configured the application server domain, you will be in the correct place in PSADMIN, otherwise repeat steps 1&2 above. 13. Enter 2 for 2) Process Scheduler then click ENTER. 14. Enter 3 for 3) Configure a Process Scheduler Server and then click ENTER. 15. Select the database and then click ENTER. 16. Enter Y to continue and shut down the process scheduler and then click ENTER. 17. Enter Y to change config values and then click ENTER. 18. Click ENTER through the items until you reach: Do you want the Application Engines configured? 19. Enter Y and then click ENTER. 20. Click ENTER through the rest of the items. 21. Enter 1 1)Start a Process Scheduler Server and then click ENTER. 22. Select the database and then click ENTER. Starting the FSCM Application Server To start the FSCM application server: 1. Log on to CTE as the instructor TCA101. 2. Double-click on the PeopleTools folder. 3. Double-click on PSADMIN icon. 4. Enter 1 for 1) Application Server then click ENTER. 5. Enter 1 for 1) Administer a Domain then click ENTER. 6. Select the 19 T1F88050 and then click ENTER. 7. Enter 1 for 1) Boot this domain then click ENTER. You will see a message indicating the processes have started. Activity Dependencies In many of the activities in this course, students create application data that is necessary for subsequent activities. This table presents the dependencies between activities within this course:
Lesson 4 4 Activity 1 2 1 Required Activities Notes STUDENT_PROFILE Testing STUDENT_PROFILE

PeopleSoft Proprietary and Confidential

Lesson 1

Course Overview

Lesson 5 6

Activity 3 4

Required Activities 1&2

Notes PeopleCode STUDENT_PROFILE \scripts\StuProfile_pc.txt STU_PROFILE_2 \scripts\StuSkill_pc.txt CRS_ENROLL \scripts\crs_enroll_pc.txt

SDK_BUS_EXP compile and run Java C:\User\bat\compilejava.bat C:\User\bat\RunJava.bat

1&2

STUDENT_PROFILE C:\User\bat\compile_stu_profile.bat C:\User\bat\run_stu_profile.bat

8 8 10 10 10 11 12 13

7 8 9 10 11 12 13 14 12 12 4

CRS_SESSN (new) STU_PROFILE_2 Set up gateway URL Rename PSFT_TRN Add nodes for neighbor and PSFT_EP SCHOOL_SYNC SCHOOL_SYNC Publish PeopleCode for SCHOOL_SYNC \scripts\SchoolPublish_pc.txt

13 13 13 14 14 15

15 16 17 18 19 20

12 12

Subscription popleCode for SCHOOL_SYNC \scripts\SchSubscription_pc.txt Add asynchronous transactions Add synchronous transactions and send COUNTRY_SYNC

16

Send and monitor asynchronous transactions SCHOOL_SYNC and LOCATION_SYNC COURSE_SYNC

12 & 14 & 15

PO_SYNC, SDL_PO_SYNC, PO_TRANSFORM (existing) SCHOOL_TRANS - \scripts\school_xslt.txt

15 16

21 22

ZIP_RESPONSE (existing) P0_SYNC CUSTOMER_ASYNC to CUSTOMER_SYNCHRONOUS

16 17

23 24 22

PSFT_EP ORDER_STATUS

PeopleSoft Proprietary and Confidential

Course Overview

Lesson 1

Lesson 17 17 18 18 18

Activity 25 26 27 28 29

Required Activities 24 25

Notes PO_TRANSFORM \scripts\psft_function.txt LOCATION_SYNC (existing)PO_TRANSFORM add filtering LOCATION_SYNC QE_SYNC_MSG - \files\account_req.xml

12

QE_SYNC_MSG - \files\account_req.xml SCHOOL_SYNC - \files\school.xml

19 20 21 21 22 22 22 23

30 31 32 33 34 35 36 37 4

PSFT_CUST_SERVER - \files\JavaCustomerServer.jar STU_PROFILE_2 COURSE_FILE - \files\NEW_COURSE_FILE.txt, BAD_COURSE_FILE.txt, INVALID_COURSE_FILE.txt PSU_COURSE_CSV - \Files\COURSE.CSV COURSE_FILE (existing file layout) EXPORT_CRS\scripts\export_crs.txt EXPORT_PO - \scripts\export_po.txt SETID_TBL - \Scripts\setid_down.txt ITEM_SYNC (new message) STOCK_ITEM (new component interface) \scripts\itemsyncci.txt

PeopleSoft Proprietary and Confidential

Lesson 1

Course Overview

Agenda: Day Two


On day two, we will present these topics: Building Component Interface APIs. Using the Excel to Component Interface Utility. Introducing PeopleSoft Integration Broker architecture. Configuring PeopleSoft Integration Broker. Creating message channels and message definitions. Describing the PeopleSoft message format. Sending and receiving messages.

Slide 5 ________________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

Course Overview

Lesson 1

Agenda: Day Three


On day three, we will present these topics: Monitoring messaging performance using Integration Broker monitor. Applying transformations. Working with relationships. Applying translations and filtering.

Slide 6 ________________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

Lesson 1

Course Overview

Agenda: Day Four


On day four, we will present these topics: Testing connector and message processing using Send Master. Creating third-party integrations Using WSDL. Using PeopleSoft published EIPs.

Slide 7 ________________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

Course Overview

Lesson 1

Agenda: Day Five


On day five, we will present these topics: Importing data into PeopleSoft using flat files. Writing data to flat file. Final activity.

Slide 8 ________________________________________________________________________________________________________

10

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview
Objectives
By the end of this lesson, you will be able to describe: PeopleSoft integration technologies. PeopleSoft Integration Broker. Component Interfaces. WSDL integrations. File interfaces. Where to find information about PeopleSoft integration tools in PeopleBooks.

Slide 10 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

11

Technology Overview

Lesson 2

PeopleSoft Integration Technologies


PeopleSoft supports integration at three levels, people, process and data. This diagram displays PeopleSofts integration technologies:
Integration Overview
People Enterprise Portal

Process

Integration Broker

PeopleSoft Applications

3rd Party Applications

Legacy Environments

Trading Partner Services

Data

Enterprise Warehouse

PeopleSoft integration overview


Slide 11 _______________________________________________________________________________________________________

Instructor Notes
Discuss the technologies that are used for PeopleSoft integration: Enterprise Portal The people layer commonly referred to as the user interface layer, is primarily concerned with the aggregation and presentation of information. This information may take the form of application transactions, analytical reports or simple web content; each of these elements being presented in a user-friendly format based on their specific role based privileges. This level of integration is the goal of the PeopleSoft Enterprise Portal. The PeopleSoft Enterprise Portal aggregates business critical transactions and provides relevant context for more accurate, timely and effective business decisions. Enterprise Warehouse The data layer is primarily concerned with the extraction of key information from application databases and disparate data sources. This data is then warehoused for later analysis, typically using an off the shelf business intelligence tool. At PeopleSoft, the PeopleSoft Enterprise Warehouse product suite enables data level archiving, retrieval and analysis for the precise purpose of gaining insight into the inner workings and performance of your business. Integration Broker The process layer is that which handles the system-to-system communications so critical to the operation of any enterprise. This layer is squarely focused on optimizing existing business processes, and enabling new value-added operations through the powerful use of web technology. Although we rarely see the system-to-system communications, they are far more frequent and complex than the simple web based interfaces we are used to as users. This challenging venue is the domain of the PeopleSoft Integration Broker.

12

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

This course will focus on the Process layer.

PeopleSoft Proprietary and Confidential

13

Technology Overview

Lesson 2

PeopleSoft Integration Technologies (continued)


PeopleSoft offers a range of integration technologies to facilitate system-to-systems integration with PeopleSoft: PeopleSoft Integration Broker Component Interfaces WSDL integrations File Processing

Slide 12 _______________________________________________________________________________________________________

14

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

PeopleSoft Integration Broker


The PeopleSoft Integration Broker is the hub of PeopleSoft integration technology. It: Facilitates the use of web services for interacting with other systems. Uses standard Internet protocols. Sends XML over HTTP.

Slide 13 _______________________________________________________________________________________________________

Student Notes
Web Services are XML applications mapped to programs, objects or databases that send XML documents created in the form of a message across the network and optionally receive a reply in the form of an XML document.

PeopleSoft Proprietary and Confidential

15

Technology Overview

Lesson 2

PeopleSoft Integration Broker (continued)


The PeopleSoft Integration Broker is a message-based system that: Facilitates synchronous and asynchronous messaging with other PeopleSoft applications and with third-party systems. Interacts with web services in response to the invocation of business events within the component processor. Uses a variety of communication structures. Facilitates the transformation of messages to a PeopleSoft-compatible message format.

Slide 14 _______________________________________________________________________________________________________

Instructor Notes
The Integration Broker is the central point for all PeopleSoft integrations.

16

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

PeopleSoft Integration Broker (continued)


This diagram shows the four key elements of the Integration Broker:
Technical Architecture
Integration Broker

Messaging Gateway HTTP

PeopleSoft Applications

Transformation JMS Intellingent Routing FTP

3rd Party Applications Email

Legacy Systems

Custom

Development and Monitoring Engine

Technical architecture
Slide 15 _______________________________________________________________________________________________________

Student Notes
The PeopleSoft Integration Broker is comprised of four key elements: Connectors Intelligent routing Transformation Development and monitoring environment

PeopleSoft Proprietary and Confidential

17

Technology Overview

Lesson 2

Instructor Notes
Explain the four elements: Packaged connectors Routing Transformations Development and monitoring environment

Explaining Packaged Connectors All messages entering or leaving the Integration Broker pass through a single mechanism known as the Gateway. The Gateway is delivered with pre-built connectors to receive and transmit traffic using various standard protocols such as HTTP or JMS. More importantly, PeopleSoft provides an environment for the development of new connectors to legacy systems, ERP applications, and other web based systems. In addition, all PeopleSoft applications are built with integration in mind from the start. Whether you have CRM, HRMS, or another product line, PeopleSoft has pre-built interfaces that enable seamless communication between our applications and also between third-party systems. Explaining Routing Central to any messaging architecture is routing. Routing ensures that the incoming message is delivered to the right receiving system(s), and that the requesting system has the appropriate security privileges. Integration Broker also understands if the message needs to be sent in real-time (synchronous), or if it is deferrable (asynchronous), and manages the queuing of deferrable messages. The queue can even be set-up to handle message delivery based on pre-defined rules that assign differing priorities to message or system types (for example always customer order data messages first) Explaining Transformation Transformation is required to translate a message between different systems. This is much like translating a sentence from one language to another. The meaning of a sentence is the same in French or English, but unless some conversion is performed, neither person will understand the message. Similarly, the Integration Broker takes a system message and converts the data from one systems format into another systems format. With the PeopleSoft integration Broker, once an application has been mapped once, the Broker enables communication to any other system automatically. In the future, as the mapped system changes, there is only one place to modify the mapping, saving time and money. Explaining the Development and Monitoring Environment Integral to the Integration Broker architecture is a development and monitoring environment. Programmers to map the complex relationships between systems use the development environment. The developers determine how the broker should transform
18 PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

and route the messages, taking care to understand the various data schemas, and business process rules that must be managed. In addition, the monitoring environment is a dashboard for the entire messaging process, giving the user a picture of all messages moving in and out of the Broker. From this dashboard, administrators can view original messages, transformed messages, delivery status, or perform higher-level operations such as canceling delivery or resubmitting a message.

PeopleSoft Proprietary and Confidential

19

Technology Overview

Lesson 2

PeopleSoft Integration Broker (continued)


This diagram below shows the message protocols that are used with the messages:
PeopleSoft Internet Architecture
Business Object Integration Broker

Outbound Async Connectors Inbound Async Consumer Sync Provider Sync CSV

ERP Application MQ Series Legacy Application Trading Partner Application WSDL Line of Business Application

OAG XML SOAP

Integration Broker messaging protocols


Slide 16 _______________________________________________________________________________________________________

Instructor Notes
The Integration Broker has the capability to communicate with third-party systems using XML, CSV and SOAP. ERP connectors use the Actional SOAPswitch, which will show in lesson 19. In this course, the Integration broker is covered in lessons 10 thru 20. In those lessons, students will set up the integration gateway, create messages, and transform messages.

20

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

Component Interfaces
Component Interfaces provide a non-graphical way to access the PeopleSoft database. This diagram shows how the Component Interfaces encapsulates the component:
Component Interface Component PeopleCode

PS

Component Interface architecture


Slide 17 _______________________________________________________________________________________________________

Instructor Notes
The component in PeopleSoft provides all of the business rules, through PeopleCode and edits, for interacting with the PeopleSoft database. The components are based on pages and presented to the user through the PeopleSoft Internet Architecture to view and update. The component interface takes this same functionality and exposes it to third-party systems in a non-graphical manner.

PeopleSoft Proprietary and Confidential

21

Technology Overview

Lesson 2

Component Interfaces (continued)


Component interfaces: Enforce all of the business rules defined on the component. Provide synchronous access to the PeopleSoft database. Provide access to PeopleSoft components through APIs.

Slide 18 _______________________________________________________________________________________________________

22

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

WSDL Integrations
PeopleSoft provides: ERP connectors to J2EE, XML, SAP, Siebel and Oracle. Ability to import web services using WSDL. WSDL for PeopleSoft published Enterprise Integration Points (EIPs). A WSDL repository of all configured web services.

Slide 19 _______________________________________________________________________________________________________

Instructor Notes
WSDL integrations will be discussed in lessons 19 and 20. Explain the following points: ERP connectors are available using the Actional SOAPswitch- a third-party product delivered with PeopleTools 8.44. This provides outbound integrations to these third-party systems. WSDL can be imported from any file or URL. Imported WSDL is used for outbound integrations. PeopleSoft publishes EIPs for all PeopleSoft messages and component interfaces. These provide the ability for third-party systems to use the WSDL to create inbound integrations. The WSDL repository stores all of the imported WSDL. Web services are created from this WSDL by adding the routing data to map the transactions to PeopleSoft nodes and messages.

PeopleSoft Proprietary and Confidential

23

Technology Overview

Lesson 2

File Interfaces
File-based integrations provide the ability to exchange files with third-party system or legacy systems that do not support messaging. Files are exchanged using: File layouts Application Engine programs

Slide 20 _______________________________________________________________________________________________________

Instructor Notes
File layouts are used to graphically define where data is located in a file. The file definition layout is then accessible to the Application Engine program to import or export the file. File layouts are discussed in lessons 21 and 22.

24

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

File Interfaces (continued)


File layouts support the following file types: Fixed format sequential files Comma delimited files XML files

Slide 21 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

25

Technology Overview

Lesson 2

File Interfaces (continued)


This diagram shows how an application engine program can be used to read and process a file:
PeopleSoft Application Server

EIP

Application Engine

Subscription PeopleCode

Map to Message Publish to Self

Component Interface

Read File

File

SQL Insert

Importing a file into the PeopleSoft system


Slide 22 _______________________________________________________________________________________________________

Instructor Notes
Explain the diagram: A file is read by the application Engine program based on the PeopleCode, you can do any of the three methods: SQL insert directly into a PeopleSoft table. Process the file through a component interface (all of the business logic is executed). Read the file into a message, publish the message to the same database and the subscription PeopleCode is used to update the database. The subscription PeopleCode could use component interfaces as well.

26

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

Finding Information About PeopleSoft Integration Tools in PeopleBooks


Use the PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker to find development information including: Configuring PeopleSoft Integration Broker. Creating message definitions and message channels. Sending and receiving messages. Appendixes.

Slide 23 _______________________________________________________________________________________________________

Student Notes
This table lists the locations of additional information in the PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker. Note that the chapters and topics listed are not all of those that are contained in the PeopleBook.
Location Understanding PeopleSoft Integration Broker Type of Information This chapter discusses: PeopleSoft Integration Broker. Integration gateway architecture. Integration engine architecture. Configuring the Messaging System This chapter discusses how to set up dedicated messaging servers for asynchronous communications. If you work with synchronous messages only, you do not need set up dedicated messaging servers. This chapter discusses how to: Create and assign dedicated servers. Edit messaging server channel lists. Delete unneeded messaging servers. Configure messaging servers in PSADMIN. Set the Tuxedo queue size for the pub/sub system. Throttle dispatched messages through the Pub/Sub system. Managing the Integration Gateway This chapter provides information about the following topics: Defining an integration gateway. Loading connectors. Refreshing the integration gateway. Accessing the integration gateway properties file. Encrypting integration-related passwords. Configuring integration gateway properties. Working with target connectors. Working with listening connectors.

PeopleSoft Proprietary and Confidential

27

Technology Overview

Lesson 2

Location Defining Message Channels and Messages

Type of Information This chapter provides overviews of messages and message channels and discusses how to: Define a message channel. Configure a message channel. Apply channel partitioning. Receive a subset of messages. Define a message. Define message versions. Use records in a message definition. Configure message properties. Access message PeopleCode.

Sending and Receiving Messages

This chapter provides overviews of sending and receiving messages and PeopleSoft Common Application Message Attributes (PSCAMA). Topics in this chapter include how to: Generate and send messages. Receive and process messages.

Using the Integration Point Wizard Using the Integration Point Viewer

This chapter discusses the Integration Point Wizard and describes how to: Create integrations using the Integration Point Wizard. Access relationships created by the Integration Point Wizard. This chapter describes the Integration Point Viewer and discusses how to: Access integrations. View integration information. View inactive objects. Activate inactive objects.

Administering Basic Integrations

This chapter provides an overview of integration administration and discusses how to: Configure nodes. Configure transactions.

Using Integration Broker Monitor

This chapter provides an overview of Integration Broker Monitor. Topics in this chapter include how to: Monitor message system information. Monitor asynchronous message details. View synchronous message details. View messaging system performance statistics.

28

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

Location Creating Third-Party Integrations Using WSDL

Type of Information PeopleSoft provides you with the ability to create inbound and outbound integrations with third-party systems, including enterprise resource planning (ERP) systems, using Web Services Description Language (WSDL). Topics in this chapter include how to: Perform Integrations using WSDL. Use Actional SOAPswitch. Generate WSDL using ERP connectors. Import WSDL into PeopleSoft. Use the WSDL repository. Creating service transaction metadata for imported WSDL. Generate WSDL from PeopleSoft component interfaces and messages.

Using Send Master to Test Message and Connector Processing Administering Relationships

This chapter discusses the Send Master utility. Topics include how to Start Send Master. Navigate in Send Master. Create Send Master projects. This chapter provides an overview of relationships and discusses how to: Configure a relationship. Inactivate a relationship. Manage transaction modifiers.

Applying Filtering, Transformation and Translation

This chapter provides overviews of filtering, transformation, and translation and the PeopleSoft base message format, and discusses how to: Develop transform programs. Filter messages and generate errors. Apply transformations. Perform data translation. Test and debug transform programs.

Appendix: Integration Scenarios

This appendix provides an overview of the basic integration scenarios you can implement using PeopleSoft Integration Broker and discusses how to: Integrate with PeopleSoft Integration Broker systems. Integrate with PeopleSoft Integration Broker systems through a firewall. Integrate with PeopleSoft Integration Broker systems by using hubs. Integrate with third-party systems. Integrate with third-party systems by using remote gateways. Integrate with PeopleSoft 8.1x systems.

Appendix: Guidelines for Developing Transformations

This appendix provides guidelines on how to create and use Application Engine Transform programs and the PeopleSoft Integration Broker transformation engine to transform an XML data structure into almost any desired format.

You can access related material by clicking the Help link in the top, right corner of the application page. This automatically takes users to the relevant information in the appropriate PeopleBook.

PeopleSoft Proprietary and Confidential

29

Technology Overview

Lesson 2

Note. Context-sensitive help is constrained to non-application specific pages in the technical database.

30

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

Finding Information About PeopleSoft Integration Tools in PeopleBooks (continued)


Use the PeopleTools 8.44 PeopleBook: PeopleSoft Component Interface to find development information including: Programming component interfaces for Java, COM and C++. Using the component interface software development kit (SDK). Using the Excel to Component Interface Utility. WSDL Bindings for Component Interfaces.

Slide 24 _______________________________________________________________________________________________________

Student Notes
This table lists the locations of additional information in the PeopleTools 8.44 PeopleBook: PeopleSoft Component Interface. Note that the chapters and topics listed are not all of those that are contained in the PeopleBook.
Location Introducing PeopleSoft Component Interfaces Developing the Component Interface Type of Information This chapter discusses: Component interface architecture. Component interface concepts, such as names and properties. Component interface definition in PeopleSoft Application Designer. This chapter discusses how to: Create a component interface definition. Use component interface keys, properties, collections and methods. Validate a component interface. Set component interface security. Test the component interface. Understand runtime considerations. Programming Component Interfaces in Java This chapter discusses how to: Build the component interface APIs. Set up the Java environment. Generate a Java runtime code template. Use and understand the generated Java code. Programming Component Interfaces in C++ This chapter discusses how to: Build the component interface APIs. Set up the C++ environment. Generate a C++ runtime code template. Use and understand the generated C++ code.

PeopleSoft Proprietary and Confidential

31

Technology Overview

Lesson 2

Location Programming Component Interfaces in COM

Type of Information This chapter discusses how to: Build the component interface APIs. Set up the COM environment. Generate a Visual Basic runtime code template. Use and understand the generated Visual Basic. Code.

Using the Component Interface Software Development Kit (SDK) Programming Component Interfaces in PeopleCode Using the Excel to Component Interface Utility

This chapter discusses how to: Set SDK prerequisites. Use the SDK_BUS_EXPENSES test page. Test the SDK_BUS_EXP component interface. Use the component interface SDK Java sample. This chapter discusses: PeopleCode behavior and limitations. PeopleCode runtime code template. PeopleSoft runtime code template. This chapter discusses how to: Set up connection information. Create a template. Manage a template. Stage and submit data. Resubmit corrected data. Construct the SOAP/XML request. Send the SOAP/XML request and receive the SOAP/XML response.

WSDL Bindings for Component Interfaces

This chapter contains an overview of the PeopleSoft implementation of the WSDL (Web Services Description Language) specification for the set of SOAP (Simple Object Access Protocol) transactions exposed for component interfaces and covers: Setting up Integration Broker. Creating the third-party message node. Adding security to the PeopleSoft objects.

You can access related material by clicking the Help link in the top, right corner of the application page. This automatically takes users to the relevant information in the appropriate PeopleBook. Note. Context-sensitive help is constrained to non-application specific pages in the technical database.

32

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

Finding Information About PeopleSoft Integration Tools in PeopleBooks (continued)


Use the PeopleTools 8.44 PeopleBook: PeopleSoft Application Designer to find development information including: Constructing file layouts. Specifying file layout, record, and field properties. Performing data interchanges.

Slide 25 _______________________________________________________________________________________________________

Student Notes
This table lists the locations of additional information in the PeopleTools 8.44 PeopleBook: PeopleSoft Application Designer. Note that the chapters and topics listed are not all of those that are contained in the PeopleBook.
Location Constructing File Layouts and Performing Data Interchanges Type of Information This chapter provides an overview of file layouts and discusses how to: Construct file layouts. Specify file layout, record, and field properties. Perform data interchanges. Produce a sample file layout.

You can access related material by clicking the Help link in the top, right corner of the application page. This automatically takes users to the relevant information in the appropriate PeopleBook. Note. Context-sensitive help is constrained to non-application specific pages in the technical database.

PeopleSoft Proprietary and Confidential

33

Technology Overview

Lesson 2

Finding Information About PeopleSoft Integration Tools in PeopleBooks (continued)


The following PeopleBooks contain information that applies to PeopleSoft Application Designer 8.44 and application development using PeopleTools: PeopleTools 8.44 PeopleBook: PeopleSoft Application Designer PeopleTools 8.44 PeopleBook: Security Administration PeopleTools 8.44 PeopleBook: Internet Technology PeopleTools 8.44 PeopleBook: PeopleCode Developer's Guide

Slide 26 _______________________________________________________________________________________________________

Student Notes
This table describes the additional PeopleBooks that contain information about PeopleSoft Application Designer and application development using PeopleTools.
PeopleBook PeopleTools 8.44 PeopleBook: PeopleSoft Application Designer PeopleTools 8.44 PeopleBook: Security Administration PeopleTools 8.44 PeopleBook: Internet Technology PeopleTools 8.44 PeopleBook: PeopleCode Developer's Guide Description This PeopleBook describes the fundamental elements of developing applications for PeopleSoft Internet Architecture. This PeopleBook describes the interface, tables, and other components associated with PeopleSoft security and how you can use them to secure pages, fields, and other definitions. This PeopleBook describes PeopleTools internet technology, including PeopleSoft Internet Architecture (PIA) and PeopleTools portal technology used for creating and managing portals. This PeopleBook covers the concepts of PeopleCode, tips for using PeopleCode, the interaction of PeopleCode and the Component Processor, and a number of other specialized topics, such as the use of the PeopleCode debugger and referencing data in the component buffer.

34

PeopleSoft Proprietary and Confidential

Lesson 2

Technology Overview

Review
In this lesson, you learned that: PeopleSoft offers a range of integration technologies to facilitate system-to-systems integration with PeopleSoft including Integration Broker, Component Interfaces, Web services and file interfaces. The PeopleSoft Integration Broker is the hub of PeopleSoft integration technology by facilitating the messaging with other systems. Component Interfaces provide a non-graphical way to access the PeopleSoft database. PeopleSoft supports Web services using WSDL integrations with third-party systems. Application Engine programs using the file layout object allow files to be imported and exported.

Slide 27 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

35

Technology Overview

Lesson 2

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

36

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces


Objectives
By the end of this lesson, you will be able to: Describe PeopleSoft Component Interfaces. Describe the PeopleSoft Component Interface architecture. List the elements of a component interface definition. Describe component interface keys. Describe properties and collections in a component interface. Describe methods for a component interface.

Slide 29 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

37

Introducing PeopleSoft Component Interfaces

Lesson 3

Describing PeopleSoft Component Interfaces


PeopleSoft Component Interfaces expose PeopleSoft data to external applications by: Providing real-time synchronous access to the PeopleSoft business rules and data. Enforcing all business rules (PeopleCode). Exposing PeopleSoft methods and properties to external applications without the use of a graphical user interface (GUI).

Slide 30 _______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Introducing Component Interfaces.

Instructor Notes
PeopleSoft Component Interfaces provide a simple way to access PeopleSoft componentsincluding all business rules and datawithout using PeopleSoft Internet Architecture pages. It is the focal point for externalizing access to PeopleSoft business logic. A component interface extends the reach of business processes beyond the users of PeopleSoft applications. It enables users throughout an organization to use third-party applications to process information through PeopleSoft Internet Architecture pages. Providing Real-Time Access Component interfaces are an evolution of the Message Agent feature (which is the technology used before PeopleSoft 8). They provide real-time synchronous access through an external application (for example, a Visual Basic or Java program) to PeopleSoft business rules and the data that is associated with components. Enforcing Business Rules You use a component interface to provide external systems with the same real-time access to business rules and data as the online system. When a component interface performs a save, the system enforces the same business logic that is used for the online page. (A few exceptions exist for events that relate only to the online system; they are discussed in the lesson on implementing component interfaces.) The data is saved to the PeopleSoft database only if it meets all of the criteria. See lesson 5, Implementing PeopleSoft Component Interfaces. Exposing Methods and Properties Component interfaces expose PeopleSoft methods (PeopleCode) and properties (data items) to external systems in a nongraphical manner.

38

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

Describing PeopleSoft Component Interfaces (continued)


A component interface is a wrapper for a component in the PeopleSoft system. It encapsulates all of the business logic associated with the component, as shown in this diagram:
Component Interface Component PeopleCode

PS

Component interface wrapper


Slide 31 _______________________________________________________________________________________________________

Student Notes
Components combine multiple pages.

Student Personal Information component with three pages

PeopleSoft Proprietary and Confidential

39

Introducing PeopleSoft Component Interfaces

Lesson 3

Instructor Notes
In the online system, pages are grouped in components. When a user navigates to a component, the user can access all of the pages and fields to which the user has been granted security rights. Point students to the Student Personal Information component, as shown in the student notes. This component contains three pages where you can enter or update data. The component contains not only the various fields and pages but also the underlying PeopleCode that provides the business logic associated with the component. Component interfaces are wrappers that encapsulate PeopleSoft data and business processes; they hide details of the structure and implementation of pages and the underlying data. Component interfaces are an important way of exposing existing portions of a PeopleSoft application to an external system, such as a third-party vendor or a web application.

40

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

Describing PeopleSoft Component Interfaces (continued)


This diagram shows the PeopleSoft Component Interfaces flow:
Methods and properties exposed to the outside Component Interface External Applications Component PeopleCode Bindings COM (VB) C/C++ Java PS

API

Online Users

PeopleSoft Component Interfaces flow


Slide 32 _______________________________________________________________________________________________________

Student Notes
External applications can access a component interfaces data only by using the component's specified properties or methods. These include: Properties, which are data items or fields (attributes). Collections, which are scroll areas or levels. Methods, which are PeopleCode functions.

Instructor Notes
Review the diagram and note the following points: In the online system, a user enters data on a page (in a GUI). Any online edits and validation for fields occur in real time as the user enters data. Alternatively, deferred processing occurs if the page has been configured that way. The page is part of a component. When the user clicks the Save button, any associated PeopleCode is initiated to validate the data.

PeopleSoft Proprietary and Confidential

41

Introducing PeopleSoft Component Interfaces

Lesson 3

If the validation is successful, the data is saved. A component interface can be thought of as an automated online user. Rather than having the GUI impose the business rules, these business rules are exposed using properties and methods. Explaining Component Interfaces A component interface can map to only one PeopleSoft component. It is intended to hide (or encapsulate) the underlying record and field structures so that they can be changed from release to release without changing the component interface. The key benefit of component interfaces is that they provide a definitional way to access the data and business rules within a PeopleSoft system. This kind of interfacewhich is separate from the GUIprovides greater flexibility and reliability when connecting an external system to a PeopleSoft system. Describing APIs An API can be defined as a set of routines, protocols, and tools for building software applications. The PeopleSoft system supports component interface APIs in: Microsoft COM, through: Visual Basic. ASP.

This is a specification for a dynamically created web page with the .ASP extension. It uses ActiveX scriptingusually VB Script or Jscript code. When a browser requests an ASP, the web server generates a page with HTML code and sends it back to the browser. ASPs are similar to CGI scripts, but they enable Visual Basic programmers to work with familiar tools. C and C++ (PeopleTools 8.10 and later). Java binding (PeopleTools 8.12 and later).

Example Suppose that a company has a purchase order system written in Visual Basic or C. This custom application can use a component interface to connect to the database to retrieve, update, and enter data. The component interface follows the business rules and security rights in the database. If the PeopleSoft system is upgraded later, the external program can communicate with the PeopleSoft application using the same (or nearly the same) component interface, even if the underlying PeopleSoft components have changed. Exposing Methods and Properties When you implement PeopleSoft Component Interfaces, components and the runtime page processor perform the same tasks that they do in the online environment. Externally, however, the component interfaces reveal only an interface, which consists of clearly defined properties and methods that follow an object-oriented programming model.

42

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

Properties Component interface properties are the data items that describe a component interface and map to the data in the page buffer associated with the component. Properties can be either fields or collections; these correspond to component record fields and scrolls, respectively. Standard properties (which are discussed later in the lesson) come with every component interface. Methods Methods perform functions for a component interface, such as creating a new purchase order, approving a purchase order, saving a purchase order, and so on. There are standard methods and user-defined methods. Executing PeopleSoft Component Interfaces PeopleSoft Component Interfaces can run in either two-tier or three-tier mode. The component interfaces are programmable through a C interface, an OLE/COM interface, Java and PeopleCode. Application Engine programs, message programs, and any other PeopleCode programs can use component interfaces. Question: Describing PeopleSoft Component Interfaces Component interfaces validate data before updating PeopleSoft data tables. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

43

Introducing PeopleSoft Component Interfaces

Lesson 3

Describing the PeopleSoft Component Interface Architecture


This diagram shows the three fundamental pieces of the overall PeopleSoft Component Interfaces architecture:
Component Component Search Keys Fields and Levels PeopleCode Functions Component Interface Keys Properties and Collections Methods API

PeopleSoft Application PeopleCode External Application COM C/C++ Java

PeopleSoft Component Interfaces architecture


Slide 33 _______________________________________________________________________________________________________

Student Notes
The three fundamental pieces of the overall PeopleSoft Component Interfaces architecture are:
Element Component Component interface Description Every component interface is based on a component. A component interface is based on a single component Its composition closely matches the component, but different terms are used to describe some of the pieces. Unlike components, component interfaces are readily accessible by internal and external applications. This is the API through which other applications have real-time access to PeopleSoft Component Interfaces. The component interface API supports the following environments: PeopleCode. Microsoft COM (Visual Basic and Active Server Pages). C and C++. Java.

Component interface application programming interface (API)

Instructor Notes
This section discusses the PeopleSoft Component Interfaces architecture.

44

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

A component interface represents a recognizable entity from the business world, such as a customer, sales order, invoice, or employee. The component interface API enables external programs to access PeopleSoft data by referring to these recognizable business entities, completely independent of the physical layout of any page. This section introduces new terminology that is used with component interfaces and relates the terminology to the existing components. Mapping Components to Component Interfaces In the online system, search keys are used to find the data that the online user wants to access. In the component interface, these search keys are directly mapped to keys. In the online system, fields and levels are displayed on the page. These fields and levels correspond to properties (fields) and collections (scroll areas or levels, such as level 1, level 2, and so on). Properties are data items or fields (attributes). Collections are scroll areas, levels, or records. PeopleCode functions are used to enforce the business logic of a component in the online system. In the component interface, PeopleCode functions are mapped to methods. Methods are PeopleCode (functions). Explaining the Component Interface API The component interface API is the API through which other applications have real-time access to PeopleSoft Component Interfaces. See lesson 7, Building Component Interface APIs. Using Component Interfaces with PeopleSoft Applications Component interfaces can be used within the PeopleSoft database to expose one component to another. When used in conjunction with a single PeopleSoft database, PeopleCode is used to expose the component. Question: Describing the PeopleSoft Component Interfaces Architecture A component interface is based on a single component. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

45

Introducing PeopleSoft Component Interfaces

Lesson 3

Listing the Elements of a Component Interface Definition


A component interface definition has four main elements: Component interface name Keys Properties and collections Methods

Slide 34 _______________________________________________________________________________________________________

Student Notes
Each component interface definition is based on a single component, as shown in this example:

Sample component interface STUDENT_CI (based on the component PSU_STUDENT)

Instructor Notes
This section discusses the four main elements of a component interface definition.

46

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

Component Interface Name As with every other definition in PeopleTools, each component interface must have a name. The component interface name is used to access the component interface. It should accurately identify the business entity that it describes. Keys Keys define the values that uniquely identify an instance of a component interface. When you create a new component interface in PeopleSoft Application Designer, the system creates component interface keys that are based on the associated components search record. You can add or modify keys, if necessary. Properties and Collections Properties are the individual data items (fields) that describe a component interface. Each property maps to a single field in the component interfaces underlying component. A collection is similar to a property, but instead of mapping to an individual field, it points to a scroll. Question: Listing the Elements of a Component Interface Definition Which of the following is not an element of a component interface definition? 1. Keys 2. Methods 3. API 4. Properties and collections Answer The answer is 3 (API). An API is generated separately; it is not an element of the component interface.

PeopleSoft Proprietary and Confidential

47

Introducing PeopleSoft Component Interfaces

Lesson 3

Describing Component Interface Keys


There are three types of keys used with component interfaces. The keys are automatically created for a component interface based on the underlying component.
Component Interface Key Get key Create key Find key Mapping to Component Maps to the Search key in the components search record. You cannot change the Get keys. Maps to the search record keys if the component allows the Add action. You cannot change the Create keys. Maps to fields marked as both Alt and Srch in the component search record. You can remove Find keys that you do not want to make available for searching.

Slide 35 _______________________________________________________________________________________________________

Student Notes
The component interface keys are automatically populated based on the components search record:

Component Interface keys for STUDENT_PROFILE The Get and Create keys are based on the Search record and actions defined on the component:

Component properties The Find keys are based on the Alt and Srch keys defined on the search record:

48

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

Search record keys

Instructor Notes
Explain the relationship of the keys: The component PSU_STUDENT has the actions Update/Display and Add. The Update/Display action indicates Get keys exist. The Get keys are obtained from the primary search keys for the record. The Add action indicates that Create keys exist. The Create keys are obtained from the primary search keys for the record. Find keys are generated from the Alternate Search keys for the record.

Question: Describing Component Interface Keys All component interfaces have Get keys, Find keys, and Create keys. 1. True 2. False Answer The answer is 2 (false). Create keys are present only when the Add action is indicated in the underlying component.

PeopleSoft Proprietary and Confidential

49

Introducing PeopleSoft Component Interfaces

Lesson 3

Describing Component Interface Properties and Collections


Properties and collections are used to expose the PeopleSoft data (namely, records and fields) to external systems. Note the following points: Properties are individual data items (fields). Each property maps to a single field in the component interfaces underlying component. A collection is similar to a property; however, instead of mapping to a field, it points to a scroll area.

Slide 36 _______________________________________________________________________________________________________

50

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

Describing Component Interface Properties and Collections (continued)


There are two main types of properties: User-defined properties Standard properties

Slide 37 _______________________________________________________________________________________________________

Instructor Notes
The next two slides explain user-defined and standard properties.

PeopleSoft Proprietary and Confidential

51

Introducing PeopleSoft Component Interfaces

Lesson 3

Describing Component Interface Properties and Collections (continued)


User-defined properties are the points where the component and the underlying database are exposed to the external system. You can define user-defined properties by either: Accepting default properties when you create a new component interface. Dragging the fields or scroll levels from the component into the component interface.

Slide 38 _______________________________________________________________________________________________________

Student Notes
User-defined properties are exposed in the component interface by dragging the property or scroll level from the component (on the left) to the component interface (on the right).

Properties, which include fields and collections (records) Note. The component interface uses the user-defined properties to add or change fields and data in the database. Also note these points: The exposed properties appear at each scroll level. You can expand or collapse a collection in the component interface view.

52

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

You can remove properties that you do not want to expose in the component interface. Every user-defined property in a component interface definition can be used as a property in the object instantiated from that component interface at runtime.

Instructor Notes
This section discusses user-defined properties. User-defined properties are any properties that you expose in the component interface. When you create a new component interface, the system prompts you to accept the defaults. If you click OK, the properties are defined for you (that is, they are exposed in the component interface). It does not matter where you insert the definition in the component interface view. The system converts the field or record into a component interface property and places it in the appropriate place in the list of properties. Also, when you drag a definition from the component view into the component interface view, all child definitions are brought into the component interface automatically. Once these child properties are added to the component interface, you can remove each property individually, if desired. Dragging a key from the search record, which precedes the level 0 record in the page view, adds a key to all appropriate key collections (Get, Create, and Find) in the component interface. Because appropriate keys are added automatically when a component interface is first created, you typically must add keys only if the new keys are added to the underlying component after the creation of the component interface. Every user-defined property in a component interface definition can be used as a property in the object instantiated from that component interface at runtime. At runtime, you can use PeopleCode to assign a value to that property (field), or to access the value of that field, as shown in the following example:
&MYCI.COUNTRY = "USA"; /* OR */

&COUNTRY = &MYCI.COUNTRY;

Note. When you accept the defaults for properties when creating a component interface, not all fields are added as properties. Image fields and record level auto update fields (typically SYNCID and SYNCDTTM) are not added. Also note that the properties are displayed in alphabetical order initially, after you save, they will be displayed in the same order as the record.

PeopleSoft Proprietary and Confidential

53

Introducing PeopleSoft Component Interfaces

Lesson 3

Describing Component Interface Properties and Collections (continued)


Every component interface comes with a standard set of properties. These properties include: Properties that affect how the component interface is run. Properties that return information about the structure of the component interface.

Slide 39 _______________________________________________________________________________________________________

Student Notes
The following properties affect how the component interface is run: EditHistoryItems GetHistoryItems InteractiveMode

The following properties return information about the structure of the component interface: CreateKeyInfoCollection FindKeyInfoCollection GetKeyInfoCollection PropertyInfoCollection

Instructor Notes
At this point, it is important for students to understand terminology. They should also understand that standard properties could be used in code (such as PeopleCode, Visual Basic, Java, and so forth) depending on where the component interface is used. PeopleCode is discussed in more detail later in the course. See lesson 5, Implementing Component Interfaces. This section discusses the standard properties. Properties That Affect How a Component Interface Is Run These properties must be set before the component interface is populated with data. That is, you must set these properties before you use the Get or Create methods. EditHistoryItems and GetHistoryItems work together to determine how data is accessed: If EditHistoryItems is False (the default) and GetHistoryItems is True, you access the data in the component interface as if you were accessing a component in Update/Display All mode.

54

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

This means that all history rows are returned; however, you can edit rows only with a date set in the future. If EditHistoryItems is True and GetHistoryItems is True, you access the data in the component interface as if you were accessing a component in Correction mode. This means that all history rows are returned, and you can edit them. If GetHistoryItems is False, you access the data in the component interface as if you were accessing a component in Update mode. The EditHistoryItems has no effect when GetHistoryItems is False. InteractiveMode causes the component interface to emulate an online component. For example, if you set a value for a field in a component interface and you have set InteractiveMode to True, then any FieldChange PeopleCode programs associated with that field are initiated as soon as you set that value. Properties That Return Information About the Structure of the Component Interface These properties are used to retrieve information from collections. Question: Describing Component Interface Properties and Collections Properties and collections in a component interface directly relate to which of the following in the underlying component? 1. Component search keys. 2. Fields and scrolls. 3. PeopleCode functions. 4. Level-1 and level-2 scrolls. Answer The answer is 2 (fields and scrolls).

PeopleSoft Proprietary and Confidential

55

Introducing PeopleSoft Component Interfaces

Lesson 3

Describing Component Interface Methods


Component interface methods are functions that can be called to perform operations in a component interface. Two types of methods exist: Standard These are created automatically for each component interface. User-defined These are defined manually in PeopleCode.
Slide 40 _______________________________________________________________________________________________________

Student Notes
Standard methods are created automatically when you create a new component interface. You can indicate which standard methods to activate with the component interface.

Standard methods

Instructor Notes
This section discusses standard methods and user-defined methods. Standard Methods Standard methods perform operations that are common to all component interfaces. For example, they indicate the mode in which to operate the component interface, and they handle creating and saving a component interface. User-Defined Methods User-defined methods are PeopleCode programs that you can write to perform operations on a component interface. Each method is specific to a particular component interface. When you create component interfaces in the next lesson, you show students how to create their own methods in PeopleCode.

56

PeopleSoft Proprietary and Confidential

Lesson 3

Introducing PeopleSoft Component Interfaces

Question: Describing Component Interface Methods Component interface methods are functions that perform operations on a component interface. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

57

Introducing PeopleSoft Component Interfaces

Lesson 3

Review
In this lesson, you learned that: Component interfaces expose PeopleSoft data to external applications in real time. Component interfaces expose PeopleSoft logic and data to external systems by encapsulating the component and exposing specific fields and records. Component interface definitions comprise the following elements: Component name Keys Properties and collections Methods

Component interface keys are based on the component search record and associated actions. Properties and collections expose the data fields and records. A component interface method performs a specific function on a component interface at runtime.

Slide 41 _______________________________________________________________________________________________________

58

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces


Objectives
By the end of this lesson, you will be able to: List the steps for creating applications that use component interfaces. Design component interface applications. Create or modify supporting definitions. Create component interfaces. Set component interface security. Test component interfaces.

Slide 43 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

59

Creating and Testing Component Interfaces

Lesson 4

Listing the Steps for Creating Applications That Use Component Interfaces
Use the following steps to create applications that use component interfaces: 1. Design the application that uses a component interface. 2. Create or modify any supporting definitions that are necessary. 3. Create the component interface. 4. Apply security for the component interface. 5. Test the component interface in PeopleSoft Application Designer. 6. Write the PeopleCode to instantiate the component interface. 7. Test the PeopleCode.
Slide 44 _______________________________________________________________________________________________________

Instructor Notes
This lesson covers steps 15. Steps 6 are 7 are covered in the next lesson. See lesson 5, Implementing Component Interfaces. This section presents a review question for the current objective. Question: Listing the Steps for Creating Applications That Use Component Interfaces How many steps are needed to develop applications that use component interfaces? 1. Four 2. Five 3. Six 4. Seven Answer The answer is 4 (seven).

60

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Designing Component Interface Applications


The first step is to design the application. You must perform these tasks: Create the business process model for the application. Identify any new definitions that need to be created. Identify any existing definitions that need to be modified. Document all definitions affected by the application.

Slide 45 _______________________________________________________________________________________________________

Student Notes
This diagram shows the business process for adding employees and enrolling them in training courses:

Personnel Administrator

Add Employee

Add Employee Information

Enroll Employee in training Training Coordinator

Does employee have a student_id? No

Yes

Enroll employee in the Training course

Create new STUDENT_ID

Sample business process In your new design, you want the system to automatically create a student ID for each new employee, as shown in this diagram:

PeopleSoft Proprietary and Confidential

61

Creating and Testing Component Interfaces

Lesson 4

Personnel Administrator

Add Employee

Add Employee Information

Create new STUDENT_ID

Training Coordinator

Enroll Employee in training

Enroll employee in the Training course

Modified business process The following definitions are currently used in the business process:
Definition Type Component Component Definition Name PERSONAL_DATA PSU_STUDENT

Instructor Notes
The student notes show a sample business process (the one that students use when they perform the activity). Once they understand the process, they need to identify all of the definitions that may be needed and the current definitions that may be affected. This section presents a review question for the current objective. Question: Designing Component Interface Applications The design for an application that uses component interfaces should include: 1. A business process model. 2. A list of any current definitions that are affected. 3. A list of any additional definitions that are necessary. 4. All of the above. Answer The answer is 4 (all of the above).

62

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Creating or Modifying Supporting Definitions


The second step is to create any supporting definitions. You must perform these tasks: Create any new definitions identified in the design phase. Make the necessary modifications to definitions (as identified in the design phase). Create a new component to be used with the component interface, if necessary.

Slide 46 _______________________________________________________________________________________________________

Instructor Notes
In the example, you do not have to create additional definitions. Depending on the application, you may need definitions such as: Mobile Applications Mobile technology in the PeopleSoft system is based on synchronizable component interfaces (on the Synchronization tab of the component interface properties). Some component interfaces may be large, even though you are only exposing a few fields. This can lead to performance problems in the field. Consequently, you should create a lightweight component that includes only the fields that you want to expose. A new page is created that never appears in the GUI (so formatting does not matter), and the component includes the new page. Similarly, if there are only a few fields that need to be exposed, you should consider a lightweight component for performance reasons. Question: Creating or Modifying Supporting Definitions Sometimes it may be necessary to create a new component on which you base the component interface. 1. True 2. False Answer The answer is 1 (true). A new component that groups pages containing the data that you want to expose. A field that must added to a record for a particular purpose.

PeopleSoft Proprietary and Confidential

63

Creating and Testing Component Interfaces

Lesson 4

Creating Component Interfaces


You create component interfaces in PeopleSoft Application Designer. To create a component interface: 1. Select File, New, Definition, Component Interface. 2. Select the component that the component interface represents. 3. Select Yes or No when prompted to accept defaults. 4. To expose records and fields, drag and drop them into the component interface. 5. Enter the definition properties. 6. Save the component interface.
Slide 47 _______________________________________________________________________________________________________

Student Notes
You build a component interface based on a single component:

Component interface source See Also PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Creating Component Interfaces.

64

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Creating Component Interfaces (continued)


If you accept the default values for the component interface: Keys are created based on the component search record. All primary fields and records are exposed in the component interface. Derived work records are not included in the component interface view. Properties that you do not want to expose in the component interface can be deleted from the component interface view.

Slide 48 _______________________________________________________________________________________________________

Student Notes
The component interface definition has two views: The left-hand side displays the component view, which is the hierarchical structure of the component. The right-hand side displays the component interface view, which is the structure that is exposed to external applications.

Component interface for PSU_STUDENT Note. Any property can be set as Read Only.

PeopleSoft Proprietary and Confidential

65

Creating and Testing Component Interfaces

Lesson 4

See Also PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Creating Component Interfaces.

Instructor Notes
This section discusses the structure of the component interface: Component View The component view shows exactly the same hierarchical record structure that you would see if you had the component open in PeopleSoft Application Designer. All objects in the component view are part of the underlying component interface, and they are accessible through user-defined methods or through PeopleCode events in the component. However, only the objects in the component interface view are exposed to the calling program at runtime. Component Interface View The component interface view displays a tree in which each object type is represented by a unique icon. Some icons are used in both the component view and the component interface view with slightly different meanings. Review the icons. Review the following five columns at the top of the component interface view: Name This is the name of a particular element (such as the name of a property or method). Record This is the name of the underlying record on which a particular element is based. Field This is the name of the field to which a component interface property points. Read Only Values are Y (yes) and N (no). Comment. Component view Component interface view

66

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Creating Component Interfaces (continued)


If you do not accept the default values for the component interface: Keys are created based on the component search record. No fields or records are added to the component interface view. You can drag and drop the properties from the component view into the component interface view to expose them.

Slide 49 _______________________________________________________________________________________________________

Student Notes
This example shows a component interface with no properties:

Component interface definition with no properties You can add properties by dragging the record into the component interface view. See Also PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Creating Component Interfaces.

PeopleSoft Proprietary and Confidential

67

Creating and Testing Component Interfaces

Lesson 4

Creating Component Interfaces (continued)


The component interface properties include: General tab, where you can enter a description and comments for the component interface. Standard Methods tab, where you can identify the standard methods that you want to expose in the component interface. Synchronization tab, where you can set up the appropriate information for synchronizable component interfaces (which are used in mobile applications for the PeopleSoft system).

Slide 50 _______________________________________________________________________________________________________

Student Notes
This example shows the properties for a component interface:

Component interface properties See Also PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Creating the Component Interface Definition.

Instructor Notes
Point out that its good application development practice to always complete the properties. You should provide a description and comments that include: Date created

68

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Name and organization Description

Note. The instructor-led course called Mobile Technologies explains how to develop and code synchronizable component interfaces.

PeopleSoft Proprietary and Confidential

69

Creating and Testing Component Interfaces

Lesson 4

Creating Component Interfaces (continued)


You can make the following modifications to individual properties: Change the name. Add a comment. Make the property read-only.

Slide 51 _______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access this dialog box in PeopleSoft Application Designer:
Dialog Box Edit Property Navigation With the component interface open, right-click on a property and select Edit Property from the pop-up menu

Edit Property dialog box

70

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Creating Component Interfaces (continued)


If the underlying structure of a component changes, the component interface may contain invalid properties. To validate a component interface, open the component interface and select Tools, Validate for Consistency.
Slide 52 _______________________________________________________________________________________________________

Student Notes
If an invalid property exists for a component interface, it is indicated with a red X on the property icon in the component interface view.

Component interface with an invalid property

Instructor Notes
It is a good idea to validate the component interface. If there are errors (as in the example), the property should be deleted.

PeopleSoft Proprietary and Confidential

71

Creating and Testing Component Interfaces

Lesson 4

Creating Component Interfaces (continued)


To add user-defined methods to a component interface: Open the component interface. Select View, View PeopleCode (or right-click and select PeopleCode from the popup menu). Enter the PeopleCode function. Save the component interface.

Slide 53 _______________________________________________________________________________________________________

Student Notes
This example shows the new method named my_method:

User-defined method The new method appears in the component interface view the next time that you open the component interface, as shown here:

Component interface with user-defined method Note. New user-defined methods do not appear in the list of methods until after you save the component interface.

Instructor Notes
Point out that the PeopleCode event consists of methods. This section presents a review question for the current objective.

72

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Question: Creating Component Interfaces Only the properties shown in the component interface view is exposed to external applications. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

73

Creating and Testing Component Interfaces

Lesson 4

Activity 1:

Creating Component Interfaces


In this activity, you will review the activity overview and: 1. Set up the development environment. 2. Create a component interface. See Integration Tools: Activity Guide, lesson 4, Creating and Testing Component Interfaces, Activity 1: Creating Component Interfaces.

Slide 54 _______________________________________________________________________________________________________

Instructor Notes
The activity overview sets up the scenario. Review the application design step with the students to ensure that they understand the application and how the component interface is used. In this application, all of the required definitions already exist, but in other cases you may need to create new definitions. All of the activities for this course use the user ID and password PTINT. You may want to have students change this in Configuration Manager. Because this is the first activity in the course, students need to set up their development environment. All of the projects in this course are stored in the INT_TOOLS project. In the workstation refresh, there are two databases available. Each student has a separate copy of the Training database. There is also a Financials database available for use in the lessons on PeopleSoft Integration Broker. At this point, it is not necessary to mention that database. Note. This activity should take approximately 10 minutes.

Warning! Students must save the component interface before deleting properties. This is a bug that keeps popping up.

Activity Overview
In this activity, you will set up a new development project for this course, setting the tools defaults and then create a new component interface named STUDENT_PROFILE. Development Environment Setup Create a new project named INT_TOOLS and set the tools defaults to insert definitions into the project when modified and saved or when deleted. Also, set the default to automatically reload the last project at startup.

74

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Application Design Based on the current business process model for adding employees as students, you have been asked to automate the process using a component interface to add a new student ID for each new employee.

Personnel Administrator

Add Employee

Add Employee Information

Enroll Employee in training Training Coordinator

Does employee have a student_id? No

Yes

Enroll employee in the Training course

Create new STUDENT_ID

Sample business process for adding employees and enrolling them in training In your new design, the system automatically creates a student ID for each new employee when you save the employees personal information.

Personnel Administrator

Add Employee

Add Employee Information

Create new STUDENT_ID

Training Coordinator

Enroll Employee in training

Enroll employee in the Training course

Modified business process The following definitions are currently used in the business process:
Definition Type Component Definition Name PERSONAL_DATA Description Used to add new employees.

PeopleSoft Proprietary and Confidential

75

Creating and Testing Component Interfaces

Lesson 4

Definition Type Component

Definition Name PSU_STUDENT

Description Used to add and maintain student information.

Creation of Supporting Definitions For this application, there are no additional definitions required. Creation of the Component Interface Create a component interface based the following information:
Source Component PSU_STUDENT Properties Exposed STUDENT_ID (read only) STUDENT_NAME CUSTOMER_ID SAME_ADDR_CUSTOMER PROJECT_ROLE

Setting Up the Development Environment


To set up the development environment: 1. Sign on to PeopleSoft Application Designer using the user ID PTINT and the password PTINT. 2. Select File, Save Project As, INT_TOOLS. 3. Click OK. 4. Select Tools, Options. 5. In the Insert Definition into Project group box, select WHEN DEFINITION IS MODIFIED AND SAVED, OR DELETED. 6. Select RELOAD LAST PROJECT AT STARTUP. 7. Click OK.

Creating a Component Interface


To create a component interface: 1. Select File, New, Component Interface. 2. Select PSU_STUDENT as the source component. 3. Select No when prompted to accept default values. 4. Drag the record PSU_STUDENT_TBL from scroll level 0 into the component interface view. 5. Save the component interface as STUDENT_PROFILE.

76

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

6. Delete any fields that you do not want to expose, and expose the following fields: STUDENT_ID (read only) STUDENT_NAME CUSTOMER_ID SAME_ADDR_CUSTOMER PROJECT_ROLE

7. Enter the definition properties by selecting File, Definition Properties and entering the following:
Page Element Description Comments Value or Status Student Profile Date, name, description

8. Save the component interface. Results STUDENT_PROFILE component interface contains the properties that will be exposed:

STUDENT_PROFILE component interface This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

77

Creating and Testing Component Interfaces

Lesson 4

Setting Component Interface Security


Note the following points about component interface security: Security access must be granted to a component interface before you can test or use the component interface at runtime. Component interfaces are secured by permission lists. Each method for a component interface can be set to either no access or full access.

Slide 55 _______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the Component Interface Permissions page:
Page Name Component Interface Permissions Navigation PeopleTools, Security, Permissions & Roles, Permission Lists, ALLPAGES

Component Interface Permissions page Click the Edit link next to the component interface name to set the permissions for methods. See Also PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Setting Component Interface Security.

78

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Instructor Notes
In the online system, components are secured with permission lists by page and action (Add, Update/Display, Update/Display All, and Correction). For a user to gain access to the component, the permission list must be included in one of the roles assigned to the user. Component interfaces must be secure because they are independent of the online system and they can be directly accessed using methods and properties. When an external application calls a component interface, the program must provide the appropriate user ID and password before access is granted. Question: Setting Component Interface Security You grant component interface security by using: 1. Roles 2. Permission lists 3. User profiles 4. Definition security Answer The answer is 2 (permission lists).

PeopleSoft Proprietary and Confidential

79

Creating and Testing Component Interfaces

Lesson 4

Testing Component Interfaces


After creating and securing a component interface, you can test it in PeopleSoft Application Designer. To invoke the Component Interface Tester tool: 1. Open the component interface in Application Designer. 2. Select Tools, Test Component Interface. 3. Double-click in the gray area to enter values.
Slide 56 _______________________________________________________________________________________________________

Student Notes
The Component Interface Tester tool enables you to test the standard methods:

Component Interface Tester tool

Instructor Notes
If you do not have security access to the component interface, you cannot test it. You receive a Not Authorized message. The component processor provides dummy rows to enable quick data entry when the level you are accessing does not have any data. This option is selected as a default.

80

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Testing Component Interfaces (continued)


You use the Component Interface Tester tool to test methods associated with the component interface: Use the Get Existing option to test the Get method. Use the Create New option to test the Create method. Use the Find option to test the Find method.

After adding or modifying data in the Component Interface Tester tool, you can test the Save method by right-clicking the component interface and selecting Save from the popup menu.
Slide 57 _______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access this definition in Component Interface Tester tool:
Definition Name Component Interface Tester Navigation STUDENT_ID: 2001, Get Existing

Results of Get Existing test

Instructor Notes
This section presents a review question for the current objective. Question: Testing Component Interfaces When you save a component interface in the Component Interface Tester tool, the PeopleSoft database is updated. 1. True

PeopleSoft Proprietary and Confidential

81

Creating and Testing Component Interfaces

Lesson 4

2. False Answer The answer is 1 (true).

82

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Activity 2:

Testing a Component Interface


In this activity, you will review the activity overview and: 1. Set security for a component interface. 2. Test the Find method for the component interface. 3. Test the Add method for the component interface. See Integration Tools: Activity Guide, lesson 4, Creating and Testing Component Interfaces, Activity 2: Testing a Component Interface.

Slide 58 _______________________________________________________________________________________________________

Instructor Notes
In CTE to start a browser session, click on the PeopleSoft PeopleTools [844] link on the right side of the workspace. If you click the IE icon, the select the PeopleSoft PeopleTools [844] link from the browser header. The browser defaults to the training database associated with the workstation. For example STA101 uses database T1B84401 and STA109 uses T1B84409. A list of databases is included in Appendix C. Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will set the security and test the STUDENT_PROFILE component interface that you created in the last activity. Perform the following tasks: 1. Add the component interface STUDENT_PROFILE to the permission list ALLPAGES and grant access to all methods in STUDENT_PROFILE. 2. Test the component interface Find method using customer XYZ. 3. Test the component Add method in the Component Interface Tester tool by entering the following information:
Page Element STUDENT_NAME CUSTOMER_ID SAME_ADDR_CUSTOMER PROJECT_ROLE Value or Status <Your Last Name,First Name> PSFT Y BSA

PeopleSoft Proprietary and Confidential

83

Creating and Testing Component Interfaces

Lesson 4

4. Test the component interface Get method by selecting the student 2007. Try changing the project role to XXX and save. Was your save successful?

Setting Security for Component Interface


To set up security: 1. Sign on to the PeopleSoft Internet Architecture using the user ID PTINT and the password PTINT. 2. Select PeopleTools, Security, Permissions & Roles, Permission Lists, ALLPAGES. 3. On the Component Interfaces tab, use the insert row button to add a new row. 4. Select STUDENT_PROFILE. 5. Click OK. 6. Click the Edit link next to STUDENT_PROFILE. 7. Click Full Access (All). 8. Click OK. 9. Click Save.

Testing the Find Method for the Component Interface


To test the Find method: 1. In PeopleSoft Application Designer, select File, Open, Component Interface, STUDENT_PROFILE. 2. Select Tools, Test Component Interface. 3. Double-click CUSTOMER_ID in the Find group box, and enter XYZ. 4. Click Find. Examine the list returned. 5. Click Cancel.

Testing the Add Method for the Component Interface


To test the Add method: 1. Click Create New. 2. Double-click next to each field, and enter the following information:
Page Element STUDENT_NAME CUSTOMER_ID SAME_ADDR_CUSTOMER Value or Status <Your Last Name, First Name> PSFT Y

84

PeopleSoft Proprietary and Confidential

Lesson 4

Creating and Testing Component Interfaces

Page Element PROJECT_ROLE

Value or Status BSA

3. Right-click STUDENT_PROFILE, and select Save. 4. Click OK. 5. Close the Component Interface Tester dialog box. 6. In the browser, select Students, Personal Information, and search for the new student.

Testing the Get method in the Component Interface Tester


To test the Get method: 1. Select Tools, Test Component Interface. 2. Double-click STUDENT_ID in the Get group box, and enter 2007. 3. Click Get Existing. 4. Double-click PROJECT_ROLE, and change the value to XXX. What happens when you press ENTER? 5. Close the Component Interface Tester dialog box. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

85

Creating and Testing Component Interfaces

Lesson 4

Review
In this lesson, you learned that: There are seven steps that you use to create component interface applications. The first step is to design the application that uses a component interface. The second step is to create or modify any supporting definitions. The third step is to create the component interface. The forth step is to apply security to the component interface. The fifth step is to test the component interface in PeopleSoft Application Designer.

Slide 59 _______________________________________________________________________________________________________

86

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces


Objectives
By the end of this lesson, you will be able to: Describe component interface instantiation. Add component interface PeopleCode to an application. Modify component interface PeopleCode.

Slide 61 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

87

Implementing Component Interfaces

Lesson 5

Describing Component Interface Instantiation


Component interfaces do not have any built-in functions. They are instantiated from the session class. The session object performs the following functions: Controls access to the component interface. Establishes connect and disconnect. Provides security validation. Provides error handling.

Slide 62 _______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleCode Reference, Session Class.

Instructor Notes
Before you can instantiate a component interface, you must establish a session with the PeopleSoft application. Component interfaces can be called from external systems. Before the external system can access the component interface, a session needs to be established with the PeopleSoft application. The external system must supply the proper credentials (user ID and password) to access the session. You use the Connect method to sign on. The session class provides the following methods to instantiate the component interface: FindCompIntfcs This returns a list of component interfaces from which you can choose. GetCompIntfc This returns the specific component interface requested.

88

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Describing Component Interface Instantiation (continued)


A component interface can be instantiated from: PeopleCode Microsoft COM (including Visual Basic) Java C or C++

Slide 63 _______________________________________________________________________________________________________

Instructor Notes
COM stands for Component Object Model. It is a software architecture developed by Microsoft to build component-based applications. COM objects are discrete componentseach with a unique identitythat expose interfaces. This enables applications and other components to access their features. COM objects are more versatile than Win32 DLLs because they are completely language-independent. Also, they have built-in interprocess communications capability, and they easily fit into an object-oriented program design. COM was first released in 1993 with OLE2, largely to replace the interprocess communication mechanism DDE used by the initial release of OLE. ActiveX is also based on COM.

PeopleSoft Proprietary and Confidential

89

Implementing Component Interfaces

Lesson 5

Describing Component Interface Instantiation (continued)


This diagram shows the life cycle of a component interface:
Session Object

1. GetCompIntfc(name)

2. Set Keys 6. Cancel() 4. Get() or Create()

3. Find()

Pick from the collection

5. Read Properties Write Properties Invoke Methods

6. Save()

Life cycle of a component interface


Slide 64 _______________________________________________________________________________________________________

Student Notes
Here is an overview of the process for instantiating a component interface: 1. Once the session is established, the GetCompIntfc method is used to instantiate the component interface. 2. The key values for the component interface are set. If the key uniquely defines a component interface, the next step is skipped. 3. If only partial keys are entered, then the Find method is used to display a list that meets the criteria. 4. You execute either the Get or Create method to retrieve data into the component interface. 5. You get property values, set property values, or run user-defined methods.
90 PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

6. You run the Save standard method to initiate the standard PeopleCode save business rules and commit any changes to the database. At any point, the standard method Cancel can be run to reset the component interface to its state in step 1.

Instructor Notes
Review the diagram and explain the steps described in the student notes. This section provides a review question for the current objective. Question: Describing Component Interface Instantiation Which method is used to instantiate a component interface? 1. CreateCompIntfc(name) 2. Find() 3. GetCompIntfc(name) 4. Get() Answer The answer is 3 (GetCompIntfc(name)).

PeopleSoft Proprietary and Confidential

91

Implementing Component Interfaces

Lesson 5

Adding Component Interface PeopleCode to an Application


Typically, PeopleCode that triggers a component interface is placed in the SavePostChange event. Note the following points: SavePostChange is initiated after the component processor updates the database. SavePostChange is generally used to update tables that are not in the component. An error and warning that is generated in SavePostChange cause the component to be canceled without saving the changes. The system issues a Structured Query Language Commit after SavePostChange terminates successfully. If the component interface update fails, so does the update to the source component.

Slide 65 _______________________________________________________________________________________________________

Instructor Notes
Because a component interface is used to update tables that are not in the component, it is usually placed in the SavePostChange event for either the record or the component. If the component interface update fails, so does the update to the source component. This prevents tables from becoming unsynchronized.

92

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Adding Component Interface PeopleCode to an Application (continued)


To create a template: 1. Drag a component interface into a PeopleCode event. 2. Modify the template as needed. 3. Replace [*] with the appropriate values.
Slide 66 _______________________________________________________________________________________________________

Student Notes
See Appendix A Sample Code.

Instructor Notes
Point out the sections of the code that are generated. Refer to the diagram showing the life cycle of a component interface. The template provides a function for handling errors, and it sets up the error logging. You do not need to modify any of this code for the error logging to work. Discuss the following process: 1. Once the session is established, the GetCompIntfc method is used. The following sections get the session and the component interface:
rem ***** Get current PeopleSoft Session *****; rem ***** Get the Component Interface *****;

2. The key values for the component interface are set:


rem ***** Set the Component Interface Mode *****; rem ***** Set Component Interface Get/Create Keys *****;

The Create key is used if you are creating a new row (as the students do in the activity). If the key uniquely defines a component interface, the next step is skipped. 3. If only partial keys are entered, then the Find method is used to display a list of component interfaces that meet the criteria. 4. You execute either the Get or Create method to instantiate the component interface:
rem ***** Execute Get *****; rem ***** Execute Create ******;

5. You get property values, set property values, or run user-defined methods:

PeopleSoft Proprietary and Confidential

93

Implementing Component Interfaces

Lesson 5

rem ***** Begin: Get/Set Component Interface Properties *****;

6. You execute the Save standard method to initiate the standard PeopleCode save business rules and commit any changes to the database:
rem ***** Execute Save *****;

At any point, the standard method Cancel can be executed to reset the component interface to its state in step 1, as in the following section:
rem ***** Execute Cancel *****;

94

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Adding Component Interface PeopleCode to an Application (continued)


The template contains a function for handling errors.
Function errorHandler() &oPSMessageCollection = &oSession.PSMessages; For &i = 1 To &oPSMessageCollection.Count &oPSMessage = &oPSMessageCollection.Item(&i); &strErrMsgSetNum = &oPSMessage.MessageSetNumber; &strErrMsgNum = &oPSMessage.MessageNumber; &strErrMsgText = &oPSMessage.Text; &LogFile.WriteLine(&strErrType | " (" | &strErrMsgSetNum | "," | &strErrMsgNum | ") - " | &strErrMsgText); End-For; rem ***** Delete the Messages from the collection *****; &oPSMessageCollection.DeleteAll(); End-Function;

Slide 67 _______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleCode Reference, Session Class.

Instructor Notes
The session object handles error processing for all APIs, such as component interfaces. All errors are contained in the PSMessages collection. (The PSMessages property of a session object returns this collection.) Each item in this collection is a PSMessage object. A PSMessage object contains information about the specific error that has occurred; for example, the explanatory text for the error, the message set number, and so on. The type of information depends on the type of error. In the template, the errors are recorded in a log file at the path indicated in the code, as shown here:
&LogFile = GetFile("C:\temp\STUDENT_PROFILE.log", "w", "a", %FilePath_Absolute); &LogFile.WriteLine("Begin");

Exception Class Exception handling is done using the exception class. This class provides a try-catch and throw mechanism so you don't need to check after each operation for errors, but can instead declare by the structure of the try-catch statements when you are interested in handling exceptions, and how you want to handle them.

PeopleSoft Proprietary and Confidential

95

Implementing Component Interfaces

Lesson 5

PeopleSoft recommends that when applicable, application class methods should throw exceptions instead of communicating back to the calling code with return values. Try-Catch The statements that immediately follow the Try keyword are called the protected statements. These are the only statements that are 'protected' by the catch clauses in the Try-Catch statements. The catch clauses in a Try-Catch statement can be executed only if an exception is thrown by the protected statements. In addition, a catch clause is executed only when handling an exception that matches the type given on the catch. Any exceptions thrown by the catch clauses are not caught by their own Try-Catch statement. The execution of the Try-Catch statement starts by executing the protected statements. If none of these statements, as well as none of the statements called by them, causes an exception to be thrown, the try-catch is done. The statements in the catch clauses are not executed. See PeopleTools 8.44 PeopleBook: PeopleCode Reference, Exception Class.

96

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Adding Component Interface PeopleCode to an Application (continued)


When calling a component interface from PeopleCode, a session has already been established. The system variable %Session is used in the code.
rem ***** Get current PeopleSoft Session *****; &oSession = %Session;

Slide 68 _______________________________________________________________________________________________________

Student Notes
The session parameters for external systems are covered later in this course. See lesson 7, Building Component Interface APIs.

PeopleSoft Proprietary and Confidential

97

Implementing Component Interfaces

Lesson 5

Adding Component Interface PeopleCode to an Application (continued)


The GetCompIntfc method is used with a session object to get the component interface by name. If the component interface definition does not exist, you receive an error.
rem ***** Get the Component Interface *****; &oStudentProfile = &oSession.GetCompIntfc(CompIntfc.STUDENT_PROFILE); If &oStudentProfile = Null Then errorHandler(); Exit; End-If;

Slide 69 _______________________________________________________________________________________________________

Instructor Notes
Note that the specified component interface definition must exist. This section presents a review question for the current objective. Question: Adding Component Interface PeopleCode to an Application Component interface PeopleCode templates can include which of the following? 1. ErrorHandler routine 2. Standard methods 3. Session connection 4. All of the above Answer The answer is 4 (all of the above).

98

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Modifying Component Interface PeopleCode


When the template is in place, you must modify the code to: Substitute values for [*]. Uncomment code. Add conditional statements, if needed. Delete or comment code.

Slide 70 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

99

Implementing Component Interfaces

Lesson 5

Modifying Component Interface PeopleCode (continued)


The standard properties for a component interface are set in the following section:
rem ***** Set the Component Interface Mode *****; &oStudentProfile.InteractiveMode = False; &oStudentProfile.GetHistoryItems = True; &oStudentProfile.EditHistoryItems = False;

Slide 71 _______________________________________________________________________________________________________

Student Notes
GetHistoryItems and EditHistoryItems are used for effective-dated tables: If EditHistoryItems is False (the default) and GetHistoryItems is True, you access the data in the component interface as if you were accessing a component in Update/Display All mode. This means that all history rows are returned; however, you can edit only rows with a date set in the future. If EditHistoryItems is True and GetHistoryItems is True, you access the data in the component interface as if you were accessing a component in Correction mode. This means that all history rows are returned, and you can edit them. If GetHistoryItems is False, you access the data in the component interface as if you were accessing a component in Update/Display mode. The EditHistoryItems has no effect when GetHistoryItems is False.

Instructor Notes
The following table describes these properties:
Property InteractiveMode Description Controls whether to apply values and run business rules immediately, or whether items are queued and business rules are run later in a single step. Interactive mode is recommended for most cases where you use a component interface to establish real-time integration with another interactive application. Controls whether the component interface runs in Update/Display mode or Correction mode when the underlying component is effective dated. Controls whether the component interface runs in Update/Display All mode, Update/Display mode, or Correction mode when the underlying component is effective dated.

GetHistoryItems EditHistoryItems

100

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Modifying Component Interface PeopleCode (continued)


The Get and Create keys need to be set by replacing [*] with the appropriate value in the following section:
rem ***** Set Component Interface Get/Create Keys *****; &oStudentProfile.STUDENT_ID = [*];

Slide 72 _______________________________________________________________________________________________________

Instructor Notes
The template uses Get and Create keys that are based on the component interface. Consequently, you need to replace [*] with the appropriate value. In the activity for this lesson, students can use a blank space, set the value, or comment the statement because they will perform an Add action, and the value is a default in the record definition. The options are:
&oStudentProfile.STUDENT_ID = ;

or
&oStudentProfile.STUDENT_ID = NEW;

or
rem &oStudentProfile.STUDENT_ID = [*];

PeopleSoft Proprietary and Confidential

101

Implementing Component Interfaces

Lesson 5

Modifying Component Interface PeopleCode (continued)


The template is coded so that a Get is performed first. The Create is commented out. In the example, you perform a Create only, so you would uncomment the following section:
rem ***** Execute Create ******; If Not &oStudentProfile.Create() Then rem ***** Unable to Create Component Interface for the Add keys provided. *****; errorHandler(); Exit; End-If;

Slide 73 _______________________________________________________________________________________________________

Student Notes
The template contains the following sections:
rem ***** Execute Get *****; If Not &oStudentProfile.Get() Then rem ***** No rows exist for the specified keys. Failed to get the Component Interface. *****; errorHandler(); Exit; End-If; rem ***** Execute Create ******; /*If Not &oStudentProfile.Create() Then rem ***** Unable to Create Component Interface for the Add keys provided. *****; errorHandler(); Exit; End-If;*/

102

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Modifying Component Interface PeopleCode (continued)


Modify the template to assign values to the other fields, as shown here:
rem ***** Begin: Get/Set Component Interface Properties *****; rem ***** Get/Set Level 0 Field Properties *****; &oStudentProfile.STUDENT_NAME = PERSONAL_DATA.NAME; &oStudentProfile.CUSTOMER_ID = PSFT; &oStudentProfile.SAME_ADDR_CUSTOMER = Y; &oStudentProfile.PROJECT_ROLE = BSA;

Slide 74 _______________________________________________________________________________________________________

Student Notes
If you perform a Get to retrieve an existing row of data and want to update the current component with the data from the component interface, you can use the following code:
PERSONAL_DATA.DEGREE= &oStudentSkill.DEGREE;

The template for the Get/Set is shown here:


rem ***** Get/Set Level 0 Field Properties *****; &fileLog.WriteLine("&oStudentProfile.STUDENT_ID = " | &oStudentProfile.STUDENT_ID); rem &oStudentProfile.STUDENT_ID = [*]; &fileLog.WriteLine("&oStudentProfile.STUDENT_NAME = " | &oStudentProfile.STUDENT_NAME); rem &oStudentProfile.STUDENT_NAME = [*]; &fileLog.WriteLine("&oStudentProfile.CUSTOMER_ID = " | &oStudentProfile.CUSTOMER_ID); rem &oStudentProfile.CUSTOMER_ID = [*]; &fileLog.WriteLine("&oStudentProfile.SAME_ADDR_CUSTOMER = " | &oStudentProfile.SAME_ADDR_CUSTOMER); rem &oStudentProfile.SAME_ADDR_CUSTOMER = [*]; &fileLog.WriteLine("&oStudentProfile.PROJECT_ROLE = " | &oStudentProfile.PROJECT_ROLE); rem &oStudentProfile.PROJECT_ROLE = [*]; rem ***** End: Get/Set Component Interface Properties *****;

Instructor Notes
In the example, you take the name from the Personal Data table. The other values are hard-coded.

PeopleSoft Proprietary and Confidential

103

Implementing Component Interfaces

Lesson 5

Modifying Component Interface PeopleCode (continued)


Note that the Save and Cancel methods are commented out. In order to execute Save or Cancel, you must uncomment the code, as shown here:
rem ***** Execute Save *****; If Not &oStudentProfile.Save() Then errorHandler(); Exit; End-If; rem ***** Execute Cancel *****; If Not &oStudentProfile.Cancel() Then errorHandler(); Exit; End-If;

Slide 75 _______________________________________________________________________________________________________

Student Notes
Note that the Save and Cancel are commented out:
rem ***** Execute Save *****; /*If Not &oStudentProfile.Save() Then errorHandler(); Exit; End-If;*/ rem ***** Execute Cancel *****; /*If Not &oStudentProfile.Cancel() Then errorHandler(); Exit; End-If;*/ &LogFile.WriteLine("End"); &LogFile.Close();

Instructor Notes
This section presents a review question for the current objective. Question: Modifying Component Interface PeopleCode The Save and Cancel methods are commented in the generated component interface template.

104

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

1. True 2. False Answer The answer is 1 (true). You must uncomment the Save and Cancel methods to execute them.

PeopleSoft Proprietary and Confidential

105

Implementing Component Interfaces

Lesson 5

Activity 3:

Activating a Component Interface


In this activity, you will review the activity overview and: 1. Add PeopleCode to instantiate a component interface. 2. Test the component interface PeopleCode. See Integration Tools: Activity Guide, lesson 5, Implementing Component Interfaces, Activity 3: Activating a Component Interface.

Slide 76 _______________________________________________________________________________________________________

Instructor Notes
In this activity, the number of fields exposed in the component interface is limited. This limitation exists for two reasons: first, to show students how to limit exposed fields, and second, to simplify the PeopleCode template. The student profile component interface is also used later in the course; it helps to simplify the Java template created in that lesson. See lesson 7, Building the Component Interface API. Note. This activity should take approximately 15 minutes. A copy of the completed PeopleCode has been placed in a text file at the following location: z:\STAnnn\Tools\1022_IntTools\Scripts\StuProfile_pc.txt. This section discusses how to: Explain the code modifications. Explain writing to a log file. Explain common errors.

Explaining the Code Modifications Here are the portions of the PeopleCode that need to be modified: Change the log file path The template creates an absolute path for the logfile to c:\temp in the CTE students do not have write access to c:\temp students need to change the path to their student folder:
rem ***** Set the Log File *****; &fileLog = GetFile("Z:\STA102\temp\STUDENT_PROFILE.log", "w", "a", %FilePath_Absolute);

Comment the Get


rem ***** Set Component Interface Get/Create Keys *****; /* &oStudentProfile.STUDENT_ID = [*];*/ rem ***** Execute Get *****;

106

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

<* If Not &oStudentProfile.Get() Then rem ***** No rows exist for the specified keys.*****; errorHandler(); throw CreateException(0, 0, "Get failed"); End-If; *>

Uncomment the Create


rem ***** Execute Create ******; If Not &oStudentProfile.Create() Then; rem ***** Unable to Create Component Interface for the Add keys provided. *****; errorHandler(); throw CreateException(0, 0, "Create failed"); End-If;

Add the Values


rem ***** Begin: Get/Set Component Interface Properties *****; rem ***** Get/Set Level 0 Field Properties *****; &fileLog.WriteLine("&oStudentProfile.STUDENT_ID = " | &oStudentProfile.STUDENT_ID); rem &oStudentProfile.STUDENT_ID = [*]; &oStudentProfile.STUDENT_NAME = PERSONAL_DATA.NAME; &fileLog.WriteLine("&oStudentProfile.STUDENT_NAME = " | &oStudentProfile.STUDENT_NAME); &oStudentProfile.STUDENT_NAME = PERSONAL_DATA.NAME; &oStudentProfile.CUSTOMER_ID = "PSFT"; &fileLog.WriteLine("&oStudentProfile.CUSTOMER_ID = " | &oStudentProfile.CUSTOMER_ID); &oStudentProfile.SAME_ADDR_CUSTOMER = "Y"; &fileLog.WriteLine("&oStudentProfile.SAME_ADDR_CUSTOMER = " | &oStudentProfile.SAME_ADDR_CUSTOMER); &oStudentProfile.PROJECT_ROLE = "BSA"; &fileLog.WriteLine("&oStudentProfile.PROJECT_ROLE = " | &oStudentProfile.PROJECT_ROLE); rem ***** End: Get/Set Component Interface Properties *****;

Uncomment the Save


rem ***** Execute Save *****; If Not &oStudentProfile.Save() Then errorHandler(); throw CreateException(0, 0, "Save failed"); End-If;

Uncomment the Cancel


rem ***** Execute Cancel *****; If Not &oStudentProfile.Cancel() Then errorHandler(); throw CreateException(0, 0, "Cancel failed"); End-If;

PeopleSoft Proprietary and Confidential

107

Implementing Component Interfaces

Lesson 5

Writing the log file The template assumes you will be doing a GET, so the value is retrieved and written to the log before you make any changes this is to capture the before picture. In the activity, the CI is used to CREATE therefore the log will only show the default values as retrieved from the record definition. This is a good opportunity to point out the fact that you did not need to set up a value for STUDENT_ID. If students would prefer to see the after values they will need to move the WriteLines after the create and move the STUDENT_ID writeline after the save as shown below:
rem ***** Begin: Get/Set Component Interface Properties *****; rem ***** Get/Set Level 0 Field Properties *****; &oStudentProfile.STUDENT_NAME = PERSONAL_DATA.NAME; &oStudentProfile.CUSTOMER_ID = "PSFT"; &oStudentProfile.SAME_ADDR_CUSTOMER = "Y"; &oStudentProfile.PROJECT_ROLE = "BSA"; &fileLog.WriteLine("&oStudentProfile.STUDENT_NAME = " | &oStudentProfile.STUDENT_NAME); &fileLog.WriteLine("&oStudentProfile.CUSTOMER_ID = " | &oStudentProfile.CUSTOMER_ID); &fileLog.WriteLine("&oStudentProfile.SAME_ADDR_CUSTOMER = " | &oStudentProfile.SAME_ADDR_CUSTOMER); &fileLog.WriteLine("&oStudentProfile.PROJECT_ROLE = " | &oStudentProfile.PROJECT_ROLE);

rem ***** End: Get/Set Component Interface Properties *****; rem ***** Execute Save *****; If Not &oStudentProfile.Save() Then; errorHandler(); throw CreateException(0, 0, "Save failed"); Else &fileLog.WriteLine("&oStudentProfile.STUDENT_ID = " | &oStudentProfile.STUDENT_ID); End-If;

Explaining Common Errors Here are some common errors that students may experience: Student Information Is Not Created Because Program Attempted a Get

Error log showing that no rows exist for key

108

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

In the PeopleCode, the Get was not commented out; there are no students with the student ID NEW. To fix this problem, make sure that students comments out the code, as shown here:
rem ***** Execute Get *****; /* If Not &oStudentProfile.Get() Then rem ***** No rows exist for the specified keys. Failed to get the Component Interface. *****; errorHandler(); Exit; End-If; */

Create Is Not Uncommented

Error log showing that Create was not performed Uncomment the Create and try again:
rem ***** Execute Create ******; If Not &oStudentProfile.Create() Then rem ***** Unable to Create Component Interface for the Add keys provided. *****; errorHandler(); Exit; End-If;

Student Information Is Not Created Because No Values Are Supplied

Error log when rem is not removed Occasionally, students might enter the correct values but forget to take out the rem. Here is how code appears:
rem ***** Begin: Get/Set Component Interface Properties *****; rem ***** Get/Set Level 0 Field Properties *****; rem &oStudentProfile.STUDENT_NAME = PERSONAL_DATA.NAME; rem &oStudentProfile.CUSTOMER_ID = "PSFT"; rem &oStudentProfile.SAME_ADDR_CUSTOMER = "Y"; rem &oStudentProfile.PROJECT_ROLE = "BSA";

PeopleSoft Proprietary and Confidential

109

Implementing Component Interfaces

Lesson 5

Have the students remove the rem and try again.

Activity Overview
In this activity, you will add PeopleCode to the PERSONAL_DATA record to create a new student for PSFT every time that a new employee is added. You will then test the PeopleCode by creating a new employee.

Adding PeopleCode to Instantiate a Component Interface


To add the PeopleCode: 1. Open the project INT_TOOLS in PeopleSoft Application Designer. 2. Open the record PERSONAL_DATA. 3. Select View, PeopleCode Display. 4. Open the PeopleCode editor for EMPLID SavePostChange event. 5. Drag the component interface STUDENT_PROFILE from the project workspace into the PeopleCode editor. 6. Change the file path for the log file from the default C:\temp to z:\STAnnn\temp where nnn is you workstation number. 7. Modify the PeopleCode to create a new student ID. Comment and uncomment code where necessary, use the following values for the level 0 properties:
Field &oStudentProfile.STUDENT_NAME &oStudentProfile.CUSTOMER_ID &oStudentProfile.SAME_ADDR_CUSTOMER &oStudentProfile.PROJECT_ROLE Value or Status PERSONAL_DATA.NAME PSFT Y BSA

Note. You do not need to set the Create key because it uses the default value NEW from the record definition. 8. Save the record. 9. Save the project.

Testing the Component Interface PeopleCode


To test the component interface PeopleCode: 1. In the browser select Employees, Personal Data.

110

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

2. Add a new employee. Enter the following information:


Page Element EmplID Name Country Address 1 City State Value or Status 01000 Smith,John USA 25 South Street York PA

3. Click Save. 4. Select Students, Personal Information. 5. Search by the customer ID PSFT. The newly created student profile appears. Note. If the student does not appear, check the error log created in z:\STAnnn\temp\STUDENT_PROFILE.log. Results The new student has been created:

Example of newly created student profile

PeopleSoft Proprietary and Confidential

111

Implementing Component Interfaces

Lesson 5

This concludes the activity. Do not continue.

112

PeopleSoft Proprietary and Confidential

Lesson 5

Implementing Component Interfaces

Review
In this lesson, you learned that: Component interfaces are instantiated from the session class. You can create a component interface PeopleCode template by dragging the component interface into the PeopleCode program. The template must be modified to use the appropriate methods and properties.

Slide 77 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

113

Implementing Component Interfaces

Lesson 5

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

114

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections


Objectives
By the end of this lesson, you will be able to: Describe component interface collections. Write PeopleCode for component interface collections. Work with effective-dated data.

Slide 79 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

115

Working with Component Interface Collections

Lesson 6

Describing Component Interface Collections


Each level of data in a component interface is know as a collection:

Level 0 ---- Level 1 (collection) ---- Level 1 (collection) ----Level 2 (collection)


Collection structure
Slide 80 _______________________________________________________________________________________________________

Student Notes
When you create a component interface collection that has level 1 and level 2, the collections appear in the component interface view, and they are represented by the collection icon, as shown here:

Component interface with level 1 and level 2 collections

Instructor Notes
The left side shows the following component structure:

116

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

Level 1 is SDK_BUS_EXP_PER Level 2 is SDK_BUS_EXP_DTL

When level 1 or level 2 is dragged into the component interface view, the collection is represented by the collection icon. You can expand or collapse the collection by clicking the plus sign (+) or minus sign () next to the icon.

PeopleSoft Proprietary and Confidential

117

Working with Component Interface Collections

Lesson 6

Describing Component Interface Collections (continued)


A data collection is dataavailable at runtime or during test modethat is associated with a particular scroll area (or record). It has the following characteristics: The data collection object returns information about each row of data (referred to as an item) that is returned for the record at runtime. To access a data collection, you use the name of the record (scroll area) as a property in a component interface. At runtime, the Item() method of a collection is used to return information about a particular row.

Slide 81 _______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the SDK Business Expenses page:
Page Name SDK Business Expenses Navigation SDK Samples, SDK Business Expense, 8001

SDK Business Expenses page To access the secondary scroll area SDK_BUS_EXP_DTL, you must get the appropriate row of the upper-level scroll area first:
&Level1 = &oCi.SDK_BUS_EXP_PER; For &i = 1 To &Level1.Count &Item = &Level1.Item(&i); &Level2 = &Item.SDK_BUS_EXP_DTL;

118

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

/* do your processing */ End-For;

Instructor Notes
In this example, you first examine the level 1 collection (SDK_BUS_EXP_PER), and you loop through the collection. Note that each row in the collection is an item. In the example, the variable &Item is used for the current row in SDK_BUS_EXP_PER. In this case, the row is for employee ID 8001 (Simon Schumacher). You can then access level 2 for that item. Level 2 has three rows in the scroll area SDK_BUS_EXP_DTL. Question: Describing Component Interface Collections The name of the record (scroll area) is used as a property in a component interface to access a data collection. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

119

Working with Component Interface Collections

Lesson 6

Writing PeopleCode for Component Interface Collections


The following data collection properties are available: Count CurrentItemNumber

Slide 82 _______________________________________________________________________________________________________

Instructor Notes
Count is used to return the number of rows in the collection. CurrentItemNumber is used if the component associated with the component interface is effective-dated. This property returns the item number for the current effective-dated item (that is, the row of data).

120

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

Writing PeopleCode for Component Interface Collections (continued)


The following methods are available for data collections: CurrentItem DeleteItem GetEffectiveItem GetEffectiveItemNum InsertItem ItemByKeys

Slide 83 _______________________________________________________________________________________________________

Student Notes
All collection methods except DeleteItem () return an Item object. New rows are inserted at the end using InsertItem.
&Level1 = &oCi.SDK_BUS_EXP_PER; For &<i> = 1 To &Level1.Count &Item = &Level1.Item(&i); &Level2 = &Item.SDK_BUS_EXP_DTL; &count = &Level2.Count; &ExpDtl = &Level2.InsertItem(&count); &ExpDtl.SDK_EXP_PER_DT = %Date; &ExpDtl.SDK_EXPENSE_CD = 01; End-For;

If the record has a unique key, you can use the ItemByKey() method to select the row:
If oPsuStudentExpCollection.ItemByKeys(PT) <> NULL Then

See Also PeopleTools 8.44 PeopleBook: PeopleCode Reference, Component Interface Classes.

Instructor Notes
Some of these methods are only used with effective-dated tables; for example: CurrentItem GetEffectiveItem GetEffectiveItemNum

PeopleSoft Proprietary and Confidential

121

Working with Component Interface Collections

Lesson 6

The most frequently used method is InsertItem. Review the code provided in the student notes.
Code
&Level1 = &oCi.SDK_BUS_EXP_PER; For &i = 1 To &Level1.Count

Explanation Assign the level-1 record. Loop through level 1 from 1 to the number of rows in level 1. Assign the item to a variable. Assign level 2 for that level-1 row. Count the level-2 rows. Insert a new row after the last level-2 row. Assign values for the new row.

&Item = &Level1.Item(&i); &Level2 = &Item.SDK_BUS_EXP_DTL; &count = &Level2.Count; &ExpDtl = &Level2.InsertItem(&count); &ExpDtl.SDK_EXP_PER_DT = %Date; &ExpDtl.SDK_EXPENSE_CD = 01; End-For;

Question: Describing Component Interface Collections Which method do you use to insert a new row in a collection? 1. CurrentItem 2. InsertItem 3. ItemByKeys 4. GetEffectiveItem Answer The answer is 2 (InsertItem).

122

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

Working with Effective-Dated Data


The following methods are used with effective-dated data: CurrentItem GetEffectiveItem GetEffectiveItemNum

Slide 84 _______________________________________________________________________________________________________

Student Notes
This example shows an effective-dated component interface:

Effective-dated component interface Here is an example of code to get the current effective-dated row:
&oPsuCourseTblCollection = &oCourseCi.PSU_COURSE_TBL; &Item = &oPsuCourseTblCollection.CurrentItem();

To get a specific item based on the effective date, use GetEffectiveItem:


&oPsuCourseTblCollection = &oCourseCi.PSU_COURSE_TBL; &DateString = String(&MyDate); &Item = &oPsuCourseTblCollection.GetEffectiveItem(&DateString, 1);

Note. To show all history for an effective-dated collection, you must set GetHistoryItems to True before you populate the component.

PeopleSoft Proprietary and Confidential

123

Working with Component Interface Collections

Lesson 6

Instructor Notes
If the component associated with the component interface is effective-dated, CurrentItem returns a reference to the current effective-dated item, as shown here:
CurrentItem()

Note. There are no parameters. To get a specific item based on the effective date, use GetEffectiveItem:
GetEffectiveItem(DateString, SeqNo)

Note. DateString takes only a string value. You must convert a date variable into a string before you can use it for DateString. You can use the String function to do this.

Question: Working with Effective-Dated Data There are specific methods available for use with effective-dated collections. 1. True 2. False Answer The answer is 1 (true).

124

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

Activity 4:

Using Component Interfaces with Collections


In this activity, you will review the activity overview and: Insert a row in a collection. Update a row in a collection.

See Integration Tools: Activity Guide, lesson 6, Working with Component Interface Collections, Activity 4: Using Component Interfaces with Collections.
Slide 85 _______________________________________________________________________________________________________

Instructor Notes
For the paths in all activities, the generic \Int_Tools is used in case the path changes in CTE. Explain to students that the path is z:\STAnnn\user taking the place of Encourage students to complete this activity by using only the activity overview. If students have trouble, they can refer to the step-by-step directions in the activity task sections. Note. This activity should take approximately 45 minutes. This section discuss how to: Explain how to insert a row in a collection. Explain how to update a row in a collection.

Explaining How to Insert a Row in a Collection The following PeopleCode example shows what needs to be added or changed. A copy of the entire code can be found in the text file at the following location: z:\STAnnn\Tools\1022_IntTools\Scripts\stuProfile_2_pc.txt.
rem ***** Set the Log File *****; &LogFile = GetFile("z:\STA102\temp\STU_PROFILE_2.log", "w", "a", %FilePath_Absolute); /* If statement for when to execute */ If PSU_STU_ENROLL.ENROLL_STATUS = "CMP" And FieldChanged(PSU_STU_ENROLL.ENROLL_STATUS) And PSU_STU_ENROLL.COURSE = "1001" Then rem ***** Set Component Interface Get/Create Keys *****; /* set the Get Keys to obtain the value from the page */ &oStuProfile2.STUDENT_ID = PSU_STU_ENROLL.STUDENT_ID;

PeopleSoft Proprietary and Confidential

125

Working with Component Interface Collections

Lesson 6

rem ***** Set/Get PSU_STUDENT_EXP Collection Field Properties -- Parent: PS_ROOT Collection *****; rem ** Use the ItemByKeys to determine if the row already exists, if it doesnt, then populate the fields ***; &oPsuStudentExpCollection = &oStuProfile2.PSU_STUDENT_EXP; If &oPsuStudentExpCollection.ItemByKeys("PT") <> Null Then Exit; Else &oPsuStudentExp = &oPsuStudentExpCollection.InsertItem(1); &oPsuStudentExp.SKILL = "PT"; &oPsuStudentExp.PROFICIENCY = "M"; &oPsuStudentExp.DATE_LAST_MAINT = PSU_CRS_SESSN.END_DATE; End-If; rem ***** End: Get/Set Component Interface Properties *****; rem ***** Execute Save errorHandler(); Exit; End-If; rem ***** Execute Cancel errorHandler(); Exit; End-If; &LogFile.WriteLine("End"); &LogFile.Close(); End-If; uncomment cancel *****; uncomment save *****; If Not &oStuProfile2.Save() Then

If Not &oStuProfile2.Cancel() Then

Explaining How to Update a Row in a Collection The following example shows the activity solution for this section:

126

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

Component PeopleCode The entire code is not provided here. The example shows only the sections where students need to add or modify code.
If not PSU_CRS_SESSN.SESSION_STATUS = "C" Then Exit; Else rem ***** Set Component Interface Get/Create Keys *****; &oPsuCrsEnroll.COURSE = PSU_CRS_SESSN.COURSE; &oPsuCrsEnroll.SESSION_NBR = PSU_CRS_SESSN.SESSION_NBR; rem ***** Set/Get PSU_STU_ENROLL Collection Field Properties -- Parent: PS_ROOT Collection *****; &oPsuStuEnrollCollection = &oPsuCrsEnroll.PSU_STU_ENROLL; For &i = 1 To &oPsuStuEnrollCollection.Count &oPsuStuEnroll = &oPsuStuEnrollCollection.Item(&i); &oPsuStuEnroll.ENROLL_STATUS = "RES"; End-For; rem ***** End: Get/Set Component Interface Properties rem ***** Execute Save - uncomment this section *****; End-If; *****;

Activity Overview
In this activity, you will analyze two scenarios in which you require a component interface that automatically updates collections. Scenario 1: Inserting a New Skill When students complete a course, the training coordinator uses the Course Enrollment component to change the status to complete (CMP). You have been asked to modify the application to automatically insert a new row into the record PSU_STUDENT_SKILL for the skill called PeopleTools. All students who complete course 1001 have a proficiency level of medium for the PeopleTools skill.

PeopleSoft Proprietary and Confidential

127

Working with Component Interface Collections

Lesson 6

Here are the definitions used in the application:


Definition Type Record Field Field Component Component Definition Name PSU_STUDENT_SKILL SKILL PROFICIENCY PSU_STUDENT PSU_CRS_ENROLL Description This record contains the skill set for a student. PT is the translate value for PeopleTools. M is the translate value for Medium. This component is used for all student information. This component is used for course enrollment.

Use the following navigation paths to access the pages that you must test:
Page Name Course Enrollment Student Education and Skills Navigation Courses, Course Enrollment Students, Personal Information

Use the following information for testing:


Field Course/Session Value 1001/27 1001/287 Students 2020 2202 2752 2756

Scenario 2: Updating Student Enrollment When a course session is canceled, the current enrollments need to be rescheduled. You need to create a component interface that is used to update the record PSU_STUDENT_ENROLLMENT to change the student status from enrolled (ENR) to reschedule (RES) for any course session that is canceled. Here are the definitions used in the application:
Definition Type Record Field Definition Name PSU_STU_ENROLLMENT ENROLLMENT_STATUS Description This record contains the students enrolled in a course session, with the enrollment status. ENR is the translate value Enrolled. RES is the translate value Reschedule. Component Component PSU_CRS_SESSN PSU_CRS_ENROLL This component is used for all Course Session information This component is used for course enrollment.

128

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

Use the following navigation paths to access the pages that you must test:
Page Name Course Sessions Course Enrollment Navigation Courses, Define, Course Sessions Courses, Course Enrollment

Use the following information for testing:


Field Course Session Session Student Value 1030 290 2466 2491

Inserting a Row in a Collection


To insert the skill called PeopleTools into the PSU_STUDENT_SKILL table for all students who complete the PeopleTools I course (course number 1001): 1. Create a new component interface based on the component PSU_STUDENT. 2. Accept the defaults. 3. Update the component properties to include a description. 4. Save the component interface as STU_PROFILE_2. 5. Apply security to the permission list ALLPAGES for the new component interface. 6. Test the Get method in PeopleSoft Application Designer for student 2020. 7. Open the record PSU_STU_ENROLL. 8. Select View, PeopleCode Display. 9. Open the PeopleCode editor for the STUDENT_ID field SavePostChange. 10. Drag the component interface STU_PROFILE_2 into the PeopleCode editor. 11. Modify the path for the log file from c:\temp to z:\STAnnn\temp where nnn is your workstation number. 12. Modify the PeopleCode template to initiate it when the student enrollment status changes to CMP and the course is 1001.
If PSU_STU_ENROLL.ENROLL_STATUS = "CMP" And FieldChanged(PSU_STU_ENROLL.ENROLL_STATUS) And PSU_STU_ENROLL.COURSE = "1001" Then

PeopleSoft Proprietary and Confidential

129

Working with Component Interface Collections

Lesson 6

13. Modify the PeopleCode template to insert a new row into PSU_STUDENT_EXP for the skill called PeopleTools (PT) with a proficiency of M if the skill does not already exist. Note. If you need assistance with this code, refer to the text file at the following location: \1022_IntTools\scripts\stuskill_pc.txt. 14. Save the record. 15. Save the project. 16. In the browser, select Courses, Course Enrollment, and test the PeopleCode by updating course/session 1001/287 and indicating the status Completed for each student. 17. Select Students, Personal Information to verify that the skill is added. Check the skills for students 2752 and 2756. Results PeopleTools has been added as a skill:

Skills for student 2752

Updating a Row in a Collection


To update the course enrollment table when a course session is canceled: 1. Create a new component interface based on the component PSU_CRS_ENROLL. 2. Accept the defaults. 3. Update the component properties to include a description. 4. Save the component interface as CRS_ENROLL.
130 PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

5. Apply security to the permission list ALLPAGES for the new component interface. 6. Test the Get method in PeopleSoft Application Designer using the course/session 1030/290. 7. Change the enrollment status for student 2466 (PSU_STU_ENROLL[1]) to RES. 8. Save the component interface. 9. Close the Component Interface Tester tool. 10. In the browser, select Courses, Course Enrollment. 11. Enter 1030 for the course and 290 for the session to confirm that the change updated the database. 12. In PeopleSoft Application Designer, open the component PSU_CRS_SESSN. 13. Select View, View PeopleCode. 14. Change the location and event to the following:
PSU_CRS_SESSN (record) SavePostChange

15. Drag the component interface into the PeopleCode and modify the template to update the student enrollment collection if the course session has been canceled:
If PSU_CRS_SESSN.SESSION_STATUS = "C"

Note. If you need assistance with the code, refer to the text file at the following location: \1022_IntTools\Scripts\crs_enroll_pc.txt. 16. Modify the path for the log file from c:\temp to z:\STAnnn\temp where nnn is your workstation number. 17. Save the component. 18. In the browser, select Courses, Define, Course Session to test canceling the course session 1030/290. 19. Change the session status to Cancelled. 20. Save the page. 21. Select Courses, Course Enrollment to verify that the student enrollment is changed. Results The student enrollment status has been changed:

PeopleSoft Proprietary and Confidential

131

Working with Component Interface Collections

Lesson 6

Course enrollment after course is canceled This concludes the activity. Do not continue.

132

PeopleSoft Proprietary and Confidential

Lesson 6

Working with Component Interface Collections

Review
In this lesson, you learned that: A component interface collection represents the scroll level in the underlying component. Specific methods and properties are used to locate, update, insert, and delete data in collections. Specific methods are available for effective-dated data.

Slide 86 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

133

Working with Component Interface Collections

Lesson 6

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

134

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs


Objectives
By the end of this lesson, you will be able to: Describe component interface API. Build component interface APIs. Generate runtime code templates. Establish a PeopleSoft session. Deploy component interfaces. Test the Java SDK sample. Create a Java API.

Slide 88 _______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

135

Building Component Interface APIs

Lesson 7

Describing Component Interface APIs


An API (application program interface) is a set of routines, protocols, and tools for building software applications. PeopleSoft provides support for building component interface APIs in: Microsoft COM (Visual Basic and Active Server pages). C/C++. Java Binding.

Slide 89 _______________________________________________________________________________________________________

Instructor Notes
This section presents a review question for the current objective. Question: Describing Component Interface APIs PeopleSoft provides support for building component interface APIs. 1. True 2. False Answer The answer is 1 (true).

136

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Building Component Interface APIs


To build component interface APIs: 1. Open any component interface in PeopleSoft Application Designer. 2. Select Build, PeopleSoft APIs. 3. Select the appropriate check boxes and enter the appropriate paths, depending on the type of binding that you want to build. 4. Select All APIs. 5. Click OK to build the bindings that you selected.
Slide 90 _______________________________________________________________________________________________________

Student Notes
There are three group boxes in the Build PeopleSoft API Bindings dialog box:

Build PeopleSoft API Bindings dialog box You can select which bindings to create and the target directory where the corresponding files will be created.
PeopleSoft Proprietary and Confidential 137

Building Component Interface APIs

Lesson 7

Instructor Notes
This section discusses how to explain: CTE environment Microsoft COM Java classes C header files

Explaining CTE environment In the CTE environment, there is one PeopleTools directory that all students use even though they have separate databases. When the Build APIs is done, the files are written to the class directory (make note you need to change the default). This only needs to be done once. Explaining Microsoft COM Target directory directory where COM type library is created. Typically <PS_HOME>\bin\client\winx86. COM server DLL location is where the PeopleSoft API adapter (psapiadapter.dll) is located: <PS_HOME>\bin\client\winx86. Use the AutoRegister check box to execute the registry file immediately upon building the API. Use the Clean-up Registry check box to clean up the registry if you have applied previous versions of PeopleSoft_PeopleSoft.reg. Explaining Java Classes The target directory indicates the directory where the Java class source files will be created. Explaining C Header Files The target directory indicates the directory where the C header source files will be created. Question: Building Component Interface APIs When building APIs, you should always select all component interfaces. 1. True 2. False Answer The answer is 1 (true).

138

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Generating Runtime Code Templates


You can create a runtime template in PeopleSoft Application Designer for Visual Basic, C++, and Java. To generate the template: 1. Open the desired component interface in Application Designer. 2. Right-click anywhere in the Definition view to display the pop-up menu. 3. Select either Generate Visual Basic Template, Generate C++ Template, or Generate Java Template. 4. Open the generated file and modify the source as needed.
Slide 91 _______________________________________________________________________________________________________

Student Notes
The template file is generated in the directory specified by the TEMP or TMP system environment variable on your client machine:

Visual Basic template

Instructor Notes
The student notes show an example of the Visual Basic runtime template generated in PeopleSoft Application Designer. The next slide shows the Visual Basic template, then in the activity students will generate a Java template. All the templates including PeopleCode are structured identically; they are simply language specific.

PeopleSoft Proprietary and Confidential

139

Building Component Interface APIs

Lesson 7

Generating Runtime Code Templates (continued)


The runtime template that is generated closely resembles the PeopleCode. The following is performed in the code: Declare the session object. Create the PeopleSoft session object to enable access to the PeopleSoft system. Connect to the PeopleSoft application server by using the Connect method. Get a reference to the component interface that provides its name. Set the keys for the component interface. Use the Get method to retrieve data from the database, associated with the key values. Get and print properties at level 0. Get and print properties at level 1. Execute the Standard and Custom methods. Disconnect from the PeopleSoft application server by using the Disconnect method.

Slide 92 _______________________________________________________________________________________________________

Student Notes
See Appendix A Sample Code, STUDENT_PROFILE component interface visual basic template.

Instructor Notes
This section discusses how to: Compare the Visual Basic template to the PeopleCode template. Question: Generate runtime code templates.

Comparing the Visual Basic Template to the PeopleCode Template Point out the similarities to the PeopleCode template that was produced for the same component interface. Additional sections would be added if this component interface had collections. The chief difference between the two templates is establishing the PeopleSoft session connection; this topic is covered on the next slide. Question: Generating Runtime Code Templates PeopleSoft provides the ability to generate component interface templates for:
140 PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

1. Visual Basic 2. C++ 3. Java 4. All of the above Answer The answer is 4 (all of the above).

PeopleSoft Proprietary and Confidential

141

Building Component Interface APIs

Lesson 7

Establishing a PeopleSoft Session


The Session object controls security and access to the PeopleSoft system. You must sign on to the PeopleSoft session with a valid operator ID and password when you use the Connect method:
oSession.Connect(1, strAppServerPath, strUserID, strPassword, 0)

Slide 93 _______________________________________________________________________________________________________

Student Notes
Note. In the generated runtime templates, the connect parameters are coded as prompts.

Instructor Notes
This section discusses how to: Explain the Connect method. Question: Establish a PeopleSoft session.

Explaining the Connect Method Explain that the Connect method connects a session object to the PeopleSoft application server. In the online system, students connected by using the current session because they were already logged in to the PeopleSoft application server with the appropriate authentication.
&oSession = %Session;

Explain that for third-party applications students need to establish that connection. The user ID and password provide the security access to the component interface. (The permission list with the component interface must be assigned to that user profile.) The Connect() method uses the following syntax:
(version, {"EXISTING" | ConnectID:Port}, UserID, Password, ExtAuth) EXISTING was

used in previous releases to reference a current connection, so it remains for backward compatibility. In any new code just use the session variable. The ExtAuth parameter is required, but it is not used in this release. Specify 0.

Question: Establishing a PeopleSoft Session Which method is used to establish a PeopleSoft session from an external application? 1. Connect 2. Disconnect 3. Count

142

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

4. Session Answer The answer is 1 (Connect).

PeopleSoft Proprietary and Confidential

143

Building Component Interface APIs

Lesson 7

Deploying Component Interfaces


When deploying COM component interfaces on a local client machine or web server, you must have the following: The third-party COM application. The PeopleSoft application server and database server. The Java Virtual Machine (JVM) supplied with Sun Microsystems Java Development Kit (JDK) found in the %PS_HOME%\JRE directory. A copy of the type library PeopleSoft_PeopleSoft.tlb that was generated during the Build PeopleSoft API Bindings process. A copy of the registry file PeopleSoft_PeopleSoft.reg that was generated during the Build PeopleSoft API Bindings process.

Slide 94 _______________________________________________________________________________________________________

Student Notes
You need to add the type library PeopleSoft_PeopleSoft.tlb to the Visual Basic applications. An example in Microsoft Excel would be Tools, References:

References VBAProject dialog box

144

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

See Also PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Programming Component Interfaces in COM.

Instructor Notes
This section discusses how to: Find the Microsoft Excel spreadsheet. View a Visual Basic example.

Finding the Microsoft Excel Spreadsheet Microsoft Excel is loaded on the student workstations. The PeopleTools SDK supplies the Excel spreadsheet sdk_bus_exp.xls, which is located in: <pshome>\sdk\pscompintfc\src\com\samples\vba\sdk_bus_exp Viewing a Visual Basic Example Warning! This is not a tested and scripted activity. Students can see the Visual Basic code by opening the Microsoft Excel spreadsheet. 1. Select Enable Macros. 2. Select Tools, Macros, Visual Basic Editor to view the Visual Basic code. 3. Select Tools, References. The words MISSING:PeopleSoft_PeopleSoft should appear. 4. Select View, Project Explorer to view the entire project.

Visual Basic code for sdk_bus_exp

PeopleSoft Proprietary and Confidential

145

Building Component Interface APIs

Lesson 7

Deploying Component Interfaces (continued)


PeopleSoft supports component interface APIs in C++. To set up the C++ API: Build the component interface APIs. Set up the C++ environment. Generate a C++ runtime code template.

Slide 95 _______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44: PeopleSoft Component Interfaces, Programming Component Interfaces in C++.

Instructor Notes
Discuss these points with students: The build API is the same build as the one shown in slide 86 student notes, by selecting the check box for C Header and indicating the target directory. You create templates the same way, by right-clicking the component interface and selecting Generate C template.

146

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Deploying Component Interfaces (continued)


PeopleSoft supports component interface APIs in Java. To set up the Java API: Build the component interface APIs. Set up the Java environment. Generate a Java runtime code template.

Slide 96 _______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44: PeopleSoft Component Interfaces, Programming Component Interfaces in Java..

Instructor Notes
The build API is the same build as shown in slide 86 student notes, by selecting the checkbox for Java and indicating the target directory. Templates are created the same way by right clicking on the component interface and selecting Generate Java template.

PeopleSoft Proprietary and Confidential

147

Building Component Interface APIs

Lesson 7

Testing the Java SDK Sample


The PeopleTools SDK provides a sample Java program for SDK Business Expense. This sample provides: Examples of implementing all of the standard properties. Examples of implementing all of the standard methods.

Slide 97 _______________________________________________________________________________________________________

Student Notes
This screen shot shows a sample Java program for PeopleSoft SDK Business Expense:

PeopleSoft SDK Business Expense for Java sample The source code is located in %PS_HOME%\sdk\PSCOMPINTFC\src\java\samples\sdk_bus_exp

Instructor Notes
This screen shot shows what the Java SDK example looks like once users connect to a session and select an employee. Notice that the template lists all of the possible methods available. In Activity 5, students will compile and test the Java SDK.

148

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Testing the Java SDK Sample (continued)


You compile the Java SDK sample from the source directory. The class path must include: The jar files psjoa.jar and psppm.jar. The target directory selected during the Build API process (the generated PeopleSoft directory). The source directory (where the java source is stored).

Slide 98 _______________________________________________________________________________________________________

Student Notes
Class Path psjoa.jar file psppm.jar Generated directory Source directory SDK Sample PS_HOME\ class\psjoa.jar PS_HOME\class\psppm.jar PS_HOME\class PS_HOME\SDK\pscompintfc\src\java\samples

Note. All the PeopleSoft generated java files must be compiled.

Instructor Notes
Discuss these points: Javac compiles Java source code and produces bytecode class files (compiled Java); the source code must have a .java suffix and the resulting class files must have a .class suffix. There are several java files that will be included in the PeopleSoft generated directory after you build the PeopleSoft APIs, these java files must be compiled and the class files must be available in the PeopleSoft generated directory in order for the java files to run. The class path provides a list of starting search directories, which can include JAR (Java archive) files.

An alternative to setting the classpath option for each application is setting the CLASSPATH environment variable. Related classes are grouped in packages.

PeopleSoft Proprietary and Confidential

149

Building Component Interface APIs

Lesson 7

In the Java source code for the SDK_BUS_EXP, you will see a package name and some import statements. The import statements enable your program to access any classes belonging to those packages:
package sdk_bus_exp; import java.io.*; import java.util.*; import psft.pt8.joa.*; import java.math.*; import PeopleSoft.Generated.CompIntfc.*;

CompileJava.bat
@echo off pushd %CD% :CheckArgs

A batch file (z:\STAnnn\bat\compileJava.bat) that substitutes these variables has been created on the workstation. You may want students to view this file:

if "%PS_HOME%"=="" :Begin set _GEN_DIR=%PS_HOME%\class if not exist %_GEN_DIR%\PeopleSoft\Generated\CompIntfc set _SDK_DIR=%PS_HOME%\SDK\pscompintfc\src\java\samples if not exist %_SDK_DIR%\sdk_bus_exp

goto :PSHomeNotSet

goto :GenNotFound

goto :SdkNotFound

set _CLASSPATH=%PS_HOME%\class\psjoa.jar;%_GEN_DIR%;%_SDK_DIR%;%PS_HOME%\class\psppm.jar set _JAVAHOME=C:\bea\jdk141_03\bin set _CMD=%_JAVAHOME%\javac -g -classpath "%_CLASSPATH%" @echo Begin> Compile.log rem ***** Compile Generated Files ***** cd %PS_HOME%\class\PeopleSoft\Generated\CompIntfc for /F "delims==" %%i IN ('dir /b %PS_HOME%\class\PeopleSoft\Generated\CompIntfc\*.java') do ( @echo Compiling %%i %_CMD% %%i 2>> z:\%USERNAME%\temp\Compile.log ) rem ***** Compile SDK ***** @echo Compiling %_SDK_DIR%\sdk_bus_exp\sdk_bus_exp.java %_CMD% %_SDK_DIR%\sdk_bus_exp\sdk_bus_exp.java 2>> z:\%USERNAME%\temp\Compile.log @echo End>> z:\%USERNAME%\temp\Compile.log goto :End

150

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

:PSHomeNotSet @echo PS_HOME not set goto :End :GenNotFound @echo Generated Files not found in %_GEN_DIR% goto :End :SdkNotFound @echo Generated Files not found in %_SDK_DIR% goto :End :End popd set _GEN_DIR= set _SDK_DIR= set _CLASSPATH= set _JAVAHOME= set _CMD=

Note. The push and pop are just used to populate an array with the variables and then remove them at the end.

PeopleSoft Proprietary and Confidential

151

Building Component Interface APIs

Lesson 7

Testing the Java SDK Sample (continued)


Run the Java SDK sample from the source directory and uses: The Java Virtual Machine (JVM) supplied with Sun Microsystems JDK. The class path must include the psjoa.jar file, the generated directory, and the source directory.

Slide 99 _______________________________________________________________________________________________________

Student Notes
Run the program from the Java home directory. For WebLogic, it is usually C:\bea\jdk131\bin.
Class Path Psjoa.jar file Generated directory Source directory SDK Sample PS_HOME\ class\psjoa.jar PS_HOME\class PS_HOME\SDK\pscompintfc\src\java\samples

Instructor Notes
A batch file that substitutes these variables has been created on the workstation at \bat\runJava.bat. You may want students to view this file: RunJava.bat
@echo off pushd %CD% :CheckArgs if "%PS_HOME%"=="" :Begin set _GEN_DIR=%PS_HOME%\class if not exist %_GEN_DIR%\PeopleSoft\Generated\CompIntfc\ set _MY_DIR=z:\%USERNAME%\USER if not exist %_MY_DIR%\student_profile\STUDENT_PROFILE.class :MYNotFound goto goto :GenNotFound goto :PSHomeNotSet

set _CLASSPATH=%PS_HOME%\class\psjoa.jar;%_GEN_DIR%;%_MY_DIR%;%PS_HOME%\class\psppm.jar set _JAVAHOME=C:\bea\jdk141_03\bin set _CMD=%_JAVAHOME%\java -classpath "%_CLASSPATH%" student_profile.STUDENT_PROFILE cd %_MY_DIR% %_CMD% goto :End

152

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

:PSHomeNotSet @echo PS_HOME not set goto :End :GenNotFound @echo Generated Files not found in %_GEN_DIR% goto :End :MYNotFound @echo Generated Files not found in %_GEN_DIR% goto :End :End popd set _GEN_DIR= set _MY_DIR= set _CLASSPATH= set _JAVAHOME= set _CMD=

PeopleSoft Proprietary and Confidential

153

Building Component Interface APIs

Lesson 7

Activity 5:

Testing SDK Java API Sample


In this activity, you will review the activity overview and: 1. Build PeopleSoft APIs. 2. Compile the PeopleSoft Generated Java and the SDK_BUS_EXP Java code. 3. Run and test the SDK Java sample. See Integration Tools: Activity Guide, lesson 7, Building Component Interface APIs, Activity 5: Testing SDK Java API Sample.

Slide 100 ______________________________________________________________________________________________________

Instructor Notes
Note. It will take approximately 10-15 minutes for the java compile. Make sure only one student or the instructor runs the compile. This activity should take approximately 30 minutes.

This section discusses how to: Build PeopleSoft Component Interface APIs. View the Bat File. Explain the application server port.

Building PeopleSoft Component Interface APIs Discuss these points: compileJava.bat Ask students to open Microsoft Internet Explorer and navigate to z:\STAnnn\bat, then right-click on compileJava.bat and select Edit (or the bat file will run) to view the bat file. %PS_HOME% will be retrieved from the environment. Start, Settings, Control Panel, System, Advanced tab, Environment variables. When the Java is compiled, you will see the .class files in the PeopleSoft generated directory: The correct PS_HOME directory appears by default in the dialog box. Students will need to change the target directory to \class instead of \web\psjoa.

154

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

The SDK class files are created in <PS_HOME>\sdk\PSCOMPINTFC\src\java\samples\sdk_bus_exp.

sdk_bus_exp directory runJava.bat This file should run as is. It will open a DOS window with the Java menu displayed. Students who are finished early may want to test some of the other methods and properties. There are some dependencies for using these properties (what is currently active). Examples:

GetPropertyByName

GetPropertyInfoByName Point out that the source code for this program is supplied in the SDK and that students can examine these samples back at their offices. If students want to add more data, they can use these expense codes:
Code 01 Description Airfare

PeopleSoft Proprietary and Confidential

155

Building Component Interface APIs

Lesson 7

Code 02 03 04 05 06 07 08

Description Lodging Car Rental Meals Telephone Travel Relocation Entertainment

Students can use these departments:


DeptID 00001 10000 10100 10200 10300 10400 10500 Description Corporate Headquarters Administrative Division Office of President Human Resources Controllers Retail Services Business Services

Students may want to try invalid values also. Explaining the Application Server Port In the CTE, the ports are assigned by workstation, use the following chart:
Workstation STA101 STA102 STA103 STA104 STA105 STA106 STA107 SAT108 STA109 STA110 STA111 STA112 TCA101 Database T1B84401 T1B84402 T1B84403 T1B84404 T1B84405 T1B84406 T1B84407 T1B84408 T1B84409 T1B84410 T1B8811 T1B8812 T1B84499 Application Server Port 9010 9020 9030 9040 9050 9060 9070 9080 9090 9100 9110 9120 9990

156

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Activity Overview
In this activity, you will build PeopleSoft APIs, compile the Java SDK sample, and run the SDK Java sample. The following files located in the bat folder for each student are available to compile and run the java: compileJava.bat runJava.bat

Building PeopleSoft Component Interface APIs


Each time you create or modify component interfaces, you need to rebuild all component interface APIs. Note. In the CTE environment, all students are accessing the same version of PeopleTools, therefore only one student needs to build the APIs. To build PeopleSoft APIs: 1. Open a component interface in PeopleSoft Application Designer. 2. Select Build, PeopleSoft APIs. 3. Build the APIs for Java by using a target directory of <PSHOME>\class for example: z:\PeopleTools\844\class. Results The system generates the APIs and creates the directory structure PeopleSoft\Generated\CompIntfc

PeopleSoft generated component interface directory

Compiling the PeopleSoft Generated Java and the SDK_BUS_EXP Java code
To compile the PeopleSoft generated java and the SDK_SDK_EXP java code: 1. Open Windows Explorer and navigate to z:\TCA101\BAT. 2. Right-click on compilejava.bat and select Edit to view the bat file. 3. Double-click the file compilejava.bat to run it.

PeopleSoft Proprietary and Confidential

157

Building Component Interface APIs

Lesson 7

Note. Only one student should run the file. The compile will take 10- 15 minutes 4. When the compile has completed: In windows explorer, navigate to <PS_HOME>\SDK\pscompintfc\src\java\samples\sdk_bus_exp and verify that the class files were created for sdk_bus_exp. In windows explorer, navigate to the <PS_HOME>\class\ PeopleSoft\Generated\CompIntfc and verify that the class files were created.

Results

Class file created in the PeopleSoft generated component interface directory

Running and Testing the SDK Java Sample


To run and test the SDK Java sample: 1. Run the program by using the runJava.bat file, located in the \bat directory. 2. Sign in by entering the following information:
Page Element Application Server Name Application Server Port Number PeopleSoft UserID PeopleSoft UserID Password Value or Status CTESERVER <your application server port> PTINT PTINT

3. Select 1)Get. 4. Accept the defaults for Interactive mode, GetHistoryItems and EditHistoryItems. 5. Enter employee ID 6602. 6. Select (9) InsertItem.

158

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

7. Enter todays date for the expense period. 8. Select (19) InsertItem to add a detail transaction. 9. Select your new expense period. 10. Enter the following information:
Page Element Expense Charge Date Expense Code Expense Amount Business Purpose Department ID Value or Status Todays date 01 400 Trip to Ca. 10100

11. Sign in to the browser using PTINT and password PTINT. 12. Select Int Tools Samples, SDK Business Expense. 13. Select Employee ID: 6602. Results

Results after saving changes in Java program This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

159

Building Component Interface APIs

Lesson 7

Creating a Java API


To generate a Java API: 1. Open the component interface. 2. Select Generate Java Template. 3. Modify the template. 4. Compile the Java. 5. Run the API.
Slide 101 ______________________________________________________________________________________________________

Student Notes
See Appendix A Sample Code, STUDENT_PROFILE Component Interface Java Template.

Instructor Notes
Point out the following: Students must specify a package name. The session connection section prompts for the information, builds the connection string, and starts a session with the application server. For the Get and Set sections, students must modify the program to perform the tasks that they want to perform.

160

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Creating a Java API (continued)


The declarations section imports the Java classes necessary to work with PeopleSoft:
//package <*>; import java.io.*; import psft.pt8.joa.*; import PeopleSoft.Generated.CompIntfc.*; public class STUDENT_PROFILE { public static ISession oSession;

Slide 102 ______________________________________________________________________________________________________

Student Notes
Note. The package should be uncommented and the package name should replace <*>.

Instructor Notes
Discuss these points: The package name must be the same as the directory where the source file is located. If you want to use the package name my_package, then the file student_profile.java should be created in: %PS_HOME%\web\psjoa\my_package\student_profile.java This Java file must include:
package my_package; import java.io.*;

To compile the file:


javac -classpath %PS_HOME%\web\psjoa\my_package;%PS_HOME%\web\psjoa %PS_HOME%\web\psjoa\my_package\student_profile.java

PeopleSoft Proprietary and Confidential

161

Building Component Interface APIs

Lesson 7

Creating a Java API (continued)


Modify the template similar to the PeopleCode template: Uncomment the statements that you want to execute. Comment the statements that you do not want to execute. Add statements where necessary. Replace [*] with appropriate values.

Slide 103 ______________________________________________________________________________________________________

Instructor Notes
Comments in Java are denoted by //.

162

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Creating a Java API (continued)


Use this code to display a prompt for StudentName, read the data entered, and update the field StudentName with the data:
String strStudentName; System.out.println("oStudentProfile.StudentName: " + oStudentProfile.getStudentName()); strStudentName = inData.readLine(); oStudentProfile.setStudentName(strStudentName);

Slide 104 ______________________________________________________________________________________________________

Instructor Notes
Discuss these points: Note that the template does not supply the declarations (for example, String strStudentName). To retrieve the data that a user entered, use the inData.readLine(). Uncomment the //oStudentProfile.setStudentName(<*>); and enter the string name in place of <*>.

PeopleSoft Proprietary and Confidential

163

Building Component Interface APIs

Lesson 7

Activity 6:

Creating a Java Component Interface API


In this activity, you will review the activity overview and: 1. Create a Java template for STUDENT_PROFILE. 2. Modify the Java template for STUDENT_PROFILE to add new students. 3. Compile the Java code. 4. Run the new Java program. See Integration Tools: Activity Guide, lesson 7, Building Component Interface APIs, Activity 6: Creating a Java Component Interface API.

Slide 105 ______________________________________________________________________________________________________

Student Notes
See Appendix A Sample Code, STUDENT_PROFILE.java

Instructor Notes
Remind students that they built the API in the last activity. When they selected Build, PeopleSoft APIs, all APIs were selected, and students have made no changes to STUDENT_PROFILE since then. Verifying the compile_stu_profile and run_stu_profile bat files The compile_stu_profile.bat and run_stu_profile.bat files are located in 2 folders z:\STAnnn\bat and z:\STAnnn\Tools\1022_IntTools. Insure that MY_DIR is set to the USER folder (because thats where the code is: set _MY_DIR=z:\%USERNAME%\USER) Explaining Changes to the Java Template This table compares the template as generated and as changed by students:
Template //package <*>; //***** Execute Get ***** if (!oStudentProfile.get()) { System.out.println("\nNo rows exist for the specified keys.\nFailed to get the Component Interface."); ErrorHandler(); return; } Change package student_profile; //***** Execute Get ***** //if (!oStudentProfile.get()) { // System.out.println("\nNo rows exist for the specified keys.\nFailed to get the Component Interface."); // // //} ErrorHandler(); return;

164

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Template //***** Execute Create ***** //if(!oStudentProfile.create()) { // System.out.println("\nUnable to Create Component Interface for the Add keys provided.\n"); // //} return;

Change //***** Execute Create ***** if(!oStudentProfile.create()) { System.out.println("\nUnable to Create Component Interface for the Add keys provided.\n"); return; }

//***** Set Level 0 Properties *****

//***** Set Level 0 Properties ***** String strStudentName; String strCustomerID; //String strSameAddrCustomer; String strProjectRole;

System.out.println("oStudentProfile.StudentId: " + oStudentProfile.getStudentId()); //oStudentProfile.setStudentId(<*>); System.out.println("oStudentProfile.StudentName: " + oStudentProfile.getStudentName()); //oStudentProfile.setStudentName(<*>); System.out.println("oStudentProfile.CustomerId: " + oStudentProfile.getCustomerId()); //oStudentProfile.setCustomerId(<*>); System.out.println("oStudentProfile.SameAddrCustomer: " + oStudentProfile.getSameAddrCustomer()); //oStudentProfile.setSameAddrCustomer(<*>); System.out.println("oStudentProfile.ProjectRole: " + oStudentProfile.getProjectRole()); //oStudentProfile.setProjectRole(<*>);

//System.out.println("oStudentProfile.StudentId: " + oStudentProfile.getStudentId()); //oStudentProfile.setStudentId("NEW"); System.out.println("oStudentProfile.StudentName: " + oStudentProfile.getStudentName()); strStudentName = inData.readLine(); oStudentProfile.setStudentName(strStudentName); System.out.println("oStudentProfile.CustomerId: " + oStudentProfile.getCustomerId()); strCustomerID = inData.readLine(); oStudentProfile.setCustomerId(strCustomerID); System.out.println("oStudentProfile.SameAddrCustomer: " + oStudentProfile.getSameAddrCustomer()); oStudentProfile.setSameAddrCustomer("Y"); System.out.println("oStudentProfile.ProjectRole: " + oStudentProfile.getProjectRole()); strProjectRole = inData.readLine(); oStudentProfile.setProjectRole(strProjectRole);

//***** Execute Save ***** //if (!oStudentProfile.save()) { // System.out.println("Unable to Save Component Interface"); // // //} ErrorHandler(); return;

//***** Execute Save ***** if (!oStudentProfile.save()) { System.out.println("Unable to Save Component Interface"); ErrorHandler(); return; }

PeopleSoft Proprietary and Confidential

165

Building Component Interface APIs

Lesson 7

Template //***** Execute Cancel ***** //if (!oStudentProfile.cancel()) { // System.out.println("Unable to Cancel Component Interface"); // // //} ErrorHandler(); return;

Change //***** Execute Cancel ***** if (!oStudentProfile.cancel()) { System.out.println("Unable to Cancel Component Interface"); ErrorHandler(); return; }

Note. A copy of the modified code is available in \1022_IntTools\scripts\STUDENT_PROFILE.java.

Activity Overview
In lesson 4, Creating and Testing Component Interfaces, you created the component interface STUDENT_PROFILE. You will now create a Java API to enter new students for external organizations through a Java program. Use the following steps to accomplish this task. 1. Create a Java template for STUDENT_PROFILE . 2. Create a new folder under z:\STAnnn\user for student_profile. Note. The name of the folder must match the package name in the java code and it is case sensitive. 3. Copy the template to the new folder. 4. Modify the template to include a package name and prompt for student name, customer ID, and project role. 5. Compile the Java code. 6. Run and test the Java code by adding yourself as a student for XYZ customer.

Creating a Java Template for STUDENT_PROFILE


To create a Java template for STUDENT_PROFILE: 1. Sign on to Application Designer as PTINT. 2. Open the component interface STUDENT_PROFILE. 3. Right-click the component interface view. 4. Select Generate Java template. The message will indicate the directory where the java template was created.

166

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

5. Create a new folder under z:\STAnnn\user (where nnn is your workstation) named student_profile. 6. Copy the generated java template to the new student_profile folder.

Modifying the Java Template for STUDENT_PROFILE to Add New Students


To modify the Java template for STUDENT_PROFILE to add new students: 1. Uncomment the package and provide the name. 2. Comment out the Get command. 3. Uncomment Create. 4. The default is created with the student ID NEW. 5. Add string values for variables and read data into the strings. 6. Read values from Student name, Customer ID, and Project Role. 7. Default the field SameAddrCustomer to Y. 8. Uncomment Save. 9. Uncomment Cancel. Note. A copy of the modified code is available in \1022_IntTools\scripts\STUDENT_PROFILE.java.

Compiling the Java Code


To compile the Java code: 1. Run the batch file compile_stu_profile.bat. 2. Check that the STUDENT_PROFILE.class file was created in z:\STAnnn\user\student_profile.

Running the New Java Program


To run the new Java program: 1. Run the batch file run_stu_profile.bat. 2. Enter the following information:
Page Element Application Server Name Application Server Port Number PeopleSoft UserID PeopleSoft UserID Password Student Name Value or Status CTESERVER <your appserver port> see appendix A PTINT PTINT <Your last name, your first name>

PeopleSoft Proprietary and Confidential

167

Building Component Interface APIs

Lesson 7

Page Element Customer ID Project Role

Value or Status XYZ DBA

3. Select Students, Personal Details on the browser to view your update. Results The new student will be displayed:

Student Personal Details page This concludes the activity. Do not continue.

168

PeopleSoft Proprietary and Confidential

Lesson 7

Building Component Interface APIs

Review
In this lesson, you learned that: PeopleSoft provides support for building component interface APIs in Microsoft COM, C/C++, and Java. You build PeopleSoft component interface APIs in PeopleSoft Application Designer by opening a component interface and selecting Build, PeopleSoft APIs. You can generate runtime code templates for Visual Basic, C/C++, or Java based on an existing component interface. A PeopleSoft session is necessary to connect to external applications. Depending on the type of component interface API, you must follow specific steps for deploying the API. The PeopleTools SDK provides samples for creating your own component interface APIs. To create a Java API, you generate the template, modify the code, and compile the Java code.

Slide 106 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

169

Building Component Interface APIs

Lesson 7

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

170

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility


Objectives
By the end of this lesson, you will be able to: Describe the Excel to Component Interface Utility. Assign public access. Connect to a PeopleSoft application. Create a template. Enter data. Submit data to PeopleSoft. Deploy the Excel workbook.

Slide 108 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

171

Using the Excel to Component Interface Utility

Lesson 8

Describing the Excel to Component Interface Utility


The Excel to Component Interface Utility is an excel spreadsheet that contains the visual basic code enabling you to upload data to your PeopleSoft database. The code: Formats the spreadsheet data into a PeopleSoft readable Document Object Model (DOM) structure. Submits the DOM structure to PeopleSoft. Parses the DOM structure. Utilizes the component interface to create entries in the PeopleSoft database. Based upon the save results, another DOM document is created that returns success, error or warnings. Records in error can be corrected and resubmitted.

Slide 109 ______________________________________________________________________________________________________

Student Notes
Note. A Microsoft Excel spreadsheet has a physical limitation of 252 columns and 65k rows. When you create a template and submit data, you will need to keep these restrictions in mind.

See PeopleTools 8.44 PeopleBook: PeopleSoft Component Interfaces, Using Excel to Component Interface Utility.

Instructor Notes
Since students have just completed the lessons on component interfaces reinforce what the component interface does: Allows consistent data into PeopleSoft Uses all the business logic built into the PeopleSoft component. Executes all the necessary PeopleCode events and field-level edits.

The Excel worksheets are used as a template to create your own worksheets that are specific to the business logic that you need to use when uploading data into your PeopleSoft system.

172

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Note. As delivered, the code supports inserting new rows in the PeopleSoft database, you can construct a SOAP/XML request to update or get component interface rows. In lesson 20 students will use the Find method with a web service.

PeopleSoft Proprietary and Confidential

173

Using the Excel to Component Interface Utility

Lesson 8

Describing the Excel to Component Interface Utility (continued)


The Excel to Component Interface workbook has five (5) worksheets, the first is the coversheet, and the next four are the steps used to upload data: 1. Coverpage 2. Connection Information 3. Template 4. Data Input 5. Staging and Submission
Slide 110 ______________________________________________________________________________________________________

Student Notes
The coversheet is used to provide information about the workbook and the process steps:

ExcelToCI spreadsheet

174

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Instructor Notes
Question: Describing the Excel to Component Interface Utility The Excel to Component Interface Utility code formats spreadsheet data into a PeopleSoft readable Document Object Model (DOM) structure and submits it to the PeopleSoft database. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

175

Using the Excel to Component Interface Utility

Lesson 8

Assigning Public Access


Public access is necessary in order to use the ExcelToCI functionality: Public Access is enabled on the web profile page. A public user ID and password need to be specified. After changing the web profile, the web server must be rebooted to take affect.

Slide 111 ______________________________________________________________________________________________________

Student Notes
Note. The public access user needs basic permissions access to WEBLIB_SOAPTOCI. PeopleSoft supplies the role PeopleSoft Guest that includes the basic permission needed. Use the following navigation path to access the web profile page:
Page Name Web Profile Navigation PeopleTools, Web Profile, Web Profile Configuration

Web profile security settings See Also PeopleTools 8.44: Internet Technology PeopleBook, Configuring Advanced Environment Features.

176

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Instructor Notes
All of the configuration files used in previous PeopleTools releases are set in the web profile in PeopleTools 8.44. The following will no longer exist: configuration.properties pstools.properties browserprops.xml cookierules.xml

The Public Access user should not have the same userID or permission used with ExcelToCI.exe and does not need to have access to the component interface. Question: Assigning Public Access Public Access is assigned in: 1. Web Profile 2. configuration.properties 3. User Profile 4. Permission List Answer The answer is 1 (Web Profile).

PeopleSoft Proprietary and Confidential

177

Using the Excel to Component Interface Utility

Lesson 8

Connecting to PeopleSoft
The Connect Information worksheet is used to define the connection to the web server for the PeopleSoft database: Default information is displayed. The default information can be customized by changing the values in the visual basic code. The value for the action field is populated when the component interface is retrieved from the database.

Slide 112 ______________________________________________________________________________________________________

Student Notes
The Connect Information worksheet defines the PeopleSoft site on the web server:

Connect Information

Instructor Notes
The connection information here is a little different than for the component interface APIs. Keep in mind that you are not connecting via the component interface you will not even define the component interface to use until step 2. Here you are making a connection to the webserver (same information as contained in your URL when you logon to PIA). The DOM documents created by the ExcelToCI Utility use iScripts to make the connection and parse the DOM documents created by the utility and then call the component interface.

178

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Note. At this point, you may choose to have students open the ExcelToCI spreadsheet so they can look at the worksheets online as you explain them in the next few slides. Keep in mind that it is not a scripted activity.

Customizing the Defaults To customize the defaults, you must change the visual basic code in the Excel spreadsheet: 1. Tools, Macros, Visual Basic 2. The easiest way is to do a find for yourPIAserver and select Current Project radio button.

Visual Basic code that sets the default values Question: Connecting to PeopleSoft The connection information worksheet defines the connection to: 1. PeopleSoft Application Server. 2. PeopleSoft Database. 3. PeopleSoft Web Server. 4. PeopleSoft File Server. Answer The answer is 3 (Web Server).

PeopleSoft Proprietary and Confidential

179

Using the Excel to Component Interface Utility

Lesson 8

Connecting to PeopleSoft (continued)


The valid actions for the worksheet are:
Action Create Update UpdateData Description Add new key at level 0. Add keys at levels other than 0. Update non-key data based on the key values provided

Slide 113 ______________________________________________________________________________________________________

Student Notes
Note. You need to submit data for each action type separately. You may want to create separate workbooks or data input sheets for the action.

Instructor Notes
If you have updates and creates on the same data input worksheet, you will get errors for the rows that do not match the action. If you change the action and then submit again, the data will be loaded. Create action is only available if you have the component interface contains create keys (add action for the component). After connecting to a component interface, this action field will be automatically updated.

180

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Creating a Template
The template worksheet displays the current template and a template action bar. To begin a new session, you need to create a template. The template is based on the structure of the component interface. The login user must have been granted authority to the component interface.

Slide 114 ______________________________________________________________________________________________________

Student Notes
The Create template icon prompts for login information.

ExcelToCI login to create a template

Instructor Notes
The connection to the database uses the web profile public access; the ability to use a specific component interface requires a separate login to retrieve the component interface.

PeopleSoft Proprietary and Confidential

181

Using the Excel to Component Interface Utility

Lesson 8

Creating a Template
To create a new template: 1. Select New Template. 2. Enter the login information and component interface name. 3. Select the input cells to use for the Data Input Sheet. 4. Select New Data Input to create the data input sheet.
Slide 115 ______________________________________________________________________________________________________

Student Notes
Note. When you create a new template, any previous information will be deleted.

182

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Creating a Template (continued)


The component interface is retrieved from the PeopleSoft database and displayed. Field attributes are displayed above the field name. The input area is displayed beneath the fields name. The template is used to build the data input page.

Slide 116 ______________________________________________________________________________________________________

Student Notes
The template for the component interface is displayed with all of the levels and fields displayed:

Template for SDK_BUS_EXP

Instructor Notes
When you select a component interface for the template, you will see all of the exposed collections and fields. Review the page shot of the Create Template point out the following: Collection defines the record name Property defines the field Record type 000 = level 0, 100 = level 1, 110 = level 2 For fields the following is defined field type, field length, key/required and sequence.

PeopleSoft Proprietary and Confidential

183

Using the Excel to Component Interface Utility

Lesson 8

Creating a Template (continued)


The data input sheet is built from the template page. The template action toolbar provides the capability to: Create a new template. Create a new data input worksheet. Select the fields for input. Select the fields for submission. Insert new child rows.

Slide 117 ______________________________________________________________________________________________________

Student Notes
Selected cells will be displayed in pink and fields selected for submission displayed in blue on the worksheet:

Template with all cells selected

Instructor Notes
From the template, you will need to build the Data Input sheet When you select New Data Input, you will receive a message Are you sure you want to delete all the existing data in the Data Input worksheet. Explain how the toolbar buttons are used:
Toolbar New Template Select Input Cell or Select All Input Cells Description Builds a new template based on the component interface supplied. Makes the cell(s) available for input.

184

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Toolbar Deselect Input Cell or Deselect All Input Cells Include for Submission or Include All for Submission Clear Template New Data Input Restore Input Cells Insert New Child

Description Removes the cell(s) from input These cells will not appear on the data input sheet but will get sent to the database. You can use this for fields that have default values or properties you want in the structure of the staging and submission sheet. Clears the current spreadsheet (you will need to build a new template). Creates the data input worksheet based on the selected cells. Restores the template to its original state and clears the defaults. Copies the select row to be inserted as a child. This creates multiple occurrences of the same record type.

PeopleSoft Proprietary and Confidential

185

Using the Excel to Component Interface Utility

Lesson 8

Entering Data
Data is entered in the Data Input Worksheet. The scroll levels are displayed in different colors. Data is entered in the appropriate cells. The toolbar contains one action Stage Data for Submission.

Slide 118 ______________________________________________________________________________________________________

Student Notes
After you select create new input worksheet, it is available on the data input worksheet and data values can be entered:

ExcelToCI data input worksheet Note. Place your cursor on an empty cell before selecting Stage Data for Submission.

Instructor Notes
After entering the rows of data, the Stage Data for Submission is used to populate the Stage & Submit worksheet.

186

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Entering Data (continued)


The following field types are set in Excel: Number Date DateTime

Slide 119 ______________________________________________________________________________________________________

Student Notes
Note. Numeric fields are formatted with a custom number format based on the field attribute in the record definition, including the decimal point.

Instructor Notes
The fields created on the data input worksheet use the field types from the record definition. For a field that is defined as number and has no decimal points, the field may be too small in Excel to accept the data and you will need to change the format.

PeopleSoft Proprietary and Confidential

187

Using the Excel to Component Interface Utility

Lesson 8

Submitting Data
The staged data is displayed on the Staging & Submission worksheet: Submit Data updates the database and returns the status Post Data updates the data input worksheet. Errors will be displayed as comments, hover over the error cell to display the error message. Errors are corrected on the Data Input worksheet.

Slide 120 ______________________________________________________________________________________________________

Student Notes
When the data is submitted to the database, the status is returned:

Data submitted with an error

Instructor Notes
Data rows that return OK have been committed to the database. Errors can be corrected and resubmitted. Use the Post Results to update the input data worksheet.

188

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Submitting Data (continued)


To correct errors: Return to the Data Input worksheet. Correct the error. Click Stage Data for Submission in the toolbar. Only error rows are submitted. Click Submit Data in the toolbar.

Slide 121 ______________________________________________________________________________________________________

Student Notes
Corrections are made on the data input worksheet and staged for submission:

Resubmitted data

PeopleSoft Proprietary and Confidential

189

Using the Excel to Component Interface Utility

Lesson 8

Activity 7:

Creating ExcelToCI Template


In this activity, you will review the activity overview and: 1. Create a new component interface. 2. Create the ExcelToCI template. See Integration Tools: Activity Guide, lesson 8, Using the Excel to Component Interface Utility, Activity 7: Creating ExcelToCI Template.

Slide 122 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will create a new component interface CRS_SESSN based on the component PSU_CRS_SESSN and then create the template in ExcelToCI to load data into your PeopleSoft database.

Creating Component Interface


To create the component interface: 1. In Application Designer, select File, New, Component Interface. 2. Select PSU_CRS_SESSN for the component. 3. Accept the defaults. 4. Save the component interface as CRS_SESSN. 5. In the browser select PeopleTools, Security, Permissions & Roles, Permission Lists, ALLPAGES. 6. Add the component interface CRS_SESSN with full access. 7. Save the Permission List. 8. Test the Get method for the component interface in Application Designer using course 1030.

Creating the ExcelToCI template


To create the ExcelToCI template: 1. Start, Programs, Microsoft Excel. 2. Select File, Open, z:\STAnnn\excel\ExcelToCI.

190

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

3. Select Enable Macros. 4. Enter the following connection information:


Page Element Web Server Machine Name HTTP Port PeopleSoft Site Node Value or Status CTESERVER.PEOPLESOFT.COM 1080 <your database name> see Appendix C TRN

5. Click on the Template worksheet tab. 6. Click New Template in the toolbar. 7. Enter the following information:
Page Element UserID Password Component Interface Value or Status PTINT PTINT CRS_SESSN

8. Click Select All Input Cells in the toolbar. 9. Click New Data Input in the toolbar. 10. Click Yes. 11. Click the Data Input worksheet tab. 12. Click on F to highlight the column (Maximum Enrollment). 13. Select Format, Cells, Number tab, highlight number. 14. Change the decimal places to 0 (zero). 15. Click OK. 16. Enter the following rows of data:
Page Element Course Code Session Number Business Unit Start Date End Date Maximum Enrollment Session Status Value or Status 1030 300 NAM01 04/05/2004 04/09/2004 14 A

PeopleSoft Proprietary and Confidential

191

Using the Excel to Component Interface Utility

Lesson 8

Page Element Instructor Training Location Classroom

Value or Status AMR TEA B

Page Element Course Code Session Number Business Unit Start Date End Date Maximum Enrollment Session Status Instructor Training Location Classroom

Value or Status 1030 302 NAM01 04/05/2004 04/09/2004 14 A KLK CHI B

Page Element Course Code Session Number Business Unit Start Date End Date Maximum Enrollment Session Status Instructor Training Location Classroom

Value or Status 1030 303 NAM01 04/05/2004 04/09/2004 14 A SHR TOR B

17. Click Stage Data for Submission in the toolbar. 18. Click Submit Data in the toolbar. 19. Enter the following information:
Page Element UserID Password Value or Status PTINT PTINT

192

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

20. Review the status and any errors. 21. Click Post Results in the toolbar. 22. Click on the Data Input Worksheet tab. 23. Change the Business Unit to NAM03 for the second row. 24. Click Stage Data for Submission in the toolbar. 25. Click on the Stage & Submit worksheet tab. 26. Click Submit Data in the toolbar. 27. Save the excel spreadsheet to your student folder as CRS_SESSN. 28. In the browser, select Courses, Define, Course Sessions. Results The new sessions will be displayed:

Course Session Details This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

193

Using the Excel to Component Interface Utility

Lesson 8

Deploying the Excel Workbook


Once the workbook has been created, copies can be distributed: Hide the worksheets that you dont want the users to view or change. Save the spreadsheet with an appropriate name. Distribute the spreadsheet to the appropriate users.

Slide 123 ______________________________________________________________________________________________________

Instructor Notes
The workbook has to include all of the worksheets to function, but users only need the data input and the staging and submission worksheets. To hide a worksheet in Excel, select Format, Sheet, Hide.

194

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

Activity 8:

Deploying Workbooks
In this activity, you will review the activity overview and: Create and deploy a workbook to add new students. Create and deploy a workbook to update student skills.

See Integration Tools: Activity Guide, lesson 8, Using the Excel to Component Interface Utility, Activity 8: Deploying Workbooks.
Slide 124 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will create a new template in ExcelToCI to support adding students (with this skills and education) to the student table; you will then create another modified version of the same template that is used to update skills. Each student may add up to three skills at a time. Creating and deploying a workbook to add new students Create a workbook using ExcelToCI and name it ADD_STUDENT. The workbook will use the component interface STU_PROFILE_2, which supports all the input fields. Since Student ID is generated using PeopleCode, this field does not need to be entered. Test the workbook by adding a new student with the following information:
Page Element Student Name Customer Emphasis Same address as customer Student Project Role Skill Proficiency Value or Status Gray,Joe AAB T Y SUP PT H

Creating and deploying a workbook to update student skills Modify the workbook you just created to support inserting multiple skills for an existing student and save the workbook as ADD_STU_SKILLS. Use the following data to test your workbook.

PeopleSoft Proprietary and Confidential

195

Using the Excel to Component Interface Utility

Lesson 8

Page Element Student ID Skill Proficiency Skill Proficiency Skill Proficiency

Value or Status 2131 PT H SQL H DBD H

Creating and Deploying a Workbook to Add New Students


To create and deploy a workbook to add new students: 1. Open the ExcelToCI spreadsheet from your student folder in Excel, enabling macros. 2. Enter the connection information. 3. Create a new template based on the component interface STU_PROFILE_2. 4. Click on Select All Input Cells in the toolbar. 5. Click on the cell D12 (Input cell for STUDENT_ID level 0). 6. Click Include for Submission in the toolbar. 7. Click New Data Input in the toolbar. 8. Click OK to clear previous data. 9. On the data input worksheet enter the data from the activity overview. 10. Submit the data. 11. Save the workbook as to your student folder as ADD_STUDENT. 12. Review the Connect Information worksheet, noting that the action is CREATE. 13. In the browser, select Students, Personal Information for Gray,Joe.

Creating and Deploying a Workbook to Update Student Skills


To create and deploy a workbook to update student skills: 1. Change the action to UPDATE. 2. Select the template worksheet. 3. Click on cell D12. 4. Click Select Input Cell in the toolbar. 5. Highlight cells E12 through O12.

196

PeopleSoft Proprietary and Confidential

Lesson 8

Using the Excel to Component Interface Utility

6. Click Deselect Input Cells in the toolbar. 7. Click A13. 8. Click Insert New Child in the toolbar. 9. Click Insert New Child in the toolbar (again). 10. Click New Data Input in the toolbar. 11. Select Yes. 12. Enter the data from the activity overview to test the template. 13. Submit the data. 14. Select the Coversheet worksheet. 15. Select Format, Sheet, Hide. 16. Select the Connect Information worksheet. 17. Select Format, Sheet, Hide. 18. Select the Template worksheet. 19. Select Format, Sheet, Hide. 20. Save the workbook as to your student folder as UPD_STUSKILLS. 21. Select File, Close. 22. Select File, Exit. 23. In the browser, select Students, Personal Information for 2131. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

197

Using the Excel to Component Interface Utility

Lesson 8

Review
In this lesson, you learned that: The Excel to Component Interface Utility provides a consistent method to load data into PeopleSoft. Public access must be defined in order to use the Excel to Component Interface Utility. Public access is assigned using the Web profile page. The Excel to Component Interface Utility connects to the web server for the database. Templates are created based on existing component interfaces. The data input worksheet is created by selecting the appropriate cells from the template. Data is submitted to the PeopleSoft database using the Staging & Submission worksheet. A status is returned for each row of data. Workbooks can be deployed to users for data entry.

Slide 125 ______________________________________________________________________________________________________

198

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture


Objectives
By the end of this lesson, you will be able to: Describe the PeopleSoft Integration Broker architecture. Describe the PeopleSoft Integration Gateway. Describe connectors. Describe the gateway services. Describe the Integration Broker Engine. Explain the flow of inbound requests to PeopleSoft Integration Broker. Explain the flow of outbound requests from PeopleSoft Integration Broker.

Slide 127 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

199

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Describing the PeopleSoft Integration Broker Architecture


The PeopleSoft Integration Broker is composed of two-high-level subsystems: Integration Gateway which resides on the PeopleSoft web server. Integration Engine which resides on the application server.

Slide 128 ______________________________________________________________________________________________________

Student Notes
The Integration Gateway is a platform that manages the actual receipt and delivery of messages passed among systems through the Integration Broker. The Integration Engine uses a variety of People Tools elements to create, implement, manage and enhance integrations.

200

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Describing the PeopleSoft Integration Broker Architecture (continued)


This diagram shows a high-level view of Integration Broker:
Integration Broker

Integration Engine

Integration Gateway External Systems

Application Server

Web Server

Integration Broker
Slide 129 ______________________________________________________________________________________________________

Instructor Notes
Question: Describing the PeopleSoft Integration Broker Architecture The Integration gateway resides on: 1. Application server 2. PeopleSoft database 3. Web server 4. External system Answer The answer is 3 (web server).

PeopleSoft Proprietary and Confidential

201

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Describing the PeopleSoft Integration Gateway


The Integration Gateway: Manages the actual receipt and delivery of messages. Provides support for leading TCP/IP protocols via connectors. Provides extensive interfaces for development of new connectors.

Slide 130 ______________________________________________________________________________________________________

Instructor Notes
The Integration Gateway is primarily a conduit that receives and sends messages among integration participants' systems. The Integration Gateway is designed with flexibility and extensibility in mind. Messages are received through listening connectors and are delivered from target connectors. The Gateway Manager is a dispatcher for messages that flow though the Integration Gateway.

202

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Describing the PeopleSoft Integration Gateway (continued)


The Integration Gateway contains the following components: Web Server Gateway Connectors Gateway Services

Slide 131 ______________________________________________________________________________________________________

Student Notes
Note. Web server will be either BEA Weblogic or IBM Websphere.

Instructor Notes
Question: Describing the PeopleSoft Integration Gateway The PeopleSoft Integration Gateway 1. Manages the actual receipt and delivery of messages. 2. Contains the gateway connectors. 3. Contains the gateway services. 4. All of the above. Answer The answer is 4 (all of the above).

PeopleSoft Proprietary and Confidential

203

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Describing Connectors
Listening and target connectors transport messages between integration participants: Connectors support asynchronous, synchronous and polling-based message handling. Connectors are configurable. Connectors are servlets that listen on a URL for HTTP Posts and HTTP Gets from an external service. PeopleSoft delivers predefined connectors. Custom connectors can be created.

Slide 132 ______________________________________________________________________________________________________

Student Notes
Note. PeopleSoft supplies an Integration Gateway Connector software development kit SDK to assist customers in creating their own custom connectors. See PeopleTools 8.44: PeopleSoft Integration Broker PeopleBook, Managing the Integration Gateway.

Instructor Notes
The Integration Gateway Connector SDK is available to assist you in creating you own custom connectors. Included in the SDK: Java classes required to create connectors JavaDocs detailing all of the java classes required to build you own custom connectors Sample Listening connector Sample Target Connector

To create a new connector: Use the supplied docs and classes to build your own connector Move the connector to the connector directory on the web server Register the new connector in the Integration Profile

204

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Describing Connectors (continued)


Listening Connectors: Receive incoming data streams. Perform services based on content of stream. Are invoked externally by other systems.

Slide 133 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44: PeopleSoft Integration Broker PeopleBook, Managing the Integration Gateway.

Instructor Notes
The inbound message flow diagram is shown in PeopleTools 8.44: PeopleSoft Integration Broker PeopleBook, Managing the Integration Gateway. You send messages to a listening connector at a URL address derived form its class location on the Gateway Web Server.

PeopleSoft Proprietary and Confidential

205

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Describing Connectors (continued)


PeopleSoft delivers four (4) listening connectors: PeopleSoft Listening Connector handles incoming requests from other PeopleSoft. Brokers. HTTP Listening Connector handles incoming HTTP requests, including Simple Object Access Protocol (SOAP) requests over HTTP. PeopleSoft 8.1 Listening Connector handles incoming requests from PeopleSoft 8.1x systems. JMS Listening Connector handles requests from Java Messaging (JMS).

Slide 134 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44: PeopleSoft Integration Broker PeopleBook, Managing the Integration Gateway.

Instructor Notes
All of the delivered listening connectors that service HTTP requests run as servlets. They configured in WebLogic or WebSphere. In PeopleSoft 8.44 the servlets are located in: <pshome>webserv\peoplesoft\applications\peoplesoft\PSIGW\WEBINF\classes\com\peoplesoft\pt\integrationgateway\listeningconnector

206

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Describing Connectors (continued)


PeopleSoft delivers ten (10) target connectors: HTTP Target Connector handles outgoing HTTP and SOAP requests. PeopleSoft Target Connector handles requests being sent to other PeopleSoft Integration Brokers. PeopleSoft 8.1 Target Connector handles requests being sent to a PeopleSoft 81x gateway servlet. FTP Target Connector handles requests being sent to a File Transfer protocol (FTP) server. SMTP Target Connector allows email to be sent to a Simple Mail Transfer Protocol (SMTP) server.

Slide 135 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44: PeopleSoft Integration Broker PeopleBook, Managing the Integration Gateway.

Instructor Notes
Target Connectors open communication with other PeopleSoft systems or third-party systems and perform various operations. A target connector may or may not receive a response from the target system during each operation. Target Connectors are located: <pshome>\peoplesoft\applications\peoplesoft\PSIGW\WEBINF\classes\com\peoplesoft\pt\integrationgateway\targetconnector

PeopleSoft Proprietary and Confidential

207

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Describing Connectors (continued)


PeopleSoft delivers ten (10) target connectors (continued): JMS Target Connector handles requests being sent to a Java Messaging Service (JMS) server. POP3 Target Connector allows email to be retrieved from Post Office Protocol (POP3) server. Simple File Target Connector allows you to write messages to a file in XML format. GetMail target connector provides functionality specific to the PeopleSoft MultiChannel Framework. LDAP target connector - provides functionality specific to LDAP servers.

Slide 136 ______________________________________________________________________________________________________

Student Notes
Note. The POP3 target connector is a deprecated technology. Its functionality is provided by the GetMail target connector. Existing integrations that use the POP3 target connector will still function without modification. See Also PeopleTools 8.44 PeopleBook: Multichannel Framework, Configuring the Email Channel, for more information on the GetMail trage connector.

208

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Describing Connectors (continued)


Most of the delivered target connectors have required and optional properties that you set to control the connectors behavior: Gateway-level properties are set in the integrationGateway.properties file. Node-level properties are identified by a property ID and property name. Default node-level properties are set in the Gateways component. Specific node-level properties can be set or overridden in the Node component.

Slide 137 ______________________________________________________________________________________________________

Instructor Notes
In lesson 10 Configuring the Integration Broker students will configure the Gateway and Nodes. Question: Describing Connectors Listening connectors: 1. Receive incoming data streams. 2. Handle outgoing HTTP and SOAP requests. 3. Route messages to external systems. 4. Transform messages requests. Answer The answer is 1 (receive incoming data streams).

PeopleSoft Proprietary and Confidential

209

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Describing the Gateway Services


The following Gateway Services are performed: Error Handling Messaging Objects XML Parsing Message Validation Connector Management Error and Message Logging

Slide 138 ______________________________________________________________________________________________________

Instructor Notes
Explain the following gateway services: Error Handling The Integration Gateway provides a standard error handling interface that is exposed to each connector. This service provides error handling and error logging for most connectors delivered with PeopleSoft Integration Broker. Messaging Objects Two objects represent the messaging objects service in the Integration Gateway: IBRequest IBResponse

These objects are central to the system as they represent the request and response that go in and out of the Integration Broker. XML Parsing Most IBRequests and IBResponses that are processed in the system usually contain a Content section, which represents the actual business message sent. Most of the time these Content sections contain XML data. Since this is the case, often connectors must parse and traverse XML. Many developers find that the standard Java XML objects are cumbersome for manipulating XML, so the Integration Gateway provides an XML Parsing service that consists of objects that provide a very intuitive interface for manipulating XML objects. This service is delivered as a set of classes: XmlDocument, XmlNode and XmlNodeList.

210

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Message Validation Messages that pass into the Integration Broker must contain certain elements in order for them to be processed. Since the Integration Gateway is the first component in the Integration Broker to process messages sent to a PeopleSoft application, the Integration Gateway performs basic message validation, such as making sure the message identifies its requestor and message name, to ensure that the Integration Engine and the target application can process them. Connector Management The Connector Management service is actually a composite of several smaller services the Integration Gateway implements to manage connectors. The Gateway processes each IBRequest to determine the appropriate connector to call in each situation. This is primarily a message routing function that has varying levels of complexity abstracted from the connectors. The connector manager also processes the IBResponse returned by each connector. Error and Message Logging The Integration Gateway provides a standard logging interface that most components in the system use, most notably the connectors.

PeopleSoft Proprietary and Confidential

211

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Describing the Gateway Services (continued)


The Gateway Manager processes every message that flows through the Integration Gateway: Listening connectors invoke the Gateway Manager when a request is received. Gateway Manager uses the handles on the message object to determine how to route the message. The Gateway Manager uses a number of the Gateway Services during this stage to perform operations such as message validation. The Gateway Manager then invokes the appropriate target connector based on the contents of the message object, and waits for a response back from the target connector. When the response is received, the Gateway Manager forwards the response back to the calling listening connector.

Slide 139 ______________________________________________________________________________________________________

Instructor Notes
The Gateway Manager processes every message that flows through the Integration Gateway and maintains links among the other major Integration Gateway components, including target connectors, listening connectors, and each of the Gateway Services. Listening connectors invoke the Gateway Manager when they receive a message request. The Gateway Manager uses handles on the messaging objects, IBRequest and IBResponse, to determine how to route each message. The Gateway Manager uses a number of the Gateway Services during this stage to perform operations such as message validation. The Gateway Manager then invokes the appropriate target connector based on the contents of the message object, and waits for a response back from the target connector. When the response is received, the Gateway Manager forwards the response back to the calling listening connector. If an error occurs, the Gateway Manager may use the Error Handling service, and works with the service to prepare an error response for the listening connector. Question: Describing the Gateway Services The Gateway Manager processes every message that flows through the Integration Gateway. 1. True 2. False Answer The answer is 1 (true).

212

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Describing the Integration Broker Engine Components


The diagram below displays the components of the Integration Broker Engine:
Web Server

JOLT

Local PSFT 8.4 Application Server

HTTP(s)

Integration Engine Integration Service Authentication Integration Profile Synchronous Request Handler Asynchronous Request Handler Message Queue Outgoing Transformation Routing Logic Incoming Transformation Integration Profile

Integration Broker Engine architecture


Slide 140 ______________________________________________________________________________________________________

Student Notes
The components that make up the Integration Broker Engine are: Integration Service First entry point into the PeopleSoft Application, it receives a request message from a remote node or gateway, which specifies your application as its target node, and indicates whether the message is to be processed asynchronously or synchronously. Integration Profile Contains the routing logic and authenticator information. Asynchronous Request Handler - The Asynchronous Request Handler invokes the message definition's subscription PeopleCode Synchronous Request Handler - The Synchronous Request Handler invokes the message definition's OnRequest PeopleCode Transformation Engine Invokes any associated transform programs. Error Handling - The Integration Gateway provides a standard error handling interface that is exposed to each connector. This service provides error handling and error logging for most connectors delivered with PeopleSoft Integration Broker

PeopleSoft Proprietary and Confidential

213

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Instructor Notes
The Integration Engine uses a variety of People Tools elements to create, implement, manage and enhance integrations. Its modular architecture separates the integration development activity from the administrative activity The Integration Engine is really a combination of Application Designer definitions, PIA definitions, People Code and XSLT code, along with the underlying mechanisms that tie all these elements together including the request handlers that process both inbound and outbound messages according to the specifications in the development and administrative elements. Question: Describing the Integration Broker Engine Components Transformations take place in the Integration Engine. 1. True 2. False Answer The answer is 1 (true).

214

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Explaining the Flow of Inbound Requests to PeopleSoft Integration Broker


The inbound message flow is shown in the diagram below:
Integration Gateway External System Request Response Listening Connector PeopleSoft Target Connector

JOLT Request JOLT Response

Application Server

Incoming message request flow


Slide 141 ______________________________________________________________________________________________________

Student Notes
The flow of an inbound request: 1. Request is received by the appropriate listening connector and passed to the PeopleSoft Target Connector. 2. Request is processed by the PeopleSoft Target Connector and passed to the PeopleSoft application server. 3. Request is received by the application server and processed. 4. Response is returned by the application server and passed to the PeopleSoft Target Connector. 5. Response is received by the PeopleSoft Target Connector and passed to the listening connector that the message was originally received from. 6. The listening connector receives response.

Instructor Notes
The flow of an inbound request: 1. Request is received by the Listening Connector The request will be written to the gateway log file exactly as it is received. The connector then attempts to populate an internal message class with the information from the received message. The incoming message has 2 parts, the credentials and the message body. The credentials provide the information that the integration broker needs to process and deliver the message. A message without credentials cannot be processed. 2. Request is processed by the PeopleSoftTarget Connector

PeopleSoft Proprietary and Confidential

215

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

In order for a message to be sent from the gateway to the application server, it must pass through the PeopleSoftTargetConnector. This connector has two major responsibilities: it serializes the message to a string, and sends that string via a JOLT connection to the application server. All communication between the gateway and the application server is done via the use of Multipurpose Internet Mail Extensions (MIME) messages. When the message is received by the connector, it builds a MIME message. Typically the MIME message will only have two sections. In the first, the message credentials are stored in an XML document in a specific format. The second section stores the message body. At this point the message is in a standard format understood by both the gateway and the application server. 3. Request is received by the Application Server When the MIME request is received by the application server, the message is parsed and is used to build a request object. The MIME structure is not propagated into the server. 4. Response is returned by the Application Server Regardless of how the request is processed, a response message must be returned by the application server to the gateway in the same thread of execution. The connection between the gateway and the application server is essentially synchronous, independent of the type of the message being exchanged. When the gateway sends a request to the application server, it expects and must get a response. 5. Response is received by the PeopleSoftTargetConnector As soon as the MIME response is received by the PeopleSoftTargetConnector, it is written to the gateway log file. The MIME response is then parsed back into a gateway request object, and is then returned to the ListeningConnector. 6. Response is received by the ListeningConnector The response object is returned to the ListeningConnector, upon which the response is mapped to a response suitable for the given protocol. Question: Explaining the Flow of Inbound Requests from PeopleSoft Integration Broker All inbound transactions are passed to the PeopleSoft application server using: 1. PeopleSoft Target Connector. 2. PeopleSoft Listening Connector. 3. HTTP Listening Connector. 4. Application Server. Answer The answer is 1 (PeopleSoft Target Connector).

216

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Explaining the Flow of Outbound Requests from PeopleSoft Integration Broker


The outbound message flow is shown in the diagram below:
Integration Gateway PeopleSoft Listening Connector Target Connector Request Response External System

Application Server

HTTP Request HTTP Response

Outbound message flow


Slide 142 ______________________________________________________________________________________________________

Student Notes
The outbound request flow: 1. Application Server generates request 2. Request is received by the PeopleSoft Listening Connector and routed to the appropriate target connector. 3. Request is received by the appropriate target connector and sent to the external system. 4. Response is received by the target connector and routed to the PeopleSoft Listening Connector. 5. Response is received by the PeopleSoft Listening Connector. 6. Response is received by the Application Server

Instructor Notes
Discuss the outbound request flow: 1. Application Server generates request Once an outgoing request message has been generated, the application server looks at the request, and extracts the information about the node that it is to be sent to. The node name is then used to look up the name of the gateway to use, the Target Connector to use on that gateway, as well as any specific connector properties that need to be passed to the connector in order to handle the request. If this information is not found, an error will occur. The application server modifies the outgoing request with the appropriate connector information. The request is then converted to the MIME standard format, and is sent to the gateway over an HTTP connection.

PeopleSoft Proprietary and Confidential

217

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

The request must be sent to the PeopleSoftListeningConnector on the gateway. The application server uses the value of the Gateway URL defined for the given gateway 2. Request is received by the PeopleSoftListeningConnector When the MIME request is received by the PeopleSoftListeningConnector, it is written to the gateway log file. The request is converted from MIME format to a gateway request object. The connector then examines the request to determine what TargetConnector the request is to be sent to; that TargetConnector is then invoked. 3. Request is received by the Target Connector The TargetConnector validates the request. Each connector requires certain properties to be set, otherwise the request cannot be sent. The TargetConnector then converts the request message into whatever format is required by the protocol. The modified request is then written to the gateway log, and the request is sent out. 4. Response is received by the TargetConnector The response received by the Target Connector is written to the gateway log, and the response is used to build a gateway response object, which is then returned to the PeopleSoftListeningConnector. 5. Response is received by the PeopleSoftListeningConnector The response object is then converted to the MIME standard format by the connector. The MIMEd response is then written to the gateway log file, and is then returned to the application server. 6. Response is received by the Application Server A response object is built out of the MIME response, and is returned to the routine that created the request. Question: Explaining the Flow of Outbound Requests from PeopleSoft Integration Broker All outbound transactions are received by the Integration Broker on: 1. PeopleSoft Target Connector. 2. PeopleSoft Listening Connector. 3. HTTP Listening Connector. 4. Application Server. Answer The answer is 2 (PeopleSoft Listening Connector).

218

PeopleSoft Proprietary and Confidential

Lesson 9

Introducing PeopleSoft Integration Broker Architecture

Review
In this lesson, you learned that: The PeopleSoft Integration Broker is composed of the Integration Gateway and the Integration Engine. The PeopleSoft Integration Gateway resides on the web server and is comprised of the web server container, connectors and gateway services. Listening and Target connectors transport messages between participants. Gateway services handle all messages flowing through the Integration Gateway. The Integration Broker Engine routes and transforms messages based on the integration profile information. Inbound requests are received via the various listening connectors and sent to the application server via the PeopleSoft target connector. Outbound messages are received from the application server by the PeopleSoft listening connector and sent to external systems using the appropriate target connector.

Slide 143 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

219

Introducing PeopleSoft Integration Broker Architecture

Lesson 9

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

220

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker


Objectives
By the end of this lesson, you will be able to: Configure PeopleSoft Integration Broker. Configure an integration gateway. Describe nodes. Rename the default local node. Create and ping remote nodes.

Slide 145 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

221

Configuring PeopleSoft Integration Broker

Lesson 10

Configuring PeopleSoft Integration Broker


There are six integration scenarios that you can implement using PeopleSoft Integration Broker. PeopleSoft 8.4 systems. PeopleSoft 8.4 systems using remote gateways. PeopleSoft 8.4 systems using hub configurations. Third-party systems. Third-party systems using remote gateways. PeopleSoft 8.1 systems.

Slide 146 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Appendixes.

Instructor Notes
The PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker features appendixes that discuss each of these integration scenarios. In class, you cover only the integration of two PeopleSoft 8.4 systems and connections to third-party systems using Send Master to test the connectors since we do not have access to a third-party system.

222

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Configuring PeopleSoft Integration Broker (continued)


Here are the high-level configuration tasks that you perform for all of the integration scenarios: Define a local integration gateway. Define a remote integration gateway. Set up a local node. Set up a remote node. Set integration gateway properties. Set up inbound and outbound transactions.

Slide 147 ______________________________________________________________________________________________________

Student Notes
Note. You may not need to perform all of these tasks. For instance, if you do not need to communicate over a firewall, you might not need to define and configure a remote gateway.

PeopleSoft Proprietary and Confidential

223

Configuring PeopleSoft Integration Broker

Lesson 10

Configuring PeopleSoft Integration Broker (continued)


This course covers the integration of two PeopleSoft 8.4 systems. This diagram depicts the classroom environment:
PeopleSoft 8.4 Training 01 MIME/ HTTP Post Integration Engine PeopleSoft 8.4 Training 02 Jolt Integration Engine

PeopleSoft Listening Connector

PeopleSoft Target Connector

Gateway Manager Application Server(s) and Database Application Server(s) and Database

Local Integration Gateway Web Server

Classroom setup
Slide 148 ______________________________________________________________________________________________________

Instructor Notes
In the classroom, students exchange messages with their neighbors. Each student has a separate database. The database has the same number as the classroom workstation (0114). The integrationGateway.properties file has already been configured to include all 14 workstations. Later in this lesson, students rename their local nodes to reflect their database numbers.

224

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Configuring PeopleSoft Integration Broker (continued)


The following tasks must be performed on the Training database: Define a local integration gateway. Set up a default local node. You must rename the node so that it uniquely identifies the local database. Set up remote nodes. Set up transactions.

Slide 149 ______________________________________________________________________________________________________

Instructor Notes
Point out the following: In the classroom, the gateway must be configured on the local workstation. As delivered, the default local node for the Training database is PSFT_TRN. Students must rename the node so that it uniquely identifies the local database. Students must set up remote nodes for any PeopleTools 8.4 databases with which they exchange messages.

PeopleSoft Proprietary and Confidential

225

Configuring PeopleSoft Integration Broker

Lesson 10

Configuring PeopleSoft Integration Broker (continued)


The following tasks must be performed for the Financials database: Set up a remote node to match the Training database node. Set up transactions.

Note. The default local node for the Financials database is PSFT_EP.
Slide 150 ______________________________________________________________________________________________________

226

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Configuring an Integration Gateway


A default definition for the local gateway is automatically created at installation. You must perform the following steps: 1. Enter the gateway URL. The gateway URL has the format:
http://<webserver>/PSIGW/PeopleSoftListeningConnector

2. Save the page. 3. Load the connectors by clicking the Load button.
Slide 151 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the Gateways page:
Page Name Gateways Navigation PeopleTools, Integration Broker, Gateways, LOCAL

Gateways page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Configuring the Integration Gateway Note. Connectors are loaded using the following path: <pshome>\webserv\peoplesoft\applications\peoplesoft\PSIGW\WEBINF\classes\com\peoplesoft\pt\integrationgateway.

PeopleSoft Proprietary and Confidential

227

Configuring PeopleSoft Integration Broker

Lesson 10

Instructor Notes
You use the Load button to register the connectors. The loaded target connectors appear on the page. Once a connector is registered, you can use it on the Connector tab of the node definition. The system loads all delivered connectors when you click the Load button. Organizations can create their own custom target connectors. To install a target connector class, you copy the class from the Java Classes directory to the following location on the local web server: <pshome>\webserv\peoplesoft\applications\peoplesoft\PSIGW\WEBINF\classes\com\peoplesoft\pt\integrationgateway \targetconnector.

228

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Configuring an Integration Gateway (continued)


Click the Gateway Properties link to set up the gateway. Note these points: The integrationGateway.properties requires a gateway user ID and password. The page displays the integrationGateway.properties file. You can use this page to view, edit, and submit changes.

Slide 152 ______________________________________________________________________________________________________

Student Notes
You must sign on with a password and a user ID. The user ID must be authorized to configure the gateway and change the integrationGateway.properties on the web server.

Gateway Signon page Note. As delivered, the user ID is administrator and the password is password.

Instructor Notes
Customers will want to change the password for the gateway properties.

PeopleSoft Proprietary and Confidential

229

Configuring PeopleSoft Integration Broker

Lesson 10

Configuring an Integration Gateway (continued)


The Gateway Properties page displays the integrationGateway.properties file. Click Apply after making changes to the page to update the file. Note. The encryption utility enables you to encrypt the passwords that are used in this file.
Slide 153 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the Gateway Properties page:
Page Name Gateway Properties Navigation PeopleTools, Integration Broker, Gateways, LOCAL, Gateway Properties

Gateway Properties page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Configuring the Integration Gateway

230

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Instructor Notes
If students have worked with the integrationGateway.properties file in previous releases, explain that the file works the same way. The only difference is that it is displayed through PeopleSoft Internet Architecture to make it easier to use. You can still open the integrationGateway.propeties file and edit it. In PeopleTools 8.44, the integrationGateway.properties file is located in the following directory: <pshome>\webserv\peoplesoft\applications\peoplesoft\PSIGW\WEB-INF Note that rather than a Refresh button, you now have an Apply button and an OK button that appears on the Gateway Properties page. When you make changes, click the Apply button to update the integrationGateway.properties file and leave the file active, or OK to update the file and dismiss the page. Click Cancel if you do not want to save your changes. Password encryption was added in PeopleTools 8.41. You need to run the pscipher utility, which you can now access on the page.

PeopleSoft Proprietary and Confidential

231

Configuring PeopleSoft Integration Broker

Lesson 10

Configuring an Integration Gateway (continued)


The BEA Jolt connect string defines the default application server:
## JOLT connect string setting for optional Default Application Server. Do NOT specify a NODENAME. # # Example: #ig.isc.serverURL=//MYSERVER:9000 #ig.isc.userid=MYUSERID #ig.isc.password=MYPASSWORD #ig.isc.toolsRel=8.44 # # Uncomment out the following four lines and replace information shown in <> with the correct

Slide 154 ______________________________________________________________________________________________________

Student Notes
Here is an example showing a default application server:

Default application server defined in BEA Jolt connect string

Instructor Notes
In lesson 20 Publishing PeopleSoft EIPs, the default application server is used for SOAPTOCI messages. The default is used when a specific node is not specified in the incoming message header. The URL will specify the web server.
232 PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Keep in mind that the default application server in this environment is set to the instructors application server.

PeopleSoft Proprietary and Confidential

233

Configuring PeopleSoft Integration Broker

Lesson 10

Configuring an Integration Gateway (continued)


Each participating PeopleSoft node needs to be defined, as shown here:
# Replace $NODENAME with the exact name used for that Node. # Replace information shown in <> with the correct information for your Node (remove the <> as well) # # If a Non-Default Node is required the following settings should be uncommented. # ig.isc.$NODENAME.serverURL=//<machine name>:<jolt port> ig.isc.$NODENAME.userid=<database user id> ig.isc.$NODENAME.password=<database password> ig.isc.$NODENAME.toolsRel=<peopletools release version>

Slide 155 ______________________________________________________________________________________________________

Student Notes
In the classroom, all the nodes have been defined, as shown here:

Defined PeopleSoft nodes

Instructor Notes
Only PeopleSoft nodes are defined in the integrationGateway.properties file. External nodes have the URL defined in the node definition on the connector tab.

234

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Students have not yet renamed the default local node, but the integrationGateway.properties is set up for the node names to match the application server ports of each workstation. The instructor database used the node PSFT_TRN.

PeopleSoft Proprietary and Confidential

235

Configuring PeopleSoft Integration Broker

Lesson 10

Activity 9:

Configuring the Gateway


In this activity, you will review the activity overview: Configure the integration gateway on the Training database. Review the gateway properties.

See Integration Tools: Activity Guide, lesson 10, Configuring PeopleSoft Integration Broker, Activity 9: Configuring the Gateway.
Slide 156 ______________________________________________________________________________________________________

Instructor Notes
When students click Load, they will get a message that 0 connectors were loaded, this is because they are all already loaded. It is still a good idea to have students do this because if they typed the URL incorrectly they will get a message: Java exception thrown: java.net.UnknownHostException, they can then correct the URL. Note. This activity should take approximately five minutes.

Activity Overview
In this activity, you will change the URL for the local gateway on the Training database to your web server.

Configuring the Gateway for the Training Database


Use the following steps to configure the integration gateway on your Training database. 1. Sign on to the browser with the user ID PTINT and the password PTINT. 2. Select PeopleTools, Integration Broker, Gateways, LOCAL. 3. Change the localhost portion of the URL to CTESERVER.PEOPLESOFT.COM:1080. 4. Save the page. 5. Click the Load button. 6. Click OK in the Load Successful dialog box. 7. Save the page.

Reviewing the Gateway Properties


To review the gateway properties: 1. Click on Gateway Properties. 2. Enter administrator for the User ID and password for the password.
236 PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

3. Scroll through the gateway properties file and find the nodes that have been defined. 4. Click Cancel. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

237

Configuring PeopleSoft Integration Broker

Lesson 10

Describing Nodes
Several types of nodes are defined in the PeopleSoft database: Database node (default local node). Content provider node. Registry node. LOCAL_NODE.

Slide 157 ______________________________________________________________________________________________________

Student Notes
Each PeopleSoft database is delivered with a default local node and remote nodes for all of the other PeopleSoft applications. This table shows examples of nodes:
Database Node PSFT_XX Default local node. (This node is renamed.) Content Provider BP CAMP CIS CRM ELM EPM ERP GFHA STAF HRMS SA SAHA VAN (These are all nonlocal nodes on the Enterprise Portal database.) Registry Node EMPL SUPP CUST MOBILE (This is the hosted-by node. A database can have multiple registry nodes.)

Instructor Notes
There are several types of nodes that are defined in the PeopleSoft database. Database Node Every PeopleSoft database has one default local node. This node is the trusted node. The node name must be unique to identify the database. Organizations rename the node. If you have multiple instances of the database (for example, development, QA, and production), each database has a unique database node name.

238

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Content Provider Node PeopleSoft application databases that contain the transaction content are referred to as the content provider databases. The names of the content providers are listed in the following table. You cannot change the names of these nodes. Note. The node type PIA indicates PeopleSoft 8.4.
Content Providers Nodes BP CAMP CIS CRM ELM EPM ERP STAF HRMS SA VAN GFHA SAHA Description Budget Planning Campus Portal Customer Information Systems Customer Relationship Management Enterprise Learning Management Enterprise Performance Management Financials/Supply Chain Front Office Human Resources Management Student Administration Vantive Government Financials HTMLAccess Student Administration HTMLAccess

Registry Node The registry node is a local node on the database indicates the portal.
Registry Nodes CUST EMPL ENTP SUPP GOVT MOBILE Description Customer Portal Employee Portal Enterprise Portal Supplier Portal Government Portal Mobile Portal

LOCAL_NODE The node LOCAL_NODE is used for objects that are never copied, such as PeopleTools. The local node does not show up as a node name in the registry, but it is used when you select the check box labeled Always use local node when registering content references.

PeopleSoft Proprietary and Confidential

239

Configuring PeopleSoft Integration Broker

Lesson 10

Describing Nodes (continued)


Each database has one default local node. The default local node has the following characteristics: It uniquely identifies the database. It must be renamed so that it is unique. It is included in the homepage URL. It is used with PeopleSoft Integration Broker for all PeopleSoft messaging.

Slide 158 ______________________________________________________________________________________________________

Instructor Notes
The default local node appears on the homepage when you log in: http://plecbf28/psp/train/EMPLOYEE/PSFT_T03/h/?tab=DEFAULT When you navigate to content, the content provider node appears in the URL. When you start a browser session, the default local node is cached in the web cache; if you rename the node, you must shut down the web server to delete the cache.

240

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Describing Nodes (continued)


The Node Definitions page is used to define the node. There are two node types used with Integration Broker: PIA This node type indicates a PeopleSoft database using PeopleSoft Integration Broker. External This node type indicates that the node does not use PeopleSoft Integration Broker.
Slide 159 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the Node Definition page:
Page Name Node Definition Navigation PeopleTools, Integration Broker, Node Definition

Node Definition page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Administering Basic Integrations.

PeopleSoft Proprietary and Confidential

241

Configuring PeopleSoft Integration Broker

Lesson 10

Instructor Notes
ICType is only used with Portals (when implementing Enterprise Portal) and not Integration Broker. Review the page with the students, and refer them to the PeopleBook for in-depth explanation of the fields. Point out the following points about the fields:
Term Description

Routing Type

This is a default setting, and it can be overridden at the transaction level or through PeopleCode. The types Implicit and Explicit are discussed in the lesson on sending and receiving messages. Certificate: This node inserts a digital certificate in messages that it sends, and requires messages that it receives to include a digital certificate. None Password: With a PIA node, PeopleSoft Integration Broker requires all messages (both outbound and inbound) to include a password, which it validates against the password entered here. If this node is external, it must handle passwords the same way as a PIA node A default local node must have security set to either Password or Certificate.

Authentication Option

Active Node

Clear this check box to inactivate the node, any transactions and relationships that use it are also inactivated. Activating the node does not automatically reactivate the transactions and relationships; they must be reactivated individually. Any nodes defined as local other than the default local node are applicable only to portals. They are not used by PeopleSoft Integration Broker. The content provider node is local to the database. In the Training database, the content provider node is TRN.

Local Node

Default Local Node Nonrepudiation Hub Node Master Node Image Name Code Set Group

There is only one default local node for a database. Refer to the PeopleBook. This node is discussed later in the lesson. This node is discussed later in the lesson. Refer to the PeopleBook. This topic is discussed later in the course.

242

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Describing Nodes (continued)


The Connectors tab in the Node Definitions component is used to: Identify the integration gateway that is used with the node. Identify the connectors that are used with the node.

Slide 160 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the Node Definition - Connectors page:
Page Name Node Definition Connectors Navigation PeopleTools, Integration Broker, Node Definition

Node Definition - Connectors page

PeopleSoft Proprietary and Confidential

243

Configuring PeopleSoft Integration Broker

Lesson 10

Describing Nodes (continued)


Use the Transactions tab in the Node Definitions component to: Define all transactions associated with a node. Indicate which transactions are active.

Slide 161 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the Node Definition - Transactions page:
Page Name Node Definition Transactions Navigation PeopleTools, Integration Broker, Node Definition

Node Definition - Transactions page

Instructor Notes
Transactions that are set up on the default local node are used for internal publications only. Most of the ones shown here are used to place reports into the report repository. Note that the transactions shown in the student notes page is the default local node. The transactions are local transactions within the database for working with reports and email. Students set up transactions later in the course. See lesson 13, Sending and Receiving Messages.

244

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Renaming the Default Local Node


Use the following 12 steps to rename the default local node: 1. Select Start, Programs, PeopleSoft 8.4, Data Mover. 2. Sign on to the system. 3. Open the Data Mover script <PS_HOME>\Scripts\appmsgpurgeall.dms. 4. Run the Data Mover script. 5. Close Data Mover. 6. Sign on to the database in PeopleSoft Internet Architecture.
Slide 162 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

245

Configuring PeopleSoft Integration Broker

Lesson 10

Renaming the Default Local Node (continued)


To rename the default local node (continued): 7. Select PeopleTools, Integration Broker, Node Definitions, PSFT_XX. 8. Rename the node. 9. Save. 10. Sign out. 11. Close the browser. 12. Restart the web server.
Slide 163 ______________________________________________________________________________________________________

246

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Activity 10:

Renaming the Default Local Node


In this activity you will review the activity overview and rename the default local node on the Training database. See Integration Tools: Activity Guide, lesson 10, Configuring PeopleSoft Integration Broker, Activity 10: Renaming the Default Local Node.

Slide 164 ______________________________________________________________________________________________________

Instructor Notes
In this activity, the instructor must restart the web server. <PS_HOME> in the CTE is z:\PeopleTools\844. Restarting Web Server To restart web server: 1. Log on to the CTE as the instructor TCA101. 2. Open the folder Instructor Tools. 3. Double-click Restart Web Server. There is no indication that PIA has started after the dialog box completes it still takes several minutes. Note. This activity should take approximately 10 minutes.

Activity Overview
In this activity you will rename the default local node for your database from PSFT_TRN to PSFT_Txx, where xx is your workstation number.

Renaming the Default Local Node


To rename the default local node: 1. Select Start, Programs, PeopleSoft 8, Data Mover. 2. Sign on to Data Mover using the userID PTINT and the password PTINT. 3. Open the Data Mover script <PS_HOME>\Scripts\appmsgpurgeall.dms. 4. Execute the Data Mover script. 5. Close Data Mover. 6. In the browser, select PeopleTools, Integration Broker, Node Definitions, PSFT_TRN. 7. Rename the node to PSFT_Txx where xx is your workstation number.

PeopleSoft Proprietary and Confidential

247

Configuring PeopleSoft Integration Broker

Lesson 10

8. Select Save. 9. Sign out. 10. Close the browser. 11. Your instructor will restart the Web Server. 12. Open the browser and sign on with the user ID PTINT and the password PTINT. Results The http address for the homepage will indicate the new node name:

URL indicating the default local node for the homepage This concludes the activity. Do not continue.

248

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Creating and Pinging Remote Nodes


Each PeopleSoft node that will participate needs to be defined as follows: Use the Node Definitions page to create or modify remote nodes. The remote node must be named the same as the local node in the corresponding database. The node needs to be defined in each participating database. The node needs to be identified in the integrationGateway.properties file.

Slide 165 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

249

Configuring PeopleSoft Integration Broker

Lesson 10

Creating and Pinging Remote Nodes (continued)


To test connectivity to the remote node: 1. Select PeopleTools, Integration Broker, Monitor, Monitor Message. 2. Select the Node Status tab. 3. Enter the node that you want to test in the Message Node Name field. 4. Click the Ping button.
Slide 166 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access the Node Status page:
Page Name Node Status Navigation PeopleTools, Integration Broker, Monitor, Monitor Message Select the Node Status tab.

Node Status page in the Monitor Message component See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using Integration Broker Monitor.

Instructor Notes
The Integration Broker Monitor is covered in depth in lesson 14 Monitoring Message System Performance Using Integration Broker Monitor. In this lesson, students will only use the Node status tab to ensure they have configured the nodes correctly.

250

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Activity 11:

Configuring Remote PeopleSoft Nodes


In this activity, you will review the activity overview and: 1. Create remote nodes. 2. Test connectivity to remote node. See Integration Tools: Activity Guide, lesson 10, Configuring PeopleSoft Integration Broker, Activity 11: Configuring Remote PeopleSoft Nodes.

Slide 167 ______________________________________________________________________________________________________

Instructor Notes
The FSCM database is T1F88050 and there is a favorite in the browser for PeopleSoft FSCM 8.8. If you need to reboot the app server for the FSCM database it is only available if you log in to the CTE as an instructor. Note. This activity should take approximately fifteen minutes.

Activity Overview
In this activity, you will create two remote nodes in your Training databaseone for PSFT_EP and one to connect to your neighbors database (as assigned by the instructor). You will then need to sign on to the FSCM 8.8 database and create a remote node to connect to your Training database. Once the nodes have been created, use the Monitor Message component in Integration Broker Monitor to verify that you can ping the other nodes.

Creating Remote Nodes


To create the remote nodes, you will: Create remote nodes in your training database. Create remote nodes in the FSCM database.

Creating Remote Node in the Training database To create remote nodes in the Training database: 1. In the browser, sign on to your Training database with the user ID PTINT and the password PTINT. 2. Select PeopleTools, Integration Broker, Node Definitions, Add a New Value. 3. Enter the following information:
Page Element Node Name Value or Status PSFT_EP

PeopleSoft Proprietary and Confidential

251

Configuring PeopleSoft Integration Broker

Lesson 10

Page Element Description Node Type Routing Type Authentication Option Password Confirm Password Connector ID

Value or Status Financials Database PIA Implicit Password PSFT PSFT PSFTTARGET

4. Save the page. 5. Select PeopleTools, Integration Broker, Node Definitions, Add a New Value. 6. Add a New Value for your neighbors database as assigned by the instructor:
Page Element Node Name Description Node Type Routing Type Authentication Option Password Confirm Password Connector ID Value or Status PSFT_Txx (where xx is your neighbors workstation number) Training Database ws xx PIA Implicit Password 123 123 PSFTTARGET

7. Save the page. 8. Sign out. Creating Remote Nodes on the FSCM Database 1. Select the PeopleSoft FSCM 8.8 in the browser by clicking the link listed in the Favorites menu. 2. Sign on with the user ID VP1 and the password VP1. 3. Select PeopleTools, Integration Broker, Node Definitions, Add a New Value. 4. Enter the following information:
Page Element Node Name Description Value or Status PSFT_Txx (your local node) Training Database xx

252

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Page Element Node Type Routing Type Authentication Option Password Confirm Password Connector ID

Value or Status PIA Implicit Password 123 123 PSFTTARGET

5. Save the page. 6. Sign out.

Testing Connectivity to Remote Nodes


To test connectivity to remote nodes: 1. Sign on to your Training database as PTINT. 2. Select PeopleTools, Integration Broker, Monitor, Message Monitor. 3. Select the Node Status tab. 4. In the Message Node Name field, select PSFT_EP. 5. Click the Ping button. 6. Verify that the Success message appears. 7. In the Message Node Name field, select your neighbors node. 8. Click the Ping button. 9. Verify that the Success message appears. Note. If your neighbor has not properly set up your node, you do not receive a successful ping.

PeopleSoft Proprietary and Confidential

253

Configuring PeopleSoft Integration Broker

Lesson 10

Results The ping will return success:

Results from successfully pinging a local node This concludes the activity. Do not continue.

254

PeopleSoft Proprietary and Confidential

Lesson 10

Configuring PeopleSoft Integration Broker

Review
In this lesson you learned that: Configuring PeopleSoft Integration Broker involves defining the integration gateway, setting up local and remote nodes, and setting up transactions. To configure the integration gateway, you need to define the gateway URL on the Gateways page; the Gateway properties page is used to configure the PeopleSoft nodes. Four types of nodes exit in the PeopleSoft database: database nodes (which are used with PeopleSoft Integration Broker), content provider nodes, registry nodes, and a local node. The default local node must be renamed to use a unique name for your database. Remote nodes refer to the PeopleSoft systems that participate in messaging.

Slide 168 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

255

Configuring PeopleSoft Integration Broker

Lesson 10

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

256

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions


Objectives
By the end of this lesson, you will be able to: List the development elements used with PeopleSoft Integration Broker. Describe message channels. Secure message channels. Describe message definitions. Create message definitions. Create test messages.

Slide 170 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

257

Creating Message Channels and Message Definitions

Lesson 11

Listing the Development Elements Used with PeopleSoft Integration Broker


The following basic development elements used with PeopleSoft Integration Broker are created and maintained in PeopleSoft Application Designer: Message channel definitions. Message definitions. Sending PeopleCode. Subscription PeopleCode. OnRequest PeopleCode.

Slide 171 ______________________________________________________________________________________________________

Instructor Notes
Explain these development elements:
Development Element Message channel definition Definition Message channels are groups of message definitions, and help to sequence messages properly and enhance scalability. In addition, they provide a simple way to define processing characteristics of similar messages as a single group. Message channels must have the identical object name in all nodes that use them. Message definition Messages are the fundamental building blocks of PeopleSoft messaging architecture. Messages are self-describing entities formatted in XML. Message definitions store information about how a single message is constructed. Each message definition is based on a multilevel structure, similar to a component, which defines the data to be inserted into the message at runtime. PeopleCode may be associated with messages to determine low-level routing rules. Routing rules control whether a message is sent to, or received by, a specific node. Sending PeopleCode PeopleCode is used to trigger a message to be sent. The PeopleCode can be placed on an existing record, component, or Application Engine program. To receive a message asynchronously, create an entry in the Message Subscriptions section of the message structure view, and enter PeopleCode into its associated Subscription PeopleCode event.

Subscription PeopleCode

258

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Development Element OnRequest PeopleCode (for synchronous messages only)

Definition To receive a message synchronously, enter PeopleCode into the existing OnRequest PeopleCode event associated with the root of the message structure. Depending on the type of messages that are exchangedasynchronous or synchronousmost of the same elements are used.

In this lesson, we will look at all of the elements in an asynchronous example, and then we will look at a synchronous example.

PeopleSoft Proprietary and Confidential

259

Creating Message Channels and Message Definitions

Lesson 11

Listing the Development Elements Used with PeopleSoft Integration Broker (continued)
The following diagram shows an example of asynchronous messaging setup for the location table:
Node PSFT_Txx Node PSFT_EP

Integration Gateway

Message LOCATION_SYNC Sending PeopleCode LOCATION_TBL

Channel ENTERPRISE SETUP

Channel ENTERPRISE SETUP

Message & Subscription PeopleCode LOCATION_SYNC

One-Way Asynchronous from PSFT_xx

LOCATION_SYNC messaging setup


Slide 172 ______________________________________________________________________________________________________

Student Notes
In the example pictured here, the following elements must be defined in PeopleSoft Application Designer: Message channel: ENTERPRISE_SETUP. Message name: LOCATION_SYNC. Sending PeopleCode: SavePostChange on LOCATION_TBL in the PSFT_Txx database. Subscription PeopleCode: LocationSync PeopleCode in the message LOCATION_SYNC on the PSFT_EP database.

Instructor Notes
This section discusses how to: Review the setup diagram. Question: List the development elements used with PeopleSoft Integration Broker.

260

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Reviewing the Setup Diagram Review the diagram and emphasize that the LOCATION_SYNC message needs to be defined on every database that participates in the messaging. The message name must be exactly the same on each of the participating databases. The message must use the same channel on each of the participating databases. The message channel must be exactly the same on each of the participating databases. Tell students that, for this example, they will send the message from the PSFT_Txx database, so the sending PeopleCode needs to reside on that database, in either the record or component SavePostChange PeopleCode. To receive the message, Subscription PeopleCode needs to be defined on the message definition of the receiving database. Question: Listing the Development Elements Used with PeopleSoft Integration Broker The elements used with PeopleSoft Integration Broker are defined in PeopleSoft Application Designer. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

261

Creating Message Channels and Message Definitions

Lesson 11

Describing Message Channels


Channels are a logical grouping of messages. Each message must belong to one message channel only. Channels are used to: Establish the message-processing sequence. Increase throughput by using unordered processing. Maintain messaging security. Maintain messages with common configuration properties. Define the processing attributes for timeout parameters, error thresholds, and delivery type.

Slide 173 ______________________________________________________________________________________________________

Student Notes
Note. The PeopleSoft system is delivered with predefined message definitions and message channels.

262

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Describing Message Channels (continued)


The message channel definition contains: All of the messages that are assigned to the message channel. Channel partitioning for the message channel.

Slide 174 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access this definition in PeopleSoft Application Designer:
Definition Name Message Channel Navigation File, Open, Definition: Message Channel

The message channel definition contains messages and channel partitioning information:

ENTERPRISE_SETUP message channel definition See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Defining Message Channels and Messages

PeopleSoft Proprietary and Confidential

263

Creating Message Channels and Message Definitions

Lesson 11

Instructor Notes
Messages are not directly entered into the message channel; they are entered from the message definition when the message channel is selected in the message properties. This is shown on a later slide.

264

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Describing Message Channels (continued)


Messages are sent in the order in which they were published. Channel partitioning enhances messaging performance. Keep the following in mind when partitioning: One or more fields at level 0 can be selected for partitioning. The partitioning field must be common to all messages in the message channel. If a common field is selected for partitioning, the messages with the same value in that field are processed sequentially. If the values in the common field are different, the messages are processed in parallel. Four fields are available for partitioning on every message. Partitioning divides the channel into subchannels.

Slide 175 ______________________________________________________________________________________________________

Student Notes
The following fields are available for partitioning on all message channels: MSGNAME MSGNAMEDETAIL PUBLISHER PUBPROC

Note. Partitioning only applies to asynchronous messages.

Instructor Notes
PeopleSoft Integration Broker creates subchannels at runtime. Each subchannel processes only the messages for which the designated common fields have identical combinations of values.

PeopleSoft Proprietary and Confidential

265

Creating Message Channels and Message Definitions

Lesson 11

Describing Message Channels (continued)


If no partitioning is used, an error in one message prevents any messages in that channel from processing, as shown in the following diagram:

Node A

8508 Data 1

8101 Job Data

8101 Data 1 Error

Node B

Message routing without partitioning


Slide 176 ______________________________________________________________________________________________________

Student Notes
In this example, series of employee-related messages flow from one node to another, with an error occurring on the lead message for EMPLID 8101. The common field across all of these messages is EMPLID, but partitioning is turned off. Without partitioning, all other employee IDs (for example 8508) are not be processed until the error is corrected. This is because, without partitioning, the system cant tell where the messages for one employee end and the where the messages for the next employee begin.

266

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Describing Message Channels (continued)


When partitioning is used, an error in one message only prevents any messages containing the partitioning field from processing, as shown in the following diagram:

8630 Data 1

8508 Job Data

8508 Data 1

Node A

Messages for all other employees are not impacted

Node B

8101 Data 2

8101 Job Data

8101 Data 1

Messages for the same employee are not processed

Error

Message routing with partitioning


Slide 177 ______________________________________________________________________________________________________

Student Notes
In this example, the EMPLID field is used to partition all messages on the channel. Therefore, subscription processes for messages on this channel are processed sequentially with respect to the EMPLID field. When there is an error for employee ID 8101, only messages for that ID are not processed. The messages for employee ID 8508 are processed in order, without disruption, while the messages in error wait in the queue (with a status of Error) until they are fixed and resubmitted.

PeopleSoft Proprietary and Confidential

267

Creating Message Channels and Message Definitions

Lesson 11

Describing Message Channels (continued)


Message channel properties are used to: Provide a description, comments, and owner. Indicate the message channel status. Indicate if messages should be archived. Indicate whether messages are ordered or unordered.

Slide 178 ______________________________________________________________________________________________________

Student Notes
The Message Channel Properties dialog box shows message channel properties:

Message channel properties See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Defining Message Channels and Messages Note. Some message channels are delivered from PeopleSoft as Paused.

Instructor Notes
Review the options available for message channels: Message Channel Status Archive Messages If a message channel is paused, all messages stay in New status. Select this check box to write messages to the message archive tables (PSAPMSGARCH*) for safekeeping and delete the messages from the current message tables (PSAPMSG*). A process in PeopleSoft Integration Broker can be run to archive messages. We will look at this process in the Integration Broker Monitor lesson. If the check box is clear, the messages are deleted from the current message tables.

268

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Unordered

Select to run the messages in this channel in parallel. By default, messages are processed one at a time in the order in which they were sent.

PeopleSoft Proprietary and Confidential

269

Creating Message Channels and Message Definitions

Lesson 11

Securing Message Channels


Use message channel security to determine which users can view messages in Integration Broker Monitor for a specific message channel. Follow these guidelines: Permission is granted on the Message Monitor page of a permission list. Access is either Full Access or Read Only. Click the Insert All Channels button to enable all channels at once.

Slide 179 ______________________________________________________________________________________________________

Student Notes
Use the Message Monitor page in the permission list to set message channel security:
Page Name Message Monitor Navigation PeopleTools, Security, Permissions & Roles, Permission Lists

Message Monitor page See Also PeopleTools 8.44 PeopleBook: PeopleTools Security, Working with Permission Lists

Instructor Notes
This section presents a review question for the current objective.

270

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Question: Securing Message Channels Security for message channels determines who can view the message channel in Integration Broker Monitor. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

271

Creating Message Channels and Message Definitions

Lesson 11

Describing Message Definitions


An asynchronous message definition has three basic parts: Message structure Message subscription Message routing

Slide 180 ______________________________________________________________________________________________________

Student Notes
Message subscription PeopleCode is used to manipulate data in the subscribing node and update the appropriate tables. It is executed automatically by BEA Tuxedo domain services in the subscribing system. Message subscription PeopleCode can be executed manually in two-tier using the Run PeopleCode menu item. In the publishing node, message routing PeopleCode determines which nodes to send (route) the message to. In the subscribing node, message routing PeopleCode determines if a received message should be accepted. Message routing PeopleCode is executed automatically by BEA Tuxedo domain services in the publishing and subscribing systems.

Instructor Notes
These three message parts are described in detail on the next slides.

272

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Describing Message Definitions (continued)


The message definition structure is a hierarchy of one or more records. In a message definition, you can: Define simple (single-level) or complex (multilevel) data structures. Include multiple records that are not related. Include and suppress fields from being published. Define aliases for dissimilar field and record names across databases. Define multiple versions of a message.

Slide 181 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

273

Creating Message Channels and Message Definitions

Lesson 11

Describing Message Definitions (continued)


The message definition consists of two main views: Message Structure view (left side). List view (right side).

Slide 182 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access this definition in PeopleSoft Application Designer:
Definition Name LOCATION_SYNC Navigation 1. 2. Select File, Open, Definition: Message, LOCATION_SYNC. Click the record name.

The message definition consists of two views:

Message definition See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Defining Message Channels and Messages Note. The Alias column is useful for cross-release and third-party applications.

Instructor Notes
Explain the two views to students.

274

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Message Structure View The Message Structure view shows several elements of the message definition, including: Different versions of the message structure. Record definitions (and child records) to be included in each message version. A list of subscription processes used to process the message.

Note. The lightening bolt indicates that the subscription PeopleCode is active. List View The List view displays the fields that make up the selected record in the message structure. The Alias column in the List view enables you to specify an XML field tag value for the message that differs from the original field name. The subscribing system uses this value instead of the original field name from the publishing system. If an alias value is not specified, the subscriber uses the original field name. The Include check box indicates the fields to be published.

PeopleSoft Proprietary and Confidential

275

Creating Message Channels and Message Definitions

Lesson 11

Describing Message Definitions (continued)


Aliases can be created in the following ways: For fields, use the Alias column in the List view. For records, right-click the record and select Message Record Properties.

Slide 183 ______________________________________________________________________________________________________

276

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Describing Message Definitions (continued)


You use message properties to: Activate the message. Indicate if non-repudiation is used. Indicate if the structure should be validated. Associate the message with a message channel. Determine the default version. Indicate where the message can be viewed or corrected.

Slide 184 ______________________________________________________________________________________________________

Student Notes
Use the Message Properties dialog box to define properties:

Message Properties page

PeopleSoft Proprietary and Confidential

277

Creating Message Channels and Message Definitions

Lesson 11

Instructor Notes
This section discusses how to: Explain nonrepudiation. Discuss message viewing and correction. Question: Describe message definitions.

Explaining Nonrepudiation PeopleSoft Integration Broker applies nonrepudiation capability to cross-node messaging by digitally signing request messages and replies. Nonrepudiation ensures that none of the nodes in integration can disavow their participation in a given transaction. In PeopleSoft applications, nonrepudiation provides two-way protectionboth the request and the reply message are nonrepudiated. PeopleSoft Integration Broker uses public-key infrastructure technology to implement nonrepudiation for messaging. Each participating node's keystore contains its own private key and the public keys of the nodes with which it exchanges messages. Discussing Message Viewing and Correction Explain that students can either use the message monitor or set up custom pages that are used for viewing and correcting messages. Question: Describing Message Definitions Which of the following is not part of the message definition? 1. Message structure. 2. Message subscription. 3. Message nodes. 4. Message routing. Answer The answer is 3 (Message nodes).

278

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Creating Message Definitions


Use the following steps to create a message definition in PeopleSoft Application Designer: 1. Select File, New, Message. 2. Click VERSION_1. 3. Select Insert, Child Record. 4. You can add additional records (siblings) and child records. 5. Indicate the fields to be published and define any aliases. 6. Select the message channel. 7. Save the message.
Slide 185 ______________________________________________________________________________________________________

Student Notes
Alternatively, you can add a record by dragging the record from the project workspace into VERSION_1.

Instructor Notes
This section discusses how to: Explain message versioning. Question: Create message definitions.

Explaining Message Versioning Remind students that when they create a new message, the default VERSION_1 appears in the structure. Records are added to versions. Versions added by selecting Insert, Version, are numbered with the next sequential number. Only one version can be the default. Additional versions may be created for specific integrations, for example you may use the same message with a PeopleSoft 8.1x application and a PeopleSoft 8.4 application where the record structure is slightly different. Question: Creating Message Definitions Each message definition must contain a version number. 1. True

PeopleSoft Proprietary and Confidential

279

Creating Message Channels and Message Definitions

Lesson 11

2. False Answer The answer is 1 (true).

280

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Creating Test Messages


Once you have created a new message, you can create a test message in these ways: Right-click the version and select Create Test Message. Click the version or record and select Insert, Create Test Message.

Slide 186 ______________________________________________________________________________________________________

Student Notes
Note. The PSCAMA record is part of every message object and is used to store audit information. The following example shows a test message being created:

Sample test message

PeopleSoft Proprietary and Confidential

281

Creating Message Channels and Message Definitions

Lesson 11

Instructor Notes
To insert values in a record, double-click the field. We discuss message format in the next chapter. Students will notice there is a PSCAMA record. This section presents a review question for the current objective. Question: Creating Test Messages Test messages are created in PeopleSoft Application Designer. 1. True 2. False Answer The answer is 1 (true).

282

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

Activity 12:

Creating a Message Definition


In this activity, you will review the activity overview and: 1. Create a new message channel. 2. Create a message using the new channel. 3. Create a test message. See Integration Tools: Activity Guide, lesson 11, Creating Message Channels and Message Definitions, Activity 12: Creating a Message Definition.

Slide 187 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 20 minutes.

Activity Overview
In this activity, you will: 1. Create a new message channel, SCHOOL_CHNL, and add this message channel to the permission list ALLPAGES. 2. Create a new message, SCHOOL_SYNC that contains the record PSU_SCHOOL_TBL. This message will use the SCHOOL_CHNL message channel. 3. Create a test message for this definition.

Creating a New Message Channel


To create a new message channel: 1. In PeopleSoft Application Designer, select File, New, Message Channel. 2. Select File, Definition Properties. 3. Add a description. 4. Set the message channel status to Pause. 5. Save the message channel as SCHOOL_CHNL. 6. Close the definition. 7. In the browser, select PeopleTools, Security, Permissions & Roles, Permission Lists, ALLPAGES. 8. On the Message Monitor page, insert a new row and select SCHOOL_CHNL.

PeopleSoft Proprietary and Confidential

283

Creating Message Channels and Message Definitions

Lesson 11

9. Grant full access to SCHOOL_CHNL. 10. Save the permission list.

Creating a New Message Using the New Message Channel


To create a new message using the new message channel: 1. In PeopleSoft Application Designer, select File, New, Message. 2. Right-click VERSION_1 and select Insert Child Record. 3. Select PSU_SCHOOL_TBL. 4. Select File, Definition Properties. 5. Add a description. 6. Select the Use tab. 7. Select SCHOOL_CHNL for the message channel. 8. Click OK. 9. Save the message as SCHOOL_SYNC.

Creating a Test Message


To create a test message: 1. Right-click VERSION_1. 2. Select Create Test Message. 3. Create a test message using the following information:
Field COUNTRY SCHOOL_CODE DESCR DESCRSHORT STATE PUBLIC_PRIVATE AUDIT_ACTN Value or Status USA TEST TEST TEST CA U A

4. Click OK. 5. Write down the publication number. 6. Click OK. 7. Close the message definition.

284

PeopleSoft Proprietary and Confidential

Lesson 11

Creating Message Channels and Message Definitions

This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

285

Creating Message Channels and Message Definitions

Lesson 11

Review
In this lesson, you learned that: The elements of messaging include: Message channel definitions. Message definitions. Sending PeopleCode. Subscription PeopleCode. OnRequest PeopleCode.

You use message channels to group messages for processing. You secure message channels on permission lists. You create message definitions in PeopleSoft Application Designer. You can create and publish test messages.

Slide 188 ______________________________________________________________________________________________________

286

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format


Objectives
By the end of this lesson, you will be able to: Describe the message formats used with PeopleSoft Integration Broker. View message structure in Integration Broker Monitor. Describe the PeopleSoft structured message format. Describe the PeopleSoft Common Application Messaging Attributes (PSCAMA) record. Edit message XML.

Slide 190 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

287

Describing the PeopleSoft Message Format

Lesson 12

Describing the Message Formats Used with PeopleSoft Integration Broker


Two types of messages are supported in PeopleSoft Integration Broker: Structured messages, which use record definitions to create a hierarchical structure for the data. Unstructured messages, which do not use record definitions.

Slide 191 ______________________________________________________________________________________________________

Student Notes
Note. This lesson focuses on structured messages.

Instructor Notes
This section discusses how to: Explain structured messages. Explain unstructured messages. Question: Describe the message formats used with PeopleSoft Integration Broker.

Explaining Structured Messages Make sure that students understand the following concepts regarding structured messages: Structured messages use record definitions to create a hierarchical structure for the data. These are generally used for data from applications, pages, components, and so on. To work with a rowset-based messagethe PeopleSoft native formatyou define a message in PeopleSoft Application Designer, insert records into the message definition in a hierarchical structure, and then populate the message and manipulate its contents using the PeopleCode Rowset and Message classes. Externally, the message is transmitted as XML with a prescribed PeopleSoft schema. The PeopleSoft message schema includes a PSCAMA record, which PeopleTools adds to every level of the message structure, that conveys basic information about the message and its data rows. Use the Rowset and Message classes for messaging between PeopleSoft applications. If a message is populated with data from a PeopleSoft application database or component buffer, the Message class is best for handling that data. Explaining Unstructured Messages Make sure that students understand that unstructured messages do not use record definitions. They are empty structures, generally used for XML and Simple Object Access Protocol (SOAP) messages.

288

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

Question: Describing the Message Formats Used with PeopleSoft Integration Broker Structured messages are based on the PeopleSoft record structure. 1. True 2. False Answer The answer is 1 (True).

PeopleSoft Proprietary and Confidential

289

Describing the PeopleSoft Message Format

Lesson 12

Viewing Message Structure in Integration Broker Monitor


To view message structure in Integration Broker Monitor: 1. Select PeopleTools, Integration Broker, Monitor, Monitor Message. 2. Click the Refresh button. 3. Select the Message Instance tab. 4. Click the Details link next to the message that you want to view.
Slide 192 ______________________________________________________________________________________________________

Student Notes
The message details page in Integration Broker Monitor contains a link to view the XML for a message. There is also a XML Message tab.

Message Properties page

Instructor Notes
Make sure that students are aware of the following points: Every PeopleSoft message is time-stamped. PeopleSoft uses the ISO 8601format for all timestamps. The timestamp is displayed on the Message Properties page in the detail view.

In activity 12, students set the message channel to Pause, so the message should be in New status.

290

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

If the student did not set the channel to Pause, and the publication contact was created, the student cannot edit the XML.

PeopleSoft Proprietary and Confidential

291

Describing the PeopleSoft Message Format

Lesson 12

Viewing Message Structure in Integration Broker Monitor (continued)


To view the XML, either: Access the XML Message Viewer page. Click the View XML link.

Slide 193 ______________________________________________________________________________________________________

Student Notes
Use the XML Message Viewer page to see the message XML:

XML Message Viewer page Note. Large messages can be downloaded to a file for viewing.

Instructor Notes
This section presents a review question for the current objective. Question: Viewing Message Structure in Integration Broker Monitor You can view XML for a message in Integration Broker Monitor. 1. True 2. False

292

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

293

Describing the PeopleSoft Message Format

Lesson 12

Describing the PeopleSoft Structured Message Format


All messages contain the same standard header and are formatted in XML with the following sections: FieldTypes MsgData

Slide 194 ______________________________________________________________________________________________________

Student Notes
Note. The header is always <?xml version =1.0?>.

Instructor Notes
Make sure that students know that if third-party applications send messages, they must also use the standard header.

294

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

Describing the PeopleSoft Structured Message Format (continued)


The FieldTypes section conveys the name of each message record and its associated fields, along with the fields data type. Each record tag consists of the name of a record, followed by a class attribute with a single valid value: the letter R. Each field tag consists of the name of a field, followed by a type attribute with the field type.
Slide 195 ______________________________________________________________________________________________________

Student Notes
The following XML illustrates a FieldTypes section:
<FieldTypes> <PSU_SCHOOL_TBL class="R"> <COUNTRY type="CHAR"/> <SCHOOL_CODE type="CHAR"/> <DESCR type="CHAR"/> <DESCRSHORT type="CHAR"/> <STATE type="CHAR"/> <PUBLIC_PRIVATE type="CHAR"/> </PSU_SCHOOL_TBL>

Instructor Notes
Make sure that students understand the following: Each message sent by a PeopleSoft Integration Broker system includes field type information. Field type information conveys the name of each message record and its constituent fields, along with each field's data type. Your receiving application can use this information to validate the data types. The field type information is contained in the FieldTypes section of the message. The field tag has three valid values: CHAR for a character field, DATE for a date field, and NUMBER for a numeric field.

PeopleSoft Proprietary and Confidential

295

Describing the PeopleSoft Message Format

Lesson 12

Describing the PeopleSoft Structured Message Format (continued)


The MsgData section includes the actual data for the message. Between the MsgData tags are one or more Transaction sections. Each transaction represents one level 0 row of data. Between the Transaction tags is a rowset hierarchy of records and fields. Within the level 0 record tags are the fields for that record, followed by any level 1 records. The last record within a transaction is a fully specified PSCAMA record, which provides information about the entire transaction. For a record at each level, within its record tags are that record's fields, followed by any records at the next lower level. Immediately following the closing tag of every record below level 0 is a PSCAMA record containing only the AUDIT_ACTN field to specify the action for that record.

Slide 196 ______________________________________________________________________________________________________

Student Notes
The XML below displays the message data section:
<MsgData> <Transaction> <PSU_SCHOOL_TBL class="R"> <COUNTRY IsChanged="Y">USA</COUNTRY> <SCHOOL_CODE IsChanged="Y">TEST</SCHOOL_CODE> <DESCR IsChanged="Y">TEST</DESCR> <DESCRSHORT IsChanged="Y">TEST</DESCRSHORT> <STATE IsChanged="Y">CA</STATE> <PUBLIC_PRIVATE IsChanged="Y">U</PUBLIC_PRIVATE> </PSU_SCHOOL_TBL>

Instructor Notes
In PeopleTools 8.44, the IsChanged attribute was added to the transaction. This attribute can be used in PeopleCode. The IsChanged field can be used to identify fields that may have a blank value (was the field left blank or changed to a blank).

296

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

Describing the PSCAMA record


PeopleTools adds the PSCAMA record to every level of the message structure during processing. PSCAMA contains fields common to all messages, such as: Language code. Audit action. Base language. Message Sequence flag. Process instance. Publish rule ID. Message node name.

Slide 197 ______________________________________________________________________________________________________

Student Notes
The following code illustrates a FieldTypes section for PSCAMA:
<PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> <BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA>

The following code illustrates a MsgData section for PSCAMA:


<PSCAMA class="R"> <LANGUAGE_CD>ENG</LANGUAGE_CD> <AUDIT_ACTN IsChanged="Y">A</AUDIT_ACTN> <BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD> <MSG_SEQ_FLG/> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID/> <MSGNODENAME/> </PSCAMA>

PeopleSoft Proprietary and Confidential

297

Describing the PeopleSoft Message Format

Lesson 12

Instructor Notes
Make sure that students understand the following: Every message contains the LANGUAGE_CODE and AUDIT_ACTN fields. The following fields are used when messaging is run in batch mode (a full-table publish with multiple rows of data): BASE_LANGUAGE_CD Indicates the base language of the sending database and is used by generic full-table subscription PeopleCode to help determine which tables to update. PROCESS_INSTANCE Contains the process instance of the batch job that created the message. MSG_SEQ_FLG Supports transmission of large transactions that may span multiple messages. Indicates whether the message is a header (H), trailer (T), or contains data (blank). The header and trailer messages dont contain message data. The following fields are optional and only used when there is routing PeopleCode associated with the message: PUBLISH_RULE_ID Indicates the publish rule invoked to create the message. Used by routing PeopleCode to locate the appropriate chunking rule, which then determines to which nodes the message should be sent. Third-party applications can ignore this field. MSGNODENAME The node to which the message should be sent. This field is passed to the Publish utility by the Application Engine program. Routing PeopleCode must look for a value in this field and return that value to the application server. Third-party applications can ignore this field.

298

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

Describing the PSCAMA record (continued)


The AUDIT_ACTN field identifies each row of data as an Add, Change, or Delete action. Valid values are:
User Action Insert or add a new row Delete a row Change a non-key value Change at least one key field Action Audit Code A D C K: contains the old value. N: contains the new value. Message published using CopyRowSetDeltaOriginal or CopyRowsetDelta O: contains the old values. C: contains the new values.

Slide 198 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

299

Describing the PeopleSoft Message Format

Lesson 12

Describing the PSCAMA record (continued)


The PSCAMA record is referenced in subscription PeopleCode to determine the appropriate action to perform on the records. The receiving process can access the fields in this record just like any other fields in the message. If a <PSCAMA> tag is not included, or if a specific row is blank or NULL, you can assume that the row hasnt changed. The first record contains all the fields, while the other PSCAMA records have only the AUDIT_ACTN field, which is the only field that can differ for each row of data.
Slide 199 ______________________________________________________________________________________________________

Student Notes
The following example shows PSCAMA transaction values on a multiple record message:
<MsgData> <Transaction> <PSU_PO_HDR class="R"> <BUSINESS_UNIT IsChanged="Y">NAM01</BUSINESS_UNIT> <ORDER_NBR IsChanged="Y">00000051</ORDER_NBR> <ORDER_DT IsChanged="Y">2003-11-23</ORDER_DT> <VENDOR_CD IsChanged="Y">ALPH04</VENDOR_CD> <ORDER_STATUS IsChanged="Y">IN</ORDER_STATUS> <STATUS_DT IsChanged="Y">2003-11-23</STATUS_DT> <DELIVER_METHOD IsChanged="Y"/> <ADDED_BY/> <APPR_STATUS/> <APPR_INSTANCE IsChanged="Y">0</APPR_INSTANCE> <PSU_PO_DTL class="R"> <BUSINESS_UNIT IsChanged="Y">NAM01</BUSINESS_UNIT> <ORDER_NBR IsChanged="Y">00000051</ORDER_NBR> <ORDER_LINE_NBR IsChanged="Y">1</ORDER_LINE_NBR> <ITEM_CD IsChanged="Y">PSU001</ITEM_CD> <QTY IsChanged="Y">1</QTY> <PART_NBR/> <ITEM_COLOR/> <PRICE IsChanged="Y">1000</PRICE> </PSU_PO_DTL> <PSCAMA class="R"> <AUDIT_ACTN>A</AUDIT_ACTN> </PSCAMA> </PSU_PO_HDR> <PSCAMA class="R">

300

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

<LANGUAGE_CD>ENG</LANGUAGE_CD> <AUDIT_ACTN>A</AUDIT_ACTN> <BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD> <MSG_SEQ_FLG/> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID/> <MSGNODENAME/> </PSCAMA> </Transaction> </MsgData>

Instructor Notes
Make sure that students understand the following: Although the first PSCAMA record is always present, not all of the remaining PSCAMA records are sent in the message. This may happen with multilevel records where the child record does not have an associated PSCAMA record. If youre receiving a message that has incremental changes, only changed rows and their parent rows are present in the message. Point out that the message students created only has one record. If there are multiple records, they each have XML tags to define the field type and transaction.
XML document <PO_SYNC> <FieldTypes> <PSU_PO_HDR class="R"> <PSU_PO_DTL class="R"> <PSCAMA class="R"> </FieldTypes> <MsgData> <Transaction> <PSU_PO_HDR class="R"> <PSU_PO_DTL class="R"> <PSCAMA class="R"> </PSU_PO_HDR> <PSCAMA class="R"> </PSCAMA> </Transaction> </MsgData> </PO_SYNC> In the MSGData section, level one records are included within the level zero tags, as well as the PSCAMA for the level one record. Description In the field types, all the records are defined.

PeopleSoft Proprietary and Confidential

301

Describing the PeopleSoft Message Format

Lesson 12

Editing Message XML


The XML Message Viewer page includes links to: Edit the XML. Print the XML.

Slide 200 ______________________________________________________________________________________________________

Student Notes
If there is an error in a message, use the Edit XML page to edit the XML and correct the message:

Edit XML page

Instructor Notes
Inform students that, before sending the message, they can update values on the PSCAMA record just like any other record in the message definition.

302

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

Activity 13:

Viewing and Editing a Structured XML Message


In this activity, you will review the activity overview and: View a structured XML message. Edit the XML.

See Integration Tools: Activity Guide, lesson 12, Describing the PeopleSoft Message Format, Activity 13: Viewing and Editing a Structured XML Message.
Slide 201 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 10 minutes.

Activity Overview
In this activity, you will view the SCHOOL_SYNC test message that was created in activity 12 and then edit the XML. You will change the DESCR field from TEST to MYTEST.

Viewing a Structured XML Message


To view the structured XML message: 1. In PeopleSoft Internet Architecture, select PeopleTools, Integration Broker, Monitor, Monitor Message. 2. Access the Message Instance page. 3. Click Refresh. Note. If you do not see your message, make sure that you granted security to view the message channel SCHOOL_SYNC. 4. Select Details next to your SCHOOL_SYNC message. 5. Access the XML Message Viewer page. 6. Scroll down the message. You should see the following:
<?xml version="1.0"?> <SCHOOL_SYNC> <FieldTypes> <PSU_SCHOOL_TBL class="R"> <COUNTRY type="CHAR"/> <SCHOOL_CODE type="CHAR"/>

PeopleSoft Proprietary and Confidential

303

Describing the PeopleSoft Message Format

Lesson 12

<DESCR type="CHAR"/> <DESCRSHORT type="CHAR"/> <STATE type="CHAR"/> <PUBLIC_PRIVATE type="CHAR"/> </PSU_SCHOOL_TBL> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> <BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA> </FieldTypes> <MsgData> <Transaction> <PSU_SCHOOL_TBL class="R"> <COUNTRY IsChanged="Y">USA</COUNTRY> <SCHOOL_CODE IsChanged="Y">TEST</SCHOOL_CODE> <DESCR IsChanged="Y">TEST</DESCR> <DESCRSHORT IsChanged="Y">TEST</DESCRSHORT> <STATE IsChanged="Y">CA</STATE> <PUBLIC_PRIVATE IsChanged="Y">U</PUBLIC_PRIVATE> </PSU_SCHOOL_TBL> <PSCAMA class="R"> <LANGUAGE_CD>ENG</LANGUAGE_CD> <AUDIT_ACTN IsChanged="Y">A</AUDIT_ACTN> <BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD> <MSG_SEQ_FLG/> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID/> <MSGNODENAME/> </PSCAMA> </Transaction> </MsgData> </SCHOOL_SYNC>

Editing the XML


To edit the XML: 1. Click Edit XML. 2. Change the DESCR field to MYTEST. 3. Click OK. 4. Select Save.

304

PeopleSoft Proprietary and Confidential

Lesson 12

Describing the PeopleSoft Message Format

5. Close the window. 6. Click Refresh. Results

SCHOOL_SYNC message displays as edited This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

305

Describing the PeopleSoft Message Format

Lesson 12

Review
In this lesson, you learned that: PeopleSoft Integration Broker supports both structured and unstructured messages. Structured messages are based on PeopleSoft record definitions. You view messages in Integration Broker Monitor. The PeopleSoft structured message format has two sections: The FieldTypes section describes the message, record, and fields, and the fields data type. The MsgData section includes the actual message data. The PSCAMA record is automatically added to every message and contains audit action information, as well as other common fields. You can edit message XML in Integration Broker Monitor.

Slide 202 ______________________________________________________________________________________________________

306

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages


Objectives
By the end of this lesson, you will be able to: List PeopleSoft Integration Broker transaction types. Describe PeopleCode used with structured messages. Publish asynchronous messages. Subscribe to asynchronous messages. Test subscription PeopleCode. Send and receive synchronous messages. Assign transactions to nodes. Describe message routing.

Slide 204 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

307

Sending and Receiving Messages

Lesson 13

Listing PeopleSoft Integration Broker Transaction Types


There are four types of messaging transactions: Outbound asynchronous Outbound synchronous Inbound asynchronous Inbound synchronous

Slide 205 ______________________________________________________________________________________________________

Student Notes
Each participating node in the integration must apply at least one transaction type, as described in the following table:
Transaction Type Outbound asynchronous Actions 1. 2. Outbound synchronous 1. 2. 3. 4. Inbound asynchronous 1. 2. Inbound synchronous 1. 2. 3. 4. Your application generates and sends a request message. Target nodes receive and process the request message. Your application generates and sends a request message. Your application suspends activity and waits for a response message. A single target node receives and processes the request message, and then generates and sends a response message. Your application resumes its activity and receives and processes the response message. A source node generates and sends a request message. Your application receives and processes the request message. A source node generates and sends a request message. The source node suspends activity and waits for a response message. Your application receives and processes the request message, and then generates and sends a response message. The source node resumes its activity and receives and processes the response message.

Instructor Notes
This section presents a review question for the current objective. Question: Listing PeopleSoft Integration Broker Transaction Types How many transaction types are available?

308

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

1. 2 2. 3 3. 4 4. 5 Answer The answer is 3 (4).

PeopleSoft Proprietary and Confidential

309

Sending and Receiving Messages

Lesson 13

Describing PeopleCode Used with Structured Messages


For any transaction type, applications invoke PeopleCode to generate and send a message, or to receive and process a message. Place sending PeopleCode on a record or component to publish the message. You can publish messages from Application Engine programs. Place subscription PeopleCode in the message definition to receive the message.
Slide 206 ______________________________________________________________________________________________________

Instructor Notes
Explain to students that the following PeopleCode events are associated with messages: OnRouteSend and OnRouteReceive.

Use these PeopleCode events with routing rules to determine where the messages are routed to and received from. OnRequest.

Use this PeopleCode event with synchronous messages, when a message has been received and requires a response. Subscription.

This PeopleCode event is initiated when the message is subscribed to asynchronously. Use this event for subscription processing to validate and load message data.

310

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Describing PeopleCode Used with Structured Messages (continued)


Use the Message class to create and access structured messages. The Message class is built on top of the following classes: Rowset class Row class Record class Field class

Slide 207 ______________________________________________________________________________________________________

Student Notes
Note. PeopleCode written to populate or access a message looks similar to PeopleCode written to populate or access the component buffer.

PeopleSoft Proprietary and Confidential

311

Sending and Receiving Messages

Lesson 13

Describing PeopleCode Used with Structured Messages (continued)


The Message class has several built-in functions. The two that we will be using are:
Built-in Function Syntax CreateMessage (MESSAGE.messagename) Description Instantiates a message object that refers to a message definition created in PeopleSoft Application Designer. Retrieves a message from the message queue for the current message being processed.

GetMessage ()

Slide 208 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleCode Reference, Message Class.

Instructor Notes
This section discusses how to: Declaring Messages Explain to students how messages are declared using the Message data type. The following shows a message declaration:
Local Message &MSG;

Declare messages. Explain the CreateMessage function. Explain the GetMessage function. Discuss messaging built-in functions.

A message object can only be instantiated from PeopleCode. This object can be used anywhere you have PeopleCode; for example, in message subscription PeopleCode, component interface PeopleCode, or record field PeopleCode. Explaining the CreateMessage Function Make sure that students know the following about the CreateMessage function: The CreateMessage function instantiates a message object that refers to a message definition created in PeopleSoft Application Designer. The CreateMessage function sets the following properties for the resulting message object, based on the values set for the message definition:
312

Name ChannelName Active

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Other properties are set when the message is published or subscribed to (the publish ID, the subscription name, and so on) or are dynamically generated at other times (size, the IsEditError property, and so on.) The CreateMessage function also sets the LANGUAGE_CD field in the level 0 PSCAMA record for a message based on the USERID default language group. If the message is published from a component, the language code is set to the USERID language code for the component. If CreateMessage is called from an Application Engine program, the language code of the user who started the batch process is used. The CreateMessage function returns a reference to a message object. Explaining the GetMessage Function Make sure that students know the following about the GetMessage function: The GetMessage function is used in any of the messaging PeopleCode events. It retrieves a message from the message queue for the current message being processed. It creates and loads a data tree for the default message version. The GetMessage function returns a reference to a message object if successful, and returns a null value if not successful. Discussing Messaging Built-in Functions Make sure that students know the built-in functions. Messaging built-in functions include: AddSystemPauseTimes CreateMessage DeleteSystemPauseTimes GetMessage GetSyncLogData PingNode ReturnToServer SetChannelStatus

PeopleSoft Proprietary and Confidential

313

Sending and Receiving Messages

Lesson 13

Describing PeopleCode Used with Structured Messages (continued)


The Message class has several methods for working with rowsets:
Method Syntax CopyRowset (source_rowset [, record_list]) CopyRowsetDelta (source_rowset [, record_list]) CopyRowsetDeltaOriginal (source_rowset [, record_list]) GetRowset () Description Copies all data from the source rowset to the like-named fields in the message object that is calling the method. Copies rows of data that have changed from the source rowset to the like-named records and like-named fields in the message object that is calling the method. Copies rows of data that have changed from the source rowset to the like-named records and like-named fields in the message. It also copies the original value of the changed rows. Returns a standard PeopleCode level 0 rowset object for the specified message version.

Slide 209 ______________________________________________________________________________________________________

Student Notes
Note. CopyRowsetDelta copies all the like-named fields from the changed row into the message. Parent rows are also included. The method does not copy just the changed likenamed fields.

314

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Describing PeopleCode Used with Structured Messages (continued)


Use the following methods to send messages:
Method Syntax Publish ([Deferred_Mode] [, NodeName]) SyncRequest ([NodeName]) Description Publishes a message to the application message queue for the default message version. Sends a synchronous message for the default message version.

Slide 210 ______________________________________________________________________________________________________

Student Notes
Note. For either method, a message is only sent if the message objects IsActive property is True. You specify messages as active in PeopleSoft Application Designer.

Instructor Notes
In their code, students will use Message class methods described on the slides. These class methods are not discussed in this course:
Method Syntax Clone () GenXMLString () Description Creates an identical copy of the message The GenXMLString method creates an XML string from a BiDocs object (used with incoming business interlinks). Obtains parameter values of a query string. Loads the message object that calls the method with the XML string XMLstring. Works with the ExecuteEdits method. Use to set the value of a field on a record that has its prompt table defined as %PromptField value. %PromptField values are used to dynamically change the prompt record for a field. Adds a parameter value to the query string. Sets the status of a publication or subscription contract, much in the same way as with Integration Broker Monitor. Updates a message in the message queue with the specified message versions. If versionlist isnt specified, the default message version is used.

GetQueryString (Parameter_Name) LoadXMLString (XMLstring) SetEditTable (%PromptField, RECORD.recordname)

SetQueryString (Parameter_Name, Value) SetStatus (Status)

Update ([versionlist])

PeopleSoft Proprietary and Confidential

315

Sending and Receiving Messages

Lesson 13

See PeopleTools 8.44 PeopleBook: PeopleCode Reference, Message Class.

316

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Describing PeopleCode Used with Structured Messages (continued)


To receive messages, use the following methods:
Method Syntax ExecuteEdits ([editlevels]) GetRowset ([version]) Description Performs standard system edits on every field for every record in the message that calls the method. Returns a standard PeopleCode level 0 rowset object for the specified message version.

Slide 211 ______________________________________________________________________________________________________

Student Notes
The following table shows the edit levels that can be set:
Parameter %Edit_DateRange %Edit_PromptTable %Edit_Required %Edit_TranslateTable %Edit_YesNo %Edit_OneZero Edit Reasonable date range. (Is the date contained within plus or minus 30 days from the current date?) Prompt table. (Is field data contained in the specified prompt table?) Required field. (Do all required fields contain data?) Translate table. (Is field data contained in the translate table?) Yes/no. (Do all yes/no fields contain yes or no data only?) 1/0. (Do all 1/0 fields contain 1 or 0 only?)

Note. The IsEditError property is True if an error has been found on any field in any record of the current message after executing the ExecuteEdits method on either a message object or a record object.

Instructor Notes
This section discusses how to: Explain the ExecuteEdits method. Explain the GetRowset method. Question: Describe PeopleCode used with structured messages.

Explaining the ExecuteEdits Method Make sure that students know the following:

PeopleSoft Proprietary and Confidential

317

Sending and Receiving Messages

Lesson 13

All edits are based on the record edits defined for the records that the message is based on. The types of edits performed depend on the edit level. If no edit level is specified, all system edits defined for the record definitions are performed. The IsEditError property is True if an error is found on any field in any record of the current message after running the ExecuteEdits method on either a message object or a record object. This property can be used with the Field class properties MessageSetNumber and MessageNumber to find the error message set number and error message number. You can use this property in subscription PeopleCode with Exit(1). Exit(1) automatically rolls back any changes that were made to the database, saves the message errors to the message queue, and marks the message status as Error. Explaining the GetRowset Method Make sure that students know the following: The GetRowset method creates an empty rowset for the specified message version if it doesnt already exist. If no message version is specified, the default message version is used. When you use the GetRowset method, you are not creating a unique copy of the object. You are making only a copy of the reference. If you change the rowset, the original message is changed. Question: Describing PeopleCode Used with Structured Messages Which built-in function is used to instantiate a message object? 1. CreateMessage 2. GetMessage 3. Message 4. CopyRowset Answer The answer is 1 (CreateMessage).

318

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Publishing Asynchronous Messages


The simplest way to populate a message with data is to copy the rowset from an existing component. The message must have the same structure as the rowset being copied. Follow these steps: 1. Instantiate the message object using the built-in function CreateMessage (MESSAGE.messagename). 2. Use the IsActive property of the message to ensure that the message is active. 3. Copy the data from the component using one of the CopyRowset methods. 4. Publish the message.
Slide 212 ______________________________________________________________________________________________________

Student Notes
Here is sample code for publishing a message:
/* Declare the message using the message data type */ Local Message &MSG; /* Use the built-in function CreateMessage */ &MSG = CreateMessage(Message.LOCATION_SYNC); /* Check to see if the message is active */ If &MSG.IsActive Then /* Copy all rowset fields that have been changed to the message */ &MSG.CopyRowsetDelta(GetRowset()); /* Publish the message */ &MSG.Publish(); End-If;

Note. Inactive messages are not published. Add the IsActive property to your code to avoid unnecessary processing.

Instructor Notes
Emphasize the note provided in the Student Notes section. Students do not need to add the code to publish PeopleCode, but the code will be more efficient.

PeopleSoft Proprietary and Confidential

319

Sending and Receiving Messages

Lesson 13

Publishing Asynchronous Messages (continued)


Use the Publish method in the following places to asynchronously send a message: A record field PeopleCode event. A component PeopleCode event. An Application Engine program. A message subscription program. The message OnRequest PeopleCode event.

Slide 213 ______________________________________________________________________________________________________

Student Notes
Note. The SavePostChange event is usually used for record field and component PeopleCode.

Instructor Notes
This section presents a review question for the current objective. Question: Publishing Asynchronous Messages You can publish messages from an Application Engine program. 1. True 2. False Answer The answer is 1 (true).

320

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Activity 14:

Publishing a Message
In this activity, you will review the activity overview and write publish PeopleCode for the SCHOOL_SYNC message. See Integration Tools: Activity Guide, lesson 13, Sending and Receiving Messages, Activity 14: Publishing a Message.

Slide 214 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 10 minutes. A copy of this PeopleCode is located in: Z:\STAnnn\Tools\1022_IntTools\scripts\SchoolPublish_pc.txt

Activity Overview
In this activity, you will write the publish PeopleCode to publish any changes on PSU_SCHOOL_TBL. Use the message SCHOOL_SYNC.

Writing the Publish PeopleCode for the SCHOOL_SYNC Message


To write the publish PeopleCode for the SCHOOL_SYNC message: 1. Select File, Open, Record, PSU_SCHOOL_TBL. 2. Select View, PeopleCode Display. 3. Open the PeopleCode editor on the field SCHOOL_CODE and select the SavePostChange Event. 4. Write the PeopleCode:
Local Message &MSG; &MSG = CreateMessage(Message.SCHOOL_SYNC); If &MSG.IsActive Then &MSG.CopyRowsetDelta(GetRowset()); &MSG.Publish(); End-If;

5. Save the record. 6. Close the PeopleCode editor. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

321

Sending and Receiving Messages

Lesson 13

Subscribing to Asynchronous Messages


The PeopleCode that you use to receive a message must be associated with the message definition. For asynchronous messages, enter subscription PeopleCode in the Message Subscriptions section of the message structure view. For synchronous messages, enter receiving PeopleCode in the OnRequest PeopleCode event associated with the root of the message structure.
Slide 215 ______________________________________________________________________________________________________

Student Notes
The following example contains asynchronous subscription PeopleCode:

Message subscription PeopleCode

Instructor Notes
Explain that the Subscription event provides the timing for executing a message subscription PeopleCode program. This event is associated with a message definition for the purpose of receiving the message asynchronously.

322

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Subscribing to Asynchronous Messages (continued)


Subscription PeopleCode should perform the following: Instantiate the message. Execute edits. Instantiate the rowsets. Evaluate the message PSCAMA record to determine the action to perform.

Slide 216 ______________________________________________________________________________________________________

Student Notes
Here is the subscription PeopleCode for LOCATION_SYNC:
Local Message &MSG; Local Rowset &MSG_ROWSET; Local Record &rLocation; /*Instantiate the message */ &MSG = GetMessage(); /* Instantiate the rowset */ &MSG_ROWSET = &MSG.GetRowset(); /* Because Locations are effective-dated, multiple rows * (transactions) may exist at level 0 of the message For &I = 1 To &MSG_ROWSET.ActiveRowCount &rLocation = &MSG_ROWSET(&I).LOCATION_TBL; /* Perform edit checking */ &MSG.ExecuteEdits(); If &MSG.IsEditError Then /* Specific error will be visible in Integration Broker Monitor */ Exit (1); Else Evaluate &MSG_ROWSET(&I).PSCAMA.AUDIT_ACTN.Value When = "C" /* Non-key data in publishing node was changed &RES = &rLocation.Update(); /* If update failed, it is probably because the data in * the two databases havent been synchronized. * Try insert action as a last resort. If &RES = False Then &rLocation.Insert(); End-If; Break; When = "A" /* New row added/inserted in publishing node */ * * */ */ * */

PeopleSoft Proprietary and Confidential

323

Sending and Receiving Messages

Lesson 13

When = "N" /* Keys changed in publishing node - new values */ &RES = &rLocation.Insert(); /* If insert failed, it is probably because the transaction * * Correct History - try an update */ If &RES = False Then &rLocation.Update(); End-If; Break; When = "D" /* Row deleted in publishing node &rLocation.Delete(); Break; End-Evaluate; End-If; End-For; */

Note. The CopyToFields method copies all like-named field values from the record object that calls the method to the specified record object. The CopyChangedFieldsTo method copies all like-named field values that have changed from the record object that calls the method to the specified record object.

Instructor Notes
Review the code with the students. LOCATION_TBL is an effective-dated table, so look at all of the level 1 rows.

324

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Subscribing to Asynchronous Messages (continued)


To create message subscription PeopleCode: 1. Open the message in PeopleSoft Application Designer. 2. Right-click anywhere in the structure and select Insert Message Subscription. 3. Select the Active check box. 4. Enter a descriptive name for the subscription program and click OK. 5. Enter PeopleCode in PeopleCode Editor. 6. Save the PeopleCode. 7. Close the PeopleCode Editor.
Slide 217 ______________________________________________________________________________________________________

Student Notes
Use the Message Subscription Properties dialog box to activate a message:

Message Subscription Properties dialog box

PeopleSoft Proprietary and Confidential

325

Sending and Receiving Messages

Lesson 13

Instructor Notes
This section discusses how to: Explain message subscription PeopleCode details. Question: Subscribe to asynchronous messages.

Explaining Message Subscription PeopleCode Details Make sure that students are aware of the following: New messages are active by default. Each message subscription PeopleCode needs a name. You use a Generate Subscription process instance to automatically produce a unique number that identifies the process request each time that PeopleSoft Process Scheduler runs this subscription in batch mode. You would use a process instance if the subscription PeopleCode was used with an Application Engine program. Question: Subscribing to Asynchronous Messages In subscription PeopleCode, what record determines the action to perform? 1. Level 0 record 2. Level 1 record 3. PSCAMA 4. AUDIT_ACTN Answer The answer is 3 (PSCAMA).

326

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Testing Subscription PeopleCode


Use the following steps to test the subscription process in PeopleSoft Application Designer. 1. Open the message in PeopleSoft Application Designer. 2. Create a test message. 3. Right-click the subscription PeopleCode name. 4. Select Run PeopleCode. 5. Enter the publication ID of the test message that you created in Step 2. 6. Click OK. 7. Check the online system to verify that your data was updated.
Slide 218 ______________________________________________________________________________________________________

Instructor Notes
Explain to students that they can debug the subscription PeopleCode if there are errors by turning on the PeopleCode debugger. Students learned how to create a test message in the last lesson.

PeopleSoft Proprietary and Confidential

327

Sending and Receiving Messages

Lesson 13

Activity 15:

Writing and Testing Subscription PeopleCode


In this activity, you will review the activity overview and: 1. Write subscription PeopleCode for the SCHOOL_SYNC message. 2. Test subscription PeopleCode. See Integration Tools: Activity Guide, lesson 13, Sending and Receiving Messages, Activity 15: Writing and Testing Subscription PeopleCode.

Slide 219 ______________________________________________________________________________________________________

Instructor Notes
Students can copy the Location Sync subscription PeopleCode and modify it. The following code shows the result. As this is not an effective-dated table, you do not need to loop; there is only one rowset. Also, you do not need N or D action codes.
/* Subscription PeopleCode for SCHOOL_SYNC */ Local Message &MSG; Local Rowset &MSG_ROWSET; Local Record &rSchool; Local Boolean &RES; &MSG = GetMessage(); &MSG_ROWSET = &MSG.GetRowset(); &rSchool = &MSG_ROWSET(1).PSU_SCHOOL_TBL; &MSG.ExecuteEdits(%Edit_Required + %Edit_TranslateTable); If &MSG.IsEditError Then /* Specific error will be visible in Integration Broker Monitor */ Exit (1); Else Evaluate &MSG_ROWSET(1).PSCAMA.AUDIT_ACTN.Value When = "C" /* Non-key data in publishing node was changed &RES = &rSchool.Update(); /* If update failed, it is probably because the data in * the two databases haven't been synchronized. * Try insert action as a last resort. If &RES = False Then &rSchool.Insert(); End-If; Break; When = "A" /* New row added/inserted in publishing node &RES = &rSchool.Insert(); /* If insert failed, it is probably because the transaction * */ * * */ */

328

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

* Correct History - try an update If &RES = False Then &rSchool.Update(); End-If; Break; End-Evaluate; End-If;

*/

Activity Overview
In this activity, you will write subscription PeopleCode for the SCHOOL_SYNC message and test the PeopleCode using the test message created in Activity 12.

Writing Subscription PeopleCode for the SCHOOL_SYNC Message


To write subscription PeopleCode: 1. Open the message SCHOOL_SYNC in PeopleSoft Application Designer. 2. Right-click anywhere in the structure and select Insert Message Subscription. 3. Select the Active check box. 4. Enter the descriptive name Synchronize School for the subscription program. 5. Click OK. 6. Enter the PeopleCode in the PeopleCode Editor. You can copy the LOCATION_SYNC subscription PeopleCode and modify it for PSU_SCHOOL_TBL. Note. A copy is located in \1022_IntTools\Scripts\School_Subscription_pc.txt. 7. Save the PeopleCode.

Testing Subscription PeopleCode


To test the subscription PeopleCode: 1. Right-click the subscription PeopleCode. 2. Select Run PeopleCode. 3. Enter the publication ID of your test message. See Lesson 11 Activity 12. 4. Click OK. 5. Click OK in the PSDBGPRC dialog box to close the dialog box. 6. In the browser, select Set Up Training, Common Definitions, School Details to check that the new school was added.

PeopleSoft Proprietary and Confidential

329

Sending and Receiving Messages

Lesson 13

Results The School Details page should reflect the content of the test message:

School details for test message This concludes the activity. Do not continue.

330

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Sending and Receiving Synchronous Messages


Synchronous messages are sent in real time, and processing does not continue until a response has been returned from the receiving node. You need to set up the following on the sending (source) database: Message channel. Message. Response record. Response message. Sending PeopleCode. Security to the message channel. Outbound transaction to the receiving node, including the response record.

Slide 220 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

331

Sending and Receiving Messages

Lesson 13

Sending and Receiving Synchronous Messages (continued)


Set up the following on the receiving (target) database: Message channel. Message. Response record. Response message. OnRequest PeopleCode. Security to the message channel. Inbound transaction from the sending node, including the response record.

Slide 221 ______________________________________________________________________________________________________

Instructor Notes
Emphasize that much of the setup for the source and target is the same. The big difference is the response record and response message. When working synchronously, you need to know immediately if the transaction has reached its destination and if the update is successful.

332

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Sending and Receiving Synchronous Messages (continued)


The response record can be any record that you want to populate with data to send as a response to the synchronous message. In addition to a response record, you create a response message. You create a response message as you would create any other message.
Slide 222 ______________________________________________________________________________________________________

Student Notes
The following examples show a response record and a response message:

TRN_REPLY record

COUNTRY_REPLY message

PeopleSoft Proprietary and Confidential

333

Sending and Receiving Messages

Lesson 13

Sending and Receiving Synchronous Messages (continued)


Use the SyncRequest method to send structured messages synchronously. You can place the method in any of the following PeopleCode events: The record field SavePreChange PeopleCode event. The record field SavePostChange PeopleCode event. The record field Workflow PeopleCode event. The record field FieldChange PeopleCode event. The message OnRequest PeopleCode event. A message subscription program.

Slide 223 ______________________________________________________________________________________________________

Student Notes
Here is sample PeopleCode to send a synchronous message:
Local Message &request, &response; Local Rowset &LEVEL0; &LEVEL0 = GetLevel0(); &request = CreateMessage(Message.COUNTRY_SYNC); If &request.IsActive Then &request.CopyRowsetDelta(&LEVEL0); /* Synchronous publish */ &response = &request.SyncRequest(); If (&response.ResponseStatus = 0) Then MessageBox(0, "", 30002, 1, "Message not found.", (&response.GetRowset().GetRow(1).GetRecord(Record.TRN_REPLY).GetField(Fiel d.DESCR).Value), (&response.GetRowset().GetRow(1).GetRecord(Record.TRN_REPLY).GetField(Fiel d.PUBNODE).Value)); End-If; End-If;

Note. The response message is returned as a result of the SyncRequest method.

Instructor Notes
Explain to students that, when sending a synchronous request from a component, you should send messages only from the SavePostChange event, either from record field or component PeopleCode. This way, if there's an error in the SyncRequest code, the data isn't committed to the database. When reviewing the code, emphasize the following:

334

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

The first part is the same as an asynchronous message. To publish the message, use the SyncRequest method. Use &request for the sending message. Use &response to contain the value returned by the request. A return value of 0 means that the message was sent successfully. When calling the program from a component, notify the user that the message was received. Use MessageBox to display the message.

PeopleSoft Proprietary and Confidential

335

Sending and Receiving Messages

Lesson 13

Sending and Receiving Synchronous Messages (continued)


When you receive an inbound request message, your response message must conform to the return type expected by the sending code. If the sender uses the Message class SyncRequest method, respond with a Message object. Place response PeopleCode in the message definition OnRequest event.
Slide 224 ______________________________________________________________________________________________________

Student Notes
Here is sample OnRequest PeopleCode for the COUNTRY_SYNC message:
Local Message &request, &response; Local Rowset &Rowset; Local Record &rCountry, &REC; &request = GetMessage(); &rCountry = CreateRecord(Record.COUNTRY_TBL); &Rowset = &request.GetRowset(); /* Multiple level 0 rows may exist in the AE batch program, but not online page processing */ &REC = &Rowset(1).COUNTRY_TBL; &AUDIT_ACTION = &request.GetRowset()(1).PSCAMA.AUDIT_ACTN.Value; Evaluate &AUDIT_ACTION When "C" /* Data from publishing node was changed */ &REC.CopyFieldsTo(&rCountry); &RES = &rCountry.Update(); /* If update failed, it is probably because the data in the two databases has not been synchronized. Try insert as a last resort */ If &RES = False Then &rCountry.Insert(); End-If; Break; When = "A" /* New high order key inserted in publishing node */ &REC.CopyFieldsTo(&rCountry); &rCountry.Insert(); Break; When = "D" /* High order key deleted in publishing node */ &REC.CopyFieldsTo(&rCountry); &rCountry.Delete(); Break;

336

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

End-Evaluate; /* Create the response message */ &response = CreateMessage(Message.COUNTRY_REPLY); /* Populate TRN_REPLY with Receiving Node Name and Description */ &response.GetRowset().GetRow(1).GetRecord(Record.TRN_REPLY).GetField(Field .PUBNODE).Value = "your node"; &response.GetRowset().GetRow(1).GetRecord(Record.TRN_REPLY).GetField(Field .DESCR).Value = "update country"; ReturnToServer(&response);

Instructor Notes
This section discusses how to: Review the sample code. Question: send and receive synchronous messages.

Reviewing the Sample Code When reviewing the code, note that the first part is the same as an asynchronous message. Emphasize that, with synchronous messages, the response record needs to be populated with the data that you want to send back to the sending database. In this case, the field PUBNODE contains the local node, and the DESCR field contains the update country. Question: Sending and Receiving Synchronous Messages Which additional definitions are required for synchronous messages? 1. Response record. 2. Reponse message. 3. Message channel. 4. Message. Answer Both 1 and 2 (Response record and response message).

PeopleSoft Proprietary and Confidential

337

Sending and Receiving Messages

Lesson 13

Assigning Transactions to Nodes


You set up a transaction for a specific message on these nodes: Each node to which you are sending a message (outbound). Each node from which you will accept messages (inbound).

Slide 225 ______________________________________________________________________________________________________

Student Notes
If your database is sending the SCHOOL_SYNC message to PSFT_T02, that node must contain an outbound asynchronous transaction. If your database will also send transactions to PSFT_T02, you must also have an inbound asynchronous transaction. Use the Transactions page to view transactions:
Page Name Transactions Navigation PeopleTools, Integration Broker, Node Definitions, PSFT_T02

Transactions page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Administering Basic Integrations.

Instructor Notes
Explain that you only set up transactions for the nodes to which you are sending messages and from which you are receiving messages. Your local default node does not need a transaction, unless its for internal processing that the user or process doesnt need to wait for, such as posting to the report repository or updating dynamic role information. Note. Mention that if students are using relationships, which we will cover later in the course, they use the Integration Broker Point wizard to configure transactions.

338

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Assigning Transactions to Nodes (continued)


To add a transaction to a node: 1. Select PeopleTools, Integration Broker, Node Definition. 2. Select the node that you will send to or receive from. 3. Select the transaction tab. 4. Click the Add Transaction button. 5. Enter the type, message request, and version. 6. Click the Add button. 7. For synchronous messages, use the message page to add the response message. 8. Save the page. 9. Click Return to Transaction.
Slide 226 ______________________________________________________________________________________________________

Student Notes
The following example shows adding an outbound asynchronous transaction:

Node Transactions page

PeopleSoft Proprietary and Confidential

339

Sending and Receiving Messages

Lesson 13

Assigning Transactions to Nodes (continued)


Use the Messages page to: Set the synchronous logging level. Specify the response message.

Slide 227 ______________________________________________________________________________________________________

Student Notes
The following example shows an outbound synchronous transaction:

Transaction messages identify the response message

Instructor Notes
Go over possible synchronous logging levels. On the Messages page, the level can be set to these values: Header Only. Header and Detail. No Logging.

340

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Activity 16:

Adding Asynchronous Transactions


In this activity, you will review the activity overview and: 1. Add asynchronous transactions to your neighbors node. 2. Add asynchronous transactions to PSFT_EP. See Integration Tools: Activity Guide, lesson 13, Sending and Receiving Messages, Activity 16: Adding Asynchronous Transactions.

Slide 228 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately fifteen minutes. The FSCM 8.8 database has the LOCATION_SYNC message. If you open the message in Application Designer, both subscription PeopleCode programs are active. The instructor should inactivate the LocationSyncEff. The Gateway on the FSCM 8.8 database has not been set. This is fine for the activities as defined in this course since we are only sending to FSCM. If you publish from FSCM, you would need to vhange the gateway URL.

Activity Overview
In this activity, you will set up the asynchronous transactions to publish to and receive SCHOOL_SYNC transactions from your neighbors training database. You will then set up the asynchronous transaction to publish LOCATION_SYNC transactions to the FSCM database (PSFT_EP).

Adding Asynchronous Transactions to Your Neighbors Node


To add asynchronous transactions to your neighbors node: 1. Select PeopleTools, Integration Broker, Node Definition. 2. Select your neighbors node. 3. Select the Transactions tab. 4. Click the Add Transaction button. 5. Enter the following information:
Page Element Transaction Type Request Message Request Message Version Value or Status Inbound Asynchronous SCHOOL_SYNC VERSION_1

PeopleSoft Proprietary and Confidential

341

Sending and Receiving Messages

Lesson 13

6. Click the Add button. 7. Click Save. 8. Click Return to Transaction List. 9. Click the Add Transaction button. 10. Enter the following information:
Page Element Transaction Type Request Message Request Message Version Value or Status Outbound Asynchronous SCHOOL_SYNC VERSION_1

11. Click the Add button. 12. Click Save. 13. Click Return to Transaction List. 14. Add additional transactions for both inbound and outbound asynchronous LOCATION_SYNC message. Results You should see the following transactions listed on the Transactions page:

Transactions to send to and receive from PSFT_T02

Adding Asynchronous Transactions for PSFT_EP


To add asynchronous transactions for PSFT_EP: 1. Select PeopleTools, Integration Broker, Node Definitions. 2. Select PSFT_EP. 3. Add an outbound asynchronous transaction for LOCATION_SYNC. 4. Save the page.

342

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

5. Sign out. 6. Select PeopleSoft FSCM 8.8 from the browser favorites. 7. Sign in with the user ID VP1 and the password VP1. 8. Select PeopleTools, Integration Broker, Node Definitions. 9. Select your database node. 10. Add an inbound asynchronous transaction for LOCATION_SYNC. 11. Save the page. 12. Sign out. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

343

Sending and Receiving Messages

Lesson 13

Activity 17:

Sending and Receiving a Synchronous Message


In this activity, you will review the activity overview and: 1. Review definitions and PeopleCode. 2. Set up synchronous transactions to send and receive messages. 3. Test the message. See Integration Tools: Activity Guide, lesson 13, Sending and Receiving Messages, Activity 17: Sending and Receiving a Synchronous Message.

Slide 229 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 20 minutes. You can also view the sending PeopleCode from the Structure tab on the component.

Activity Overview
In this activity, you will set up your database to send and receive the COUNTRY_SYNC message synchronously. First, you will add an outbound synchronous transaction, so that you can publish to your neighbors database. Then you will add an inbound synchronous transaction to receive a message from your neighbors database. Test the message by adding a new country. Name the country with the letter T followed by your workstation number. For example, T01. The COUNTRY_SYNC message is set up to use the message channel TRAINING_CHNL. You will need to add the security to the permission list ALLPAGES to view messages for this channel on the Message Monitor page. The response record is TRN_REPLY. The response message has already been defined on your database as COUNTRY_REPLY. The sending PeopleCode is on the component COUNTRY_TABLE in the SavePostChange event. The OnRequest PeopleCode already exists in the COUNTRY_SYNC message.

Reviewing Definitions and PeopleCode


To review the definitions and PeopleCode: 1. In Application Designer, select File, Open, Message, COUNTRY_SYNC. 2. Review the message properties.
344 PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

3. Select View, View PeopleCode. 4. Select the COUNTRY_SYNC message and the event OnRequest, and review the receiving PeopleCode. 5. Change the text for the PUBNODE field to your database node.
&response.GetRowset().GetRow(1).GetRecord(Record.TRN_REPLY).GetField(Field .PUBNODE).Value = "PSFT_Txx";

6. Save the message and close it. 7. Select File, Open, Component, COUNTRY_TABLE. 8. Select View, View PeopleCode and review the sending PeopleCode. 9. Close the component. 10. Select File, Open, Message, COUNTRY_REPLY. 11. Review the definition and then close it.

Setting up Synchronous Transactions to Send and Receive


To set up synchronous transactions to send and receive: 1. Select PeopleTools, Integration Broker, Node Definitions. 2. Select your neighbors node. 3. Select the Transactions tab. 4. Click the Add Transaction button. 5. Enter the following information:
Page Element Transaction Type Request Message Request Message Version Value or Status Outbound Synchronous COUNTRY_SYNC VERSION_1

6. Click the Add button. 7. Review the transaction. 8. Select the message tab. Enter the following information:
Page Element Synchronous Logging Response Message - Name Response Message Version Value or Status Header and Detail COUNTRY_REPLY VERSION_1

PeopleSoft Proprietary and Confidential

345

Sending and Receiving Messages

Lesson 13

9. Click Save. 10. Select Return to Transaction. 11. Click the Add Transaction button. 12. Enter the following information:
Page Element Transaction Type Request Message Request Message Version Value or Status Inbound Synchronous COUNTRY_SYNC VERSION_1

13. Click the Add button.. 14. Review the transaction. 15. Add the response message on the Message page. Enter the following information:
Page Element Response Message - Name Response Message Version Value or Status COUNTRY_REPLY VERSION_1

16. Click Save. 17. Click Return to Transaction.

Testing the Message


To test the message: 1. Select Setup Training, Common Definitions, Locations, Country. 2. Add a new value using the letter T followed by your workstation number. For example, T01. 3. Add a description. 4. Save. Results You should see a message that the synchronous message was received:

346

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Country page This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

347

Sending and Receiving Messages

Lesson 13

Describing Message Routing


For each transaction defined in the node definition, there are two kinds of routing types: Implicit.

All nodes with this routing type are included as target nodes unless the sending PeopleCode references specific nodes. This is considered high-level message routing. Explicit.

The selected node is not included as a target node unless you specify it directly in the sending PeopleCode. This is considered low-level message routing and overrides the node's specified routing type.
Slide 230 ______________________________________________________________________________________________________

Instructor Notes
Make sure that students understand the following: For each messaging node, transactions were defined to map high-level message routings to other nodes in the messaging system. The routing type associated with each node determines if these high-level routings are used, or if low-level routings (controlled by PeopleCode) determine to which nodes messages are sent. When the integration engine receives a message, it searches the transaction definitions associated with that message definition to determine the valid target nodes for the message, and then passes the message to the synchronous or asynchronous request handler as appropriate. The handler directs the message to the specified nodes, using the gateway and target connector specified by the node definition. The handler could also direct the message to local subscription or OnRequest PeopleCode. A transaction might also be modified by a defined relationship that could involve a transformation. As an example of explicit routing, you can filter the list of included nodes using the OnRouteSend PeopleCode event associated with the message definition, to produce a single destination node.

348

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Describing Message Routing (continued)


Routing PeopleCode is defined in the message in one of the following events. Use the OnRouteSend event to apply PeopleCode that filters the destination nodes to which PeopleSoft Integration Broker routes the message. Use the OnRouteReceive event to apply PeopleCode that determines whether the default local node accepts the inbound message.

Slide 231 ______________________________________________________________________________________________________

Instructor Notes
Clarify for students that, with the OnRouteSend and OnRouteReceive events, PeopleCode can get and examine the message being routed, but you cant modify the message content. Only one statement in your code affects the message: The Message class built-in function ReturnToServer.

PeopleSoft Proprietary and Confidential

349

Sending and Receiving Messages

Lesson 13

Describing Message Routing (continued)


The following OnRouteSend PeopleCode routes a message according to a newly generated target node list thats based on a field value in the message:
Local message &MSG; Local array &NODE_ARRAY; &MSG = GetMessage(); &Setid = &MSG.GetRowset()(1).LOCATION_TBL.SETID.Value; &SELECT_SQL = CreateSQL("select PUBNODE from PS_SETID_NODE where SETID = :1", &Setid); &NODE_ARRAY = CreateArray(); While &SELECT_SQL.Fetch(&PUBNODE) &NODE_ARRAY.Push(&PUBNODE); End-While; ReturnToServer(&NODE_ARRAY);

Slide 232 ______________________________________________________________________________________________________

350

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Describing Message Routing (continued)


The following OnRouteReceive PeopleCode accepts the message if it contains a field value thats matched in the local database:
Local message &MSG; &MSG = GetMessage(); &Setid = &MSG.GetRowset()(1). LOCATION_TBL.SETID.Value; SQLExec("Select SETID From PS_ LOCATION_TBL where SETID = :1",&Setid,&FOUND); If all(&FOUND) Then ReturnToServer(True); Else ReturnToServer(False); End-if;

Slide 233 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

351

Sending and Receiving Messages

Lesson 13

Review
In this lesson, you learned that: PeopleSoft Integration Broker supports four types of messaging transactions: Outbound transactions can send messages either asynchronously or synchronously; and inbound transactions can receive messages either asynchronously or synchronously. You populate messages using the PeopleCode Rowset and Message classes. You publish synchronous messages using the Publish method. To receive a message asynchronously, create an entry in the Message Subscriptions section of the Message Structure view, and enter PeopleCode into its associated subscription PeopleCode event.

Slide 234 ______________________________________________________________________________________________________

352

PeopleSoft Proprietary and Confidential

Lesson 13

Sending and Receiving Messages

Review (continued)
In this lesson, you learned that: Subscription PeopleCode can be tested in PeopleSoft Application Designer by creating a test message and running the subscription PeopleCode. For synchronous transactions, create a response record, response message, and message OnRequest PeopleCode to receive the message and send a response back to the sender. You assign transactions to nodes on the Node Definitions page. You handle explicit message routing through either OnRouteSend or OnRouteReceive PeopleCode.

Slide 235 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

353

Sending and Receiving Messages

Lesson 13

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

354

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor


Objectives
By the end of this lesson, you will be able to: Describe Integration Broker Monitor. Describe asynchronous message flow. List the message statuses. Use Integration Broker Monitor. View messaging system performance statistics. Archive messages. Perform error notification.

Slide 237 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

355

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Describing Integration Broker Monitor


System administrators use the Integration Broker Monitor tool to monitor message transaction information. Integration Broker Monitor provides: Status information on channels, nodes, and individual messages. Access to view and, depending on the message status, edit message XML. The ability to control and administer all domains that have publish and subscribe servers running against the current database. Statistics on messaging performance. Queries that enable you to gather information about messaging system metadata. Error notification. Archiving.

Slide 238 ______________________________________________________________________________________________________

Student Notes
See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using Integration Broker Monitor Note. Integration Broker Monitor is designed for system administrators, not for endusers.

Instructor Notes
Performance statistics were added in PeopleTools 8.44.

356

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Describing Integration Broker Monitor (continued)


Integration Broker Monitor provides the status for the following: Message instances Publication contracts Subscription contacts Synchronous messages Channel status Node status Domain status

Slide 239 ______________________________________________________________________________________________________

Student Notes
A tab is available for each status page:

Integration Broker Monitor overview page

Additional Integration Broker Monitor tabs

Instructor Notes
This section discusses how to: Explain message flow. Question: Describe Integration Broker Monitor.

PeopleSoft Proprietary and Confidential

357

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Explaining Message Flow To understand the various statuses displayed in Integration Broker Monitor, it is important for students to understand the flow of messaging. The next few slides trace the flow of messages. The following table lists the PeopleTools tables that are used with messaging:
PeopleTools Table PSAPMSGPUBHDR PSAPMSGPUBDATA PSAPMSGPUBCON PSAPMSGSUBCON PSAPMSGPCONDATA PSAPMSGSCONDATA Description Message header Message data Publication contract header Subscription contract header Publication contract data Publication subscription data

The following table lists the error tables that are used with messaging:
Error Table PSAPMSGPUBERR PSAPMSGPUBERRP PSAPMSGPUBCERR PSAPMSGPUBCERRP PSAPMSGSUBCERR PSAPMSGSUBCERRP Description

Question: Describing Integration Broker Monitor True or False: Integration Broker Monitor is designed for administrators. 1. True 2. False Answer The answer is 1 (true).

358

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Describing Asynchronous Message Flow


The following diagram depicts outbound asynchronous message flow:
Message Queue Publication Contract Queue

3 Message Broker

1 Broker Dispatcher PSBRKDSP

4 2 Broker Handler PSBRKHND

Publication Contractor Publication Handler PSPUBHND

Publication Dispatcher PSPUBDSP

Integration Gateway 6 Yes Destination Node Available? No Failure

Success

Publication to a remote node


Slide 240 ______________________________________________________________________________________________________

Student Notes
When a message is published, the following steps occur: 1. A business event triggers the message using the &MSG.Publish method. The message arrives into the message queue. The message instance status is New. The dispatcher finds the new message instance and passes it to the handler. 2. The broker handler reads the publication message. The message instance status is Working. The handler runs publication routing rules to see where the message should be delivered. The handler runs subscription routing rules to see if the message should be processed locally.

PeopleSoft Proprietary and Confidential

359

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

3. Since remote node delivery is indicated, the broker handler performs these tasks: a. Creates a publication contract for the publication contractor to handle. b. Sends an asynchronous call to notify the publication contractor that it has work to do. 4. The publication contractor reads the contract and sets the following status values: a. It sets the publication contract status to New. b. It sets the message instance status to Done. The publication contractor notifies its handler to perform an HTTP post of the publication message to the integration gateway.The integration gateway sends a publication message to the remote node. If the remote node is PeopleSoft, the message is sent with a synchronous call via BEA Jolt into the PSAPPSRV server in the application server domain. If the destination node is available, the following tasks are performed: a. The publication contract status is set to Working. b. PSAPPSRV returns the delivery status for the message to the remote node. This status is sent back to the publication contractor on the originating node via the gateway. c. The publication contract status is set to Done. If the destination node is not available, publication contract status is set to Retry. The number of retry attempts is configurable for the publication handler on the application server. Once this number of retry attempts is reached, the publication contract status is set to Timeout.

360

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Describing Asynchronous Message Flow (continued)


The following diagram depicts inbound asynchronous message flow:
Integration Gateway Subscription Contractor

Integration Broker

Subscription Contract Queue

Subscription Dispatcher PSSUBDSP

Subscription Handler PSSUBHND

Message Queue

6 3

Message Broker

Subscription PeopleCode Program(s)

Broker Dispatcher PSBRKDSP

Broker Handler PSBRKHND Application Data Tables

Subscription process flow


Slide 241 ______________________________________________________________________________________________________

Student Notes
When a message is received, the following steps occur: 1. The message arrives via the integration gateway. PSAPPSRV creates a publication message to be handled locally. The message instance status is New. 2. The publication broker handler creates the subscription contract for the subcontractor to handle. The message instance status is Working. 3. The publication broker handler sends an asynchronous call to notify the subcontractor that it has work to do. 4. The subscription contractor dispatcher reads the subscription contract and performs these tasks:

PeopleSoft Proprietary and Confidential

361

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

a. Sets the subscription contract status to New. b. Sets the message instance status to Done. 5. The subscription contractor starts working on the subscription and sets the subscription contrast status to Started. 6. The subscription contractor notifies its handler to run the subscription PeopleCode for it. The contractor sets the subscription contract status to Working. Each PeopleCode program attempts to update the application data tables. If the application update is successful, subscription contract status is set to Done. If the application update is unsuccessful, subscription contract status is set to Error.

Instructor Notes
This section presents a review question for the current objective. Question: Describing Asynchronous Message Flow If a message has successfully been published to a node, the message has the following status. 1. The message instance is New. 2. The publication contact is New. 3. The publication contact is Done. 4. The message instance is Done. Answer The answer is 3 (Publication Contract is Done ).

362

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Listing the Message Statuses


The following table presents the possible status messages that you may encounter using Integration Broker Monitor:
Status Error New Started Working Done Cancelled Description An error occurred during processing. Manual intervention is required. Either the item has been written to the queue, but has not been dispatched yet, or the item has just been resubmitted. The dispatcher is in the process of passing the item to a handler, but the handler has not received it yet. The handler has accepted the item and is currently processing it. The handler successfully processed the item. The item has been canceled. The system can't process the item until you resubmit.

Slide 242 ______________________________________________________________________________________________________

Student Notes
Depending on the type of process you are monitoring, the Done status indicates these different outcomes: For the message instance, all contracts have been created. For publication contracts, the publication has been successfully received by the subscribing node. For subscription contracts, the subscription process ran successfully.

PeopleSoft Proprietary and Confidential

363

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Listing the Message Statuses (continued)


The following table presents the possible status messages that you may encounter using Integration Broker Monitor:
Status Retry Timeout Description For asynchronous messages only, the system encountered an intermittent error during processing. The system retries messages with this status automatically. After a certain number of retries, as determined by the application server domain configuration, the publication contractor was unable to connect to the target system. Manual intervention is required. The publication data for the item has been edited. Processing does not resume until you resubmit the item. The item has been canceled. The system can't process the item until you resubmit.

Edited Cancelled

Slide 243 ______________________________________________________________________________________________________

Instructor Notes
This section presents a review question for the current objective. Question: Listing the Message Statuses An edited message needs to be resubmitted. 1. True 2. False Answer The answer is 1 (true).

364

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Using Integration Broker Monitor


Use Message Monitor Overview page to view: A high-level overview of the messages. The number of messages in each status. Additional details through drill down.

You can sort messages by channel or status, and filter to limit the data thats displayed. Click Refresh to update the current display.
Slide 244 ______________________________________________________________________________________________________

Student Notes
Use the Monitor Message Overview page to view message information.
Page Name Monitor Message Navigation PeopleTools, Integration Broker, Monitor, Monitor Message

Monitor Message Overview page

PeopleSoft Proprietary and Confidential

365

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Using Integration Broker Monitor (continued)


You can filter data on most Integration Broker Monitor pages. Filter options appear at the top of the page and include these basic options: Publish nodes. Last (to indicate time interval). Archived.

Each page has additional filters available.


Slide 245 ______________________________________________________________________________________________________

Student Notes
Note. After changing the filter, click Refresh to see the filtered data.

Instructor Notes
Because Integration Broker Monitor provides information from every aspect of the messaging system, students need to understand how to filter the information to reduce the number of items to view.

366

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Using Integration Broker Monitor (continued)


The Message Instances page displays : Every publication and subscription contract associated with a message instance. Details for each message instance, through a details link. All messages in the subchannel in the order in which they will be processed, through a subchannel link.

You can use this page to resubmit or cancel messages.


Slide 246 ______________________________________________________________________________________________________

Student Notes
Use the Message Instances page to view message information.
Page Name Message Instances Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Message Instances

Message Instances page The pictured page shows one new message. This message is in the New status because the channel is paused.

Instructor Notes
There have been some additions in PeopleTools 8.44. For selected messages, you can either resubmit or cancel the message from this page. The sub Channel link will let you see what is in the channel.

PeopleSoft Proprietary and Confidential

367

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Using Integration Broker Monitor (continued)


Click the Details link on the Message Instances page to access three details pages. The Message Properties page provides: Message information, including timestamp, publisher, and status. The ability to resubmit, cancel, or archive a message depending on its current status. A link to view the original XML. Publication contract information. Subscription contract information.

Slide 247 ______________________________________________________________________________________________________

Student Notes
Use the Message Properties page to view message details.
Page Name Message Properties Navigation Click the Details link on the Message Instances page.

Message Properties page Since the message in this example has a status of New, no publication or subscription contract has been created.

368

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Using Integration Broker Monitor (continued)


Use the Message Errors page to view information on any message with a status of Error. A link is provided to correct the XML. After correcting errors, messages can be resubmitted. Use the XML Viewer page to view and edit XML.
Slide 248 ______________________________________________________________________________________________________

Student Notes
Use the Message Errors page to view reasons for errors:
Page Name Message Errors Navigation Click the Details link on the Message Instances page. Select Message Errors.

Message Errors page

PeopleSoft Proprietary and Confidential

369

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Using Integration Broker Monitor (continued)


Contracts are created based on the type of transaction: Outbound messages create publication contracts. Inbound messages create subscription contracts.

Slide 249 ______________________________________________________________________________________________________

Student Notes
Use these pages to view contract information:
Page Name Pub Contracts Sub Contracts Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Pub Contracts PeopleTools, Integration Broker, Monitor, Monitor Message, Sub Contracts

Use the Pub Contracts page to view publication contracts:

Pub Contracts page Use the Sub Contracts page to view subscription contracts:

370

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Sub Contracts page

Note. The system does not create publication contracts for routing to the local node.

PeopleSoft Proprietary and Confidential

371

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Using Integration Broker Monitor (continued)


Use the Synchronous Messages page to view a log of synchronous messages. For synchronous messages with errors, the message fails. A unique identifier is assigned to each synchronous message.
Slide 250 ______________________________________________________________________________________________________

Student Notes
Use the Synchronous Messages page to view synchronous message information.
Page Name Synchronous Messages Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Synchronous Messages

Synchronous Messages page Synchronous transactions only appear in Integration Broker Monitor if the synchronous logging level has been set for the transaction in the node definition.

372

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Using Integration Broker Monitor (continued)


The Channel Status page displays the status of the channels defined in the local node. A channel has two states: Running and Paused. Pausing a channel prevents messages from being processed on that channel. Certain channels are delivered from PeopleSoft as Paused.
Slide 251 ______________________________________________________________________________________________________

Student Notes
Use the Channel Status page to run and pause channels:
Page Name Channel Status Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Channel Status

Channel Status page

Instructor Notes
Make sure that students understand the following: If you notice a backup within a particular channel, check the Channel Status page to make sure the channel is running. The button to the right of the status value reflects the opposite status value. To pause a running channel or to start a paused channel, click the button that corresponds to the channel name.

PeopleSoft Proprietary and Confidential

373

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Using Integration Broker Monitor (continued)


Use the Node Status page to: View the pause times for the local node. Add a pause time for the local node. Delete an existing pause time for the local node. Test the local node. Ping a remote node.

Slide 252 ______________________________________________________________________________________________________

Student Notes
Use the Node Status page to set node pause times and test nodes:
Page Name Node Status Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Node Status

Node Status page

Instructor Notes
This section discusses how to: Pause nodes. Schedule pause times. Ping nodes. Test Node

374

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Pausing Nodes
You might schedule a pause time so that you can perform regular maintenance tasks or devote server resources to an important batch run. For example, say that you have a complex batch program that runs on the same server machine as a particular message node every Monday morning from 12:05 a.m. to 3:30 a.m. To make sure that the batch program has enough memory devoted to it, you can set a pause time for the message node that runs from 12:00 a.m. to 4:00 a.m. A pause time like this enables you to make sure batch run has ample system resources to complete successfully within the batch window. During a pause time, messages arent published or received by the local system. The node can't accept the message sent to it, and the publishing node must attempt to send the message again later. The publishing node continues to send the message until it exceeds the local timeout period. When this happens, the message assumes Timeout status in the publishers message queue. The timeout period is an attribute of the publication channel, not the subscription channel.

Scheduling Pause Times


When a pause time begins, the messaging node is effectively shut down until the pause time is scheduled to end. If your system attempts to send a message while the message node is paused, the system writes the message to the publish and subscribe queues, but the system cant physically publish the message until the system is no longer in the paused state.

Pinging Nodes
To check to see if a remote node is currently running and able to receive messages from the local node, you ping the remote node from the Node Status page. A successful ping indicates that the remote node is currently available. An unsuccessful ping could indicate that the node or the gateway are not running. Testing the Local Node The Test node button will test that the local node is active.

PeopleSoft Proprietary and Confidential

375

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Using Integration Broker Monitor (continued)


The Domain Status page features three sections: The Domain Criteria section enables you to perform actions on all domains on the messaging system. The Domain Status section provides application server name and path information for all machines that have domains on the messaging system. The Dispatcher Status section displays information about machines in the messaging system that have dispatcher processes associated with them.

Slide 253 ______________________________________________________________________________________________________

Student Notes
Use the Domain Status page to view domain information and perform actions on domains:
Page Name Domain Status Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Domain Status

Domain Status page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using Integration Broker Monitor

Instructor Notes
The Domain Status page enables you to view the domains that have publish and subscribe servers on them running against your database.

376

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Grace periods allow processing on a domain to finish before you pause processing or take a domain down. If a machine with a domain crashes, the messaging system may still expect processes on the domain are still working in the runtime tables. If you make the domain inactive, other publish and subscribe servers can complete the processing, thus enabling you to recover from domain and machine crashes. With domain failover, PeopleSoft Integration Broker continues processing message requests and responses even if it incurs errors or other problems in the primary domain. Use the Setup Failover link to configure failover. Note. If your messages are staying in New status, check that the domain is active. You activate domains on this page.

PeopleSoft Proprietary and Confidential

377

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Using Integration Broker Monitor (continued)


Use the Queries page to gather information about messaging system metadata, including: Request message transactions. Response message transactions. Message status at node. Messages that belong to a channel. Channels and messages at a node. Channels to archive or purge messages.

Slide 254 ______________________________________________________________________________________________________

Student Notes
Use the Queries page to view domain information and perform actions on domains:
Page Name Queries Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Queries

Instructor Notes
This section discusses how to: Explaining Queries Keeping track of definitions and routings can become an unwieldy task. With the Queries page, you can gather information about messaging system metadata without having to access message definitions, channel definitions in PeopleSoft Application Designer, or node definitions in PeopleSoft Internet Architecture. These queries are not intended to be run every day or even on a regular basis. You might find that they are most useful for providing auditing information shortly after an implementation or upgrade. Question: Using Integration Broker Monitor After changing the filter on a page in Integration Broker Monitor, you need to click. 1. Update. 2. Resubmit. Explain queries. Question: Using Integration Broker Monitor.

378

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

3. Refresh. 4. Cancel. Answer The answer is 3 (Refresh).

PeopleSoft Proprietary and Confidential

379

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Activity 18:

Monitoring Messages
In this activity, you will review the activity overview and: 1. Publish messages. 2. Review Integration Broker Monitor information. 3. Create a message containing an error. 4. Correct the message in error. See Integration Tools: Activity Guide, lesson 14, Monitoring Messaging System Performance Using Integration Broker Monitor, Activity 18: Monitoring Messages.

Slide 255 ______________________________________________________________________________________________________

Instructor Notes
When introducing this activity, review the following with the class: Diagnosing problems with messages. Publishing to PSFT_EP. Inactivating a message. Optionally viewing at statistics. Correcting the Error.

Note. This activity should take approximately thirty minutes. Diagnosing Problems In this activity, the message will all be in a NEW status. In Step 9 under Reviewing Integration Broker Monitor Information students need to diagnosis the problem. Their domain will be inactive and remember the SCHOOL_CHNL is paused. Tell students when they get to step 9 that they will need to find the problem and correct it before their messages will be sent. Students will need to: Set the status of the SCHOOL_CHNL to run. Activate the Domain. Cancel the Edited SCHOOL_SYNC message.

380

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Publishing to PSFT_EP As delivered, the FSCM 8.8 database has several domains that will display. You need to click Purge Domain Status and then activate the domain before any messages will be received. The ENTERPRISE_SETUP channel as delivered is Paused, so you will need to change the status to Run. If you want students to navigate to the locations page, so they can see all of the locations that were received, use Set Up Financials/Supply Chain, Common Definitions, Location, Location. If you view the message monitor Sub Contracts page, you will see two subscription PeopleCode programs are run depending on the transaction (inserting a new effectivedated row or doing an add or correct history, only one is actually updating the database). Inactivating a Message In the section for Creating a Message Containing an Error, we do not want the error sent to the Financials database, so students will need to inactivate the outbound asynchronous message to PSFT_EP. Viewing Statistics You may wish to have students view the statistics pages when they have completed this activity. Students will still be in the Message Monitor at the end of the activity, so they may want to just follow along as you review performance statistics. Correcting the Error The message LOCATION_SYNC has two subscription PeopleCode programs LocationSync and LocationSyncCI. LocationSyncCI has been set to active and LocationSync to inactive. The message will error with either version of the subscription PeopleCode, but the error will only be visible in the monitor if the CI version is used.

Activity Overview
In this activity, you will: 1. Publish messages. Create a new school and a new location. Name the school and location with the letter T followed by your workstation. (For example, T01.) These messages should get published. Subscribe to the SCHOOL_SYNC message to receive messages from your neighbor. 2. Review the Integration Broker Monitor information. In the last lesson, you created and edited a message for SCHOOL_SYNC, you will need to cancel this message. 3. Create a message containing an error.

PeopleSoft Proprietary and Confidential

381

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

To create a message containing an error, pause the message channel, publish a message, edit the XML for the message to contain some invalid data, set the message channel to run, and then resubmit the message, 4. Correct the message in error. The subscription PeopleCode will detect the error and set the subscription contact status to Error. Correct the error and resubmit.

Publishing Messages
To publish messages: 1. Select Set Up Training, Common Definitions, School Details. 2. Create a new school. 3. Enter the following information:
Page Element Country School Code State Description Public/Private Value or Status Your home country The letter T followed by your workstation (for example, T01). Your home state Test from ws xx Public

4. Save the page. 5. Select Locations, Location. 6. Select the Add a New Value tab. 7. Add a new location using the SetID SHARE and the location Txx where xx is your workstation number. 8. Fill in all the required fields. 9. Save the page.

Reviewing Integration Broker Monitor Information


To review Integration Broker Monitor information: 1. Select PeopleTools, Integration Broker, Monitor, Monitor Message. 2. Set the filter on the Overview page to view all messages for the last two days. 3. Click Refresh. 4. Access the Message Instances page. 5. Click Refresh.

382

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

6. Click the check box for the original edited SCHOOL_SYNC message. 7. Click Cancel Message. 8. Click OK. 9. If there are any messages that are still in New status, this indicates a problem. 10. To examine the problem : a. Access the Channel Status page. Ensure that the ENTERPRISE_SETUP and SCHOOL_CHNL channels are running. b. Access the Node Status page. Ensure that your node is active. c. Try pinging the remote node. d. Access the Domain Status page. Your application server should have a status of Active. If the status is not Active, then change it to Active and click Update. 11. Access the Message Instances page and set the filter to view all messages for the last two days. 12. Click Refresh. 13. Access the Pub Contracts page. 14. Click Details for the SCHOOL_SYNC message. 15. Review the XML for SCHOOL_SYNC message. 16. Close the details window. 17. Access the Sub Contracts page. 18. Click Details for the SCHOOL_SYNC message. 19. Review the page. 20. Close the details window.

Creating a Message Containing an Error


To create a message containing an error: 1. Select PeopleTools, Integration Broker, Node Definition. 2. Open the node definition for PSFT_EP. 3. Select the Transactions page.

PeopleSoft Proprietary and Confidential

383

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

4. Inactivate the LOCATION_SYNC message by selecting Edit and changing the status to inactive. 5. Save the node definition. 6. Select PeopleTools, Integration Broker, Monitor, Message Monitor. 7. Access the Channel Status page. 8. Click Pause for ENTERPRISE_SETUP to pause the channel. 9. Select Set Up Training, Common Definitions, Locations, Location. 10. Add a new location with the following information:
Page Element SetID Location Code Description Value or Status SHARE The letter E followed by your workstation (for example, E01). Test errors

11. Select PeopleTools, Integration Broker, Monitor, Monitor Message. 12. Access the Message Instances page. 13. Click Refresh. Your message should be displayed with a status of New. 14. Click Details. 15. Access the XML Viewer page. 16. Click Edit XML. 17. Change the field value for EFF_STATUS from A to X. 18. Click OK. 19. Save. 20. Close the details window. 21. Click Refresh. The status is now Edited. 22. Access the Channel Status page. 23. Click Run for the ENTERPRISE_SETUP channel. 24. Select the Message Instance page. 25. Select your edited message and click Resubmit.

384

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

26. Click Refresh. When the status is Done, the message has been sent to your neighbor. Meanwhile, your neighbor has been creating an erroneous message and sending it to you. Results Your neighbor will receive the following error:

Subscription contract error

Correcting the Message in Error


To correct the message in error: 1. Access the Sub Contracts page. 2. Click Details for the LOCATION_SYNC message in error. 3. Select the Message Errors tab. 4. Review the error message. 5. Select the Message Properties tab. 6. Select Edit_XML. 7. Correct the error by changing the EFF_STATUS back to A. 8. Click OK. 9. Click Resubmit from the Message Properties page. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

385

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Viewing Message System Performance Statistics


Use the Statistics page to select runtime performance data for messaging: To collect application server data, the PeopleSoft Integration Broker profile must be set to Y in the application server. To collect integration gateway data, the profile information for PeopleSoft Integration Broker must be set to True. You can only view performance statistics for the local system.
Slide 256 ______________________________________________________________________________________________________

Student Notes
Use the Statistics page to view performance data:
Page Name Statistics Navigation PeopleTools, Integration Broker, Monitor, Monitor Message, Statistics

Statistics page

Instructor Notes
Point out the various options on the page. For asynchronous transactions, statistics are captured for the flow of messages through the following pub/sub components:

386

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Asynchronous Pub/Sub Component Inbound Asynchronous Post

Description Includes posting messages to the integration gateway, as well as posting messages to the application server and putting them in the queue. Takes all messages put into the queue and determines the transaction type. Based on the transaction type, creates a subscription contract, publication contract or both. Runs PeopleCode associated with message. Routes the message to another destination.

Broker Handler

Subscription Contract Handler Publication Contract Handler

For synchronous transactions:


Synchronous Transaction Type Inbound Synchronous Description Inbound messages from PeopleSoft and nonPeopleSoft systems. The sending system requires a response from the receiving PeopleSoft system before additional processing occurs. Outbound messages from PeopleSoft and nonPeopleSoft systems. The sending system requires a response from the receiving system before additional processing occurs A local PeopleSoft system that sends inbound and outbound messages to itself. This scenario is typically used for testing purposes.

Outbound Synchronous

Local Synchronous

For asynchronous transactions, you can capture statistics about the performance of the remote PeopleSoft system without any setup in the integrationGateway.properties or PSADMIN. The sending PeopleSoft system includes an identifier in the message request that prompts the remote PeopleSoft system for performance information. This information is part of the response message.

PeopleSoft Proprietary and Confidential

387

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Viewing Message System Performance Statistics (continued)


To enable the message system performance statistics feature on the application server: 1. Access PSADMIN. 2. Select 1. Application Server. 3. Select 1. Administer a Domain. 4. Select the domain. 5. Select 4) configure this domain. 6. Select Y to shut down the domain.
Slide 257 ______________________________________________________________________________________________________

Instructor Notes
IB profile has already been set to Y in the classroom environment. The instructions are here so students know how to turn on statistics for the application server, but they do not need to do this.

388

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Viewing Message System Performance Statistics (continued)


To enable the message system performance statistics feature on the application server (continued): 7. Select 12) Custom Configuration. 8. Select Y to change any config values. 9. Press ENTER to move through the list of options and accept all existing values until you locate the following section: Values for Config Section Integration Broker. 10. Change the IB PROFILE Information setting to Y. 11. Press ENTER to finish moving through the remaining lists of options. When you are finished, PSADMIN loads the new configuration. 12. Boot the domain.
Slide 258 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

389

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Viewing Message System Performance Statistics (continued)


To enable the statistics feature on the integration gateway: 1. Access the integrationGateway.properties file. 2. Locate the Profile Information section at the end of the file. 3. Set the ig.ProfileInformation property to True. 4. Save the file. 5. Refresh the integration gateway.
Slide 259 ______________________________________________________________________________________________________

Student Notes
Use the Gateways page to access the integrationGateway.properties file:
Page Name Gateway Properties Navigation PeopleTools, Integration Broker, Gateways, LOCAL, Properties, signon (default UserId is administrator, default password is password)

ProfileInformation set to true

390

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Instructor Notes
Profile information has already been set to TRUE in the classroom environment. The instructions are here so students know how to turn on statistics for the web server, but they do not need to do this.

PeopleSoft Proprietary and Confidential

391

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Viewing Message System Performance Statistics (continued)


Statistics display in numeric format on tabbed pages: Depending on the respective messaging runtime performance data selected various tabs are available. All timing are shown in milliseconds.

Slide 260 ______________________________________________________________________________________________________

Student Notes
This page shows an example of statistics for the publication contract handler.

Publication Contract Handler gateway statistics

Instructor Notes
In this course we are not going to cover how to tune the Integration Broker. The main purpose for showing this is to point out that if there are bottlenecks, you can identify where the problems is. See PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Configuring the Messaging System for more information on configuring servers, dedicated servers, queues and so forth.

392

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Viewing Message System Performance Statistics (continued)


You can choose to view the statistics in either: Bar chart Pie chart

Note. Data displayed in a bar chart and pie chart formats are averages.
Slide 261 ______________________________________________________________________________________________________

Student Notes
The following example shows a pie chart for publication contract handler:

Pie chart for publication contract handler See PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using Integration Broker Monitor.

Instructor Notes
This section presents a review question for the current objective. Question: Viewing Messaging System Performance Statistics Performance statistics are only for the local system.

PeopleSoft Proprietary and Confidential

393

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

1. True 2. False Answer The answer is 1 (true).

394

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Archiving Messages
A batch process is available to archive messages. Messages can be archived based on: Status: Done or Canceled. Number of days. All messages.

Slide 262 ______________________________________________________________________________________________________

Student Notes
Use the Run Archive page to run a process to archive messages:
Page Name Run Archive Navigation PeopleTools, Integration Broker, Monitor, Archive Messages

Run Archive page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using Integration Broker Monitor

Note. The batch process can be set up to run as a recurring process on PeopleSoft Process Scheduler.

PeopleSoft Proprietary and Confidential

395

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Instructor Notes
This section presents a review question for the current objective. Question: Archiving Messages You can set criteria for archiving messages. 1. True 2. False Answer The answer is 1 (true).

396

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Performing Error Notification


The batch error notification process uses workflow to notify the messaging administrator of errors. To enable error notification: Grant access to the PT_AMM_DUMMY component interface. Assign users to the role APP_MSG_ADMINISTRATOR. Add email addresses for users assigned to APP_MSG_ADMINISTRATOR role.

Slide 263 ______________________________________________________________________________________________________

Student Notes
Use the Error Notification page to run batch error notification:
Page Name Error Notification Navigation PeopleTools, Integration Broker, Monitor, Error Notification

Error Notification page

Instructor Notes
The Application Engine batch program PT_AMM_WF can be scheduled to run on a recurring basis. Email addresses are added to the user in the user profile. The role is added to the user in the user profile. We do not have an activity that will use this in class. The process scheduler has not been tested with this class, so it may not be configured properly in the classroom. Email has not been setup in the classroom either. Question: Running Batch Error Notification Process Error notification uses workflow.

PeopleSoft Proprietary and Confidential

397

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

1. True 2. False Answer The answer is 1 (true).

398

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

Activity 19:

Sending and Receiving Messages


In this activity, you will review the activity overview and create and test a new message. See Integration Tools: Activity Guide, lesson 14, Monitoring Messaging System Performance Using Integration Broker Monitor, Activity 19: Sending and Receiving Messages .

Slide 264 ______________________________________________________________________________________________________

Instructor Notes
This activity combines everything from lessons 9 through 14. Note. This activity should take approximately 30 minutes.

Activity Overview
In this activity, you will create and test a new asynchronous message. PSU_COURSE_TBL contains the course information. Create an asynchronous message to send to your neighbors database whenever a course is added or updated.
Task Define the message channel. Define the messages. Add subscription PeopleCode. Add publish PeopleCode to PSU_COURSE_TBL. Grant permission to view the COURSE_CHNL channel. Define transactions for the nodes. Definition COURSE_CHNL COURSE_SYNC Add or update courses SavePostChange ALLPAGES Publish to your neighbors node Subscribe to your neighbors node Test the message by selecting Courses, Define, Course Definition. Add a new course

Validate the results in the Integration Broker Monitor. If you run into any problems with the messages, reference Appendix B Integration Broker Troubleshooting Guide.

Creating and Testing a New Message


To create and test a new message: 1. Create a new message channel COURSE_CHNL. 2. Create a new message COURSE_SYNC.

PeopleSoft Proprietary and Confidential

399

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

a. Insert child record PSU_COURSE_TBL. b. Associate the message with the COURSE_CHNL channel. c. Save the message. 3. Insert the subscription PeopleCode CourseSync. Note. A copy of the subscription PeopleCode is available in \1022_IntTools\scripts\course_subscription_pc.txt. 4. Add the following publish PeopleCode to the record PSU_COURSE_TBL for the field COURSE in SavePostChange.
Local Message &MSG; If ActiveRowCount() = CurrentRowNumber() Then &MSG = CreateMessage(Message.COURSE_SYNC); If &MSG.IsActive Then &MSG.CopyRowsetDelta(GetRowset()); &MSG.Publish(); End-If; End-If;

Note. PSU_COURSE_TBL is effective-dated, so make sure the publish only triggers once (on the last active row at level one). 5. Grant access to view the message channel COURSE_CHNL on the permission list ALLPAGES. 6. Add an outbound asynchronous transaction and an inbound asynchronous transaction for COURSE_SYNC to your neighbors node definition. 7. Select Courses, Define, Course Definition. 8. Add a new value with the following information:
Page Element COURSE Effective Date Status Course Description Length (Days) Units Curriculum Developer Value or Status Your initials 01/01/2003 Active Your name and an apostrophe S, followed by the word Course. 1 1 CDF

9. Validate the results in Integration Broker Monitor.

400

PeopleSoft Proprietary and Confidential

Lesson 14

Monitoring Messaging System Performance Using Integration Broker Monitor

If you run into any problems with the messages see Integration Tools: Student Guide, appendix B, Integration Broker Troubleshooting Guide. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

401

Monitoring Messaging System Performance Using Integration Broker Monitor

Lesson 14

Review
In this lesson, you learned that: System administrators use Integration Broker Monitor to monitor asynchronous and synchronous message transactions, status information, and other integration engine data. Asynchronous outbound messages create a publication contract, and inbound asynchronous messages create subscription contracts. Administrators use message status to track asynchronous message flow. You use Integration Broker Monitor to track the status of messages, channels, nodes and domains. Message performance statistics can be collected for application servers and web servers. The statistics can appear in Integration Broker Monitor. PeopleSoft provides a batch process for archiving messages. PeopleSoft provides a batch process for error notification.

Slide 265 ______________________________________________________________________________________________________

402

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations
Objectives
By the end of this lesson, you will be able to: Describe transform programs. Develop a transformation program. Write the XSLT to transform a message. Test transform programs. Transform a message to a SOAP request.

Slide 267 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

403

Applying Transformations

Lesson 15

Describing Transform Programs


Transform programs are used to do any of the following: Change the structure of a message to comply with the target system's requirements. Perform a data translation on a message according to the target system's conventions. Determine whether to pass a message through to its target, by filtering it based on its content.

Slide 268 ______________________________________________________________________________________________________

Instructor Notes
In order to process messages, the Integration Broker expects the message to comply with the PeopleSoft base message format. When exchanging messages with vendors, customers and other third party applications, there will be inherent differences in the messages. Application Engine transform programs are used to apply transformation, data translation and filtering on either inbound or outbound messages. In this lesson, we will concentrate on transforming messages, in lesson 17 Applying Translation and Filtering we will concentrate on translations and filtering.

404

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Describing Transform Programs (continued)


A transformation is applied to a message to make its structure comply with the target systems requirements. This diagram shows a message transformed from message A to message B:

Sending Node Msg A Transform Program

Receiving Node Msg B

Transformations change the structure of the message


Slide 269 ______________________________________________________________________________________________________

Student Notes
Transformation examples include: Change the record structure of the message. PeopleSoft generated messages are in a structured XML format the receiving system may be expecting something entirely different that is in an unstructured XML format. The message name and fields may have a different structure in the receiving node. The outbound message may be asynchronous and the receiving system expects a synchronous message.

PeopleSoft Proprietary and Confidential

405

Applying Transformations

Lesson 15

Describing Transform Programs (continued)


Transform programs are invoked by Integration Broker when a transaction modifier has been defined for the transaction. Transaction modifiers can be associated with: Outbound transactions (message is transformed before it is sent). Inbound transactions (message is received and then transformed).

Slide 270 ______________________________________________________________________________________________________

Instructor Notes
Transaction modifiers will be discussed later in this lesson.

406

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Describing Transform Programs (continued)


Transform programs are written in Application Engine: The program type is Transform Only. The action type can be either PeopleCode or Extensible Stylesheet Language Transformation (XSLT). Each transform program step operates on the message content that results from the previous step, so you can break your transform program into a sequence of discrete steps. XSLT works only on XML DOM compliant data.

Slide 271 ______________________________________________________________________________________________________

Student Notes
Note. Multiple transform actions within a step can produce unwanted effects, so be sure to insert each XSLT or PeopleCode action in its own step. See PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Applying Filtering, Transformation and Translation

Instructor Notes
XSLT works only on XML DOM compliant data, so Integration Broker assures that both outbound and inbound messages are in XML DOM compliant form when transform programs are applied to them.

PeopleSoft Proprietary and Confidential

407

Applying Transformations

Lesson 15

Describing Transform Programs (continued)


Keep the following guidelines in mind when deciding which language to use: XSLT is a well-recognized standard language perfectly suited to manipulating XML structures, so it's highly recommended for implementing transformations. XSLT is highly recommended for data translation. Currently, the ability to filter messages based on content is not available through XSLT, so filtering must be implemented in PeopleCode. You can use both XSLT and PeopleCode steps in a single transform program.

Slide 272 ______________________________________________________________________________________________________

Instructor Notes
Question: Describing Transform Programs Transform programs are used for: 1. Transformations. 2. Data Translations. 3. Filtering based on content. 4. All of the above. Answer The answer is 4 (all of the above).

408

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Developing Transformation Programs


To develop a transformation program, you must know: The initial structure (and possibly content) of the message. The resulting structure (and possibly content) of the message.

Slide 273 ______________________________________________________________________________________________________

Student Notes
Note. All participating nodes must agree on a format or employ transformations to accommodate the variations.

PeopleSoft Proprietary and Confidential

409

Applying Transformations

Lesson 15

Developing Transformation Programs (continued)


The following diagram shows how the transform program reads the inbound message and reformats the outbound message:
Source message <PSU_PO_HDR class="R"> <BUSINESS_UNIT IsChanged="Y">NAM01</BUSINESS_UNIT> <ORDER_NBR IsChanged="Y">00000038</ORDER_NBR> <ORDER_DT IsChanged="Y">2003-10-09</ORDER_DT> <VENDOR_CD IsChanged="Y">ALPH04</VENDOR_CD>

TRANSFORM PROGRAM
<xsl:template match="PSU_PO_HDR"> <SDK_RP_PO>xsl:attribute name="class"><xsl:value-of select="@class" /></xsl:attribute> <SDK_RP_PO_NUMBER> TR<xsl:value-of select="ORDER_NBR" /></SDK_RP_PO_NUMBER> <SDK_RP_PODATE> <xsl:value-of select="ORDER_DT" /></SDK_RP_PODATE> <SDK_RP_SITENAME> <xsl:value-of select="BUSINESS_UNIT" /></SDK_RP_SITENAME> <SDK_RP_VENDORNAME><xsl:value-of select="VENDOR_CD" /></SDK_RP_VENDORNAME>

Result message <SDK_RP_PO class="R"> <SDK_RP_PO_NUMBER>TR00000038</SDK_RP_PO_NUMBER> <SDK_RP_PODATE>2003-10-09</SDK_RP_PODATE> <SDK_RP_SITENAME>NAM01</SDK_RP_SITENAME> <SDK_RP_VENDORNAME>ALPH04</SDK_RP_VENDORNAME>

Transformation program creates a new message


Slide 274 ______________________________________________________________________________________________________

Student Notes
In the example displayed in the diagram, the sending node uses the record PSU_PO_HDR and the receiving node is expecting the record SDK_RP_PO. The table below shows the relationship:
Sending Node (Source tree) PO_SYNC (message) PSU_PO_HDR (record) BUSINESS UNIT (field) ORDER_NBR (field) ORDER_DT (field) VENDOR_CD (field) Receiving Node (Resulting tree) SDK_PO_SYNC (message) SDK_RP_PO (record) SDK_RP_SITENAME (field) SDK_RP_PO_NUMBER (field) SDK_RP_PODATE (field) SDK_RP_VENDORNAME (field)

410

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Note. This is only a section of the entire message.

Instructor Notes
Review the message format basics learned in lesson 12 Describing the PeopleSoft Message Format: The <fieldtypes> section of the PeopleSoft structured message is used to describe the message structure. PO_SYNC message (reviewed in activity 20) has the following structure: PSU_PO_HDR (parent) PSU_PO_DTL (child) The receiving node will not be able to process the message because the fields do not match. You could create the message with aliases for the records and fields. In the transaction, an external name could be used for the message. However, you may also use this same message with another system that has the same format or another entirely different format. By creating a transformation program it will only apply to the nodes you later specify in the relationship.

PeopleSoft Proprietary and Confidential

411

Applying Transformations

Lesson 15

Developing Transformation Programs (continued)


The source message is the source tree. Each XML tag is a node in the tree. The root node is the message name. The nodes of the source message are shown below:
<PO_SYNC> <FieldTypes> <PSU_PO_HDR> <PSU_PO_DTL> <PSCAMA> <MsgData> <Transaction> <PSU_PO_HDR class="R"> <PSU_PO_DTL class="R"> <PSCAMA class="R"> <PSCAMA class="R">

Slide 275 ______________________________________________________________________________________________________

Instructor Notes
The source message would have the following format:
<?xml version="1.0"?> <PO_SYNC> <FieldTypes> <PSU_PO_HDR class="R"> <BUSINESS_UNIT type="CHAR"/> <ORDER_NBR type="CHAR"/>

Additional records and fields


</FieldTypes> <MsgData> <Transaction> <PSU_PO_HDR class="R"> <BUSINESS_UNIT IsChanged="Y">NAM02</BUSINESS_UNIT> <ORDER_NBR IsChanged="Y">00000039</ORDER_NBR> <ORDER_DT IsChanged="Y">2003-10-09</ORDER_DT> <VENDOR_CD IsChanged="Y">ALPH03</VENDOR_CD> <ORDER_STATUS IsChanged="Y">IN</ORDER_STATUS> <STATUS_DT IsChanged="Y">2003-10-09</STATUS_DT> <PSU_PO_DTL class="R"> <BUSINESS_UNIT IsChanged="Y">NAM02</BUSINESS_UNIT> <ORDER_NBR IsChanged="Y">00000039</ORDER_NBR> <ORDER_LINE_NBR IsChanged="Y">1</ORDER_LINE_NBR> <ITEM_CD IsChanged="Y">PSU026</ITEM_CD> <QTY IsChanged="Y">100</QTY>

412

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

<PRICE IsChanged="Y">1</PRICE> </PSU_PO_DTL> <PSCAMA class="R"> <AUDIT_ACTN>A</AUDIT_ACTN> </PSCAMA> </PSU_PO_HDR> <PSCAMA class="R"> <LANGUAGE_CD>ENG</LANGUAGE_CD> <AUDIT_ACTN>A</AUDIT_ACTN> <BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD> <MSG_SEQ_FLG/> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID/> <MSGNODENAME/> </PSCAMA> </Transaction> </MsgData> </PO_SYNC>

Question: Developing Transformation Programs As long as you know the format of the resulting message, you can write the transformation program. 1. True 2. False Answer The answer is 2 (false you need to know the format of both the original and resulting message).

PeopleSoft Proprietary and Confidential

413

Applying Transformations

Lesson 15

Writing the XSLT to Transform a Message


A transformation expressed in XSLT is called a stylesheet. XSLT operates on an XML document as a tree. The stylesheet (xsl) contains a template of rules.

Slide 276 ______________________________________________________________________________________________________

Student Notes
The stylesheet has 2 parts: 1. A pattern that is matched against nodes in the source tree. 2. A template that can be instantiated to form part of the result tree. See Also http://www.w3.org/TR

Instructor Notes
As previously stated, when changing the structure of a message, XSLT is the best method to use. XSLT is a language for transforming XML documents into other XML documents. A transformation expressed in XSLT describes the rules for transforming a source tree into a result tree. The transformation is accomplished by associating patterns with templates. The tree contains nodes. There are SEVEN (7) kinds of nodes:
Description The root node is the root of the tree. For PeopleSoft Messages, the root node is the message name. In this example, the root is PO_SYNC

XSL tree node types Root Nodes

Element node

There is an element node for every element in the document. The children of an element node are element nodes, comment nodes, processing nodes and text nodes for its content. Character data is grouped into text nodes. Each element node may have an associated set of attribute nodes Each element has an associated set of namespace nodes, one for each namespace prefix that is in scope for the element and one for the default namespace if one

Text node Attribute node Namespace node

414

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

XSL tree node types Processing instruction nodes Comment nodes

Description There is a processing node for every processing instruction This is a string equal to the text of the comment not including the opening <!- -or closing -- >.

The XSLT action will include: Standard wrapper for transformations. Apply templates. Matches. Copy additional nodes. Template containing the field types.

PeopleSoft Proprietary and Confidential

415

Applying Transformations

Lesson 15

Writing the XSLT to Transform a Message (continued)


Each XSLT program must be enclosed in the following wrapper:
<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> ... </xsl:stylesheet>

Slide 277 ______________________________________________________________________________________________________

Student Notes
Note. Third-party XSLT development tools may generate a wrapper that specifies a different URI. Make sure the URI in your program is exactly as above, or your program may not work as expected.

Instructor Notes
Note. In activity 20, students are instructed to review the PO_TRANSFORM program, you may find it easier to teach this section by instructing the students to open the program now and follow along as you explain the XSLT code in the next few slides.

This section discusses how to explain: Explaining Header The header specifies the version of XSLT that is used in the code. A stylesheet is represented by an xsl:stylesheet element in the XML document. xmlns (namespace) - XSLT processors must use the XML namespaces mechanism for both documents and stylesheets. All XSLT defined elements, that is those specified with a prefix of xsl:, will only be recognized by the XSLT processor if they belong to a namespace with the URI http://www.w3.org/1999/XSL/Transform/1.0; XSLT defined elements are recognized only in the stylesheet not the source document. Header Namespace

416

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Explaining Namespace Namespace is a unique identifier. XSLT processors must use the XML namespace mechanism to recognize elements and attributes. PeopleSoft expects the namespace listed in the code on the slide. Parsers used by PeopleSoft transform programs are: Xalan XSLT Xerces - XML

PeopleSoft Proprietary and Confidential

417

Applying Transformations

Lesson 15

Writing the XSLT to Transform a Message (continued)


Apply-templates is used to start instantiating the result tree.
<xsl:template match="PO_SYNC"> <SDK_PO_SYNC> <xsl:apply-templates/> </SDK_PO_SYNC> </xsl:template>

Slide 278 ______________________________________________________________________________________________________

Student Notes
The template for SDK_PO_SYNC is included in the XSLT code and defines the field types for the resulting tree:
<xsl:template match = "FieldTypes"> <FieldTypes> <SDK_RP_PO class="R"> <SDK_RP_PO_NUMBER type="CHAR"/> <SDK_RP_PODATE type="DATETIME"/> <SDK_RP_SITENAME type="CHAR"/> <SDK_RP_VENDORNAME type="CHAR"/>

Additional field types


</FieldTypes> </xsl:template>

Instructor Notes
The Apply Templates code is saying When you see a match to PO_SYNC, then start outputting the information in the SDK_PO_SYNC template (as defined in the xsl at the bottom of the code). This specifies the tree structure for the resulting message. The field types section defines the record and fields for the transformed message. If the records and fields are the same, they could be copied, though, an <xsl:copy> or <xsl:apply-templates> command, rather than specific. XSLT code. For example the PSCAMA record is always the same in all PeopleSoft databases.

418

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Writing the XSLT to Transform a Message (continued)


The XSLT code is recursive, so it will continue looking for the specific fields to match as it instantiates the result tree. The code below shows the following: The source record PSU_PO_HDR is matched to SDK_RP_PO using the class attribute. The data value for the result tree is specified by the xsl:value-of-select. Specific data can be entered as content. If there is a specific set of logic that needs to happen when a node is encountered, create a template for that node name.

Slide 279 ______________________________________________________________________________________________________

Student Notes
The portion of the XSLT that applies the templates is shown below:
<xsl:template match="PSU_PO_HDR"> <SDK_RP_PO><xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> <SDK_RP_PO_NUMBER>TR<xsl:value-of select="ORDER_NBR"/></SDK_RP_PO_NUMBER> <SDK_RP_PODATE><xsl:value-of-select="ORDER_DT"/></SDK_RP_PODATE> <SDK_RP_SITENAME><xsl:value-of select="BUSINESS_UNIT"/></SDK_RP_SITENAME> <SDK_RP_VENDORNAME><xsl:value-of select="VENDOR_CD"/></SDK_RP_VENDORNAME> <PO_STATUS><xsl:value-of select="ORDER_STATUS"/></PO_STATUS> <!-Because we have a subrecord, you need to apply-templates to continue processing --> <xsl:apply-templates /> </SDK_RP_PO> </xsl:template> <xsl:template match="PSU_PO_DTL"> <SDK_RP_POLINE><xsl:attribute name="class"><xsl:value-of select="@class"/> </xsl:attribute> <SDK_RP_PO_NUMBER><xsl:value-of select="ORDER_NBR" /></SDK_RP_PO_NUMBER> <SDK_RP_SITENAME><xsl:value-of select="BUSINESS_UNIT" /></SDK_RP_SITENAME> <SDK_RP_PO_PARTNAME><xsl:value-of select="ITEM_CD" /></SDK_RP_PO_PARTNAME> <SDK_RP_QUANTITIES><xsl:value-of select="QTY" /></SDK_RP_QUANTITIES> <SDK_RP_UNIT_PRICE><xsl:value-of select="PRICE" /></SDK_RP_UNIT_PRICE> </SDK_RP_POLINE> </xsl:template>

Instructor Notes
This section discusses how to: Match specific nodes Match subrecords

PeopleSoft Proprietary and Confidential

419

Applying Transformations

Lesson 15

Matching Specific Nodes Once you have the tree structure, the code will start entering the data values: It is a recursive script first it outputs tags for <SDK_PO_SYNC>, then goes to the next node. Do I have a PSU_PO_HDR match that to SDK_RP_PO. PSU_PO_HDR has the attribute class, so a class attribute will be created with the value R As it goes through the code the value-of is used to assign the data values from the original XML to the new template. SDK_RP_PO_NUMBER takes the value from ORDER_NBR, etc.

If you look at the line:


<SDK_RP_PO_NUMBER>TR<xsl:value-of select="ORDER_NBR"/></SDK_RP_PO_NUMBER>

TR will be prefixed to the order number in the result tree. Matching child records In the example PSU_PO_DTL is a child record of PSU_PO_HDR. In this case, you need to apply-templates for the parent record before continuing to the child (if you fail to do this, the child record templates will not get applied). If this is not done, the result message will not contain any data for the child record (since the child record is just another node in the parent.)

420

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Writing the XSLT to Transform a Message (continued)


If nodes simply need to be copied, the following code will copy all nodes and their children:
<!-- This will copy a node/attribute and its children --> <xsl:template match="node() | @*"> <xsl:copy> <xsl:apply-templates select="node() | @*"/> </xsl:copy> </xsl:template>

Slide 280 ______________________________________________________________________________________________________

Student Notes
If you select to copy all nodes and you have already specified specific nodes in your code, you must add a line to ignore the nodes that have already been identified:
<!-Ignore these fields -->

<xsl:template match="processing-instruction() | BUSINESS_UNIT | ORDER_NBR | ORDER_DT | VENDOR_CD | ORDER_STATUS | STATUS_DT | DELIVER_METHOD | ADDED_BY | APPR_STATUS | APPR_INSTANCE | ORDER_LINE_NBR | ITEM_CD | QTY | PART_NBR | ITEM_COLOR | PRICE"> <!-do nothing --> </xsl:template>

Instructor Notes
This section discusses how to: Copy all nodes and attributes. Ignore nodes

Copying All Nodes and Attributes The following explain the characters used in the code: Comments in XSLT use <!--and -->. Node () refers to xml tag as a node. @ is used for attributes.

This code will copy says match the node/attribute and all its children, as well as tell the Transformation Engine to apply templates to nodes with corresponding templates if they are found.

PeopleSoft Proprietary and Confidential

421

Applying Transformations

Lesson 15

This matches all of the nodes that have not been explicitly defined in the code PSCAMA,MsgData and FieldTypes. Ignoring Nodes This is new in PeopleTools 8.44 if you copy all nodes and attributes, it will copy everything you need to identify the fields that you do not want to copy. | is used for or If you specifically identify every node in the XSLT program, you would not use either of these pieces of code. Question: Writing the XSLT to Transform a Message XSLT operates on an XML document as a tree. 1. True 2. False Answer The answer is 1 (true).

422

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Testing Transform Programs


To test a transform program: 1. Create a test message (or obtain the message from the participating node). 2. Copy the XML to a file. 3. In the browser, select PeopleTools, Integration Broker, Utilities, Transformation Test. 4. Create a new Project. 5. Enter the information and test file path. 6. Click Transform.
Slide 281 ______________________________________________________________________________________________________

Student Notes
Use the Transformations Test page to test a transform program:
Page Name Transform Page Navigation PeopleTools, Integration Broker, Utilities, Transformation Test

Transform page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Applying Filtering, Transformation and Translation

PeopleSoft Proprietary and Confidential

423

Applying Transformations

Lesson 15

Instructor Notes
You can examine the message text to ensure that the message was transformed as expected. If there are any errors in your XSLT code, the error will be displayed. The transformation test page does not use the relationship, so the values entered in the Source and Dest node editboxes are not used by the transform program. Question: Testing Transform Programs You need to have a connection to the participating node in order to test your transformation programs. 1. True 2. False Answer The answer is 2 (false the Transformation tester reads the XML from a flat file).

424

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Activity 20:

Reviewing, Writing and Testing Transform Programs


In this activity, you will review the activity overview and: 1. Review the PO_TRANSFORM program. 2. Test the PO_TRANSFORM program. 3. Write and test a transform program. See Integration Tools: Activity Guide, lesson 15, Applying Transformations, Activity 20: Reviewing, Writing and Testing Transform Programs.

Slide 282 ______________________________________________________________________________________________________

Instructor Notes
In this activity, students modify the SCHOOL_TRANS program to add additional code to the XSLT statement. This transform program will only be used with the Transform Utility to show that the program functions properly and reformats the message. Note. This activity should take approximately fifteen minutes. Completed XSLT for SCHOOL_TRANS program:
<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="SCHOOL_SYNC"> <SCHOOL_SYNC> <xsl:apply-templates/> </SCHOOL_SYNC> </xsl:template> <xsl:template match="PSU_SCHOOL_TBL"> <SCHOOL_TBL><xsl:attribute name="class"><xsl:value-of select="@class"/></xsl:attribute> <SCHOOL_ID><xsl:value-of select="SCHOOL_CODE"/></SCHOOL_ID> <xsl:apply-templates/> </SCHOOL_TBL> </xsl:template> <!-- This will copy a node/attribute and its children --> <xsl:template match="node() | @*"> <xsl:copy> <xsl:apply-templates select="node() | @*"/> </xsl:copy>

PeopleSoft Proprietary and Confidential

425

Applying Transformations

Lesson 15

</xsl:template> <!-- Ignore these fields --> <xsl:template match="processing-instruction() | SCHOOL_CODE "> <!-- Do nothing --> </xsl:template> <xsl:template match="FieldTypes"> <FieldTypes> <SCHOOL_TBL class="R"> <COUNTRY type="CHAR" /> <SCHOOL_ID type="CHAR" /> <DESCR type="CHAR" /> <DESCRSHORT type="CHAR" /> <STATE type="CHAR" /> <PUBLIC_PRIVATE type="CHAR" /> </SCHOOL_TBL> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> <BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA> </FieldTypes> </xsl:template> </xsl:stylesheet>

Warning! The transformation does not match the FSCM database , so DO NOT try to set this transaction up with PSFT_EP or you will get errors.

Activity Overview
In this activity, you will review the PO_TRANSFORM program and test the PO_TRANSFORM program using the file z:\STAnnn\Tools\1022_IntTools\Files\PO_sync.xml. After reviewing and testing the existing program, it is time to write you own program. You have already set up the SCHOOL_SYNC message and sent messages to your neighbors database, now you want to use that same message with the HCM system, however the record structure is slightly different. The record name is SCHOOL_TBL and the field SCHOOL_ID is used instead of SCHOOL_CODE. Below is the message that you will receive. This message is located in z:\STAnnn\Tools\1022_IntTools\files\SCHOOL_SYNC.xml.
<?xml version="1.0"?>

426

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

<SCHOOL_SYNC> <FieldTypes> <SCHOOL_TBL class="R"> <COUNTRY type="CHAR"/> <SCHOOL_ID type="CHAR"/> <DESCR type="CHAR"/> <DESCRSHORT type="CHAR"/> <STATE type="CHAR"/> <PUBLIC_PRIVATE type="CHAR"/> </SCHOOL_TBL> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> <BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA> </FieldTypes> <MsgData> <Transaction> <SCHOOL_TBL class="R"> <COUNTRY IsChanged="Y">USA</COUNTRY> <SCHOOL_ID IsChanged="Y">FDU</SCHOOL_ID> <DESCR IsChanged="Y">Fairleigh Dickinson University</DESCR> <DESCRSHORT IsChanged="Y">Fairleigh</DESCRSHORT> <STATE IsChanged="Y">NJ</STATE> <PUBLIC_PRIVATE IsChanged="Y">P</PUBLIC_PRIVATE> </SCHOOL_TBL> <PSCAMA class="R"> <LANGUAGE_CD>ENG</LANGUAGE_CD> <AUDIT_ACTN IsChanged="Y">A</AUDIT_ACTN> <BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD> <MSG_SEQ_FLG/> <PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID/> <MSGNODENAME/> </PSCAMA> </Transaction> </MsgData> </SCHOOL_MSG>

A partially completed application engine program has already been created for you called SCHOOL_TRANS. Open the XSLT action and complete the code by adding the code to populate the SCHOOL_ID field and ignore any fields specifically defined. After completing and saving the transform program, test the program using the sample message shown above.
PeopleSoft Proprietary and Confidential 427

Applying Transformations

Lesson 15

Reviewing the PO_TRANSFORM Program


To review the PO_TRANSFORM program: 1. In Application Designer, open the application engine program PO_TRANSFORM. 2. Double-click on the XSLT action. 3. Review the code.

Testing the PO_TRANSFORM program


To test the PO_TRANSFORM program: 1. In the browser, select PeopleTools, Integration Broker, Utilities, Transformation Test. 2. Add a new project PO_TEST. 3. Enter the following information:
Page Element Program Name Source Node Dest Node File Name Value or Status PO_TRANSFORM Your local node Your neighbors node z:\STAnnn\Tools\1022_IntTools\Files\PO_sync.xml

4. Click Transform. 5. Save the page. Result Message Text


<?xml version="1.0"?> <SDK_PO_SYNC><FieldTypes><SDK_RP_PO class="R"><SDK_RP_PO_NUMBER type="CHAR"/><SDK_RP_PODATE type="DATE"/><SDK_RP_SITENAME type="CHAR"/><SDK_RP_VENDORNAME type="CHAR"/><PO_STATUS type="CHAR"/></SDK_RP_PO><SDK_RP_POLINE class="R"><SDK_RP_PO_NUMBER type="CHAR"/><SDK_RP_SITENAME type="CHAR"/><SDK_RP_LINENUM type="CHAR"/><SDK_RP_PARTSITE type="CHAR"/><SDK_RP_PARTNAME type="CHAR"/><SDK_RP_QUANTITIES type="CHAR"/><SDK_RP_UNIT_PRICE type="NUMBER"/></SDK_RP_POLINE><PSCAMA class="R"><LANGUAGE_CD type="CHAR"/><AUDIT_ACTN type="CHAR"/><BASE_LANGUAGE_CD type="CHAR"/><MSG_SEQ_FLG type="CHAR"/><PROCESS_INSTANCE type="NUMBER"/><PUBLISH_RULE_ID type="CHAR"/><MSGNODENAME type="CHAR"/></PSCAMA></FieldTypes><MsgData><Transaction><SDK_RP_PO class="R"><SDK_RP_PO_NUMBER>TR00000037</SDK_RP_PO_NUMBER><SDK_RP_PODATE>20 03-1009</SDK_RP_PODATE><SDK_RP_SITENAME>NAM01</SDK_RP_SITENAME><SDK_RP_VENDORNA ME>ALPH04</SDK_RP_VENDORNAME><PO_STATUS>IN</PO_STATUS><ORDER_STATUS IsChanged="Y">IN</ORDER_STATUS><SDK_RP_POLINE class="R"><SDK_RP_PO_NUMBER>TR00000037</SDK_RP_PO_NUMBER><SDK_RP_SITENAME> NAM01</SDK_RP_SITENAME><SDK_RP_PARTNAME>PSU001</SDK_RP_PARTNAME><SDK_RP_QU ANTITIES>1</SDK_RP_QUANTITIES><SDK_RP_UNIT_PRICE>1000</SDK_RP_UNIT_PRICE>< /SDK_RP_POLINE><PSCAMA class="R"><AUDIT_ACTN>A</AUDIT_ACTN></PSCAMA></SDK_RP_PO><PSCAMA class="R"><LANGUAGE_CD>ENG</LANGUAGE_CD><AUDIT_ACTN>A</AUDIT_ACTN><BASE_LA

428

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

NGUAGE_CD>ENG</BASE_LANGUAGE_CD><MSG_SEQ_FLG/><PROCESS_INSTANCE>0</PROCESS _INSTANCE><PUBLISH_RULE_ID/><MSGNODENAME/></PSCAMA></Transaction></MsgData ></SDK_PO_SYNC>

Writing and Testing a Transform Program


To write and test a transform program: 1. In the Application Designer, select File, Open, App Engine Program SCHOOL_TRANS. 2. Double-click in the gray area for the XSLT action. Complete the XSLT code for the template match: a. Replace the comment <!-- ADD THE CODE HERE TO POPULATE SCHOOL_ID-->
<xsl:template match="PSU_SCHOOL_TBL"> <SCHOOL_TBL> <xsl:attribute name="class"> <xsl:value-of select="@class"/> </xsl:attribute> <SCHOOL_ID> <xsl:value-of select="SCHOOL_CODE"/> </SCHOOL_ID> <xsl:apply-templates/> </SCHOOL_TBL> </xsl:template>

b. Replace the comment <!-- ADD THE CODE HERE TO IGNORE THE FIELDS THAT HAVE BEEN SPECIFICALLY POPULATED -->
<!-- Ignore these fields --> <xsl:template match="processing-instruction() | SCHOOL_CODE "> <!-- Do nothing --> </xsl:template>

Note. A copy of the entire code is located in \1022_IntTools\Scripts\School_xslt.txt. 3. Save the program. 4. In the browser, select PeopleTools, Integration Broker, Utilities, Transformation Test. 5. Add a new project SCHOOL_TEST. 6. Enter the following information:
Page Element Program Name Value or Status SCHOOL_TRANS

PeopleSoft Proprietary and Confidential

429

Applying Transformations

Lesson 15

Page Element Source Node Dest Node File Name

Value or Status Your local node PSFT_HR Z:\STAnnn\Tools\1022_IntTools\Files\school_sync.xml

7. Click Transform. Result Message text


<?xml version="1.0"?> <SCHOOL_SYNC><FieldTypes><SCHOOL_TBL class="R"><COUNTRY type="CHAR"/><SCHOOL_ID type="CHAR"/><DESCR type="CHAR"/><DESCRSHORT type="CHAR"/><STATE type="CHAR"/><PUBLIC_PRIVATE type="CHAR"/></SCHOOL_TBL><PSCAMA class="R"><LANGUAGE_CD type="CHAR"/><AUDIT_ACTN type="CHAR"/><BASE_LANGUAGE_CD type="CHAR"/><MSG_SEQ_FLG type="CHAR"/><PROCESS_INSTANCE type="NUMBER"/><PUBLISH_RULE_ID type="CHAR"/><MSGNODENAME type="CHAR"/></PSCAMA></FieldTypes><MsgData><Transaction><SCHOOL_TBL class="R"><COUNTRY IsChanged="Y">USA</COUNTRY><SCHOOL_ID IsChanged="Y">FDU</SCHOOL_ID><DESCR IsChanged="Y">Fairleigh Dickinson University</DESCR><DESCRSHORT IsChanged="Y">Fairleigh</DESCRSHORT><STATE IsChanged="Y">NJ</STATE><PUBLIC_PRIVATE IsChanged="Y">P</PUBLIC_PRIVATE></SCHOOL_TBL><PSCAMA class="R"><LANGUAGE_CD>ENG</LANGUAGE_CD><AUDIT_ACTN IsChanged="Y">A</AUDIT_ACTN><BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD><MSG_S EQ_FLG/><PROCESS_INSTANCE>0</PROCESS_INSTANCE><PUBLISH_RULE_ID/><MSGNODENA ME/></PSCAMA></Transaction></MsgData></SCHOOL_SYNC>

This concludes the activity. Do not continue.

430

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Transforming a Message to a SOAP Request


In order to interact with web services, you will need to create a transform program that formats the data for the web service. This example is a synchronous request, so you will need the following: A transformation program to format the request as a SOAP document. A transformation program to format the SOAP response into a structured message.

Slide 283 ______________________________________________________________________________________________________

Student Notes
Below is a sample web service to look up zip codes and return the city and state:

FindCityState The web service provides a sample SOAP request and response that it is expecting.

PeopleSoft Proprietary and Confidential

431

Applying Transformations

Lesson 15

Instructor Notes
The following definitions are defined in the Training database to be used with this web service: Message Definition. Message Channel. Publish PeopleCode. Transform program to create the SOAP request. Transform program to transform the SOAP response. Node definition for the web service. Relationship for the web service.

432

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Transforming a Message to a SOAP Request (continued)


The transformation program for the request needs to: Create a SOAP request Insert the transactional data from the PeopleSoft structured message into the SOAP request.

Slide 284 ______________________________________________________________________________________________________

Student Notes
Below is shown the sample SOAP request provided by the web service provider and the transform program XSLT to format the message: Sample SOAP request:
POST /trwest/trwest_zip4/zip4.asmx HTTP/1.1 Host: upload.eraserver.net Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://trwest.com/webservices/FindCityState" <?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <FindCityState xmlns="http://trwest.com/webservices/"> <zip>string</zip> </FindCityState> </soap:Body> </soap:Envelope>

Transform Program XSLT to format the message in for the web service:
<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="ZIP_REQUEST"> <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body> <a:FindCityState xmlns:a="http://trwest.com/webservices/"> <a:zip>

PeopleSoft Proprietary and Confidential

433

Applying Transformations

Lesson 15

<xsl:value-of select="MsgData/Transaction/CONTACT_TBL/POSTAL"/> </a:zip> </a:FindCityState> </soap:Body> </soap:Envelope> </xsl:template> </xsl:stylesheet>

Instructor Notes
This transform program is ZIP_REQUEST. The soap envelope created is in exactly the format that the web service requested. The web service also showed the example of how they wanted the soap-body constructed. The transactional data for zip is taken from the PeopleSoft formatted message:
<xsl:value-of select="MsgData/Transaction/CONTACT_TBL/POSTAL"/>

In this example, the message is initiated from the CONTACT_TBL field POSTAL FieldChange.
Local Message &msgZipRequest, &msgZipResponse; Local Rowset &RS, &rsMessageRowset; &RS = GetLevel0(); &msgZipRequest = CreateMessage(Message.ZIP_REQUEST); &msgZipRequest.CopyRowset(&RS); &msgZipResponse = &msgZipRequest.SyncRequest(Node.ZIPTOCITYANDSTATE); &rsMessageRowset = &msgZipResponse.GetRowset(); &rsMessageRowset.CopyTo(&RS); CONTACT_TBL.CITY = Proper(CONTACT_TBL.CITY);

434

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Transforming a Message to a SOAP Request (continued)


PeopleCode is to read incoming unstructured messages: %TransformData is a system variable that returns a reference to the TransformData object. The GenXmlString method produces an XML string with all the data on a single line. Substitute replaces every occurrence of a substring found in a string with a new substring. The ParseXMLString method fills the XmlDoc object with the data and shape from an XML string.

Slide 285 ______________________________________________________________________________________________________

Student Notes
Below is the PeopleCode to receive the SOAP response message and create an XmlDoc.
/* Get the data from the AE Runtime */ Local TransformData &incomingData = %TransformData; /* Set a temp object to contain the incoming document */ Local XmlDoc &tempDoc = &incomingData.XmlDoc; Local string &str = &tempDoc.GenXmlString(); Local string &str2 = Substitute(&str, "FindCityStateResponse xmlns=""http://trwest.com/webservices/""", "FindCityStateResponse"); &ret = &tempDoc.ParseXmlString(&str2);

See Also PeopleTools 8.44PeopleBook: PeopleCode Reference, XmlDoc Class.

Instructor Notes
The PeopleCode takes the incoming SOAP message (%TranformData), places it in an XML document. This section discusses: GenXmlString method Built-in function Substitute

PeopleSoft Proprietary and Confidential

435

Applying Transformations

Lesson 15

GenXmlString method Use the GenXmlString method to return an XML string representing the XmlDoc object. The GenXmlString method produces an XML string with all the data on a single line. If you want a formatted XML string, that is, with new line characters and indents, use the GenFormattedXmlString method instead. Built-in function - Substitute Substitute replaces every occurrence of a substring found in a string with a new substring. To replace text that occurs in a specific location in a text string use Replace. The syntax is:

Substitute(source_text, old_text, new_text) Parameters

source_text - A String in which you want to replace substrings. old_text - A String equal to the substring of source_text you want to replace. new_text - A String with which to replace occurrences of old_text in source_text. Returns

Returns a String resulting from replacing every occurrence of old_text found in source_text with new_text. Example

The following example changes "Second Annual Conference" to "Third Annual Conference": &newstr = Substitute("Second Annual Conference","Second","Third");

436

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Transforming a Message to a SOAP Request (continued)


Once the SOAP response has been formatted into an XmlDoc, XSLT can be used to structure the message: Each transform program step operates on the message content from the previous step. Each transform action should be should be inserted into its own step.

Slide 286 ______________________________________________________________________________________________________

Student Notes
Below is the XSLT that structures the XmlDoc created in the first step to a PeopleSoft structured message:
<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="//FindCityStateResult"> <ZIP_RESPONSE> <FieldTypes> <CONTACT_TBL class="R"> <CITY type="CHAR"/> <STATE type="CHAR"/> <BUTTON type="CHAR"/> </CONTACT_TBL> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR"/> <AUDIT_ACTN type="CHAR"/> <BASE_LANGUAGE_CD type="CHAR"/> <MSG_SEQ_FLG type="CHAR"/> <PROCESS_INSTANCE type="NUMBER"/> <PUBLISH_RULE_ID type="CHAR"/> <MSGNODENAME type="CHAR"/> </PSCAMA> </FieldTypes> <MsgData> <Transaction> <CONTACT_TBL class="R"> <CITY><xsl:value-of select="City"/></CITY> <STATE><xsl:value-of select="State"/></STATE> <BUTTON/> </CONTACT_TBL> <PSCAMA class="R"> <LANGUAGE_CD>ENG</LANGUAGE_CD> <AUDIT_ACTN>C</AUDIT_ACTN> <BASE_LANGUAGE_CD>ENG</BASE_LANGUAGE_CD> <MSG_SEQ_FLG/>

PeopleSoft Proprietary and Confidential

437

Applying Transformations

Lesson 15

<PROCESS_INSTANCE>0</PROCESS_INSTANCE> <PUBLISH_RULE_ID/> <MSGNODENAME/> </PSCAMA> </Transaction> </MsgData> </ZIP_RESPONSE> </xsl:template></xsl:stylesheet>

438

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Activity 21:

Testing Transform Program from a SOAP Document


In this activity, you will review the activity overview and test the transform program from a SOAP document. See Integration Tools: Activity Guide, lesson 15, Applying Transformations, Activity 21: Testing Transform Program from a SOAP Document.

Slide 287 ______________________________________________________________________________________________________

Instructor Notes
The purpose of this activity is to show that you can use a transform program to convert a SOAP request into PeopleSoft message format to be used with the PeopleSoft system. The transform utility shows how the message is transformed. This URL no longer seems to be working which is not part of the activity since we are only testing in the Transform Utility. However, if you would like to view the service: Open the node ZIPTOCITYANDSTATE. Access the Connectors page. Copy the URL and paste it in the browser.

You can see the web service. There is a test and you will notice if you try it does not return the city and state. This used to work but with free access to sites you can never determine when they will no longer be available. This web service was associated with the record CONTACT_TBL.POSTAL. The page can be accessed Customer, Contacts. If the web service works in the future, the page will also. Note. This activity should take approximately fifteen minutes.

Activity Overview
In this activity, you will look at the test SOAP response from the web service (z:\STAnnn\Tools \1022_IntTools\files\zip_return.xml) and then test the transform program ZIP_RESPONSE in the Integration Broker transform test utility.

Testing Transform Program from a SOAP Document


To test the transform program from a SOAP document: 1. Open the file z:\STAnnn\Tools \1022_IntTools\files\zip_return.xml. 2. Review the SOAP document. 3. Close the file.

PeopleSoft Proprietary and Confidential

439

Applying Transformations

Lesson 15

4. In the browser, select PeopleTools, Integration Broker, Utilities, Transformation Test. 5. Add a new project ZIP_TEST. 6. Enter the following information:
Page Element Program Name Source Node Dest Node File Name Value or Status ZIP_RESPONSE ZIPTOCITYANDSTATE Your node Z:\STAnnn\Tools\1022_IntTools\Files\zip_return.xml

7. Click Transform. 8. Save the page. Results The transformed XML is displayed in the message text:

Transformation test results

440

PeopleSoft Proprietary and Confidential

Lesson 15

Applying Transformations

Review
In this lesson, you learned that: Transform programs are used to do any of the following: Change the structure of a message. Perform a data translation on a message. Filtering a message based on its content.

Transformation programs are application engine programs where the steps contain either XSLT or PeopleCode. The program will reformat the source message into a new result message. XSLT is a well-recognized standard language perfectly suited to manipulating XML structures. The XSLT defines the structure of the result message and uses the template match to match the source tree to the result tree. Transformation programs can be tested in the browser using PeopleTools, Utilities, Transformation Test. Messages can be transformed to SOAP documents.

Slide 288 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

441

Applying Transformations

Lesson 15

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

442

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships


Objectives
By the end of this lesson, you will be able to: Describe relationships. Create integration points using the Integration Point Wizard. View an integration point. Maintain relationships.

Slide 290 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

443

Working with Relationships

Lesson 16

Describing Relationships
Relationships are required when: The source node sends a message asynchronously, but the target node expects to receive it synchronously. A hub configuration is used. One or more messages in a transaction need to be filtered, transformed, or translated upon sending or receiving.

Slide 291 ______________________________________________________________________________________________________

Instructor Notes
Relationships are not required when each node expects the message to have the same structure, version and encoding as the other nodes such as all of the transactions we have used in this course up until now.

444

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Describing Relationships (continued)


The relationship defines the point-to-point integration: Use the Integration Point Wizard to guide you through the process of setting up the relationship. Use the Relationships component to maintain the relationship.

Slide 292 ______________________________________________________________________________________________________

Student Notes
Note. The Integration Point Wizard is for one-time use, after you save the integration point with the wizard, you must use the appropriate PeopleSoft Application Designer and PeopleSoft Internet Architecture pages to make any subsequent modifications to the integration point.

Instructor Notes
If a transaction has already been set up for a specific node in the node definition, you will not be able to save an integration point using the Integration Point Wizard (it will give you a message that the transaction already exists). If you make a mistake when saving an integration point using the Integration Point Wizard, you will need to correct it using the Relationships component. If you want top delete integration point, remove the transaction in the node definition page this deletes everything associated with that transaction. Question: Describing Relationships Relationships are necessary for all transactions. 1. True 2. False Answer The answer is 1 (false).

PeopleSoft Proprietary and Confidential

445

Working with Relationships

Lesson 16

Creating Integration Points Using the Integration Point Wizard


The Integration Gateway must be set up and configured, as well as the following definitions, before using the Integration Point Wizard: Sending Node. Receiving Node. Request Message. Response Message. (synchronous message only) Request transformation. (when using transformations) Response transformation. (when using transformations) Asynchronous message reply. (for asynchronous-to-synchronous transactions only)

Slide 293 ______________________________________________________________________________________________________

446

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Creating Integration Points Using the Integration Point Wizard (continued)


The Integration Point Wizard provides five or six steps for creating integration points: 1. Nodes and Transaction Types. 2. Sender Message Information. 3. Transformation Information. 4. Receiver Information. 5. Summary for asynchronous or synchronous transactions. Asynchronous reply and transformation for asynchronous-to-synchronous transactions. 6. Summary for asynchronous-to-synchronous transactions.
Slide 294 ______________________________________________________________________________________________________

Student Notes
Note. Depending on the type of integration point, not all of the steps may be necessary. By using the Next button, you will be prompted for the applicable information.

Instructor Notes
There is one additional step if the integration point is asynchronous-to-synchronous.

PeopleSoft Proprietary and Confidential

447

Working with Relationships

Lesson 16

Creating Integration Points Using the Integration Point Wizard (continued)


The first step is used to define: Sender Node. Receiver Node. Transaction Type.

Slide 295 ______________________________________________________________________________________________________

Student Notes
Use Integration Point Wizard: to create new integration points:
Page Name Integration Point Wizard Navigation PeopleTools, Integration Broker, Integration Point Wizard

Step 1 - Specify nodes and transaction type page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using the Integration Point Wizard.

448

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Creating Integration Points Using the Integration Point Wizard (continued)


The second step is used to define the sender message information: For asynchronous and asynchronous-to-synchronous transactions the request message information is entered. For synchronous transactions the request message and the response message information is entered.

Slide 296 ______________________________________________________________________________________________________

Student Notes
Step 2 specifies the sender message information:

Step 2 - Sender message information for an asynchronous transaction

Instructor Notes
If a message has the same structure between to participating nodes and the only difference is the message name, then the External name could be used without a transform program.

PeopleSoft Proprietary and Confidential

449

Working with Relationships

Lesson 16

Creating Integration Points Using the Integration Point Wizard (continued)


The third step is used to define the transformation information: For an asynchronous or an asynchronous-to-synchronous transaction the request transformation information is entered. For a synchronous transaction the request transformation and the response transformation information is entered.

Slide 297 ______________________________________________________________________________________________________

Student Notes
Step 3 specifies the transform program:

Step 3 Transformation information for an asynchronous message

450

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Creating Integration Points Using the Integration Point Wizard (continued)


The forth step is used to define the receiver message information: For an asynchronous transaction the receiver message information is entered. For a synchronous or an asynchronous-to-synchronous transaction the request message and the response message information is entered. An Advanced page is available to specify transaction properties and override connector properties.

Slide 298 ______________________________________________________________________________________________________

Student Notes
Step 4 specifies the message the receiver is expecting:

Step 4 Receiver message information for an asynchronous transaction Note. This is the message name after the transformation.

Instructor Notes
The transaction properties for a synchronous transaction include logging and routing type (implicit or explicit). Notice that the Request Message is a prompt button. In the case of the activity we will be doing in class, the SDK_PO_SYNC message exists on the training database, but if it did not, you would need to create a message with the transformed name (no record).

PeopleSoft Proprietary and Confidential

451

Working with Relationships

Lesson 16

Creating Integration Points Using the Integration Point Wizard (continued)


The fifth step provides a summary of the integration point: For asynchronous-to-synchronous transactions step 5 is used to define the asynchronous reply and transformation information. Review the summary page before saving. Select the Previous button or the step numbers to make corrections. Select Finish to save the integration point.

Slide 299 ______________________________________________________________________________________________________

Student Notes
Step 5 displays the summary information:

Step 5 Asynchronous transaction summary

452

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Instructor Notes
If a transaction already exists for the nodes specified, you will receive an error message when you click Finish.

Error message if transaction already exists. Question: Creating Integration Points Using the Integration Point Wizard The Integration Point Wizard can be used for? 1. Asynchronous transactions. 2. Synchronous transactions. 3. Asynchronous-to-synchronous transactions. 4. All of the above. Answer The answer is 4 (all of the above.).

PeopleSoft Proprietary and Confidential

453

Working with Relationships

Lesson 16

Viewing the Integration Point


The Integration Point Viewer can be used to: Identify any problems with the integration point. Link to node definitions and transaction modifiers. Activate inactive definitions.

Slide 300 ______________________________________________________________________________________________________

Student Notes
Use the Integration Point Wizard to identify any inactive objects for the integration point:
Page Name Integration Point Viewer Navigation PeopleTools, Integration Broker, Integration Point Viewer

Integration point viewer page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using the Integration Point Viewer.

454

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Instructor Notes
Point out the link at the top of the page Go to Inactive Objects page. Sometimes it is difficult to determine where an error is occurring for the integration point, this link will identify which objects are inactive.

PeopleSoft Proprietary and Confidential

455

Working with Relationships

Lesson 16

Activity 22:

Creating Integrations Using the Integration Point Wizard


In this activity, you will review the activity overview: Create an asynchronous integration points using the Integration Point Wizard. Test the asynchronous transaction. Create an asynchronous-to-synchronous integration point using the Integration Point Wizard. Test the asynchronous-to-synchronous transaction.

See Integration Tools: Activity Guide, lesson 16, Working with Relationships, Activity 22: Creating Integrations Using the Integration Point Wizard.
Slide 301 ______________________________________________________________________________________________________

Instructor Notes
When students start Query Analyzer they need to change to SQL SERVER Once this is done, the system saves it. The login name and password is currently satst, however this may change in the future on the CTE.
AUTHENTICATION.

Note. This activity should take approximately 25 minutes. Point out that the receiving node must have an inbound asynchronous transaction for SDK_PO_SYNC message. If the message sits in NEW status, students should use the Troubleshooting Guide to determine the problem. The TRAINING_CHNL may be paused.

Activity Overview
In this activity, you will create two separate integration points using the Integration Point Wizard: Asynchronous Integration Point In lesson 15 Applying Transformations, you reviewed the transform program to transform the PO_SYNC message to SDK_PO_SYNC, you will now set up the integration point to send the PO_SYNC message to your neighbor who will receive the message as SDK_PO_SYNC. Note. You need to add the inbound transaction for SDK_PO_SYNC to your neighbors node before continuing. All of the necessary definitions are listed in the table below:
Definition Type Sending node Definition Name Your node

456

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Definition Type Receiving Node Sender node Request Message Request Transformation Receiver node Request Message

Definition Name Your neighbors node PO_SYNC PO_TRANSFORM SDK_PO_SYNC

Test the integration point by adding a new Purchase Order. To add a purchase order select Purchasing, Maintain Purchase Orders and enter your new order. Asynchronous-to-synchronous Integration Point In this scenario, you want to publish an asynchronous message CUSTOMER_ASYNC every time you add or change customer information. The receiving system is expecting a synchronous message CUSTOMER_SYNCHRONOUS and will return the CUSTOMER_REPLY synchronously. Both the messages CUSTOMER_ASYNC and CUSTOMER_SYNCHRONOUS are based on the PSU_CUST_TBL and the messages have exactly the same structure. On your training database there is a project CUST_PROJ. This project contains all of the definitions that are necessary.
Definition CUST_OAOS_TR CUST_OAOS_RP Description Transformation program to convert CUSTOMER_ASYNC to CUSTOMER_SYNCHRONOUS. Transformation program to change the reply message CUSTOMER_REPLY to the asynchronous message reply ASYNC_CUST_REPLY. Asynchronous reply message. Asynchronous customer message. Synchronous customer reply message. Synchronous customer message. Record used for the ASYNC_CUST_REPLY message. Customer record with SavePostChange event to publish the CUSTOMER_ASYNC message. Record used for the CUSTOMER_REPLY message

ASYNC_CUST_REPLY CUSTOMER_ASYNC CUSTOMER_REPLY CUSTOMER_SYNCHRONOUS ASYNC_REPLY PSU_CUST_TBL TRN_REPLY

Use the Integration Point Wizard to create the integration point that will send the CUSTOMER_ASYNC message asynchronously from your local node transform it to a synchronous message CUSTOMER_SYNCHRONOUS for your neighbor. The synchronous reply CUSTOMER_REPLY must then be transformed into an asynchronous response ASYNC_CUST_RESPONSE. Test the integration point by adding a new customer. To add a customer select Customers, General Information and enter your new customer.

PeopleSoft Proprietary and Confidential

457

Working with Relationships

Lesson 16

Creating an Asynchronous Integration Point Using the Integration Point Wizard


To create an asynchronous integration point using the Integration Point Wizard: 1. In the browser, select PeopleTools, Integration Broker, Node Definitions. 2. Select your neighbors node. 3. Select the Transactions page. 4. Add the inbound asynchronous transaction for SDK_PO_SYNC. 5. Save the page. 6. Select PeopleTools, Integration Broker, Integration Point Wizard. 7. Enter the following information:
Page Element Sending node Receiving Node Transaction Type Value or Status Your node Your neighbors node Asynchronous

8. Click Next. 9. Enter the following information:


Page Element Sender Node Request Message Version Value or Status PO_SYNC VERSION_1

10. Click Next. 11. Enter PO_TRANSFORM for the request transformation. 12. Click Next. 13. Enter the following information:
Page Element Receiver Node Request Message Version Value or Status SDK_PO_SYNC VERSION_1

14. Click Next.

458

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Results The integration point summary will be displayed, ensure it is correct before clicking Finish:

Summary page for asynchronous integration 15. Click Finish.

Testing the Asynchronous Transaction


To test the asynchronous transaction: 1. Select Purchasing, Maintain Purchase Orders. 2. Add a new purchase order with the following information:
Page Element Business Unit Vendor Code Item Code Quantity Price Value or Status NAM01 ALPH04 PSU001 1 2000

3. Save the purchase order. 4. Check the Integration Broker Monitor for the status of the message.

PeopleSoft Proprietary and Confidential

459

Working with Relationships

Lesson 16

5. In the Details page, you can view the XML on the source message and the XML on the result message. 6. Select Start, Programs, Microsoft SQL Server, Query Analyzer. 7. Select SQL SERVER AUTHENTICATION. 8. Enter satst for the login name and satst for the password , then click OK to log in to Query Analyzer. 9. Change the database drop-down edit box to your neighbors database. 10. Enter the following statements:
SELECT * FROM PS_SDK_RP_PO SELECT * FROM PS_SDK_RP_POLINE

Creating an Asynchronous-to-Synchronous Integration Point Using the Integration Point Wizard


To create an asynchronous-to-synchronous integration point using the Integration Point Wizard: 1. In the browser, select PeopleTools, Integration Broker, Node Definition. 2. Select your neighbors node. 3. Add inbound synchronous transaction for CUSTOMER_SYNCHRONOUS message with the reply message CUSTOMER_REPLY. 4. Set the logging level to Header and Detail. 5. Save the Transaction. 6. Select PeopleTools, Integration Broker, Integration Point Wizard. 7. Enter the following information:
Page Element Sending node Receiving Node Transaction Type Value or Status Your node Your neighbors node Async To Sync

8. Click Next. 9. Enter the following information:


Page Element Sender Node Request Message Version Value or Status CUSTOMER_ASYNC VERSION_1

460

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

10. Click Next. 11. Enter CUST_OAOS_TR for the request transformation. 12. Click Next. 13. Enter the following information:
Page Element Receiver Node Request Message Version Receiver Node Response Message Version Value or Status CUSTOMER_SYNCHRONOUS VERSION_1 CUSTOMER_REPLY VERSION_1

14. Click the Go to Advanced Page link. 15. Set Logging to Header and Detail and click Done. 16. Click Next. 17. Enter the following information:
Page Element Async Reply Message Version Transformation Value or Status ASYNC_CUST_REPLY VERSION_1 CUST_OAOS_RP

18. Click Next.

PeopleSoft Proprietary and Confidential

461

Working with Relationships

Lesson 16

Results The integration point summary will be displayed, ensure it is correct before clicking Finish:

Summary for asynchronous-to-synchronous integration 19. Click Finish.

Testing the Asynchronous-to-Synchronous Transaction


To test the Asynchronous-to-Synchronous transaction: 1. In the browser, select Customers, General Information. 2. Enter a new customer.
Page Element Customer Description Street City Country State Value or Status TESTxx (where xx is your workstation number) My Test Customer 25 My Street Anywhere USA NJ

3. Save the customer.

462

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

4. Check the Integration Broker Monitor to see if the subscription message for ASYNC_CUST_REPLY was received. Results The asynchronous reply is shown in the subscription contracts:

Subscription contract for ASYNC_CUST_REPLY received This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

463

Working with Relationships

Lesson 16

Maintaining Relationships
The Relationships component is used to maintain a relationship: Relationships created using the Integration Point Wizard are named WIZARD and the datetime created. You can change the description and add comments. The Trans Modifiers page has tab separators to display the initial message and the result message. Use the Edit link on the Trans Modifiers page to edit the transaction.

Slide 302 ______________________________________________________________________________________________________

Student Notes
Use the Relationships page to maintain relationships created using the Integration Point Wizard:
Page Name Relationships Navigation PeopleTools, Integration Broker, Relationships

Edit transaction modifiers page Note. You can inactivate a relationship. If a transaction is deleted in the node definition, the relationship will remain with no transaction modifiers for that transaction.

464

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Instructor Notes
Once you create a relationship, you can only maintain it in the Relationships component. If you try to create a new relationship for one that already exists, the Integration Point Wizard will not save it. If you add a new relationship using the Relationships component, you must first set up the transaction in the node definition.

PeopleSoft Proprietary and Confidential

465

Working with Relationships

Lesson 16

Maintaining Relationships (continued)


You also can create relationships using the Relationships component: The transaction must be entered in the node definition before creating the relationship. Indicate the initial node and the result node names. Add transaction modifiers using the Trans Modifiers page.

Slide 303 ______________________________________________________________________________________________________

Student Notes
Use the Relationships page to manually create new relationships:
Page Name Relationships Navigation PeopleTools, Integration Broker, Relationships, Add a New Value

Adding a new relationship

Instructor Notes
Question: Maintaining Relationships Relationships can be deleted. 1. True 2. False

466

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

467

Working with Relationships

Lesson 16

Activity 23:

Adding a Relationship Using the Relationship Component


In this activity, you will review the activity overview and add a relationship using the Relationships component. See Integration Tools: Activity Guide, lesson 16, Working with Relationships, Activity 23: Adding a Relationship Using the Relationship Component .

Slide 304 ______________________________________________________________________________________________________

Instructor Notes
In this activity, students set up the transaction and relationship with PSFT_HR for SCHOOL_SYNC. This transaction will be used in lesson 18 Testing Connector and Message Processing Using SendMaster. Do NOT change this to PSFT_EP because the transform program is NOT set up to work with that database. Note. This activity should take approximately fifteen minutes.

Activity Overview
In this activity, you will add a new relationship for the node PSFT_HR for the inbound asynchronous message SCHOOL_SYNC using the SCHOOL_IA_TR program.

Adding a Relationship Using the Relationships Component


To add a relationship using the Relationships component: 1. Select PeopleTools, Integration Broker, Node Definitions, PSFT_HR. 2. Add the Inbound asynchronous transaction for SCHOOL_SYNC. 3. Save the node definition. 4. Select PeopleTools, Integration Broker, Relationships, Add a New Value, Relationship ID: HCM. 5. Enter the following information:
Page Element Description Relationship Status Node Name Node Name Value or Status HCM relationships Active PSFT_HR PSFT_HR

6. Select Save.

468

PeopleSoft Proprietary and Confidential

Lesson 16

Working with Relationships

7. Click on the Trans Modifiers page. 8. Select Add Transaction Modifier. 9. Enter the following information:
Page Element Initial Node Request Message Name Source Request Message Version Transaction Type Result Node Request Message Name Target Request Message Version Value or Status PSFT_HR SCHOOL_SYNC VERSION_1 IA PSFT_HR SCHOOL_SYNC VERSION_1

10. Click Add. 11. Enter the following information:


Page Element Result transaction type Transformations Request Value or Status IA SCHOOL_IA_TR

12. Select Save. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

469

Working with Relationships

Lesson 16

Review
In this lesson, you learned that: Relationships are required when: The source node sends a message asynchronously, but the target expects to receive it synchronously. A hub configuration is used. One or more messages in a transaction need to be filtered, transformed, or translated upon sending or receiving. The Integration Point Wizard is used to simplify the process of creating relationships. The Integration Point Viewer is used to diagnosis any problems in a point-to-point integration. Relationships are maintained in the relationship component.

Slide 305 ______________________________________________________________________________________________________

470

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering


Objectives
By the end of this lesson, you will be able to: Describe Data Translation. Describe Codesets. Create a Codeset Group. Create a Codeset. Create Codeset values. Write a transform program for data translation. Describe filtering. Write a transform program for filtering.

Slide 307 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

471

Applying Translations and Filtering

Lesson 17

Describing Data Translation


Data translation is used to modify message content. It is used: When sending and receiving systems use different field values. When different combinations of fields and values are used to represent the same information.

Slide 308 ______________________________________________________________________________________________________

Student Notes
Listed below are some sample scenarios: Scenario 1 In this scenario the sending and receiving systems use different field values: Application A uses status codes of New, Open, Closed, Pending. Application B uses status codes of 1 (Initiated), 2 (Open), 3 (Closed). Scenario 2 Application A transmits customer names in four fields Title, First, Middle, Last. Application B uses two fields Last, First. It doesn't use a title, but includes the middle name as part of the First field. Application C uses only one field Name. It uses the format First, Last.

Instructor Notes
Clearly, the representation used by one application won't be understood by either of the other two. Integration Broker can apply a transform program to translate each of these representations into a version appropriate to the target application. Being able to transform a messages structure is extremely important, but what about being able to transform the data contained within that message? For instance, system A represents all of its purchase order status codes in an easily readable format, using words such as Open and Partial. On the other hand, system B represents all of its purchase order status codes as numerical values. If either of these systems were to pass along their own internal status codes within the messages, the receiving system would have no idea how to interpret it. This data value mapping which converts systems As status codes into system Bs can be easily achieved through the used of Codeset.

472

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Describing Data Translation (continued)


Data translation relies on a repository of codeset metadata comprised of the following elements: Codeset Group contains a list of significant data fields and their values that a particular node might send in an initial message. Codeset contains a specific set of match/name value pairs selected from the existing codeset group. Codeset Values contains the named value you predefine as the Return value. Translation program, which invokes the codeset and codeset values youve designed.

Slide 309 ______________________________________________________________________________________________________

Student Notes
Note. We will refer to these elements collectively as a codeset.

Instructor Notes
These elements are used to created metadata that can be reused for different data translations. A transformation can modify an entire message until it no longer resembles the original at all. So can a data translation. The difference is that you must hard code everything you want to accomplish in a transformation, whereas the data translation relies on a repository of codeset metadata that you define. This means you can establish consistent rule-based translations, and reuse the same data without having to re-enter it. You can combine transformation and data translation in a single transform step. It is recommended that you keep these processes in separate steps if possible, producing a modular program you can more easily maintain, and code you can reuse in other transform programs. Question: Describing Data Translation Data translations are used to modify the content of a message. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

473

Applying Translations and Filtering

Lesson 17

Describing Codesets
A codeset is a predefined mapping that will translate data values between multiple systems. By leveraging the codeset functionality, developers can solve the following: A direct one to one mapping. One to many mapping. Many to one mapping. Many to many mapping.

Slide 310 ______________________________________________________________________________________________________

Instructor Notes
The word codeset is often associated with character encoding, in our case however, a PeopleSoft Codeset is the predefined mapping that will translate data values between multiple systems. Codesets not only allow a developer the ability to create these simple one to one data value mappings, it allows gives them the opportunity to create much more complicated mappings. For instance, since system B represents all status codes as numerical values, it will need to convert all status codes to a readable format when communicating with system A. What if system A has offices all across the globe, with each of their software installations utilizing the local language? Would passing a status code of Open to one of the offices that was expecting Abierto really be of any benefit? No. To resolve this, the system B developer would not only have to use the status code, but a possible language code contained within the message. By using both of these values together, the appropriate system A status code can be generated.

474

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Describing Codesets (continued)


The following development sequence is used to define the elements for translation: 1. The codeset group must exist before you can define a codeset based on it. 2. A codeset and two groups must exist so you can define values associated with them. 3. A codeset and associated codeset values must exist before you can invoke them in your translation program.
Slide 311 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

475

Applying Translations and Filtering

Lesson 17

Describing Codesets (continued)


The diagram below depicts the relationship between codeset groups, codesets and codeset values:
Codeset Assigned to PSFT_T01(local) Codeset Group: TRAINING PO_STATUS PO_STATUS PO_STATUS TYPE TYPE C D O F T Codeset Assigned to PSFT_T02 Codeset Group: PARTICIPANT

Codeset : PO_STATUS PO_STATUS PO_STATUS PO_STATUS C D O

From Group: TRAINING Codeset Value:PO_STATUS To Group: PARTICIPANT PO_STATUS RTN_STATUS C CL

Codeset relationship
Slide 312 ______________________________________________________________________________________________________

Instructor Notes
In the diagram there are 2 codesets groups Training and Participant. Training is associated with the local node and Participant is the remote node. Since the transformation will take place on the local system, all possible values need to be entered. Specific codesets are then created from the codeset group. The codeset value is used for a specific mapping from a codeset group to a codeset group.

476

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Creating a Codeset Group


The Codeset group is used to maintain a list of the significant data fields and their values that a particular node might send in an initial message. The codeset group consists of name/value pairs. The name/value pairs are known as match names and match values. A codeset group needs to be created for each PeopleSoft node that will be participating in the data translation. Some of the codeset groups may not contain any name/value pairs.

Slide 313 ______________________________________________________________________________________________________

Instructor Notes
The Codeset group is used to maintain a list of the significant data fields and their values that a particular node might send in an initial message. These are name/value pairs a translation program might find (match) and use as the basis for determining what the result message should contain. These name/value pairs are known as match names and match values. You will need to create a codeset group for each PeopleSoft node that will be participating in the data translation. Some of the codeset groups may not contain any name/value pairs.

PeopleSoft Proprietary and Confidential

477

Applying Translations and Filtering

Lesson 17

Creating a Codeset Group (continued)


The codeset group is used with a specific node. The codeset group may contains several different match names and values. For example, the codeset group below includes the following: Match name TYPE is used to provide the values that will be associated with courses types. Match name PO_STATUS will be used to provide the values associated with a purchase order status. A match value of blank can be used to set up a default value when the codeset is defined.

Slide 314 ______________________________________________________________________________________________________

Student Notes
Use the Codeset Group page to create and maintain codeset groups:
Page Name Codeset Groups Navigation PeopleTools, Integration Broker, Codeset Groups

Code set group See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Applying Filtering, Transformation and Translation.

478

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Instructor Notes
The translate values for ORDER_STATUS are listed below:

Translate values for ORDER_STATUS The translate values for PO_STATUS are listed below:

Translate values for PO_STATUS

PeopleSoft Proprietary and Confidential

479

Applying Translations and Filtering

Lesson 17

Creating a Codeset Group (continued)


A codeset group is defined for each participating node. The codeset group for the node where the translation program is initiated will contain codeset values. The codeset group for the participating node will not contain any values.

Slide 315 ______________________________________________________________________________________________________

Student Notes
Some codeset groups may not contain any data:

Code set group for participating node

480

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Creating a Codeset Group (continued)


Every source and destination node involved in a data translation must belong to a codeset group: You must assign each participating node to an appropriate codeset group by an entry in its node properties. The assignment for each node is required only in the database of the node performing the data translation. The translating node does not need to be either the source or the target.

Slide 316 ______________________________________________________________________________________________________

Student Notes
Use the Node definition page to identify the node with a codeset group:
Page Name Node Definition Navigation PeopleTools, Integration Broker, Node Definition

Code Set Group is assigned to a node on the node definition page

Instructor Notes
The translating node may be a hub node where the message is routed before reaching its final destination.

PeopleSoft Proprietary and Confidential

481

Applying Translations and Filtering

Lesson 17

Creating a Codeset Group (continued)


The following diagram shows the association of codeset groups to nodes:

Codeset Group: TRAINING PO_STATUS PO_STATUS PO_STATUS TYPE TYPE C D O F T

List of Nodes PSFT_T01 (default local) PSFT_T02

Codeset Group: PARTICIPANT (this group may be empty)

Codeset groups are assigned to nodes


Slide 317 ______________________________________________________________________________________________________

Instructor Notes
Explain the diagram: There are 2 nodes defined in the database PSFT_T01 is the local node and uses the codeset group TRAINING. PSFT_T02 is a remote node using the codeset group PARTICIPANT. The transform program will be on PSFT_01 and the values will be translated using TRAINING codeset group. Question: Creating a Codeset Group Codeset groups are only created for the local node. 1. True 2. False Answer The answer is 2 (false).

482

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Creating Codesets
The Codeset is used to define a specific set of translations. Each codeset: Defines a specific set of match name/match value pairs selected from an existing codeset group. Determines the selected name/value pairs available for field value combinations in a message or translation program. Represents one set of fields among possibly many requiring translation for a given message.

Slide 318 ______________________________________________________________________________________________________

Student Notes
When creating codesets, keep the following in mind: The names should describe what the Codeset will accomplish and must be unique within a given Codeset Group. The same Codeset name can be used if it is associated with a different Codeset Group.

Use the Codesets page to create and maintain codesets:


Page Name Codesets Navigation PeopleTools, Integration Broker, Codesets

Codeset group

Instructor Notes
Codesets are built on a codeset group. The values must be selected from the codeset group. If you recall the codeset group contains multiple match names for this unique codeset PO_STATUS, only the PO_STATUS match name is being used.

PeopleSoft Proprietary and Confidential

483

Applying Translations and Filtering

Lesson 17

Codesets may include multiple match names, such as PO_STATUS and LANG (for language). Question: Creating Codesets Codesets are created from existing codeset groups. 1. True 2. False Answer The answer is 1 (true).

484

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Creating Codeset Values


A codeset value is a named value you predefine: Codeset values are unique to a relationship between nodes. A codeset values is also known as a return value. Each Codeset value needs to be defined by a description. The return name and return value define the value that will be used by the translation. The translation program can output the return value as a result of matching a specific combination of match values.

Slide 319 ______________________________________________________________________________________________________

Student Notes
Use the Codeset Values page to define the return name and value for each match name and value:
Page Name Codeset Values Navigation PeopleTools, Integration Broker, Codeset Values

Codeset values

Instructor Notes
When you add a new codeset, you need to define the: From Group

PeopleSoft Proprietary and Confidential

485

Applying Translations and Filtering

Lesson 17

Codeset Name To Group

For each permutation of match values selected from the codeset, you define a different combination of codeset values to apply to your result message. Point out that all of the values from the codeset are displayed. To define each return value, the student needs to add a new row, using the insert icon next to the description, enter the description, select the checkbox, then enter the return name and return value. Question: Creating Codeset Values Codeset values are unique to a relationship between nodes. 1. True 2. False Answer The answer is 1 (True).

486

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Activity 24:

Creating Codeset Groups, Codesets and Codeset Values


In this activity, you will review the activity overview and: 1. Create codeset groups. 2. Create a code set. 3. Create codeset values. See Integration Tools: Activity Guide, lesson 17, Applying Translations and Filtering, Activity 24: Creating Codeset Groups, Codesets and Codeset Values.

Slide 320 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately twenty minutes. Students can open the fields and look at the translate values if they want to see the description.

Activity Overview
In this activity, you will create a codeset group, codeset and codeset values for the purchase order status field. In the PSU purchase order application, the field ORDER_STATUS has associated translate values for the purchase order status. In the SDK PSU purchase order application, the field PO_STATUS has associated translate values for the purchase order status. The table below shows status and the associated translate values for ORDER_STATUS and PO_STATUS.
Status PSU_PO_HDR ORDER_STATUS translate value O P D C CAN H I IN SDK_RP_PO PO_STATUS translate value OPN PD DSP CL OT OT OT OT

Open Paid Dispatched Closed Cancelled Held Invalid Initial

Based on this criteria, create a codeset group, codeset and codeset values. Remember to associate the codeset group with the specific nodes.

PeopleSoft Proprietary and Confidential

487

Applying Translations and Filtering

Lesson 17

Creating Codeset Groups.


To create codeset groups. 1. Select PeopleTools, Integration Broker, Codeset Groups. 2. Select Add a New Value and enter TRAINING. 3. Click Add. 4. Enter five (5) rows using PO_STATUS as the match name and the following values for match value: blank C D O P

5. Save the page. 6. Click the Add button. 7. Enter PARTICIPANT for a new codeset group. 8. Click Add. 9. Save the page. 10. Select PeopleTools, Integration Broker, Node Definitions. 11. For your local node add TRAINING as the Codeset. 12. Save the node definition. 13. For your neighbors node add PARTICIPANT as the Codeset. 14. Save the node definition.

488

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Results The codeset Group should have five rows of data:

TRAINING codeset group

Creating a Codeset
To create a codeset: 1. Select PeopleTools, Integration Broker, Codesets. 2. Select Add a New Value. 3. Select TRAINING as the codeset group. 4. Enter PO_STATUS for the codeset name. 5. Click Add. 6. Use the prompt icon to select all 5 values that were defined for the codeset group. 7. Save the codeset. Results The codeset should have five rows of data:

PO_STATUS codeset

PeopleSoft Proprietary and Confidential

489

Applying Translations and Filtering

Lesson 17

Creating Codeset Values


To create codeset values: 1. Select PeopleTools, Integration Broker, Codeset Values. 2. Select Add a New Value. 3. Enter the following information:
Page Element From Group Code Set name To Group Value or Status TRAINING PO_STATUS PARTICIPANT

4. Click Add. 5. Select the checkbox for the first row with a value of blank. 6. Enter the following information:
Page Element Description Return Name Return Value Value or Status Default RTN_STATUS OT

7. Insert a new row. 8. Select the checkbox for the second row with a value of C. 9. Enter the following information:
Page Element Description Return Name Return Value Value or Status Closed RTN_STATUS CL

10. Insert three more rows for the remaining 3 values. a. Match to D.
Page Element Description Return Name Return Value Value or Status Dispatched RTN_STATUS DSP

490

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

b. Match to O.
Page Element Description Return Name Return Value Value or Status Open RTN_STATUS OPN

c. Match to P
Page Element Description Return Name Return Value Value or Status Paid RTN_STATUS PD

11. Save the page. Results The codeset values page should contain one row for each of the five matched values:

Codeset values for PO_STATUS from TRAINING to PARTICIPANT This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

491

Applying Translations and Filtering

Lesson 17

Writing a Transform Program for Data Translation


The following functions are available to extract values from the codeset. XSLT psft_function. PeopleCode FindCodeSetValues.

Slide 321 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleCode Reference, PeopleCode Built-in Functions.

492

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Writing a Transform Program for Data Translation (continued)


The psft_function is used to identify the codeset and match the value. Below is an example:
<psft_function name="codeset" codesetname="PO_STATUS"> <parm name="PO_STATUS"><xsl:value-of select="ORDER_STATUS"/></parm> <value name="RTN_STATUS" select="."/> </psft_function>

Slide 322 ______________________________________________________________________________________________________

Student Notes
The following attributes are used with the psft_function: name - codeset is the only name allowed in PeopleTools 8.4x. codesetname - name of the codeset the transformation engine will use in the lookup. Remember, the codeset group name is associated with the node definition. dest not required, but can be used to override the transactions destination PeopleSoft Node. source not required, but can also be used to override the transactions source PeopleSoft Node.

The following attributes are used with the parm: Name specifies the match name to use within the codeset. In this case PO_STATUS.

The following attributes are used with the value: name - contains the return name to use when processing the value node. select contains the Xpath to use when outputting data. CreateIfDNE used create a node if it does not exist CreateNodefrom value used to create a node from the value.

Instructor Notes
This section discusses the attributes:

Parm Contained within each psft_function node must be at least one parm node. A parm node acts as the vehicle for specifying the Match Name/Value pairs, which means there could

PeopleSoft Proprietary and Confidential

493

Applying Translations and Filtering

Lesson 17

be many of them contained within a psft_function node. The data contained within the parm node corresponds to the Match Value. value Just as the parm node, there must be at least one value node contained within the psft_function node. Without value nodes, the Transformation Engine would have no idea where to insert the returned data from the Codeset lookup. If there is more than one return value expected for a Codeset, make sure to create the necessary value nodes as needed. There are four attributes that can be utilized when using the value node: name This attribute contains the Return Name to use when processing the value node. In the example the Return Name specified for the Codeset was RET_TYPE. What this does is give the Transformation Engine the ability to uniquely determine where to use the data returned from the Codeset lookup. select This attribute contains the XPath to use when outputting the data. In most cases the XPath will be ., which means current working node. When the Transformation Engine encounters the ., it will replace the psft_function node with the returned data. Much more complex XPath expressions can be used here to determine where to generate the output. At any rate, the psft_function node will be removed after the second pass. createIfDNE This attribute can have two values, either yes or no. By default the value is no. If a value of yes is found, the Transformation Engine will create the nodes specified in the XPath. For example, if an XPath of ../Header/Address/Name is encountered, the Transformation Engine will create any part of that path that is not found and insert the Return Value there. createNodeFromValue This attribute can have two values as well, either yes or no. By default the value is no. If yes is found, the Transformation Engine will create a new node with the Return Value being used as the name. With an XPath of ../Header/Shipping and a Return Value of FedEx, the Transformation Engine will navigate through the XML Document using the XPath and create a node with the name of FedEx. Any child nodes found within a value node with this flag turn on will be appended to the newly created node.

494

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Activity 25:

Writing a Transform Program for Data Translation


In this activity, you will review the activity overview and: Add the psft_function to PO_TRANSFORM. Create a new purchase order. Verify the results.

See Integration Tools: Activity Guide, lesson 17, Applying Translations and Filtering, Activity 25: Writing a Transform Program for Data Translation.
Slide 323 ______________________________________________________________________________________________________

Instructor Notes
Mention that the transformation program worked without errors because the program did not execute edits on translate values. If you add the translate edit to the SDK_PO_SYNC subscription PeopleCode, the current version of the transform programs would produce an error on the receiving node. The script psft_function.txt is located in Z:\STAnnn\Tools\1022_IntTools\Scripts. Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will add the psft_function code to the application engine program PO_TRANSFORM to utilize the codeset values defined in the last activity. After you have saved the program, you will test the transaction and verify the results.

Adding psft_function
To add the psft_function to the PO_TRANSFORM program: 1. In Application Designer, select File, Open, Application Engine, PO_TRANSFORM. 2. Modify the XSLT action by adding the psft_function for PO_STATUS.
<PO_STATUS> <psft_function name="codeset" codesetname="PO_STATUS"> <parm name="PO_STATUS"><xsl:value-of select="ORDER_STATUS"/></parm> <value name="RTN_STATUS" select="."/> </psft_function> </PO_STATUS>

3. Save the code.

PeopleSoft Proprietary and Confidential

495

Applying Translations and Filtering

Lesson 17

Creating a New Purchase Order


To create a new purchase order: 1. In the browser, select Purchasing, Maintain Purchase Orders. 2. Add a new purchase order. Leave the Order status as the default value of Initial. 3. Save the change.

Verifying the Results


To verify the results: 1. Select Start, Programs, Microsoft SQL Server, Query Analyzer. 2. Enter satst for the login name ans password, then click OK to login. 3. Select your neighbors database in the database dropdown. 4. Enter the following statements:
SELECT * FROM PS_SDK_RP_PO SELECT * FROM PS_SDK_RP_POLINE

5. The order status will be OT since that was the default value if a match was not found. 6. In the browser, select Purchasing, Maintain Purchase Orders. 7. Select your last purchase order. 8. Change the order status to Closed. 9. Save the change. 10. Return to Query Analyzer. 11. Execute the statements again. This concludes the activity. Do not continue.

496

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Describing Filtering
Filtering is used to suppress an input message based on its content. Filtering: Must be included in a transform program. Can only be coded with PeopleCode. Typically is the first step in a transform program. Uses the XmlDoc and XmlNode classes.

Slide 324 ______________________________________________________________________________________________________

Instructor Notes
Messages entering the Integration Broker can be filtered using the Transformation Engine. If a developer chooses to filter out messages based on its data, they can achieve this via PeopleCode. If a message currently utilizes a transform the developer would simply need to add a PeopleCode step. This step will usually be placed as the first step in a transformation, but it is up to the developer to decide at which step filtering should occur.

PeopleSoft Proprietary and Confidential

497

Applying Translations and Filtering

Lesson 17

Describing Filtering (continued)


The relationship for the node transaction must indicate the transform program. For new integrations use the Integration Setup Wizard. For existing transactions use the relationship component.

Slide 325 ______________________________________________________________________________________________________

Student Notes
Use the transaction modifiers page of the relationship component is used to add a relationship for an existing transaction:
Page Name Relationships Navigation PeopleTools, Integration Broker, Relationships

Relationship for LOCATION_SYNC using a filter transform program See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Applying Filtering, Transformation and Translation

498

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Writing a Transform Program for Filtering


Filtering requires the following actions in your PeopleCode: 1. Retrieve the message content from the %TransformData system variable. 2. Examine the filtering criteria. 3. If the message meets your criteria, no further action is required. 4. If the message fails to meet your criteria, replace the entire message content with a single node called Filter, containing the reason for the failure. 5. Set the TransformData Status property to 1 to indicate failure.
Slide 326 ______________________________________________________________________________________________________

Student Notes
Below is a sample PeopleCode filter:
/* Get the data from the AE Runtime */ Local TransformData &incomingData = %TransformData; /* Set a temp object to contain the incoming document */ Local XmlDoc &tempDoc = &incomingData.XmlDoc; /* Find the COUNTRY*/ Local string &countryCode = &tempDoc.DocumentElement.FindNode("MsgData/Transaction/LOCATION_TBL/COUNTR Y").NodeValue; /* Make sure the country code is USA */ If &countryCode <> "USA" Then /* Clear out the doc and put in the "Filter" root node */ If (&tempDoc.ParseXmlString("<?xml version=""1.0""?><Filter/>")) Then &rootNode = &tempDoc.DocumentElement; /* Set the root node value to be the reason for failing filter */ &rootNode.NodeValue = "Country Code of '" | &countryCode | "' is not allowed."; /* Set the status of the transformation to 1 for failed filter*/ &incomingData.Status = 1; End-If; End-If;

PeopleSoft Proprietary and Confidential

499

Applying Translations and Filtering

Lesson 17

Instructor Notes
Review the actions in the code:

500

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Activity 26:

Applying Filtering
In this activity, you will review the activity overview and: Filter the LOCATION_SYNC message. Modify the PO_TRANSFORM program to include filtering.

See Integration Tools: Activity Guide, lesson 17, Applying Translations and Filtering, Activity 26: Applying Filtering.
Slide 327 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 15 minutes. There is a copy of the code located in Z:\STAnnn\Tools\1022_IntTools\Scripts \po_filter_pc.txt.

Activity Overview
In this activity, you will first create a relationship for LOCATION_SYNC to use the LOC_FILTER transform program and then modify the PO_TRANSFORM program to filter purchase orders so that purchase orders for CORPS are not sent.

Filtering the LOCATION_SYNC Message


To filter the LOCATION_SYNC message: 1. In the browser, select PeopleTools, Integration Broker, Relationships. 2. Add a new relationship LOCATION. 3. Enter the following information:
Page Element Description Relationship Status Initial node Result node Value or Status Location Filter Active Your neighbors node Your neighbors node

4. Select Save. 5. Select the Trans Modifiers tab. 6. Select Add Transaction Modifier. 7. Enter the following information:
PeopleSoft Proprietary and Confidential 501

Applying Translations and Filtering

Lesson 17

Page Element Initial Node Request Message Name Source Request Message Version Transaction Type Result Node Request Message Name Target Request Message Version

Value or Status Your neighbors node LOCATION_SYNC VERSION_1 OutAsync Your neighbors node LOCATION_SYNC VERSION_1

8. Click Add. 9. Enter the following information:


Page Element Result - Transaction Type Transformations - Request Value or Status OA LOC_FILTER

10. Select Save. 11. Select Set Up Training, Common Definitions, Locations, Location. 12. Select SetID:SHARE /Location Code: ALBERTA. 13. Add a new effective-dated row. 14. Enter Filter test in Address 2. 15. Select Save. 16. Select PeopleTools, Integration Broker, Monitor, Monitor Message. 17. Find the LOCATION_SYNC publication contract. 18. View the details. 19. View the error message. 20. Cancel the message.

502

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Results The error will be displayed in the Integration Broker Monitor:

Error message generated when the message does not meet the filter criteria

Modifying the PO_TRANSFORM program to include filtering.


To modify the PO_TRANSFORM program to include filtering: 1. In Application Designer, open the application engine program PO_TRANSFORM. 2. Click on the section Main. 3. Select Insert, Step/Action. 4. Click on the step name Step 02 and change the name to Filter. 5. Change the action type to PeopleCode. 6. Double-click on the action to open the PeopleCode editor. 7. Write the PeopleCode to filter the message so that any messages for the Business Unit CORPS will produce an error.
/* Get the data from the AE Runtime */ Local TransformData &incomingData = %TransformData; /* Set a temp object to contain the incoming document */ Local XmlDoc &tempDoc = &incomingData.XmlDoc; /* Find the BUSINESS_UNIT*/ Local string &BU = &tempDoc.DocumentElement.FindNode("MsgData/Transaction/PSU_PO_HDR/BUSINESS _UNIT").NodeValue; /* Check if the Business units is If &BU = "CORPS" Then /* Clear out the doc and put in the "Filter" root node */ CORPS */

PeopleSoft Proprietary and Confidential

503

Applying Translations and Filtering

Lesson 17

If (&tempDoc.ParseXmlString("<?xml version=""1.0""?><Filter/>")) Then &rootNode = &tempDoc.DocumentElement; /* Set the root node value to be the reason for failing filter */ &rootNode.NodeValue = "Business Unit of '" | &BU | "' is not allowed."; /* Set the status of the transformation to 1 for failed filter*/ &incomingData.Status = 1; End-If; End-If;

Note. You can copy the code from LOC_FILTER and modify it as necessary. 8. Save the application engine program. 9. In the browser, select Purchasing, Maintain Purchase Order. 10. Add a new order for Business Unit CORPS. 11. Save the purchase order. 12. Review the message in the message monitor. 13. Cancel the message. Results The error will be displayed in the Integration Broker Monitor:

Error message for purchase order with a business unit of CORPS This concludes the activity. Do not continue.

504

PeopleSoft Proprietary and Confidential

Lesson 17

Applying Translations and Filtering

Review
In this lesson, you learned that: Data translation is used to modify message content. Data translation relies on a repository of codeset metadata. A codeset is a predefined mapping that will translate data values between multiple systems. The Codeset group is used to maintain a list of the significant data fields and their values that a particular node might send in an initial message. The Codeset is used to define a specific set of translations. A codeset value is a named value that is unique to a relationship between nodes. A codeset values is also known as a return value. You can write a data translation program using either: XSLT psft_function. PeopleCode FindCodeSetValues.

Filtering is used to suppress an input message based on its content. Filtering programs are written using the XmlDoc and XmlNode classes.

Slide 328 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

505

Applying Translations and Filtering

Lesson 17

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

506

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master


Objectives
By the end of this lesson, you will be able to: Test FILEOUTPUT connector. Describe Send Master. Identify Send Master workspaces. Identify the Send Master project types. Create an input file project. Create an Integration Broker project.

Slide 330 ______________________________________________________________________________________________________

Instructor Notes
Now that students are familiar with sending application messages between PeopleSoft nodes, we will look at integrating with third parties. For third party integration, customers will probably use the JMS or HTTP connectors. Customers can also build their own custom connectors. PeopleSoft supplies a utility to test sending messages to third partiesSend Master.

PeopleSoft Proprietary and Confidential

507

Testing Connector and Message Processing Using Send Master

Lesson 18

Testing FILEOUTPUT Connector


The FILEOUTPUT connector allows you to send messages to a file output directory. The connector uses the following properties: SendUncompressed FilePath Password Method (optional)

Slide 331 ______________________________________________________________________________________________________

Student Notes
The properties are defined on the connectors tab for the node definition:

Connector properties for node FILEOUT

Instructor Notes
Point out that the file encryption utility is used to enter the password. The password is new in PeopleTools 8.44 as part of meeting the security standards. The password protects which file directories can be written to.

508

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Testing FILEOUTPUT Connector (continued)


The password must match password entered in the integrationgateway.properties for the file connector:
#File connector password. # Use the supplied encryption utility to provide an encrypted password for the entry below ig.fileconnector.password=lGAaGV+VdHM= #End of file connector properties.

Slide 332 ______________________________________________________________________________________________________

Instructor Notes
The file connector is the very last entry in the integrationGateway.properties file. In lesson 10 Configuring the Integration Broker students learned how to update the gateway properties using the Gateway component. The integrationGateway.properties file already has the password (123) encrypted. Question: Testing FILEOUTPUT Connector A password is required to use the FILEOUTPUT connector. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

509

Testing Connector and Message Processing Using Send Master

Lesson 18

Activity 27:

Testing FILEOUTPUT Connector


In this activity, you will review the activity overview and: Create a node using the FILEOUTPUT connector. Send a test message.

See Integration Tools: Activity Guide, lesson 18, Testing Connector and Message Processing Using Send Master, Activity 27: Testing FILEOUTPUT Connector.
Slide 333 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 10 minutes.

Activity Overview
In this activity, you will create a new node FILEOUT that uses the FILEOUTPUT connector. The FILEOUTPUT connector uses the password 123 and writes to the directory z:\STAnnn\TEMP. Add the outbound asynchronous transaction SCHOOL_SYNC and then test by changing an existing location.

Create a Node Using the FILEOUTPUT Connector


To create a node using the FILEOUTPUT connector: 1. Add a new node FILEOUT. 2. Enter the following information:
Page Element Description Node Type Routing Type Authentication option Value or Status File Output Node External Implicit None

3. Select the Connectors tab. 4. Enter the following information:


Page Element Connector ID SendUncompressed FilePath Value or Status FILEOUTPUT Y Z:\STAnnn\TEMP

510

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Page Element Password

Value or Status Encrypt 123

Note. You need to insert a new line in properties to add password. Use the encryption utility at the bottom of the page to encrypt the password. 5. Select the transactions tab. 6. Add the outbound asynchronous message SCHOOL_SYNC. 7. Save the node. Results The completed connectors page identifies three properties for the connector:

FILEOUT connect page

Sending a Test Message


To send a test message: 1. In the browser select Set Up Training, Common Definitions, School Details. 2. Add a school Gxx where xx is your workstation number. 3. Save the page. 4. Look in z:\<student folder>\temp for the file <node name>.SCHOOL_SYNC.<message instance>.xml:

PeopleSoft Proprietary and Confidential

511

Testing Connector and Message Processing Using Send Master

Lesson 18

Results The output file contains the XML message generated:

File created in student temp folder This concludes the activity. Do not continue.

512

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Describing Send Master


Send master is utility that enables you to test the overall message processing in the Integration Broker. It can test: Listening connector functionality. Target connector functionality. Transactions. Connector introspection. Stress test.

Slide 334 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Using Send Master to Test Message and Connector Processing.

Instructor Notes
Send Master is all JAVA It is used to mimic how PeopleSoft works Explain the following: Listening and target connector functionality Transactions Connector introspection Stress test

Listening connector functionality and Target Connect functionality Construct messages and send them over HTTP(S) to Web servers or PeopleSoft application servers to test target connector and listening connector functionality on the Integration Gateway. Send Master enables you to Post any data format, including the PeopleSoft MIME message format, to web and application servers over HTTP(s). GET is used to grab data off a website we will not be going over that piece in class. POST is used to simulate an inbound message. Integration Broker uses MIME documents this packages things up (if PS to PS). Most Mail systems all use MIME.

PeopleSoft Proprietary and Confidential

513

Testing Connector and Message Processing Using Send Master

Lesson 18

Transactions

Perform GET functions and ping application messaging gateways and third-party servers. Mimic sending messages to the Integration Broker, as well as messages you send from the Integration Engine to the Integration Gateway.

You can test specific transactions, including the transformations. Connector Introspection For Integration Broker projects, you can specify the target connector and connector properties to test. Stress Test You can also use Send Master to simultaneously test groups of different types of messages, as well as stress test your system. Automate the testing process by enabling you to create groups of different types of messages and test them with a click of a button. Stress test groups containing projects with a click of a button.

514

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Describing Send Master (continued)


To access Send Master, you must have the Integration Gateway installed. To open Send Master: In Windows launch the startsendmaster.bat located in %PS_HOME%/SENDMASTER. In UBIX launch startsendmaster.sh file located in the Integration Gateway directory.

Slide 335 ______________________________________________________________________________________________________

Student Notes
Note. In order to launch Send Master in a windows environment, PS_HOME must be set in the environment variables.

Instructor Notes
Point out the note the environment variable for PS_HOME must be set. Right-click My Computer, select Properties. On the Advanced tab, select Environment variables. Ensure that PS_HOME is included in the user variables and is set to the PS_HOME directory (for example C:\PT8.44). Question: Describing Send Master Send Master enables you to Post any data format: 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

515

Testing Connector and Message Processing Using Send Master

Lesson 18

Identifying Send Master Workspaces


The Send Master Workspaces has three main sections:
Section Project Definition Description Area where you add and define a new Send Master project. The information you specify in this section includes the Web server URL where you POST or GET messages. Area where you create and format MIME messages. Displays information returned when you perform a GET or POST on a Web server.

Input Information Output Information

Slide 336 ______________________________________________________________________________________________________

Student Notes
Send Master has three main sections:

Send Master

516

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Identifying Send Master Project Types


There are five types of Send Master Projects: Input File - enables you to test servers that are expecting XML data over HTTP(S). 8.4 Integration Broker (MIME) - enables you to test servers that are expecting MIME data in PeopleSoft format over HTTP(S). 8.4 Integration Broker (XML) - enables you to test servers that are expecting XML data in PeopleSoft format over HTTP(S). EIP Testing (Batch) enables test batches of messages from a file directory. MQSeries enables you to test and post synchronous and asynchronous messages to MQSeries queues.

Slide 337 ______________________________________________________________________________________________________

Student Notes
The type of communication you will be testing determines which project type to use. The table below shows which type to use:
To Test Using Integration Broker to send PeopleSoft 8.4 messages to: Other PeopleSoft 8.4 systems Remote PeopleSoft gateways Connector introspection. Communication to an Integration Gateway via connectors: 3rd-party systems PeopleSoft 8.1 systems Communications from a PeopleSoft 8.1 system to a PeopleSoft 8.4 system. Sending SOAP messages to a PeopleSoft 8.4 system. Target connectors that sit on the Integration Gateway. Listening connectors that use HTTP(s) to communicate. Communications from a third-party system to Integration Broker. Input File Input File Integration Broker Input File or Integration Broker. Input File Integration Broker Input File or Integration Broker. use this project type Integration Broker

PeopleSoft Proprietary and Confidential

517

Testing Connector and Message Processing Using Send Master

Lesson 18

Instructor Notes
Question: Identifying Send Master Project Type Which project type would you use to test sending SOAP messages to a PeopleSoft 8.4 system. 1. Input File 2. 8.4 Integration Broker (MIME) 3. 8.4 Integration Broker (XML) 4. EIP Testing (Batch) Answer The answer is 1 (input file).

518

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Creating an Input File Project


When you create an input file project, you must specify the header information, a sample header is shown below:
From: TEST To: QE_LOCAL MessageName: QE_SYNC_MSG MessageVersion: VERSION_1 MessageType: sync

Slide 338 ______________________________________________________________________________________________________

Instructor Notes
Question: Creating an input file project Headers are required for the input file. 1. True 2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

519

Testing Connector and Message Processing Using Send Master

Lesson 18

Activity 28:

Creating Send Master Projects


In this activity, you will review the activity overview and: Create a new node using HTTPTARGET connector. Create a new relationship. Create a Send Master project for an output file using HTTPConnector

See Integration Tools: Activity Guide, lesson 18, Testing Connector and Message Processing Using Send Master, Activity 28: Creating Send Master Projects.
Slide 339 ______________________________________________________________________________________________________

Instructor Notes
Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will test a synchronous message QE_SYNC_MSG in Send Master. The following definitions have been created in the Training Database:
Definition QE_SYNC_MSG QE_RESPONSE_MSG SYNC_XFRM SYNC_XFRMRSP Description Synchronous message Synchronous response message Transformation program to reformat the incoming synchronous message. Transformation program to reformat the response message

The test message is stored in z:\STAnnn\Tools\1022_IntTools\files\account.xml.


<?xml version="1.0"?> <ACCOUNT> <ID>26</ID> <NAME>Jason Franco</NAME> <ADDRESS>F18 HORNET WAY</ADDRESS> <PHONE>2065441264</PHONE> </ACCOUNT>

The transform programs used with this message are SYNC_XFRM and SYNC_XFRMRSP.

520

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Creating a New Node Using HTTPTARGET Connector


To create a new node using HTTPTARGET connector: 1. Add a new node TEST. 2. Enter the following information:
Page Element Description Node Type Routing Type Authentication option Value or Status Test HTTP Connector External Implicit None

3. Select the Connectors tab. 4. Enter the following information:


Page Element Connector ID HEADER - SendUncompressed HTTPPROPERTY - Method PRIMARYURL - URL Value or Status HTTPTARGET Y POST http://cteserver/test

Note. The URL is not valid, but we will only be testing inbound messages.

5. Select the transactions tab. 6. Add the inbound synchronous message QE_SYNC_MSG with the response message QE_RESPONSE_MSG. 7. Save the transaction. 8. Save the node.

Creating a new Relationship


To create a new relationship: 1. Add a new relationship NON_PS. 2. Enter the following information:
Page Element Description Value or Status Non PeopleSoft Node

PeopleSoft Proprietary and Confidential

521

Testing Connector and Message Processing Using Send Master

Lesson 18

Page Element Initial Node Requesting Node Transaction Type Request Message Request Message Version Result Message Result Message Version Result transaction Type Transformation Request Transformation Response

Value or Status TEST TEST InSync QE_SYNC_MSG VERSION_1 QE_SYNC_MSG VERSION_1 IS SYNC_XFRM SYNC_XFRMRSP

3. Save the relationship.

Creating a Send Master project for an output file using HTTPConnector


To create a Send Master project for an output file using HTTPConnector: 1. Open the PeopleTools folder on the desktop. 2. Double-click on the StartSendmaster icon. 3. Select File, New Project. 4. Enter the following information:
Page Element Project Name Project Type Value or Status qe_sync_account_nn Input file

Note. Since all students are using the same Send Master, you will be able to view other students projects. Make sure you add your workstation number to the end of your project name.

5. Click OK. 6. Enter the following information:


Page Element Server URL Value or Status http://cteserver.peoplesoft.com:1080/PSIGW/HttpListeningConnector

522

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Page Element Headers

Value or Status Content-Type: text/xml; charset=UTF8 From: TEST To: PSFT_Txx (where xx is your workstation) MessageName: QE_SYNC_MSG MessageVersion: VERSION_1 MessageType: sync

Input File

Z:\STAnnn\Tools\1022_IntTools\files\ACCOUNT_REQ.xml

The input file has the following format:


<?xml version="1.0"?> <ACCOUNT> <ID>26</ID> <NAME>Jason Franco</NAME> <ADDRESS>F18 HORNET WAY</ADDRESS> <PHONE>2065441264</PHONE> </ACCOUNT>

7. Select File, Save Project. 8. Click POST. Results The synchronous response message is displayed in the Output Information window:

Testing the HTTP connector in Send Master This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

523

Testing Connector and Message Processing Using Send Master

Lesson 18

Creating an Integration Broker Project


The Integration Broker project type can be used to test: Messages between PeopleSoft systems. Remote PeopleSoft gateways. Communication to an Integration gateway via connectors. Target connectors that sit on the Integration Gateway. Listening connectors that use HTTP(S) to communicate.

Slide 340 ______________________________________________________________________________________________________

524

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Creating an Integration Broker Project


To create integration broker project has four tabs to enter the input information: Headers and Headers cont. are used to enter all of the header information. Input File allows you to select the input file to test. Connector is used for introspection.

Slide 341 ______________________________________________________________________________________________________

Student Notes
The Input Information section allows you to enter the header information:

Integration Broker project headers

PeopleSoft Proprietary and Confidential

525

Testing Connector and Message Processing Using Send Master

Lesson 18

Activity 29:

Creating Integration Broker Projects in Send Master


In this activity, you will review the activity overview and: Create a transaction and add the transaction modifier. Create an Integration Broker Project in Send Master for a synchronous transaction. Create an Integration Broker Project in Send Master for an asynchronous transaction. Verify the asynchronous message in the message monitor.

See Integration Tools: Activity Guide, lesson 18, Testing Connector and Message Processing Using Send Master, Activity 29: Creating Integration Broker Projects in Send Master.
Slide 342 ______________________________________________________________________________________________________

Instructor Notes
The transaction and relationship for inbound transaction SCHOOL_SYNC was created in lesson 16 Working with Relationships Activity 26. Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will create Integration Broker Send Master projects for synchronous and asynchronous messages from other PeopleSoft 8.4 systems. In order for the Send Master project to work, the nodes and relationships must have been set up in PeopleSoft. Set up the appropriate transactions and relationships, then create the following send master projects: Create a transaction and add a transaction modifier. Create the transactions for the inbound synchronous transaction QE_SYNC_MSG for the node PSFT_HR. Add a transaction modifier to the relationship HCM for the QE_SYNC_MSG. The transformation programs used with the QE_SYNC_MSG are transformation request SYNC_XFRM and transformation response SYNC_XFRMRSP. Create an Integration Broker Project in Send Master for a synchronous transaction. The input file is located in z:\STAnnn\Tools\1022_IntTools\files\ACCOUNT_REQ.xml. Create an Integration Broker Project in Send Master for the asynchronous transaction SCHOOL_SYNC inbound from PSFT_HR. The input file is located in z:\STAnnn\Tools\1022_IntTools\files\IN_SCHOOL.xml.

526

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Creating a New Transaction and Adding the Transaction:


1. Select PeopleTools, Integration Broker, Node Definitions, PSFT_HR. 2. Add the inbound synchronous transaction for QE_SYNC_MSG, the response message is QE_RESPONSE_MSG. 3. Save the transaction. 4. Select PeopleTools, Integration Broker, Relationships, HCM. 5. Select Trans Modifiers tab. 6. Click Add Transaction Modifier. 7. Enter the following information:
Page Element Initial Node Requesting Node Transaction Type Request Message Request Message Version Result Message Result Message Version Transformation Request Transformation Response Value or Status PSFT_HR PSFT_HR InSync QE_SYNC_MSG VERSION_1 QE_SYNC_MSG VERSION_1 SYNC_XFRM SYNC_XFRMRSP

8. Click Save.

Creating an Integration Broker Project in Send Master for a synchronous transaction.


To create a Send Master Integration Broker Project for a synchronous transaction: 1. Open SendMaster. 2. Select File, New Project. 3. Enter the following information:
Page Element Project Name Project Type Value or Status qe_sync_ib_nn 8.4 Integration Broker (MIME)

4. Click OK. 5. Enter the following information:


PeopleSoft Proprietary and Confidential 527

Testing Connector and Message Processing Using Send Master

Lesson 18

Page Element Server URL Requesting Node Message name Message type Message Version Password Originating node Destination node

Value or Status http://cteserver.peoplesoft.com:1080/PSIGW/PeopleSoftListeningConnector PSFT_HR QE_SYNC_MSG Sync VERSION_1 PSFT PSFT_HR PSFT_Txx (where xx is your workstation)

6. Select the Input file tab. 7. Open the file z:\STAnnn\Tools\1022_IntTools\files\ACCOUNT_REQ.xml


<?xml version="1.0"?> <ACCOUNT> <ID>26</ID> <NAME>Jason Franco</NAME> <ADDRESS>F18 HORNET WAY</ADDRESS> <PHONE>2065441264</PHONE> </ACCOUNT>

8. Click POST. 9. You can select to view Raw Data, Metadata or Section 1. Try each of these.

528

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

Results The Raw Data shows the Mime document:

Raw data posted in MIME format

Creating an Integration Broker Project in Send Master for an Asynchronous Transaction.


To create an Integration Broker Project in Send Master for an asynchronous transaction: 1. Open SendMaster. 2. Select File, New Project. 3. Enter the following information:
Page Element Project Name Project Type Value or Status school_async_nn 8.4 Integration Broker (MIME)

4. Click OK. 5. Enter the following information:


Page Element Server URL Requesting Node Message name Value or Status http://cteserver.peoplesoft.com:1080/PSIGW/PeopleSoftListeningConnector PSFT_HR SCHOOL_SYNC

PeopleSoft Proprietary and Confidential

529

Testing Connector and Message Processing Using Send Master

Lesson 18

Page Element Message type Message Version Password Originating node Destination node

Value or Status async VERSION_1 PSFT PSFT_HR PSFT_Txx (where xx is your workstation)

6. Select the Input file tab. 7. Open the file z:\STAnnn\Tools\1022_IntTools\files\IN_SCHOOL_SYNC.xml 8. Click POST. 9. Select the <META Data> view. 10. Click the If Valid XML, format icon. Note the publication number. Results The Output Information displayed in formatted XML:

530

PeopleSoft Proprietary and Confidential

Lesson 18

Testing Connector and Message Processing Using Send Master

SCHOOL_ASYNC project

Verifying the Message


To verify the message: 1. Sign on to PeopleSoft Internet Architecture as PTINT. 2. Select PeopleTools, Integration Tools, Monitor, Monitor Message. 3. Access the Sub Contacts page and locate the publication id that matches SendMaster. This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

531

Testing Connector and Message Processing Using Send Master

Lesson 18

Review
In this lesson, you learned that: The FILEOUTPUT connector allows you to send messages to a file output directory. Send master is utility that enables you to test the overall message processing in the Integration Broker. It can test - listening connector functionality, target connector functionality and connector introspection. The Send Master Workspaces has three main sections project definitions, input information and output information. There are five types of Send Master Projects - Input file, Integration Broker (MIME), Integration Broker (XML), EIP Testing (Batch), and MQseries. The header information on the input file project identifies the message, nodes and message type to use. The Integration Broker project type can be used to test messages between PeopleSoft systems, remote PeopleSoft gateways, communication to an Integration gateway via connectors, target connectors that sit on the Integration Gateway or listening connectors that use HTTP(S) to communicate.

Slide 343 ______________________________________________________________________________________________________

532

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL


Objectives
By the end of this lesson, you will be able to: Describe Web Services. Describe the Actional SOAPswitch. Describe the Actional SOAPswitch Administration Console. Add a system. Add a Web service. Create routing data. Complete the integration. Import WSDL.

Slide 345 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

533

Creating Third-Party Integrations Using WSDL

Lesson 19

Describing Web Services


Web Services are XML applications mapped to programs, objects or databases: XML documents are created in the form of a message. A program sends a request to a web service across the network and optionally receives a reply also in the form of an XML document.

Slide 346 ______________________________________________________________________________________________________

Instructor Notes
A WSDL document is an XML file that contains information about interface, semantics and other details of a call to a Web Service. Web Services are small units of code designed to handle a limited set of tasks. A web service uses standard Internet protocols (for example XML, HTTP and SOAP) to communicate and exchange data with other applications over the Internet. The benefit is that a web service can be exposed to applications written in any language and hosted on any operating system.

534

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Describing Web Services (continued)


Web Services standards: Define the format of the message. Specify the interface to which the message is sent. Describe conventions for mapping the contents into and out of the programs implementing the service. Define mechanisms to publish and discover Web Services interfaces.

Slide 347 ______________________________________________________________________________________________________

Instructor Notes
Standards for web services are set by the World Wide Web Consortium (W3C). For more information, visit http://WWW.W3.ORG.

PeopleSoft Proprietary and Confidential

535

Creating Third-Party Integrations Using WSDL

Lesson 19

Describing Web Services (continued)


Web Services require several related XML-based technologies to transport and transform data into and out of programs and databases: XML (Extensible Markup language) WSDL (Web Services Description Language) SOAP (Simple Object Access Protocol) UDDI (Universal Description, Discovery, and Integration)

Slide 348 ______________________________________________________________________________________________________

Instructor Notes
WSDL is an XML based technology that defines Web services interfaces, data and message types, interaction patterns, and protocol mappings. SOAP is a collection of XML-based technologies that defines the envelope for Web services communication- mappable to HTTP and other transports- and provides a serialization format for transmitting XML documents over a network. UDDI is a Web registry and discovery mechanism that is used for storing and categorizing business information and for retrieving pointers to Web services interfaces.

536

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Describing Web Services (continued)


PeopleSoft provides the following capabilities for web services: ERP connectors (using the third-party Actional SOAPswitch). Ability to import WSDL. Ability to publish EIPs. WSDL Repository.

Slide 349 ______________________________________________________________________________________________________

Student Notes
Note. Loading ERP connectors is an option on the PeopleTools install. If you select to install ERP connectors, you will be prompted for a directory to load SOAPswitch.

Instructor Notes
In this lesson we will look at the Actional SOAPswitch and how it is used to integrate with third-party systems. Actional SOAPswitch is used for outbound transactions (your PeopleSoft system wants to get information or update a third-party system). PeopleSoft also provides the capability to manually import WSDL via a file or URL, to create integrations. These can be inbound or outbound, although inbound is more typical. Published EIPs can be used to expose PeopleSoft to third-party applications (inbound transactions for component interfaces and either inbound or outbound for messages). Published EIPs are covered in lesson 20. The WSDL repository stores all of the web services imported into PeopleSoft (either through SOAPswitch, a file or a URL).

PeopleSoft Proprietary and Confidential

537

Creating Third-Party Integrations Using WSDL

Lesson 19

Describing the Actional SOAPswitch


Actional SOAPswitch is a wizard-driven product that enables you to expose software functionality via web services. SOAPswitch: Generates WSDL for the web services. Accepts SOAP requests for these web services. Translates the requests into calls to the back-end system. Formats SOAP replies based on back-end system responses.

Slide 350 ______________________________________________________________________________________________________

Student Notes
Actional SOAPswitch delivers MySQL as the default database for event and audit logging.

Instructor Notes
SOAPswitch is delivered as part of PeopleTools 8.44. During the PeopleTools installation if you select to Load ERP connectors, you are prompted for the directory to load SOAPswitch. The default directory is C:\SOAPswitch. The Actional SOAPswitch expects SOAP over HTTP the SOAPswitch will then figure out how to set up the message based on the third-party (back-end system). Since PeopleSoft expects and sends messages in PeopleSoft Message format a transform program is necessary on the PeopleSoft side to transform the message to PeopleSoft format. The WSDL describes what the SOAP document needs to look like. The terminology used with PeopleSoft WSDL integrations is: Outbound transactions = integrations Inbound transactions = notifications.

538

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Describing the Actional SOAPswitch (continued)


Actional SOAPswitch is comprised of three main components: SOAPswitch Server Administration Console Web Services Viewer

Slide 351 ______________________________________________________________________________________________________

Student Notes
See PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Creating Third-Party Integrations Using WSDL.

Instructor Notes
This section discusses: SOAPswitch Listens for SOAP requests from web service customers and forwards the request to backend servers via SOAPswitch adapters. Administration Console Allows you to configure SOAPswitch to expose new web services, manage security, and monitor logging activity. Web Services Viewer Enables you to explore published web services and provide a directory of exposed web services, in WSDL format, for use by service customers/clients. SOAPswitch Server Administration Console Web Services Viewer

PeopleSoft Proprietary and Confidential

539

Creating Third-Party Integrations Using WSDL

Lesson 19

Describing the Actional SOAPswitch (continued)


The following adapters are provided with the Actional SOAPswitch product delivered with PeopleTools 8.44: J2EE Adapter Oracle Applications Database (OAP) Adapter SAP R/3 Adapter Siebel Adapter XML Adapter

Slide 352 ______________________________________________________________________________________________________

Student Notes
Note. Actional SOAPswitch uses the term adapter to refer to connector.

Instructor Notes
Table below shows adapter use:
Adapter J2EE Adapter Description Enables you to access Enterprise Java Beans (EJBs) and Java classes for SOAPswitch Web Services. This is used primarily for testing purposes. Enables you to access stored procedures, tables, and views from Oracle applications that run on Oracle 8i or 9i databases. Enables you to access R/3 Function modules and ALR IDOCs. Enables you to access the Siebel eBusiness 200 Enterprise Edition application components. Enables you to set up and access XML objects for use with SOAPswitch.

Oracle Applications Database (OAP) Adapter

SAP R/3 Adapter Siebel Adapter XML Adapter

540

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Describing the Actional SOAPswitch (continued)


To start SOAPswitch: In the windows environment, select Start, Programs, Actional SOAPswitch, Start SOAPswitch Server. In the UNIX environment, launch the file runsoapswitch located in <ERPConnector_Install_Dir>/bin.

Slide 353 ______________________________________________________________________________________________________

Instructor Notes
Once you have started SOAPswitch, you will see the icon on the toolbar to indicate that it is running.

PeopleSoft Proprietary and Confidential

541

Creating Third-Party Integrations Using WSDL

Lesson 19

Describing the Actional SOAPswitch (continued)


To stop SOAPswitch: In the windows environment, right-click on the SOAPswitch Server icon in the system tray and close it. In the UNIX environment, navigate to <ERPConnector_Install_Dir>/bin and enter: runsoapswitch.sh.stop.

Slide 354 ______________________________________________________________________________________________________

542

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Describing the Actional SOAPswitch (continued)


In order to login to SOAPswitch, you must supply ERP Connector API URL - 4400 and 8080 are the default ports to communicate with Actional SOAPswitch. UserId and password information admin is the default userID and password is the default password.

Note. The default information will be displayed on the page.


Slide 355 ______________________________________________________________________________________________________

Student Notes
Use the following navigation to access the ERP connectors page:
Page Name ERP Connectors Admin Navigation PeopleTools, Integration Broker, Web Services, ERP Connector Admin

ERP connectors administration page See Also PeopleTools 8.44 PeopleBook: PeopleSoft Integration Broker, Creating Third-Party Integrations Using WSDL.

Instructor Notes
The ERP Connector API URL is in the format:

PeopleSoft Proprietary and Confidential

543

Creating Third-Party Integrations Using WSDL

Lesson 19

http;//<machinename>:4400/ssw/api The userId and password can be changed using the change user id and change password checkboxes and entering the new information.

544

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Describing the Actional SOAPswitch Administration Console


Once you have the ERP Connector configured, you can the login to the Actional SOAPswitch Administration Console. The Getting Started wizard displays the steps: Step 1 Add a system Step 2 Add Roles and Users Step 3 Add Web Services

Slide 356 ______________________________________________________________________________________________________

Student Notes
The Actional SOAPswitch menu is displayed when you open the ERP connectors page:
Page Name ERP Connectors Navigation PeopleTools, Integration Broker, Web Services, ERP Connectors

Actional SOAPswitch

Instructor Notes
Systems define the back-end system that you want to use. Roles and users are optional and we will not cover them in this course (refer to the documentation). Web Services define the specific transactions to use with the system. Note. This course does NOT cover how to set up integrations with SAP, Oracle and Siebel. We do not have access to those systems. This information is NOT covered in PeopleBooks it is covered as part of the Actional SOAPswitch product. Actional SOAPswitch documentation should be used for specific integrations.

PeopleSoft Proprietary and Confidential

545

Creating Third-Party Integrations Using WSDL

Lesson 19

Actional SOAPswitch has its own menu in the left-hand navigation.


Menu Item Configuration Systems Consumer Systems Access Control Web Services Notifications Status & Alerts Auditing Event log Documentation Specify inbound asynchronous or synchronous transactions. Specify outbound asynchronous or synchronous transactions. Monitor SOAPswitch statistics Monitor specific operations for failure or invocation Monitor SOAPswitch for potential problems and events Access the SOAPswitch manuals online. Description Configure the ERP Connector. Identifies the back-end system to interact with SOAPswitch Specifies the destination that Actional SOAPswitch uses for notification.

546

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Describing the Actional SOAPswitch Administration Console (continued)


The Actional SOAPswitch Administration Console provides links to Actional documentation: SOAPswitch Manuals Available Adapter Guides

Slide 357 ______________________________________________________________________________________________________

Student Notes
Actional Documentation is provided online:

Actional SOAPswitch Documentation links

Instructor Notes
In this course we will not go into detail on all of the SOAPswitch options. We do not have access to external systems, however we have a java servlet that simulates an SAP customer transaction we will use the J2EE adapter to connect to this java servlet.

PeopleSoft Proprietary and Confidential

547

Creating Third-Party Integrations Using WSDL

Lesson 19

Adding Systems
To add a system: 1. Select PeopleTools, Integration Broker, Web Services, ERP Connectors. 2. Select Systems from the Actional menu. 3. Select the adapter type and use the wizard by clicking next.
Slide 358 ______________________________________________________________________________________________________

Student Notes
The installed adapters are displayed on the system definition page:

Adapters page

Instructor Notes
The available adapters are displayed. In the classroom you can only use J2EE or XML because they are general purpose. The other adapters would need a relationship with the third-party using that particular system. The J2EE allows us to access a Java class.

548

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Adding Systems (continued)


The second step identifies: System definition including a unique identifier. Application Server Login. Additional parameters.

Slide 359 ______________________________________________________________________________________________________

Student Notes
Each system requires a unique identifier:

System definition step 2

Instructor Notes
In this case we are naming our system PSFT_TEST.

PeopleSoft Proprietary and Confidential

549

Creating Third-Party Integrations Using WSDL

Lesson 19

Adding Systems (continued)


The third step is used to: Set environment. Add or change and environment variables.

Slide 360 ______________________________________________________________________________________________________

Student Notes
Environment variables can be edited, added or deleted:

Environment configuration

Instructor Notes
To change an environment variable, click on the variable and then edit it at the bottom of the page. Click Set when you are finished. To add a new variable enter the variable name and value on the bottom of the page, and then click Set. When you click Finish on the variables page, the system will show as successfully added if there were no errors.

550

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Depending on the type of system you are creating, the environment variables will be different. In this course, we do not cover what is needed for SAP, Oracle or Siebel implementations refer students to the Actional documentation. In the activity, we are using a Java servlet; therefore we need to indicate in the CLASSPATH where to find the servlet. The system also needs to know where to find Java (JAVA_HOME).

PeopleSoft Proprietary and Confidential

551

Creating Third-Party Integrations Using WSDL

Lesson 19

Adding a Web Service


There is a wizard that will guide you through adding a web service. To add a web service: 1. Select Web Services from the Actional menu. 2. Click Add. 3. Expand the folder for the system where you would like to add a web service. 4. Select the service and click Next.
Slide 361 ______________________________________________________________________________________________________

Student Notes
You can expand the system folders to select a web service.

Service implementation

Instructor Notes
Once the back-end system is created, SOAPswitch will be able to connect to the system and provide the classes and methods available in that system. In this case the java servlet contains the web services available. By expanding the Classes folder, you can see the services available to configure.

552

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Adding a Web Service (continued)


The web service wizard guides you through selecting: Methods. Protocol and security. Documentation. Importing the WSDL. Publishing the WSDL to PeopleSoft.

Slide 362 ______________________________________________________________________________________________________

Student Notes
Completed Web service:

PSFT_CUST_SERVICE Web service

Instructor Notes
The magnifying glass next to the web service in the status section, allows you to test the request. The magnifying glass shows the following page with try it links:

PeopleSoft Proprietary and Confidential

553

Creating Third-Party Integrations Using WSDL

Lesson 19

Web service viewer In the activity, students will complete all of the steps in the wizard. Note that the previous slide shows 9 steps in the wizard. The page shown in the student notes here is step 9.

554

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Creating Routing Data


Once a web service has been created and imported, it is added to the WSDL Repository. In order to use the web service, you need to create the routing data. The routing data includes: Node Definition use an existing node or create a new node. Message Name use an existing message or create a new message.

Slide 363 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access this page:
Page Name Service Details Navigation PeopleTools, Integration Broker, Web Services, WSDL Repository, click service details next to the desired web service.

Service details for PSFT_CUST_SERVICE

Instructor Notes
Once routing data has been created, you will see a delete next to the service.

PeopleSoft Proprietary and Confidential

555

Creating Third-Party Integrations Using WSDL

Lesson 19

Creating Routing Data (continued)


Once you click Create for the routing data, a wizard will guide you through creating the routing data: Step 1 Node Definition Step 2 Message Definition Step 3 Message Channel Step 4 Summary
Slide 364 ______________________________________________________________________________________________________

Student Notes
The wizard displays the steps:

Routing data wizard node definition page

Instructor Notes
In the activity, students will set up the routing data using a new node and message definition.

556

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Creating Routing Data (continued)


When the routing data has been entered, you can verify the data in the node definition: The node type is PIA and the routing type is Implicit. The connector is HTTPTARGET and the primary URL is the endpoint of the WSDL. The transaction includes override connector. The connector for the transaction is HTTPTARGET. The SOAPAction is the same as the SOAP Action header on the service details page. The primary URL is the endpoint of the WSDL.

Slide 365 ______________________________________________________________________________________________________

Student Notes
The routing data creates the appropriate transaction detail overrides for the connector:

Connector tab for the message QE_GET_CUST_LIST

Instructor Notes
The connector information shown on this page was created by the routing data wizard.

PeopleSoft Proprietary and Confidential

557

Creating Third-Party Integrations Using WSDL

Lesson 19

Completing the Integration


To complete the Web Service, you need to: Create transformations. Create the Relationship.

Slide 366 ______________________________________________________________________________________________________

Instructor Notes
The transformation program to convert the SOAP message to a PeopleSoft message needs to be written. The relationship for the participating nodes also needs to be defined.

558

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Completing the Integration (continued)


Once the integration is complete, you can test it though SOAPswitch: 1. Select PeopleTools, Integration Broker, Web Services, ERP Connectors. 2. Select Web services from the Actional SOAPswitch menu. 3. Check the appropriate Web service. 4. Click the magnifying glass icon. 5. Select try it next to the method.
Slide 367 ______________________________________________________________________________________________________

Student Notes
When you select to try the method, the generated SOAP document is displayed:

Try the operation: get_customer_list When you click Send SOAP request, you will see the results displayed at the bottom of the page:

PeopleSoft Proprietary and Confidential

559

Creating Third-Party Integrations Using WSDL

Lesson 19

SOAP reply

Instructor Notes
In the activity we will test using a page in PIA, however this is to point out that you can test from the SOAP switch and also view what the SOAP request looks like.

560

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Activity 30:

Creating a Web Service using Actional SOAPswitch


In this activity, you will review the activity overview and: Add a system. Add a web service. Create routing data. Verify the routing data. Create the relationship. Test the SOAPswitch transaction.

See Integration Tools: Activity Guide, lesson 19, Creating Third-Party Integrations Using WSDL, Activity 30: Creating a Web Service using Actional SOAPswitch
Slide 368 ______________________________________________________________________________________________________

Instructor Notes
There is one Actional Soapswitch for the classroom, therefore the instructor will start SOAPswitch and configure the system. Starting SOAPswitch To start SOAPswitch: 1. Log on to any student or instructor workstation. 2. Open the PeopleTools folder. 3. Double-click on SOAPswitch. You will only see the icon in the system tray on the workstation where you started SOAPswitch. If you log off this workstation, SOAPswitch will stop. Adding a System The system can only be added once because it is defined in SOAPswitch not the individual database. Students can then create their own service. Note. This activity should take approximately thirty minutes.

When you complete the web service, students will see that it was successfully created.

PeopleSoft Proprietary and Confidential

561

Creating Third-Party Integrations Using WSDL

Lesson 19

Confirmation page The WSDL then needs to be imported:

WSDL name and content

Activity Overview
In this activity, you will add a system and web service for retrieving a customer list. Since we do not have access to any third-party systems in the classroom, you will be connecting to a java servlet JavaCustomerServer.jar. This servlet simulates retrieving a customer list from an SAP system.

Adding a System
To add a system: 1. Close all browser sessions.

562

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Note. The instructor will perform steps 2 through 18. 2. Open the PeopleTools folder and Double-click on SOAPswitch. 3. Click the PeopleSoft PeopleTools [844] link and signon as PTINT. 4. Select PeopleTools, Integration Broker, Web Services, ERP Connectors Admin. 5. Change the localhost in the URL to CTESERVER.. 6. Click Save. 7. Select PeopleTools, Integration Broker, Web Services, ERP Connectors. 8. Select Systems from the Actional menu and click the Add button. 9. Select the adapter type J2EE then click Next. 10. Enter PSFT_TEST for the Identifier then click Next. 11. Select the Use Custom Environment radio button. 12. Select CLASSPATH. 13. On the bottom of the page add the following path to the CLASSPATH (all paths are separated with a semicolon). Z:\JavaCustomerServer.jar. 14. Click Set. 15. Add a new variable JAVA_HOME in the variable edit box. 16. Enter the path to the jdk file in the SOAPswitch directory: z:\soapswitch\j2sdk1.4.1_02. 17. Click Set. 18. Click Finish. Results

System has been successfully added

Adding a Web Service


To add a web service:

PeopleSoft Proprietary and Confidential

563

Creating Third-Party Integrations Using WSDL

Lesson 19

1. Click the PeopleSoft PeopleTools [844] link and signon as PTINT. 2. Select PeopleTools, Integration Broker, Web Services, ERP Connectors. 3. Select Web Services from the Actional menu. 4. Click Add. 5. Expand the folder for PSFT_TEST. 6. Expand the Class folder. 7. Expand the CustServer folder. Note. If you do not see the CustServer folder, the CLASSPATH variable was not properly set to the location of the jar file. 8. Click on CustomerServerImpl service. 9. Click Next. 10. Enter the following information:
Page Element Service Name Value or Status Tnn_CUST_SERVICE Where nn is your workstation number. Category Description CUSTOMER Test

11. Click Next. 12. Select the Methods checkbox. 13. Click Next. 14. Select the HTTP without Authentication radio button. 15. Click Next. 16. Click Next to accept the defaults. 17. Click Next for step 6. 18. Enter the following as Free Text test documentation. 19. Click Next for step 7. 20. Click Next for step 8. 21. Make sure both checkboxes are checked. These will activate and monitor the web service. 22. Click Finish.

564

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

23. The confirmation page will be displayed. 24. Click Publish to PeopleSoft. 25. The WSDL name and content are displayed. 26. Click Import. 27. If the WSDL has been successfully imported, you will be transferred to the WSDL Repository page. Results The completed Web service is displayed:

WSDL repository page

Creating Routing Data


To create routing data: 1. Click on Service Details. Note. If you closed the previous page, select PeopleTools, Integration Broker, Web services, WSDL Repository. 2. Click the Create link for add_customer. 3. Select the Create a New Node Definition radio button. 4. Enter the following information:
Page Element Node name Description Authentication Option Value or Status SSW_TEST Test SSW None

5. Click Next. 6. Select the Use Exiting New Message button for both the request and response messages. 7. Enter the following information:
Page Element Value or Status

PeopleSoft Proprietary and Confidential

565

Creating Third-Party Integrations Using WSDL

Lesson 19

Page Element Request Message Name Request Version Response Message Response Version

Value or Status QE_ADD_CUST VERSION_1 QE_ADD_CUST_RESPONSE_SSW VERSION_1

8. Click Next. 9. Select the existing message channel WEB_SERVICES. 10. Click Next. 11. Review the summary page. 12. Click Finish. 13. Click OK on the operation successful dialog box. 14. Create the routing data for get_customer_list using the information below:
Page Element Existing Node Request Message Response Message Value SSW_TEST QE_GET_CUST_LIST QE_GET_CUST_LIST_RESPONSE

Results After the routing data has been created, you will see a delete link for the operations:

566

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Service details page Note. Note the endpoint and Soap Action for CustomerServerImpl1.

Verifying the Routing Data


To verify the routing data: 1. Select PeopleTools, Integration Broker, Node Definition. 2. Open the node SSW_TEST. 3. The node type is PIA and the routing type is Implicit. 4. Select the Connectors tab. 5. The connect ID is HTTPTARGET and the primary URL is the endpoint of the WSDL. 6. Click on the Transactions tab. 7. Click Edit next to the QE_ADD_CUST message. 8. On the transactions detail tab verify that the override connector checkbox is selected. 9. Click on the Connectors tab. 10. The status is Active, the primary URL is the endpoint of the WSDL and the SOAPAction is the same as the SOAP Action on the service details page.

Creating the Relationship


To create the relationship: 1. Select PeopleTools, Integration Broker, Relationships.

PeopleSoft Proprietary and Confidential

567

Creating Third-Party Integrations Using WSDL

Lesson 19

2. Add a new relationship CUSTOMER with the following information:


Page Element Description Relationship Status Node Name Node Name Value or Status SSW Customer test Active SSW_TEST SSW_TEST

3. Select Save. 4. Click on the Trans Modifiers page. 5. Select Add Transaction Modifier. 6. Enter the following information:
Page Element Initial Node Request Message Name Source Request Message Version Transaction Type Result Node Request Message Name Target Request Message Version Value or Status SSW_TEST QE_ADD_CUST VERSION_1 OS SSW_TEST QE_ADD_CUST VERSION_1

7. Click Add. 8. Enter the following information:


Page Element Result transaction type Transformations Request Value or Status OS QE_CSTLSTRSP

9. Click Save. 10. Select Add Transaction Modifier. 11. Enter the following information:
Page Element Initial Node Request Message Name Source Request Message Version Value or Status SSW_TEST QE_GET_CUST_LIST VERSION_1

568

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Page Element Transaction Type Result Node Request Message Name Target Request Message Version

Value or Status OS SSW_TEST QE_GET_CUST_LIST VERSION_1

12. Click Add. 13. Enter the following information:


Page Element Result transaction type Transformations Request Transformations Response Value or Status OS QE_CSTLSTRSP QE_CSTLSTRSP

14. Click Save.

Testing the SOAPswitch transaction


To test the SOAPswitch transactions: 1. Select Int Tools Samples, Get Customer List. 2. Click the Get Customer List push button. 3. The list will be displayed (there are five customers). 4. Add a customer. 5. Click the Add Customer push button. 6. Click the Get Customer List push button and your new customer will be displayed.

PeopleSoft Proprietary and Confidential

569

Creating Third-Party Integrations Using WSDL

Lesson 19

Results Your new customer ( as well as those added by your classmates) will be displayed:

New customers will be displayed This concludes the activity. Do not continue.

570

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Importing WSDL
WSDL can also be imported from a file or URL. To import WSDL: 1. PeopleTools, Integration Broker, Web Services, Import WSDL. 2. Select the file or URL. 3. Select the appropriate Load button. 4. Enter a name for the WSDL. 5. Click the Import button.
Slide 369 ______________________________________________________________________________________________________

Student Notes
The WSDL content will be displayed:

Import WSDL page

Instructor Notes
In the first part of this lesson, we saw how to import the WSDL that was created from an ERP adapter. WSDL can also be imported from a file or URL you do not have to use SOAPswitch. Typically you would import WSDL to create inbound transactions with a third-party. The WSDL is exposing the properties and methods that can be used.

PeopleSoft Proprietary and Confidential

571

Creating Third-Party Integrations Using WSDL

Lesson 19

The name entered for the WSDL is that name that will be available in the WSDL Repository.

572

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Importing WSDL (continued)


The imported WSDL will display: The available operations. A link to create the service.

Note. Services details are displayed after you click import. The services details can also be accessed from the WSDL Repository.
Slide 370 ______________________________________________________________________________________________________

Instructor Notes
The operation is added to the WSDL repository. The endpoint is the URL that is the URL for the participating system. The service details show the methods available:

Service details Example displayed above may be confusing to students at this point in time, which is why it is in the instructor notes only. To recreate the file for importing into your training database: 1. Open a browser for FSCM. 2. Select PeopleTools, Integration Broker, Web Services, Published EIPs. 3. Select the Component Interface ORDER_TRACK_QUERY and view the WSDL. 4. Save the WSDL as z:\STAnnn\1022_IntTools\files\ORDER_TRACK_QUERY.wsdl. 5. Sign off.

PeopleSoft Proprietary and Confidential

573

Creating Third-Party Integrations Using WSDL

Lesson 19

6. On your training database, select PeopleTools, Integration Broker, Web Services, Import WSDL. 7. Name the WSDL ORDER_TRACKING. 8. Import the WSDL from the file z:\STAnnn\1022_IntTools\files\ORDER_TRACK_QUERY.wsdl. There is no activity for importing WSDL because you will really import from a thirdparty and not another PeopleSoft node.

574

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Importing WSDL (continued)


Imported WSDL require the same set up as WSDL imported using the SOAPswitch: Create the routing data. Create transformations. Create the Relationship.

Slide 371 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

575

Creating Third-Party Integrations Using WSDL

Lesson 19

Review
In this lesson, you learned that: Web services are XML applications mapped to programs, objects and databases. Web services use the following XML-based technologies to transport and transform data into and out of programs and databases: XML WSDL SOAP UDDI

Actional SOAPswitch is a third-party product that provides ERP adapters enabling you to create WSDL and integration points. Act ional SOAPswitch is delivered with PeopleTools 8.44.

Slide 372 ______________________________________________________________________________________________________

576

PeopleSoft Proprietary and Confidential

Lesson 19

Creating Third-Party Integrations Using WSDL

Review (continued)
In this lesson, you learned that (continued): The Actional SOAPswitch administration console is used to create and administer integrations with third-party systems. A system is the endpoint of the integration. A web service defines the transactions with the third-party system. The routing data defines the transaction with the third-party system on the node definition. To complete the integration, the appropriate transform programs, and relationships. WSDL can be imported from URLs and files.

Slide 373 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

577

Creating Third-Party Integrations Using WSDL

Lesson 19

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

578

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs


Objectives
By the end of this lesson, you will be able to: Describe PeopleSoft published EIPs. Generate WSDL from component interfaces and messages. List the definitions used with Component Interface WSDL bindings. Define the third-party node. Generate WSDL for Component Interfaces. Send a SOAP Message to PeopleSoft.

Slide 375 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

579

Using PeopleSoft Published EIPs

Lesson 20

Describing PeopleSoft Published EIPs


PeopleSoft Enterprise Integration Points (EIPs) are published for all PeopleSoft Component Interfaces and messages allowing PeopleSoft Web services to be available to third-party systems: WSDL is available for all component interface methods. WSDL is available for messages based on the message and node.

Slide 376 ______________________________________________________________________________________________________

Instructor Notes
In the last lesson, you looked at PeopleSoft integration with third-party systems via web services giving PeopleSoft access to the data in the third-party system. The published EIPs provide a way for the third-party system to access data in the PeopleSoft system. From the PeopleSoft prospective these will be inbound transactions. In lesson 7 Building Component Interface APIs, you looked at how third-parties can access PeopleSoft data using COM, Java and C/C++. In lesson 8 Using the Excel to CI Utility you looked at how SOAPTOCI is used with Excel spreadsheets. The web services for component interfaces uses the same SOAPTOCI technology that is used with Excel to CI. For messages, the WSDL is more specific and includes the specific node for the transaction. The node and transaction must be defined in PeopleSoft before the WSDL is available. Question: Describing PeopleSoft Published EIPs A published EIP is a Web service? 1. True 2. False Answer The answer is 1 (true).

580

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Generating WSDL From Component Interfaces and Messages


PeopleSoft Integration Broker enables you to generate WSDL documents from: PeopleSoft Component Interfaces PeopleSoft Messages

Slide 377 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

581

Using PeopleSoft Published EIPs

Lesson 20

Generating WSDL From Component Interfaces and Messages (continued)


To generate WSDL from a component interface: 1. Select PeopleTools, Integration broker, Web Services, Published EIPs. 2. Select the Component Interface option. 3. Enter the Component Interface name or description. 4. Click Search. 5. Click the Web service desired.
Slide 378 ______________________________________________________________________________________________________

Student Notes
A Web services to CI section opens at the bottom of the page and lists the items that match the search:

Web services to CI for STU_PROFILE_2 Note. Only the methods for which the user has been granted security access will appear.

Instructor Notes
Point out that when you create the WSDL it is based on the security access granted to the user. If the method you wish to access do not appear, you will need to either grant security access or generate the WSDL with a different user login.

582

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Generating WSDL From Component Interfaces and Messages (continued)


The generated WSDL is displayed when your click the WSDL link: The WSDL includes all the component interface methods. The WSDL describes how the third-party accesses the component interface. Based on the WSDL, the third-party must generate their SOAP document to interface with PeopleSoft.

Slide 379 ______________________________________________________________________________________________________

Student Notes
The WSDL link displays the generated WSDL:

WSDL for STU_PROFILE_2

Instructor Notes
Note that the WSDL describes how the third-party interfaces with PeopleSoft. Note. There are third-party products such as XMLSpy that can be used to generate a SOAP document from the WSDL file. Refrain from naming products as they change frequently.

PeopleSoft Proprietary and Confidential

583

Using PeopleSoft Published EIPs

Lesson 20

Generating WSDL From Component Interfaces and Messages (continued)


To generate WSDL from a PeopleSoft Message: 1. Select PeopleTools, Integration Broker, Web Services, Published EPIs. 2. Select the Message option. 3. Enter the node and message. 4. Click Search. 5. Click the web service desired.
Slide 380 ______________________________________________________________________________________________________

Student Notes
Note. The message transaction must exist on the node definition in order to create the WSDL.

After selecting the node, you can see the transactions available:

Published EIPs for the node PSFT_EP

Instructor Notes
Question: Generating WSDL From Component Interfaces and Messages WSDL can be generated for any PeopleSoft component interfaces or messages. 1. True

584

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

2. False Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

585

Using PeopleSoft Published EIPs

Lesson 20

Listing the Definitions Used with Component Interface WSDL Bindings


WSDL binding with component interfaces use the following PeopleSoft delivered definitions: Message SOAPTOCI. Message Channel IBCHNL. The Local gateway must be configured with the default server information.

Slide 381 ______________________________________________________________________________________________________

Student Notes
Note. The SOAP document does not specify a destination node; therefore the gateway must forward the message to the default application server as specified in the integrationGateway.properties file. See Integration Tools lesson 10 Configuring PeopleSoft Integration Broker Configuring an Integration Gateway.

Instructor Notes
PeopleSoft delivers the message SOAPTOCI all component interfaces using web services will be received on this message. The message is set up on the message channel IBCHNL. Remember that component interfaces will always be synchronous transactions with the third party system. If the third-party was using the WSDL to create a web service, but not using the SOAPTOCI message, you would not have to configure the nodes and transactions but in this example, we will use the PeopleSoft delivered message with the CI. The incoming message does not include a destination node. It is posted to the HttpListeningConnector on the gateway; therefore it uses the default node that was configured in the integrationGateway.properties file. Point out the following: Check in Application Designer that the message SOAPTOCI is active. Check that the message channel IBCHNL is running.

Question: Listing the Definitions Used with Component Interface WSDL Bindings A message definition needs to be created for each component interface that uses a WSDL binding. 1. True 2. False

586

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Answer The answer is 2 (false the same message SOAPTOCI is used for all component interfaces).

PeopleSoft Proprietary and Confidential

587

Using PeopleSoft Published EIPs

Lesson 20

Defining the Third-Party Node


The third-party node that participates in the transaction needs to de defined with the following: Node type will be External and the routing type Explicit. The connector is HTTPTARGET. Connector properties need to include the header properties of Content-Type and SOAPAction. The content-type is text/xml and the SOAPAction will be blank.

Slide 382 ______________________________________________________________________________________________________

Student Notes
Example connector tab for a third-party node using component interface WSDL for integration:

Connectors tab for node definition page

Instructor Notes
After selecting the connector ID, the properties will appear. You need to add rows for Content-Type and SOAPAction, the other rows will default. You will need to add the value for the URL.

588

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Defining the Third-Party Node (continued)


The transactions for the third-party node need to include: Inbound synchronous transaction SOAPTOCI. The response message for both the inbound transaction is SOAPTOCI.

Slide 383 ______________________________________________________________________________________________________

Student Notes
Inbound and outbound synchronous transactions for SOAPTOCI are included in the node definition:

Transactions for the third-party node

Instructor Notes
Make sure that the transactions are active. If the message has been inactivated in Application Designer, it will have an inactive status. Question: Defining the Third-Party Node The third-party node in a component interface WSDL binding uses what connector? 1. PSFTTARGET 2. HTTPTARGET 3. FILEOUTPUT 4. FTPTARGET Answer The answer is 2 (HTTPTARGET).

PeopleSoft Proprietary and Confidential

589

Using PeopleSoft Published EIPs

Lesson 20

Generating WSDL for Component Interfaces


The WSDL for component interfaces can be created by either using the Published EIPs or by accessing the iScript directly. To access the WSDL directly through a URL string, use the following format:
http://servername:port/psc/ps/PORTAL_TEMPLATE/LOCAL_NODE/s/WEBLIB_SOAPTOCI .WSDLSUMMARY.FieldFormula.IScript_WSDLDiscovery?userid=USER&password=PASS& disconnect=y&postDataBin=y&APIName=CI_NAME

Slide 384 ______________________________________________________________________________________________________

Student Notes
An example of a URL string is shown below: http://plecbf28/psc/ps/EMPLOYEE/PSFT_TRN/s/WEBLIB_SOAPTOCI.WSDLSUMM ARY.FieldFormula.IScript_WSDLDiscovery?userid=PTTRN&password=PTTRN&disc onnect=y&postDataBin=y&APIName=STU_PROFILE_2

WSDL using a URL string

Instructor Notes
Remember when you are generating the WSDL, it is for the third-party to use. By providing the third-party with the URL, they can access the WSDL. Question: Generating WSDL for Component Interfaces There are two methods of generating WSDL for component interfaces. 1. True 2. False

590

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Answer The answer is 1 (true).

PeopleSoft Proprietary and Confidential

591

Using PeopleSoft Published EIPs

Lesson 20

Sending a SOAP Message to PeopleSoft


The SOAP doc will include the security information to access the component interface. Below is a sample SOAP document:
<?xml version="1.0"?> <SOAP-ENV:Envelope SOAPENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding" xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header> <Security_Request> <Username>PTINT</Username> <Password>PTINT</Password> </Security_Request> </SOAP-ENV:Header> <SOAP-ENV:Body> <FIND__CompIntfc__STU_PROFILE_2> <STUDENT_ID></STUDENT_ID> <STUDENT_NAME></STUDENT_NAME> <CUSTOMER_ID>AAB</CUSTOMER_ID> </FIND__CompIntfc__STU_PROFILE_2> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Slide 385 ______________________________________________________________________________________________________

Instructor Notes
This section discusses how to: Explain the SOAP doc Question on Sending a SOAP Message to PeopleSoft Example of how to view a soapdoc from ExcelToCI

Explaining the SOAP doc Note. We are not showing students how to create a soap doc from the WSDL there are 3rd party products that will do this. The WSDL document contains all of the methods in this example we are doing a Find, so that is the only element we need to use with the associated find keys. If you look at the very end of the WSDL, you will see the security request information.

592

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Question: Sending a SOAP Message to PeopleSoft The SOAP document to access a component interface needs to include the security request. 1. True 2. False Answer The answer is 1 (true). Viewing the SOAP doc in ExcelToCI The SOAP document is similar to the SOAP document that is generated and sent to PeopleSoft when using the Excel to CI Utility. Below are the steps you can take to see the actual SOAP doc that is generated and sent to PeopleSoft from Excel. Note. This is not a scripted activity and the soap document produced will not necessarily work as shown. It is provided here as instructor information. Instructors can choose whether or not they want to share this information with students. To view the SOAP doc created: 1. Open one of your existing ExcelToCI spreadsheets: 2. Select Tools, Marcos, Visual Basic Editor. 3. In the project area, double click on StagingAndSubmission.

Project 4. Click in the code section 5. Select Tools, Find look for xDoc.xml in the current module. 6. On the line that contains xDoc.xml click F9 to set a breakpoint 7. Select View, Immediate window

PeopleSoft Proprietary and Confidential

593

Using PeopleSoft Published EIPs

Lesson 20

8. Type ?xDoc.xml in the immediate window. 9. Click Alt F11 9TO VIEW THE Excel spreadsheet) 10. Submit the data on the Excel 11. Click on the question mark and hit ENTER you will see the soapdoc in the immediate window.

SOAP doc displayed Note. In the document created in ExcelToCI, you do not have the security information because it was sent when you entered the userID and password.

594

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Activity 31:

Testing Component Interface WSDL Binding


In this activity, you will review the activity overview and: Create an external node. Review the published WSDL for STU_PROFILE_2. Use Send Master to test the component interface.

See Integration Tools: Activity Guide, lesson 20, Using PeopleSoft Published EIPs, Activity 31: Testing Component Interface WSDL Binding.
Slide 386 ______________________________________________________________________________________________________

Instructor Notes
Make sure that you set up the node on the instructor database. If you do not, then change the gateway.properties file to point to a different default application server where the node has been configured. If all students get this message, the node was not set up on the default app server:

Unable to find the requesting node Note. This activity should take approximately twenty minutes. Point out in the activity overview that the goal of this activity is to create an inbound web service that will query PS to search for students who work from an arbitrary customer (AAB) by calling the "find" method of the CI as a web service. For students who want to explore this further, they can change the customer in the SOAP document to find other customers.
<?xml version="1.0"?> <SOAP-ENV:Envelope SOAPENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding" xmlns:SOAPENC="http://schemas.xmlsoap.org/soap/encoding" xmlns:SOAPENV="http://schemas.xmlsoap.org/soap/envelope" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Header> <Security_Request>

PeopleSoft Proprietary and Confidential

595

Using PeopleSoft Published EIPs

Lesson 20

<Username>PTINT</Username> <Password>PTINT</Password> </Security_Request> </SOAP-ENV:Header> <SOAP-ENV:Body> <FIND__CompIntfc__STU_PROFILE_2> <STUDENT_ID></STUDENT_ID> <STUDENT_NAME></STUDENT_NAME> <CUSTOMER_ID>AAB</CUSTOMER_ID> </FIND__CompIntfc__STU_PROFILE_2> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Point out that the SOAPAction always includes the message SOAPTOCI and the third party node sending the message. You can have students change the customer ID in the input to select other customers.

Activity Overview
In this activity, you will create an external node SOAPTEST that will send SOAP requests for web services available through component interfaces in PeopleSoft. This node will request a list of students for the customer AAB. The component interface that supports this transaction is STU_PROFILE_2 using the Find method. Review the WSDL for the component interface and the methods that are available. A SOAP document has been created for you in z:\STAnnn\Tools\1022_IntTools\files\STU_SOAP_test.txt. Create a new send master project that posts the SOAP message to PeopleSoft and review the data returned from PeopleSoft. Warning! The SOAPTOCI message uses the default application server to receive the message. In the CTE environment the default application server is cteserver:9990 which is the instructor database. If the node SOAPTEST has not been configured on that database, you will receive an error message in SendMaster. The alternative is to change the default application server for the Gateway to one of the student workstations.

Creating an External Node


To create an external node: 1. PeopleTools, Integration Broker, Node Definition. 2. Add a new node SOAPTEST with the following information:
Page Element Description Node Type Routing Type Authentication Value or Status SOAP test External Explicit None

596

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

3.

On the Connectors tab, select the Connector ID HTTPTARGET and enter the following properties:
Property ID HEADER HEADER HEADER HTTPPROPERTY PRIMARYURL Property Name Content-Type SOAPAction SendUncompressed Method URL Value Text/xml Leave blank Y POST http://mytest.com

4. Click Save. 5. On the Transaction tab add the inbound synchronous message SOAPTOCI with the synchronous response SOAPTOCI. 6. Save the node definition. Results The node contains one transaction:

Node transactions for SOAPTEST node

Reviewing the Published WSDL for STU_PROFILE_2.


To review the published WSDL for STU_PROFILE_2: 1. Select PeopleTools, Integration Broker, Web Services, Published EIPs. 2. Select the Component Interface radio button. 3. Enter STU_PROFILE_2 for the Component Interface Web Service. 4. Click Search. 5. Click on the WSDL link. Results The WSDL will be displayed:

PeopleSoft Proprietary and Confidential

597

Using PeopleSoft Published EIPs

Lesson 20

WSDL for component interface STU_PROFILE_2

Using Send Master to Test the Component Interface


To use Send Master to test the component interface: 1. Open Send Master and create a new input file project STU_PROFILE_nn with the following information:
Page Element Server URL Headers Value or Status http:/cteserver.peoplesoft.com:1080/PSIGW/HttpListeningConnector Content-Type: text/xml SOAPAction: #SOAPTOCI#SOAPTEST Input File z:\STAnnn\Tools \1022_IntTools\files\STU_SOAP_test.txt

Note. The SOAPAction in the header takes the form #SOAPTOCI#third-party message node. 2. Click Post 3. Click the If valid XML, format icon in the output window. 4. Review the data returned.

598

PeopleSoft Proprietary and Confidential

Lesson 20

Using PeopleSoft Published EIPs

Results The output window will display the returned data:

Send Master test for Find method on STU_PROFILE_2 This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

599

Using PeopleSoft Published EIPs

Lesson 20

Review
In this lesson, you learned that: PeopleSoft published Enterprise Integration Points (EIPs) are published for all PeopleSoft Component Interfaces and messages allowing PeopleSoft Web services to be available to third-party systems. WSDL can be generated for component interfaces and messages through the Published EIPs page. PeopleSoft supplies the message SOAPTOCI that is used with all Component Interface WSDL bindings. The third-party node in a WSDL binding uses the HTTPTARGET connector configured with the SOAPAction property in the header. Component Interface WSDL binding can be generated from the Published EIPs page or directly through the iScript URL. SOAP messages are configured based on the WSDL and sent to PeopleSoft via HTTP.

Slide 387 ______________________________________________________________________________________________________

600

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data into the PeopleSoft System Using Flat Files


Objectives
By the end of this lesson you will be able to: Describe file layouts. Create file layout definitions. Import data using file layouts. Describe the generated Application Engine PeopleCode. Run Application Engine import programs. Add field attributes to a file layout.

Slide 389 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

601

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing File Layouts


A file layout is a definition that represents the data structure of a text file to be processed. The file layout: Serves as a template to identify and process the files records and fields. Works with hierarchical and nonhierarchical data. Handles files that combine data records with nondata records (that is, audit and control records). Simplifies reading, writing, and manipulating hierarchical transaction data with PeopleCode.

Slide 390 ______________________________________________________________________________________________________

Student Notes
PeopleTools supports reading from and writing to plain text files and files that are based on a file layout.

Instructor Notes
A file layout is a definition (or mapping) of a file to be processed. It identifies where the data fields are located in the file. Once a file layout has been created, you can write PeopleCode programs that use the file layout either to read data from or write data to a file. File layouts work with hierarchical and nonhierarchical data, and they can handle files that combine data records with nondata records (that is, audit and control records). Using a file layout definition simplifies reading, writing, and manipulating hierarchical transaction data with PeopleCode. Note the following points: You dont have to create a file layout definition for accessing data in a file. If the file is a plain text file, data is read or written using text strings. If the file is based on a file layout definition, you can use text strings, rowset objects, or record objects to access data in the file.

A file layout simplifies the PeopleCode used to read from and write to files. When you use a file layout, you can use: Text strings Rowset class Record class

602

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Describing File Layouts (continued)


File layouts are used to: Write data to flat files (export data). Read data from flat files (import data). If a file layout is mapped to a flat file, you can have the system generate an Application Engine program to perform the data import.
Slide 391 ______________________________________________________________________________________________________

Instructor Notes
Occasionally, you may need to exchange data with external systems that do not use messaging or component interfaces. In these cases, the third party sends data as a file, which can be a fixed sequential file, a comma-delimited file, or an XML file. You can use file layouts to move data between the PeopleSoft database and external systems (data interchange), using flat files as the transmission medium. Once a file layout has been created and mapped to a flat file, you can have the system generate an Application Engine program to perform the data import.

PeopleSoft Proprietary and Confidential

603

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing File Layouts (continued)


The PeopleSoft system supports three file layout formats: Fixed position (FIXED) Comma-separated values (CSV) XML tagged (XML)

Slide 392 ______________________________________________________________________________________________________

Instructor Notes
The PeopleSoft system supports three file layout formats: Fixed position (FIXED) Each field has a starting position and a length, which together specify its location in the file. This is the default format for new file layouts. Comma-separated values (CSV) Fields are located in the file by their sequence, and they are separated by commas. XML tagged (XML) A field is located not by its position or sequence within a record but by the named XML tags surrounding it.

604

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Describing File Layouts (continued)


In a file with the fixed position format, each fields starting position and length provide its descriptive location. Here is an example:
1234567890123456789012345678901234567890123456789012345678901234567890123456789 6020 6021 6022 6023 6024 08/01/2002ANew 08/01/2002ANew 08/01/2002ANew 08/01/2002ANew 08/01/2002ANew Course Course Course Course Course 6020 6021 6022 6023 6014 T T T T T 4.0 4.0 5.0 5.0 5.0 4.0YJGY 4.0YWLK 5.0YJPG 5.0YCDF 5.0YSXD 840 840 840 840 840 840 840 840 840 840

Fixed position file


Slide 393 ______________________________________________________________________________________________________

Instructor Notes
Each fields starting position and length provide its descriptive location. This is the most common type of flat file that PeopleSoft EDI Manager processes. Almost all EDI processing currently uses this file type. Each data element is oriented by a fixed or column-dependent position within the file.

PeopleSoft Proprietary and Confidential

605

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing File Layouts (continued)


In CSV files, fields are separated by commas, and the order of their appearance provides a descriptive location. Here is an example:
6020, 08/01/2002, A, New Course 6021, 08/01/2002, A, New Course 6022, 08/01/2002, A, New Course 6023, 08/01/2002, A, New Course 6024, 08/01/2002, A, New Course 6020, T, 4., 4.0, Y, JGY, 840, 840 6021, T, 4.0, 4.0, Y, WLK, 840, 840 6022, T, 5.0, 5.0, Y, JPG, 840, 840 6023, T, 5.0, 5.0, Y, CDF, 840, 840 6014, T, 5.0, 5.0, Y, SXD, 840, 840

CSV file
Slide 394 ______________________________________________________________________________________________________

Instructor Notes
Fields are separated by commas, and the order of their appearance provides a descriptive location. In this type of file, each data element is surrounded with a separator, a qualifier, or both. File record IDs can be used to determine which table data is moved to or from; however, in most cases this type of file contains homogenous records.

606

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Describing File Layouts (continued)


In tagged XML files, each field has predefined tags (or identifiers) surrounding it. Here is an example:
<?xml version="1.0"?> <Start> <PSU_COURSE_TBL> <COURSE>6020</COURSE> <EFFDT>08/01/2002</EFFDT> <EFF_STATUS>A</EFF_STATUS> <DESCR>New Course 6020</DESCR> <COURSE_TYPE>T</COURSE_TYPE> <LENGTH_DAYS>4.0</LENGTH_DAYS> <TRAINING_UNITS>4.0</TRAINING_UNITS> <ONSITE>Y</ONSITE> <INSTRUCTOR>JGY</INSTRUCTOR> <APP_REL>840</APP_REL> <TOOLS_REL>840</TOOLS_REL>

XML file
Slide 395 ______________________________________________________________________________________________________

Instructor Notes
Each field has predefined tags (or identifiers) surrounding it. This type of file contains data represented in a hierarchical or treelike structure. A tag surrounds each data element. A file record tag can group multiple elements. XML files are covered in the PeopleSoft Integration Broker portion of this course. Consequently, the examples in this lesson focus on the fixed position and CSV file formats.

PeopleSoft Proprietary and Confidential

607

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Creating File Layouts


File layouts: Provide a mapping of the file to be processed. Identify where the data fields are located in a file. Simplify the hierarchical structure of the records.

Slide 396 ______________________________________________________________________________________________________

608

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Creating File Layouts (continued)


To create a file layout definition: 1. In PeopleSoft Application Designer select File, New, File Layout. 2. Select Insert, Record or drag the record into the file layout from the project. 3. Set the file layout properties. 4. Modify the records and field level properties as needed. 5. Save the file layout.
Slide 397 ______________________________________________________________________________________________________

Student Notes
When you create a new file layout, the default root node is NEW FILE. The name changes to the file layout name when you save the file layout definition.

Sample file layout for PSU_COURSE_TBL Note. Any changes to records are not reflected in the file layout. File records and file fields are stored within the file layout only.

PeopleSoft Proprietary and Confidential

609

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Creating File Layouts (continued)


File layout properties store the following information at the file layout (root) level: Description. Comments. File layout name and type information.

Slide 398 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access this definition in PeopleSoft Application Designer:
Definition Name File Layout Definition Properties Navigation File, Definition Properties, or click the Definition Properties icon.

File layout format Note. You can select only one layout type per file layout. Options are FIXED, CSV, and XML.

Instructor Notes
Earlier in the lesson, you explained the three file layout formats. When you change the file layout format, the prompts change.

610

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Format Fixed position (FIXED) Comma-separated values (CSV)

Description Each fields starting position and length provide its descriptive location Fields are separated by commas, and the order of their appearance provides a descriptive location. In this type of file, each data element is surrounded with a separator, a delimiter, or both. Each field has predefined tags (or identifiers) surrounding it. This type of file contains data represented in a hierarchical or treelike structure. A file record tag can group multiple elements.

XML tagged (XML)

PeopleSoft Proprietary and Confidential

611

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Creating File Layouts (continued)


File layout record properties define the properties of the file layout. The file layout formats have the following attributes:
Format FIXED CSV XML Attributes File record name, maximum record length, file record ID, start position, and length. File record name, ID sequence number, maximum record length, file record ID, length, default qualifier, and field delimiter. File record name, maximum record length, and record tag.

Slide 399 ______________________________________________________________________________________________________

Student Notes
Use the following navigation path to access this definition in PeopleSoft Application Designer:
Definition Name File Layout Segment Properties Navigation Double-click the record in the file layout view.

File layout segment properties

612

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

See Also PeopleTools 8.44 PeopleBook: PeopleSoft Application Designer, Constructing File Layouts and Performing Data Interchanges.

Instructor Notes
File layout segment properties describe a record or segment. You discuss segments later in this lesson. Discuss the following points:
Property File Record Name ID Seq. No. File Record ID Description Used when accessing the file layout from PeopleCode. Used for CSV only. Used with multilevel file layouts. This number is automatically written to the file when you use the WriteRecord or WriteRowset methods and the file is fixed or CSV. You discuss more details on how to use this field in the multilevel layout section of this lesson. Used for FIXED only. Automatically generated. You can increase the length, but you cannot decrease the length to a number smaller than the number of characters in the file record ID. Used for CSV files. This value overrides the default qualifier in the file layout properties for the record. Used for CSV files. Used for XML files. Used for documentation purposes only.

ID Start Position ID Length

Default Qualifier Field Delimiter Record tag Record description

PeopleSoft Proprietary and Confidential

613

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Importing Data Using File Layouts


There are several options for importing data, as shown here:
PeopleSoft Application Server EIP Subscription PeopleCode Application Engine Map to Message Publish to Self Component Interface SQL Insert Read File File

Importing data into the PeopleSoft system


Slide 400 ______________________________________________________________________________________________________

Student Notes
There are three ways that you can import data. As you have seen with messaging and component interfaces, the way that you write the PeopleCode determines how data is imported. You can have the system: Read the data directly into the database (using an SQL Insert statement). Read the data and use a component interface to validate the data. Map the data to a message and then publish the message to the same database using the predefined messages.

Instructor Notes
Review the diagram and the three methods for importing data.

614

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Importing Data Using File Layouts (continued)


You can use the file layout to import data. Use the following steps to set up and run a file import program: 1. Provide the import data in a properly formatted flat file. 2. Create a file layout definition to match the record and field structure of the data. 3. Preview and troubleshoot the input data format and content. 4. Save the file layout. 5. Generate the data import Application Engine program. 6. Run the Application Engine program to import the data.
Slide 401 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

615

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Importing Data Using File Layouts (continued)


Once you have created a file layout, select the Preview tab to map the file layout to a flat file. Use the following steps to display the preview: 1. Select the Preview tab of the file layout. 2. Select the record name in the Segment Name drop-down list box. 3. In the Default File Name field, enter the name of the file to which you are mapping. 4. Select View, Refresh Preview Data (F5), or click the refresh icon to preview the data.
Slide 402 ______________________________________________________________________________________________________

Student Notes
The page below shows an example of mapping:

File layout preview

Instructor Notes
The first few lines of the input file are displayed. Verify that the data is correct and that it appears in the appropriate field.

616

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Importing Data Using File Layouts (continued)


Here are some common input data errors: The preview grid does not appear. Only the first column of the preview grid contains data. The preview grid appears for some records but not for others. Data for a field appears truncated in the preview grid. A field appears to start in the middle of the data.

Slide 403 ______________________________________________________________________________________________________

Student Notes
This table lists some possible errors and provides solutions:
Symptom The preview grid does not appear. The preview grid does not appear. Only the first column of the preview grid is populated. The preview grid appears for some records but not for others. Data for a field appears truncated in the preview grid. A field appears to start in the middle of the data. Possible Reason The input file format doesnt match the file layout format that you specified in the File Layout Definitions Properties dialog box. A CSV file doesn't use the definition qualifier that you specified in the File Layout Definition Properties dialog box A CSV file doesn't use the definition delimiter that you specified in the File Layout Definition Properties dialog box. The files record IDs for the missing records don't match their file record IDs specified in the File Layout Segment Properties dialog box. With a FIXED file, the field length that you specified in the File Layout Field Properties dialog box is too short to accommodate the field data. With a FIXED file, the start position you specified in the File Layout Field Properties dialog box is too great to include the start of the field data. Solution Change the file layout to match the input format. Change the definition qualifier to match the one used in the input file. Change the definition delimiter to match the one used in the input file.

Specify file record IDs that match the input file records.

Increase the field length to accommodate the input data.

Decrease the start position and adjust the field length to match the input data start position and length.

PeopleSoft Proprietary and Confidential

617

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Importing Data Using File Layouts (continued)


To create the import Application Engine program: 1. Save the file layout. 2. Select Edit, Generate Import AE, or click the AE icon on the toolbar. 3. Enter the Application Engine program name in the dialog box. The Application Engine program is created, and it appears in the project work space.
Slide 404 ______________________________________________________________________________________________________

Student Notes
This example shows a newly generated Application Engine program:

Generated Application Engine program Use the following navigation path to access this definition in PeopleSoft Application Designer:
Definition Name Program Properties Navigation File, Definition Properties Select the Advanced tab.

Application Engine program properties

618

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Note. The generated program has the program type Import Only. Also, for the initial testing, you should Disable Restart.

Instructor Notes
Point out that the program has the type Import Only. This means that it is automatically generated; it serves as documentation only. Also, point out the Disable Restart check box. When testing an import program, if the program does not terminate successfully, no data is imported. By selecting Disable Restart, you can rerun the program. If the Disable Restart check box is not selected and an error occurs, when you try to run the program a second time, you receive a Suspended message. To run the program again, you can use a new run control ID. Question: Importing Data Using File Layouts To automatically create an import Application Engine program, you need to: 1. Use an XML file. 2. Map a file layout to a flat file in preview. 3. Define a multilevel file layout. 4. Assign a record file ID to the file layout record. Answer The answer is 2 (map a file layout to a flat file in preview).

PeopleSoft Proprietary and Confidential

619

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing the Generated Application Engine PeopleCode


The Application Engine program contains one PeopleCode action. The template contains the following functions and data: Error Handling function Import Segment function PeopleCode to import data

Slide 405 ______________________________________________________________________________________________________

Student Notes
The following examples show the generated PeopleCode template. Error Handling
Function EditRecord(&REC As Record) Returns boolean; Local integer &E; &REC.ExecuteEdits(%Edit_Required + %Edit_DateRange + %Edit_YesNo + %Edit_OneZero); If &REC.IsEditError Then For &E = 1 To &REC.FieldCount &MYFIELD = &REC.GetField(&E); If &MYFIELD.EditError Then &MSGNUM = &MYFIELD.MessageNumber; &MSGSET = &MYFIELD.MessageSetNumber; &LOGFILE.WriteLine("****Record:" | &REC.Name | ", Field:" | &MYFIELD.Name); &LOGFILE.WriteLine("****" | MsgGet(&MSGSET, &MSGNUM, "")); End-If; End-For; Return False; Else Return True; End-If; End-Function;

Import Segment
Function ImportSegment(&RS2 As Rowset, &RSParent As Rowset) Local Rowset &RS1, &RSP; Local string &RecordName; Local Record &REC2, &RECP; Local SQL &SQL1; Local integer &I, &L; &SQL1 = CreateSQL("%Insert(:1)"); &RecordName = "RECORD." | &RS2.DBRecordName;

620

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

&REC2 = CreateRecord(@(&RecordName)); &RECP = &RSParent(1).GetRecord(@(&RecordName)); For &I = 1 To &RS2.ActiveRowCount &RS2(&I).GetRecord(1).CopyFieldsTo(&REC2); If (EditRecord(&REC2)) Then &SQL1.Execute(&REC2); &RS2(&I).GetRecord(1).CopyFieldsTo(&RECP); For &L = 1 To &RS2.GetRow(&I).ChildCount &RS1 = &RS2.GetRow(&I).GetRowset(&L); If (&RS1 <> Null) Then &RSP = &RSParent.GetRow(1).GetRowset(&L); ImportSegment(&RS1, &RSP); End-If; End-For; If &RSParent.ActiveRowCount > 0 Then &RSParent.DeleteRow(1); End-If; Else &LOGFILE.WriteRowset(&RS); &LOGFILE.WriteLine("****Correct error in this record and delete all error messages"); &LOGFILE.WriteRecord(&REC2); For &L = 1 To &RS2.GetRow(&I).ChildCount &RS1 = &RS2.GetRow(&I).GetRowset(&L); If (&RS1 <> Null) Then &LOGFILE.WriteRowset(&RS1); End-If; End-For; End-If; End-For; End-Function;

PeopleCode to Import Data


rem *****************************************************************; rem * PeopleCode to Import Data Local File &FILE1; Local Record &REC1; Local SQL &SQL1; Local Rowset &RS1, &RS2; Local integer &M; &FILE1 = GetFile("C:\User\1022_IT\Files\NEW_COURSE_FILE.txt", "r", "a", %FilePath_Absolute); &LOGFILE = GetFile("C:\User\1022_IT\Files\NEW_COURSE_FILE.txt.err", "W", %FilePath_Absolute); &FILE1.SetFileLayout(FileLayout.PSU_COURSE_FILE); &LOGFILE.SetFileLayout(FileLayout.PSU_COURSE_FILE); *; rem *****************************************************************;

PeopleSoft Proprietary and Confidential

621

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

&RS1 = &FILE1.CreateRowset(); &RS = CreateRowset(Record.PSU_COURSE_TBL); &SQL1 = CreateSQL("%Insert(:1)"); &RS1 = &FILE1.ReadRowset(); While &RS1 <> Null; ImportSegment(&RS1, &RS); &RS1 = &FILE1.ReadRowset(); End-While; &FILE1.Close(); &LOGFILE.Close();

Instructor Notes
Note that the template refers to segments, which are records. In the next lesson, you review creating segments. See lesson 23, Writing Data to Flat Files. Keep in mind that a segment and a record are treated the same way in PeopleCode.

622

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Describing the Generated Application Engine PeopleCode (continued)


The File class enables the exchange of data with flat files by using: Functions Methods Properties

Slide 406 ______________________________________________________________________________________________________

Student Notes
This table lists the File class functions, methods, and properties:
File Class File functions Functions, Methods, and Properties FileExists FindFile GetFile File methods Close CreateRowset Open ReadLine ReadRowset SetField SetFileLayout SetPosition WriteLine WriteRecord WriteRowset WriteString File properties CurrentRecord GetPosition IgnoreInvalidid IsError IsNewFileID IsOpen Name RecTerminator

See Also PeopleTools 8.44 PeopleBook: PeopleCode Reference, File Class.

PeopleSoft Proprietary and Confidential

623

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing the Generated Application Engine PeopleCode (continued)


Errors are handled using the ExecuteEdits method in the following manner: If errors are detected, the rowset objects IsEditError property returns the value True. The EditError property of every field in the rowset is examined to find the one that returns the value True. The fields MessageSetNumber and MessageNumber properties determine the relevant error message.

Slide 407 ______________________________________________________________________________________________________

Student Notes
This example shows the EditRecord function:
Function EditRecord(&REC As Record) Returns boolean; Local integer &E; &REC.ExecuteEdits(%Edit_Required + %Edit_DateRange + %Edit_YesNo + %Edit_OneZero); If &REC.IsEditError Then For &E = 1 To &REC.FieldCount &MYFIELD = &REC.GetField(&E); If &MYFIELD.EditError Then &MSGNUM = &MYFIELD.MessageNumber; &MSGSET = &MYFIELD.MessageSetNumber; &LOGFILE.WriteLine("****Record:" | &REC.Name | ", Field:" | &MYFIELD.Name); &LOGFILE.WriteLine("****" | MsgGet(&MSGSET, &MSGNUM, "")); End-If; End-For; Return False; Else Return True; End-If; End-Function;

Instructor Notes
If an error occurs in any field of a record in a rowset object that is populated with the ReadRowset method, the rowset objects IsEditError property returns the value True. For example, you can use the method ExecuteEdits with a record to verify that the data in the record is valid. This type of error is indicated by the IsEditError. To determine which field has the error, you must examine the EditError property of every field in the rowset to find the one that returns the value True. You can then examine that

624

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

fields MessageSetNumber and MessageNumber properties to determine the relevant error message. Execute edits are covered earlier in the course, so students should already be familiar with the edits. See lesson 13, Sending and Receiving Messages .

PeopleSoft Proprietary and Confidential

625

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing the Generated Application Engine PeopleCode (continued)


You instantiate the File object by using the GetFile function:
&FILE1 = GetFile("C:\User\1022_IT\Files\NEW_COURSE_FILE.txt", "r", "a", %FilePath_Absolute); &LOGFILE = GetFile("C:\User\1022_IT\Files\NEW_COURSE_FILE.txt.err", "W", %FilePath_Absolute);

Slide 408 ______________________________________________________________________________________________________

Student Notes
You can instantiate a file in any of the following modes: Read (R) Write (W) Append (A) Update (U) Exists (E) New (N)

The file path can be either absolute or relative.

Instructor Notes
This section discusses how to: Explain the File object. Explain modes. Explain the pathtype parameter.

Explaining the File Object You instantiate the File object by using the GetFile function. When you instantiate a file, you can determine the mode (read, write, append, update exists, or new). If you are opening a file for writing, the file does not need to already existthe system creates it. In this example, two file objects are instantiated: one for the source file and one for the log file. The following is the syntax for the GetFile function: GetFile(filespec, mode [, charset] [,pathtype] Review the parameters.

626

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Explaining Modes The following modes are available:


Mode R W A U Description Read mode: Opens the file for reading, starting at the beginning. Write mode: Opens the file for writing. When you specify Write mode, any existing content in the file is discarded and is overwritten. Append mode: Opens the file for reading or writing, starting at the end. Any existing content is retained. Update mode: Opens the file for reading or writing, starting at the end. Any existing content is retained. Use this mode and the GetPosition and SetPosition methods to maintain checkpoints of the current read/write position in the file. In Update mode, any write operation clears the file of all data that follows the position that you set. Conditional exists read mode: Opens the file for reading only if it exists, starting at the beginning. If it doesnt exist, Open has no effect. Before attempting to read from the file, use the IsOpen property to confirm that its open. Conditional new write mode: Opens the file for writing, only if it doesnt already exist. If a file by the same name already exists, Open has no effect. Before attempting to write to the file, use the IsOpen property to confirm that its open. You can insert an asterisk (*) in the file name to ensure that a new file is created. The system replaces the asterisk with numbers starting at 1 and incrementing by 1, and it checks for the existence of a file with each resulting name in turn. It uses the first name for which a file does not already exist. In this way, you can generate a set of automatically numbered files. If you insert more than one asterisk, all but the first are discarded.

Explaining the pathtype Parameter If you have prepended a path to the file name, you use the pathtype parameter to specify whether it is absolute or relative, as shown here: %FilePath_Relative This is the default. %FilePath_Absolute

If you dont specify a path, the file is assumed to be in one of the following two locations, depending on where the PeopleCode program is executing: When the program is running on the client, the location is the directory specified by the TEMP environment variable. When the program is running on the server, the location is the files directory under the directory specified by the PeopleSoft PS_SERVDIR environment variable.

If you specify a relative path, that path is appended to the TEMP or PS_SERVDIR variable (depending on where the PeopleCode runs). Do not include a drive letter when using a relative path. If the path is an absolute path, the exact path that you specify is used. You must specify a drive letter and the complete path. You cant use any wildcards when specifying the path.
PeopleSoft Proprietary and Confidential 627

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing the Generated Application Engine PeopleCode (continued)


The SetFileLayout methods associates the specific file layout definition with a file object, as shown here:
&FILE1.SetFileLayout(FileLayout.PSU_COURSE_FILE); &LOGFILE.SetFileLayout(FileLayout.PSU_COURSE_FILE);

Slide 409 ______________________________________________________________________________________________________

628

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Describing the Generated Application Engine PeopleCode (continued)


To import data, a rowset is created for the record and the ReadRowset method is used to populate the rowset with one transaction from the file record, plus all of its subordinate data, as shown in this example:
&RS1 = &FILE1.CreateRowset(); &RS = CreateRowset(Record.PSU_COURSE_TBL); &SQL1 = CreateSQL("%Insert(:1)"); &RS1 = &FILE1.ReadRowset(); While &RS1 <> Null; ImportSegment(&RS1, &RS); &RS1 = &FILE1.ReadRowset(); End-While;

Slide 410 ______________________________________________________________________________________________________

Instructor Notes
The ReadRowset method is a file layout method. It instantiates a PeopleCode rowset object based on the file layout definition. It then populates the rowset with one transaction from the file. A transaction is treated as one instance of level-0 data contained in a file record, plus all of its subordinate data. When ReadRowset is executed, it moves the starting point for the next read operation to the beginning of the next rowset so that each transaction in the file can be read in turn by subsequent ReadRowset operations. When no more data remains to be read from the file, ReadRowset returns NULL.

PeopleSoft Proprietary and Confidential

629

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Describing the Generated Application Engine PeopleCode (continued)


This diagram shows the progression of data from flat files through a file layout to the record definition:
<Invoice> <From>Joe Bloggs</From> <To>A. Another</To> <Date year = 2000 month = 2 day = 1/> <Amount currency = Dollars>100.00</Amount> <TaxRate>07</TaxRate> 1001,08/01/2000,PeopleTools I,8,T,05 <TotalDue currency = Dollars>107.00</TotalDue> 1002,08/01/2000,PeopleTools II, 8,T,05 2001,02/07/2000,PeopleTools 8 Delta,8,T,02 2001,08/01/2000,Integration Tools, 8,T,03 2002,08/01/2000,Object Based PC, 8,T,03 1013,02/15/2000,Enterprise Warehouse,8,T,04 100108/01/2000PeopleTools I 8T05 100208/01/2000PeopleTools II 8T05 200102/07/2000PeopleTools 8 Delta 8T02 200108/01/2000Integration Tools 8T03 200208/01/2000Object Based PC 8T03 101302/15/2000Enterprise Warehouse8T04

XML

SetFileLayout File Layout

GetFile File Object

CSV

Fixed

PS DB

100108/01/2000PeopleTools I 8T05 100208/01/2000PeopleTools II 8T05 200102/07/2000PeopleTools 8 Delta 8T02 200108/01/2000Integration Tools 8T03 200208/01/2000Object Based PC 8T03 101302/15/2000Enterprise Warehouse8T04

Plain Text File

File object
Slide 411 ______________________________________________________________________________________________________

Instructor Notes
This section presents a review question for the current objective. Question: Describing the Generated Application Engine PeopleCode You can run the generated import Application Engine program without making any modifications. 1. True 2. False Answer The answer is 1 (true).

630

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Running the Application Engine Program


To run the Application Engine program from PeopleSoft Application Designer: 1. Open the Application Engine program in PeopleSoft Application Designer. 2. Select Edit, Run Program. 3. Enter the run control ID. 4. Indicate whether to run the program minimized. 5. Indicate whether the system creates a log file. 6. Click OK.
Slide 412 ______________________________________________________________________________________________________

Student Notes
This example shows the run request:

Application Engine run request

Instructor Notes
The system assigns the default run control RUN01. You can change the run control if you want.

PeopleSoft Proprietary and Confidential

631

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

You can run the program minimized (that is, the DOS window does not open when the program starts). You can also output to a log file. This can be useful if you the program does not function as expected. Select the Output Log to File check box.

632

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Running the Application Engine Program (continued)


When the program completes, you can: Check the log. Check the error file (.err). Verify that the data has been updated in the database.

Slide 413 ______________________________________________________________________________________________________

Student Notes
The following examples show a log file and an error log file:

Sample import log

Sample error file

Instructor Notes
The error file is located in the same directory as the input file.

PeopleSoft Proprietary and Confidential

633

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Activity 32:

Using a File Layout to Import Data


In this activity, you will review the activity overview and: 1. Create a file layout and map it to a flat file. 2. Generate an Application Engine program. 3. Run the Application Engine program. 4. Correct a file. 5. Modify the Application Engine PeopleCode for the import. See Integration Tools: Activity Guide, lesson 21, Importing Data into the PeopleSoft System Using Flat Files, Activity 32: Using a File Layout to Import Data.

Slide 414 ______________________________________________________________________________________________________

Instructor Notes
This section discusses how to explain the bad course file example. This example shows how the preview window appears:

BAD_COURSE_FILE preview The BAD_COURSE file does not have the correct start position for the COURSE_TYPE field. It is in position 47 instead of position 48. Open the file and insert a blank space before the T in each row. Alternatively, you could change the length of the DESCR field to 29. Then you would select the COURSE_TYPE field and select -1 in the Propagate box. Click the triple right arrow button (>>>), and then refresh.

634

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Changing the start position Note. This activity should take approximately twenty minutes.

Activity Overview
In this activity, you will create a file layout for the record PSU_COURSE_TBL. Next you map the file layout to three fixed sequential files as shown here. Then you generate and run the Application Engine program to import the data. The files are located in z:\STAnnn\Tools\1022_IntTools\files.

NEW_COURSE_FILE.txt

BAD_COURSE_FILE.txt

PeopleSoft Proprietary and Confidential

635

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

INVALID_COURSE_FILE.txt Note. You need to generate a new Application Engine import program for each file. Disable Restart in case you encounter errors that need to be corrected.

Creating a File Layout and Mapping It to a Flat File


To create and map the file layout: 1. Select New, File Layout. 2. Select Insert, Record, PSU_COURSE_TBL. 3. Select File, Definition Properties. 4. Enter a description and ensure that the format is FIXED. 5. Click OK. 6. Select the Preview tab. 7. Set the segment name to PSU_COURSE_TBL. 8. Set the default file name to z:\STAnnn\Tools\1022_IntTools\files\NEW_COURSE_FILE.TXT. 9. Select View, Refresh Preview Data. 10. Review the data. 11. Save the file layout as PSU_COURSE_FILE.

Generating an Application Engine Program


To generate the Application Engine program: 1. Select Edit, Generate Import AE. 2. Name the program IMP_CRS_FILE. 3. Expand the PeopleCode action and review the PeopleCode. 4. Close the PeopleCode. 5. Select File, Definition Properties. 6. Select the Advanced tab. 7. Select the Disable Restart check box.
636 PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

8. Click OK. 9. Save the program.

Running the Application Engine Program


To run the Application Engine program: 1. With the Application Engine program open in PeopleSoft Application Designer, select Edit, Run Program. Enter the following information:
Page Element Run Control ID Output to Log Log File Name Value or Status RUN01 Selected Z:\STAnn\IMP_CRS_FILE.LOG

2. Click OK to run the program. 3. When the program has completes, review the log file to verify that the program ran successfully. 4. Select Start, Programs, Microsoft SQL Server, Query Analyzer. 5. Enter satst for the login name and password, then click OK. 6. Change the database to your database. 7. Enter the following SQL command:
SELECT * FROM PS_PSU_COURSE_TBL WHERE COURSE > 6000

Results

Query Analyzer displaying new courses in the database

PeopleSoft Proprietary and Confidential

637

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Correcting a File
To correct a file: 1. Open the PSU_COURSE_FILE file layout. 2. On the preview tab map, select PSU_COURSE_TBL for the segment and enter z:\STAnn\Tools\1022_IntTools\files\BAD_COURSE_FILE as the default file name. 3. Click the Refresh icon. 4. Examine the data preview. 5. Expand the DESCR field. 6. Note that the flat file does not have the fields in the correct sequential position. The COURSE_TYPE field should start at position 48. In the flat file, it starts at position 47. There are two ways to correct this problem: Add a blank space in the flat file before the T for each row of data, and save the file. Adjust the file layout to match the flat file.

To do this, you can change the length of the DESCR field to 29. Then set the Propagate edit box to -1 for the COURSE_TYPE field and use the triple right arrow button (>>>) to change that field and all remaining fields. 7. Click the Refresh icon. 8. Save the file layout. 9. Generate the Application Engine program as BAD_COURSE. 10. Select Disable Restart in the program properties. 11. Save the Application Engine program. 12. Run the Application Engine program. 13. In the Query Analyzer utility, execute the following SQL command again:
SELECT * FROM PS_PSU_COURSE_TBL WHERE COURSE > 6000

Results

Query Analyzer displaying the new courses in the database

638

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Modifying the Application Engine PeopleCode for the Import


To modify the Application Engine PeopleCode, you map to another file that requires edits in the translate table: 1. Open the PSU_COURSE_FILE file layout. 2. On the preview tab map, select PSU_COURSE_TBL for the segment and enter z:\STAnnn\Tools\1022_IntTools\files\INVALID_COURSE_FILE as the default file name. 3. Click the Refresh icon. 4. Examine the data preview. 5. Save the file layout. 6. Generate the Application Engine program as INVALID_CRS. 7. Select Disable Restart in the program properties. 8. In the PeopleCode, change the ExecuteEdits statement that is commented. As generated, there are two ExecuteEdits statements. The first is a comment, and it contains edits for the translate and prompt tables, as well as for required, date range, yes or no, and one or zero. Uncomment the first statement and make the second a comment, as shown here:
Function EditRecord(&REC As Record) Returns boolean; Local integer &E; &REC.ExecuteEdits(%Edit_Required + %Edit_DateRange + %Edit_YesNo + %Edit_TranslateTable + %Edit_PromptTable + %Edit_OneZero); rem &REC.ExecuteEdits(%Edit_Required + %Edit_DateRange + %Edit_YesNo + %Edit_OneZero);

9. Save the program. 10. Close the PeopleCode window. 11. Run the Application Engine program. 12. Check the error log created in z:\STAnnn\Tools\1022_IntTools\Files\INVALID_COURSE_FILE.txt.err.

PeopleSoft Proprietary and Confidential

639

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Results

Error log indicating invalid translate values This concludes the activity. Do not continue.

640

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Adding Field Attributes to a File Layout


When you map a file to a file layout, you can change the following field attributes: Field length Field qualifier Strip characters Set default values Set field inheritance

Slide 415 ______________________________________________________________________________________________________

Student Notes
This example shows the addition of a default value for the EFF_STATUS field:

Sample default value Note. The changed attributes do not appear in the preview data.

Instructor Notes
This section presents a review question for the current objective.

PeopleSoft Proprietary and Confidential

641

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Question: Adding Field Attributes to a File Layout Default values can be defined in the file layout. 1. True 2. False Answer The answer is 1 (true).

642

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Activity 33:

Importing a File with Field Attributes


In this activity, you will review the activity overview and import a CSV file that requires field attribute changes. See Integration Tools: Activity Guide, lesson 21, Importing Data into the PeopleSoft System Using Flat Files, Activity 33: Importing a File with Field Attributes.

Slide 416 ______________________________________________________________________________________________________

Instructor Notes
In the input file for the COURSE.CSV, note that the third field (EFF_STATUS) has two commas (,,) to denote a field. If you do not include this placeholder, the system places DESCR field as the third field. Note. This activity should take approximately 10 minutes.

Activity Overview
In this activity, you will create a new file layout that maps to the file shown here:

COURSE_CSV.txt You will also create an Application Engine import program and run the program.

Importing a CSV File That Requires Field Attribute Changes


To import a CSV file requiring field attribute changes: 1. In PeopleSoft Application Designer, select New, File Layout. 2. Select Insert, Record, PSU_COURSE_TBL. 3. Select File, Definition Properties. 4. Enter a description and ensure that the format is CSV. 5. Click OK. 6. Select the Preview tab. 7. Set the segment name to PSU_COURSE_TBL.

PeopleSoft Proprietary and Confidential

643

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

8. Set the default file name to z:\STAnnn\Tools\1022_IntTools\files\COURSE_CSV.txt. 9. Select View, Refresh Preview Data. 10. Examine the data. 11. Add the default value of A for the EFF_STATUS field. 12. Use a quotation mark as a qualifier for the DESCR field. 13. Save the file layout as PSU_COURSE_CSV. 14. Select Edit, Generate Import AE. 15. Name the program IMP_CRS_CSV. 16. Expand the PeopleCode action and review the PeopleCode. 17. Close the PeopleCode. 18. Select File, Definition Properties. 19. Select the Advanced tab. 20. Select the Disable Restart check box. 21. Click OK. 22. Save the program. 23. With the Application Engine program open in PeopleSoft Application Designer, select Edit, Run Program. Enter the following information:
Page Element Run Control ID Output to Log Log File Name Value or Status RUN01 Selected Z:\STAnnn\IMP_CRS_CSV.LOG

24. Check the results in the Query Analyzer utility.


SELECT * FROM PS_PSU_COURSE_TBL WHERE COURSE > 3000

This concludes the activity. Do not continue.

644

PeopleSoft Proprietary and Confidential

Lesson 21

Importing Data Into the PeopleSoft System Using Flat Files

Review
In this lesson, you learned that: A file layout is a definition (or mapping) of a file to be processed; it identifies where the data fields are located in the file. The file layout has a Preview tab that you can use to view the data from FIXED and CSV files before creating an import program. Application Engine import programs can be automatically generated after you map the file layout to an input file. The File class provides methods and properties for reading from and writing to files. You can run a generated Application Engine import program from PeopleSoft Application Designer. You can change attributes when importing fields in the file layout preview.

Slide 417 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

645

Importing Data Into the PeopleSoft System Using Flat Files

Lesson 21

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

646

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files


Objectives
By the end of this lesson, you will be able to: List the methods used to read from and write to plain text files. Write to files defined by a file layout. Create Application Engine programs to export data to flat files. Create multilevel file layouts. Use PeopleCode with multilevel file layouts. Create and use segments in file layouts.

Slide 419 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

647

Writing Data to Flat Files

Lesson 22

Listing the Methods Used to Read From and Write to Plain Text Files
Use the File class to read from and write to plain text files using strings. The following methods are used with strings. Readline (string) WriteLine (string) WriteString (string)

Slide 420 ______________________________________________________________________________________________________

Student Notes
The following sample program reads a plain text file from file.in and writes it back out to file.out.
Local File &F1,&F2; Local String &Str; &F1 = GetFile(file.in, R); &F2 = GetFile(C:\output\file.out, W, %FilePath_Absolute); While &F1.ReadLine(&Str); &F2.WriteLine(&Str); End-While; &F1.Close(); &F2.Close();

Instructor Notes
In many programs, the WriteLine method is used to write out errors. Students should be familiar with this from the component interface lessons, where the template wrote the error log out to a file. This section discusses how to: Review the ReadLine method. Review the WriteLine method. Review the WriteString Method. Review the sample program. Question: List the methods used to read from and write to plain text files.

Reviewing the ReadLine Method The ReadLine method reads one line of text from the external file. The line includes the newline character used on the platform where the file is stored, but ReadLine strips out the newline character and inserts the result into the string variable &Str.
648 PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

When ReadLine runs, it moves the starting point for the next read operation to the end of the text just retrieved, so that each line in the file can be read in turn by subsequent ReadLine operations. When no more data remains to be read from the file, ReadLine returns False and clears the string variable is of any content. Reviewing the WriteLine Method The WriteLine method writes one string of text, string, to the output file associated with the File object calling this method, followed by a newline character appropriate to the platform where the file is being written. To build a single line using multiple strings, use the WriteString method. Reviewing the WriteString Method The WriteString method writes one string of text to the output file associated with the File object executing this method, without any newline character. Each string that is written extends the current line in the file. You can start a new line by using the WriteLine method to write the last part of the current line. WriteLine always adds a newline character appropriate to the platform where the file is being written, whether you supply a character string of any length, or a null string. Reviewing the Sample Program Describe whats going on in each section of the program.
Explanation Set variables. Program Code
Local File &F1,&F2; Local String &Str;

Instantiate the file object and open it in read mode.

&F1 = GetFile("file.in, R);

Instantiate the file object and open it in write mode with an absolute path.

&F2 = GetFile(C:\output\file.out,W, %FilePath_Absolute);

Read a line from the file and continue until the endof-file character. Write a line with a newline character. Disassociate the file object, release resources, and go out of scope.

While &F1.ReadLine(&Str); &F2.WriteLine(&Str); End-While; &F1.Close(); &F2.Close();

Question: Listing the Methods Used to Read From and Write to Plain Text Files Plain text files use strings for reading and writing. 1. True 2. False

PeopleSoft Proprietary and Confidential

649

Writing Data to Flat Files

Lesson 22

Answer The answer is 1 (True).

650

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Writing to Files Defined by a File Layout


Use the following methods to write to files defined by a file layout definition: WriteRecord(record) Write Rowset(rowset)

Slide 421 ______________________________________________________________________________________________________

Student Notes
Note the following about the using WriteRecord: Not all the fields in the file layout definition and the record have to match. The WriteRecord method only writes to like-named records. The WriteRecord method takes a record object as its parameter.

Note the following about the using WriteRowset: Not all the fields in the file layout definition and the records have to match. The two structures must be the same.

Instructor Notes
This section discusses how to: Review the WriteRecord method. Review the WriteRowset method. Review the CreateRowset method.

Reviewing the WriteRecord Method The WriteRecord method writes the contents of a record object to the output file. (A record object contains only one row of data from a SQL table.) You can use this method to build a transaction in the output file, one file record at a time, without having to instantiate and populate a rowset object. You can apply this method to any record whose structure and name matches that of a record defined in the current file layout. Note the following about the WriteRecord method: Not all the fields in the file layout definition and the record have to match. The WriteRecord method, like all file layout methods (refer to lesson 21 Importing Data into PeopleSoft System Using Flat Files for file layout methods), only pays attention to the like-named fields. If there are additional fields in the record or in the file layout definition, they are ignored.
PeopleSoft Proprietary and Confidential 651

Writing Data to Flat Files

Lesson 22

The WriteRecord method only writes to like-named records. If you rename a record after you use it to create a file layout definition, you have to rename it to the same name in your file layout. Because WriteRecord writes likenamed records, the same file layout definition can contain more than one record.

The WriteRecord method takes a record object as its parameter. A populated record object references a single row of data in the SQL table. This is why a SQL Fetch statement is used in a condition around the WriteRecord method. This fetches every row of data from the SQL table, then writes it to the file.

Reviewing the WriteRowset Method The WriteRowset method writes the contents of a rowset object, rowset, to the output file associated with the file object that calls this method. Regardless of whether the number of transactions that the rowset contains, (level zero row), calling this method once writes the entire contents of the rowset to the output file. Note the following abut WriteRowset: Every field in the two structures doesn't have to match (that is, every field or record thats in the file layout doesnt have to be in the component, and vice versa). The two structures must be the same. For example, if the component has PERSONAL_DATA at level zero and EMPL_CHECKLIST at level one, the file layout must have the same hierarchy. Reviewing the CreateRowset Method The CreateRowset method creates an empty rowset that has the structure of the file layout definition. Use the GetLevel0 function to get all the data from the component and copy it into the rowset. The GetLevel0 method copies all like-named fields to like-named records. The WriteRowset method writes all the component data to the file.

652

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Writing to Files Defined by a File Layout (continued)


The SQL class provides a built-in function, CreateSQL, to instantiate a SQL object.
&SQL1 = CreateSQL("%selectall(:1)", &recl);

%SelectAll is shorthand for selecting all fields in the specified record.


Slide 422 ______________________________________________________________________________________________________

Student Notes
The following is an example of using the File class and the SQL class to write a file:
/* Method: WriteRowSet */ Local File &MYFILE; Local Record &recl; Local SQL &SQL1; /********** Create an Instance of the records ***************/ &recl = CreateRecord(Record.PSU_COURSE_TBL); /** Create and instance of the file-that will be opened in Write mode with an absolute path. Then associate it with the appropriate File Layout */ &MYFILE = GetFile("c:\temp\COURSE_OUT.txt", "A", %FilePath_Absolute); &MYFILE.SetFileLayout(FileLayout.COURSE_FILE); /* Create SQL object to retrieve the values from the rowset %selectall select all fields */ &SQL1 = CreateSQL("%selectall(:1)", &recl); /* */ Loop through the rowset to get the values and write the rowset to file Description: Write the Course table to a file

While &SQL1.Fetch(&recl) &MYFILE.WriteRecord(&rec1); End-While; /* Close the file */ &MYFILE.Close();

Instructor Notes
This section discusses how to: Explain the CreateSQL function. Review the sample program. Question: Write to files defined by a file layout.

PeopleSoft Proprietary and Confidential

653

Writing Data to Flat Files

Lesson 22

Explaining the CreateSQL Function The CreateSQL function instantiates a SQL object from the SQL class and opens it on the given sqlstring and input values. The sqlstring parameter is a PeopleCode string value that provides the SQL statement. Any errors in the SQL processing cause the PeopleCode program to be terminated with an error message. SelectAll Syntax The SelectAll function uses the following syntax: %SelectAll(:num [ correlation _id] ) %SelectAll is shorthand for selecting all fields in the specified record, wrapping DateTime fields with %DateOut, %TimeOut, and so on. The pseudocode looks like this: Select (All Fields, :num correlation_id) from %Table(:num) prefix This shortcut is only appropriate if the statement is being used in PeopleCode or PeopleSoft Application Engine to read data into memory. Dynamic views should retain the internal database formats for DateTime fields. Reviewing the Sample Program Describe whats going on in each section of the program.
Explanation Declare variables. Program Code
Local File &MYFILE; Local Record &recl; Local SQL &SQL1;

Instantiate the record.

/** Create an Instance of the records ******/ &recl = CreateRecord(Record.PSU_COURSE_TBL);

Instantiate the file and associate it with the file layout.

/** Create and out */ &MYFILE = GetFile("c:\temp\COURSE_OUT.txt", "A", %FilePath_Absolute); &MYFILE.SetFileLayout(FileLayout.COURSE_FILE);

Create a SQL object.

/*

Create SQL object %selectall - select

all fields */ &SQL1 = CreateSQL("%selectall(:1)", &recl);

Fetch the values. Write the record to the file.

/*

Loop through the rowset to get the values

and write the rowset to file */ While &SQL1.Fetch(&recl) &MYFILE.WriteRecord(&rec1); End-While; /* Close the file */

&MYFILE.Close();

654

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Question: Writing to Files Defined by a File Layout Which method do you use to write files defined by a file layout? 1. WriteRow 2. WriteRowset 3. WriteCollection 4. WriteString Answer The answer is 2 (WriteRowset).

PeopleSoft Proprietary and Confidential

655

Writing Data to Flat Files

Lesson 22

Creating Application Engine Programs to Export Data to Flat Files


Use the following steps to create an export Application Engine program. 1. In PeopleSoft Application Designer, select File, New, Application Engine Program. 2. Select Insert, Action. 3. Save the program. 4. Change the action type to PeopleCode. 5. Enter the PeopleCode to export the file. 6. Save the program. 7. Run the program.
Slide 423 ______________________________________________________________________________________________________

Instructor Notes
This section presents a review question for the current objective. Question: Writing Application Engine Programs to Export Data to Flat Files Application Engine programs that export data to a file need which type of action? 1. SQL 2. PeopleCode 3. Do Select 4. Log Message Answer The answer is 2 (PeopleCode).

656

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Activity 34:

Writing Data to a File


In this activity, you will review the activity overview and: 1. Create an Application Engine program to write data to a flat file. 2. Write the file in Microsoft Excel format. See Integration Tools: Activity Guide, Writing Data to Flat Files Activity 34: Writing Data to a File.

Slide 424 ______________________________________________________________________________________________________

Instructor Notes
This code is shown on slide 422. There is also a copy of the code in z:\TCA101\Tools\1022_IntTools\scripts\export_crs.txt. Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will create an Application Engine program to write data from the PSU_COURSE_TBL to a flat sequential file. After the write was successful, modify the file layout to write the file in Microsoft Excel format.

Creating an Application Engine Program to Write Data to a File


To create an Application Engine program to write data to a file: 1. In PeopleSoft Application Designer, select File, New, Application Engine Program. 2. Select File, Definition Properties. 3. Select Disable Restart. 4. Click OK. 5. Click on the Step01 6. Select Insert, Action. 7. Save the program as EXPORT_CRS. 8. Change the action type to PeopleCode. 9. Double-click in the gray area for the PeopleCode and enter the PeopleCode to export the file. Note. A copy of the PeopleCode is located in \1022_IntTools\scripts\export_crs.txt. If you copy this text, you will need to change the file path to your student folder.
PeopleSoft Proprietary and Confidential 657

Writing Data to Flat Files

Lesson 22

10. Save the program. 11. Run the program. 12. Check that the flat file was created by looking in your student folder. Results This is what the flat file should look like:

Flat file from created

Writing the File in Microsoft Excel Format


To write the file in Microsoft Excel format: 1. Open the file layout COURSE_FILE. 2. Select File, Definition Properties, Use tab. 3. Select Excel format. 4. Click OK. 5. Save the file layout. 6. Open the Application Engine program EXPORT_CRS. 7. Change the output file name to COURSE_FILE.CSV. 8. Save the Application Engine program. 9. Run the Application Engine program EXPORT_CRS. 10. Start Microsoft Excel. 11. Open the file z:\STAnnn\COURSE_FILE.CSV in Excel. Results This is what the Microsoft Excel file should look like:

658

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Excel spreadsheet This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

659

Writing Data to Flat Files

Lesson 22

Creating Multilevel File Layouts


In PeopleSoft, relationships between records are based on key structure and parent/child relationship. The file layout provides a way to map file data to the PeopleSoft rowset, as shown in the following diagram:
PeopleSoft Tables File Layout Object PO_FILE PO_HDR PO_HDR PO_LINE PO_LINE PO_SHIP 000 001 002 Rec ID

Fixed File PO_SHIP 000 .. 001 ... 002 ...

Multilevel file relationship


Slide 425 ______________________________________________________________________________________________________

Student Notes
The following example shows a multilevel file layout:

660

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

SDK_BUS_EXP file layout showing parent/child records

Instructor Notes
In PeopleSoft, data is stored in a relational database. Rather than writing separate files, we want to combine these files.

PeopleSoft Proprietary and Confidential

661

Writing Data to Flat Files

Lesson 22

Creating Multilevel File Layouts (continued)


To create a multilevel file layout: 1. Create a new file layout. 2. Insert the records. 3. Use the toolbar arrows to place the records in the appropriate hierarchy. 4. Double-click the record name to set the file layout segment properties. 5. Assign a unique file record ID to each record. The start position and length are automatically updated. 6. Adjust the maximum record length to include the record ID. 7. Click OK. 8. Click Yes to automatically increment the start position of all fields. 9. Save the file.
Slide 426 ______________________________________________________________________________________________________

Student Notes
The following illustration shows the toolbar arrows:

Toolbar arrows

662

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Creating Multilevel File Layouts (continued)


The file record ID identifies the record. Note the following about file record IDs: They can be used with fixed and CSV files. The ID must be included on the flat file. They are assigned at the file layout segment level.

Slide 427 ______________________________________________________________________________________________________

Student Notes
Use the File Layout Segment Properties dialog box to assign file record IDs:
Page Name File Layout Segment Properties Navigation 1. 2. File, Open, File Layout, SDK_BUS_EXP Double click SDK_PERS_DATA.

File Layout Segment Properties dialog box

PeopleSoft Proprietary and Confidential

663

Writing Data to Flat Files

Lesson 22

Instructor Notes
This section discusses how to: Explain the student notes example. Question: Create multilevel files.

Explaining the Student Notes Example In the example in the student notes, the file record ID for SDK_PERS_DATA is 001. It is not necessary to use file record IDs with XML files, as the tags identify the records. Question: Creating Multilevel File Layouts True or false: File record IDs are only used with fixed or CSV files. 1. True 2. False Answer The answer is 1 (True).

664

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Using PeopleCode with Multilevel File Layouts


The following code segment shows creating the rowsets and file:
/********** Create an Instance of the rowsets ***************/ &rowset1 = CreateRowset(Record.PSU_PO_HDR, CreateRowset(Record.PSU_PO_DTL)); &rowset2 = &rowset1.GetRow(1).GetRowset(1); /** Create an instance of the File - this will be opened in Write mode with an absolute path. Then associate it with the appropriate File Layout */ &MYFILE = GetFile("c:\temp\PO_OUT.txt", "W", %FilePath_Absolute); &MYFILE.SetFileLayout(FileLayout.PO_FILE);

Slide 428 ______________________________________________________________________________________________________

Instructor Notes
For the level zero record PSU_PO_HDR, explain that students need to include level zero and level one. For level one, explain that you use the first row in level zero.

PeopleSoft Proprietary and Confidential

665

Writing Data to Flat Files

Lesson 22

Using PeopleCode with Multilevel File Layouts (continued)


The following code segment shows creating the SQL statements.
/* Create SQL object to retrieve the values from the rowset */

&Order = "00000001"; &SQL1 = CreateSQL("%selectall(:1)where ORDER_NBR = :2 ", &recl, &Order); &SQL2 = CreateSQL("%selectall(:1)where ORDER_NBR = :2 ", &rec2, &Order);

Slide 429 ______________________________________________________________________________________________________

Instructor Notes
Explain that, in this case, we are only retrieving one row at level zero, for the ORDER_NBR 00000001. Let students know that when you export data, you will probably be taking data from an online page. Here is an example:
&Order = PSU_PO_HDR.ORDER_NBR";

666

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Using PeopleCode with Multilevel File Layouts (continued)


The following piece of code shows looping through the level one record:
While &SQL1.Fetch(&recl) /*copy record to rowset */ &recl.CopyFieldsTo(&rowset1.GetRow(1).PSU_PO_HDR); &I = 1; /* Fetch data from PSU_PO_DTL */ While &SQL2.Fetch(&rec2) /* Copy record to the rowset */ &rec2.CopyFieldsTo(&rowset2.GetRow(&I).PSU_PO_DTL); &rowset2.InsertRow(&I); &I = &I + 1; End-While; /* Write rowset to file */ &MYFILE.WriteRowset(&rowset1); End-While;

Slide 430 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

667

Writing Data to Flat Files

Lesson 22

Activity 35:

Creating a Multilevel File Layout


In this activity, you will review the activity overview and: 1. Create a multilevel file layout. 2. Create and test an export Application Engine program. See Integration Tools: Activity Guide, Writing Data to Flat Files Activity 35: Creating a Multilevel File Layout.

Slide 431 ______________________________________________________________________________________________________

Instructor Notes
Here is the PeopleCode. It is also located in Z:\TCA101\TOOLS\1022_intTools\scripts\export_po.txt. Students need to change the file path.
/***********************************************************************/ /* Method: WriteRowSet for multi-level file /* Description: Write the PO header and detail for Order 00000021 */ */

/***********************************************************************/ Local File &MYFILE; Local Rowset &rowsetl, &rowset2; Local Record &recl, &rec2; Local SQL &SQL1, &SQL2; /********** Create an Instance of the records ***************/ &recl = CreateRecord(Record.PSU_PO_HDR); &rec2 = CreateRecord(Record.PSU_PO_DTL); /********** Create an Instance of the rowsets ***************/ &rowset1 = CreateRowset(Record.PSU_PO_HDR, CreateRowset(Record.PSU_PO_DTL)); &rowset2 = &rowset1.GetRow(1).GetRowset(1); /** Create an instance of the File - this will be opened in Write mode with an absolute path. Then associate it with the appropriate File Layout */ &MYFILE = GetFile("c:\temp\PO_OUT.txt", "W", %FilePath_Absolute); &MYFILE.SetFileLayout(FileLayout.PO_FILE); /* Create SQL object to retrieve the values from the rowset */

&Order = "00000021"; &SQL1 = CreateSQL("%selectall(:1)where ORDER_NBR = :2 ", &recl, &Order);

668

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

&SQL2 = CreateSQL("%selectall(:1)where ORDER_NBR = :2 ", &rec2, &Order); /* */ Loop through the rowset to get the values and write the rowset to file

While &SQL1.Fetch(&recl) /*copy record to rowset */ &recl.CopyFieldsTo(&rowset1.GetRow(1).PSU_PO_HDR); &I = 1; /* Fetch data from PSU_PO_DTL */ While &SQL2.Fetch(&rec2) /* Copy record to the rowset */ &rec2.CopyFieldsTo(&rowset2.GetRow(&I).PSU_PO_DTL); &rowset2.InsertRow(&I); &I = &I + 1; End-While; /* Write rowset to file */ &MYFILE.WriteRowset(&rowset1); End-While; /* Close the file */ &MYFILE.Close();

Note. This activity should take approximately 15 minutes.

Activity Overview
In this activity, you will create a multilevel file layout for purchase orders. The parent record is PSU_PO_HDR (header file) and the child is PSU_PO_DTL (detail file). The header file should have a file record ID of 001, and the detail file should have a file record ID of 002. After you create the file layout, create and test an Application Engine program to write the header and detail data for purchase order 00000021 to a flat fixed file.

Creating a Multilevel File Layout


To create the multilevel file layout: 1. Select File, New, File Layout. 2. Insert records PSU_PO_HDR and PSU_PO_DTL. Make sure that PSU_PO_DTL is a child of PSU_PO_HDR. If necessary, use the toolbar arrows to arrange the structure. 3. Double click PSU_PO_HDR and set the file segment properties. Enter the following information:

PeopleSoft Proprietary and Confidential

669

Writing Data to Flat Files

Lesson 22

Page Element Max Record Length File Record ID

Value or Status 68 001

4. Click OK. 5. Select Yes to increment start positions on all fields. 6. Double-click PSU_PO_DTL and set the file segment properties: Enter the following information:
Page Element Max Record Length File Record ID Value or Status 55 002

7. Click OK. 8. Select Yes to increment start positions on all fields. 9. Save the file layout as PO_FILE.

Creating and Testing an Export Application Engine Program


To create an Application Engine program: 1. Select File, New, Application Engine Program. 2. Set the program properties to include a description, and disable restart. 3. Click Step01. 4. Select Insert, Action. 5. Save the program as EXPORT_PO. 6. Change the action type to PeopleCode. 7. Enter the PeopleCode to export the file. Note. A copy of the PeopleCode is located in \1022_IntTools\scripts\export_po.txt. If you copy this text, you will need to change the file path to your student folder. 8. Save the program. 9. Run the program. 10. Check that the flat file was created.

670

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Results The flat file should look like this:

Output file created This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

671

Writing Data to Flat Files

Lesson 22

Creating and Using Segments in File Layouts


Instead of inserting records into a file layout, you can insert segments. A segment is the same as a record, except it does not initially contain any record or field information. You need to manually add all the segment information. After you add the information, you can treat a segment just like any other record.
Slide 432 ______________________________________________________________________________________________________

672

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Creating and Using Segments in File Layouts (continued)


Here are some examples of how segments can be used: Indicate the action to take for the rows of data. Limit the fields on the file layout. Identify the file layout.

Slide 433 ______________________________________________________________________________________________________

Student Notes
The following example shows a file layout definition that was created using a segment that only contains three fields from the PERSONAL_DATA record:

File layout containing segment

Instructor Notes
Review some examples of using segments. Indicating the Action to be Taken for the Rows of Data We will do this in the activity. There may be times when you need to send a flat file to another application and you want to indicate the action that needs to be taken: insert, update, delete, and so forth. By adding a segment, you can use the segment to indicate the action. Limiting the Fields on the File Layout Refer to the student notes. Rather than inserting the record into the file layout and deleting all the unwanted fields, you can just add the fields that you want. Identifying the File Layout You may receive a file that has multiple record data in one file. You use a segment to identify the file record ID. In the following file, the 999 line is the segment.
999 PRODUCT /*the following rowset uses the PRODUCT layout */ 001 /* level 0 record */ 101 /* level 1 record */

PeopleSoft Proprietary and Confidential

673

Writing Data to Flat Files

Lesson 22

201 /* level 2 record */ 201 /* level 2 record */ 999 ORDER /*the following rowset uses the ORDER layout */ 001 /* level 0 record */ 111 /* level 1 record */ 111 /* level 1 record */

There is a good example of the PeopleCode to use for this type of segment. See PeopleTools 8.44 PeopleBook: PeopleCode Reference, File Class.

674

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Creating and Using Segments in File Layouts (continued)


To create a segment: 1. Select Insert, Segment. 2. Specify the file record name, maximum record length, and file record ID, if applicable. 3. With the cursor positioned on the segment name, select either Insert, FileField or Insert, Database Field. 4. Arrange all segments and fields in the correct order.
Slide 434 ______________________________________________________________________________________________________

Student Notes
The segment is equivalent to a record; however, you define the length and fields manually, as shown in the following example:

Segment properties

PeopleSoft Proprietary and Confidential

675

Writing Data to Flat Files

Lesson 22

The fields are added to a segment using either the FileField or Database Field commands. If you select FileField, you must supply the field name manually. If you select Database Field, you can select the field name. The following example shows the FileField process:

File Layout Field Properties dialog box

Note. If you use the FileField command, you must manually enter all the field attributes.

676

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

Activity 36:

Importing Data Using Segments


In this activity, you will review the activity overview and: 1. Create a file layout using segments. 2. Add PeopleCode to write a row to a flat file when a row is added or changed. 3. Test the PeopleCode. See Integration Tools: Activity Guide, Writing Data to Flat Files Activity 36: Importing Data Using Segments.

Slide 435 ______________________________________________________________________________________________________

Instructor Notes
When the students have created the file layout, they can view the data. Note. The order does not really matter, as we are writing out a file; however, this same file layout may be used for import.

Activity Overview
In this activity, you will create a file layout to import setIDs. Every time you add or change a table setID (SETID_TBL record), a row needs to be written to a flat file. You will create a segment with the file ID 888 that will contain one field to indicate if the transaction is an add (A) or a change (C). The resulting flat file will contain a row indicating the action followed by a row containing the transaction data. The PeopleCode should be placed on the SavePostChange event for the field SETID on the record SETID_TBL. To access the TableSet ID page, select PeopleTools, Utilities, Administration, TableSet IDs. Note. DESCRLONG fields have a length of zero. To use a DESCRLONG field in a file layout, you must assign a valid length to the field.

Creating a File Layout Using Segments


To create a file layout using segments: 1. Select File, New, File Layout. 2. Select Insert, Record, SETID_TBL. 3. Double-click SETID_TBL and set the file record ID to 000.

PeopleSoft Proprietary and Confidential

677

Writing Data to Flat Files

Lesson 22

4. Click OK and then click Yes to increment all fields. 5. Double click the SETID field, and set the start position to 5. 6. In the Propagate field, enter 1 and click the >>> button. 7. Click OK. 8. Double-click the DESCRLONG field and change the length to 80. 9. Click OK. 10. Double-click SETID_TBL and set the maximum record length to 130. 11. Click OK. 12. Select Insert, Segment. Enter the following information:
Page Element File Record Name Max Rec Length File Record ID Value or Status PSCAMA 4 888

13. Click OK. 14. Click PSCAMA. 15. Select Insert, Database Field, AUDIT_ACTN. 16. Change the start position to 4. 17. Click OK and close. 18. Ensure that the records are in the correct order. 19. Save the file layout as SETID_FILE. Results The file layout that you created should look like this:

678

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

SETID_FILE file layout

Adding PeopleCode to Write a Row to a Flat File When a Row Is Added or Changed
To add the PeopleCode to write a row to a flat file when a row is added or changed: 1. Select File, Open, Record, SETID_TBL. 2. Select View, View PeopleCode. The PeopleCode editor opens the SavePostChange event on the SETID field. Notice that PeopleCode already exists. The following PeopleCode shows how to write the flat file:
/********************Declare Variables for SetID *********************/ Local File &SETIDOUT; Local Record &rRec1, &rRec2; Local SQL &SQL1; /**************End Declare Variables for SetID **********************/ Declare Function add_tableset_cntrl PeopleCode FUNCLIB_UTIL.FIELDNAME FieldFormula; /* when adding a setid always add a tableset control */ If %Mode = "A" Then add_tableset_cntrl(SETID_TBL.SETID, SETID_TBL.SETID); Gray(SETID_TBL.PARTIAL_SHARING); End-If; /*************** Create an Instance of the records *****************/ &rRec1 = CreateRecord(Record.PSCAMA); &rRec2 = CreateRecord(Record.SETID_TBL); /** Create and instance of the File - open in Append mode with an absolute path. Then associate it with the appropriate File Layout ******/

PeopleSoft Proprietary and Confidential

679

Writing Data to Flat Files

Lesson 22

&SETIDOUT = GetFile("z:\<student folder>\SETID_OUT.txt", "A", %FilePath_Absolute); &SETIDOUT.SetFileLayout(FileLayout.SETID_FILE); /*********** Set the Tax location code to get the value from the page ****/ &SETID = SETID_TBL.SETID; /*******Set the value for the AUDIT_ACTN and write the record********/ If %Mode = "A" Then &rRec1.AUDIT_ACTN.Value = "A"; Else &rRec1.AUDIT_ACTN.Value = "C"; End-If; &SETIDOUT.WriteRecord(&rRec1); /*********** Write the SETID record ********************************/ &rRec2 = GetRecord(); &SETIDOUT.WriteRecord(&rRec2); /*************Close the file****************************************/ &SETIDOUT.Close();

Note. A copy of the PeopleCode is located in \1022_IntTools\scripts\setid_down.txt. If you copy this text, you will need to change the file path to your student folder. 3. Save the record.

Testing the PeopleCode


To test the PeopleCode: 1. In the browser, sign in as PTINT, using the password PTINT. 2. Select PeopleTools, Utilities, Administration, TableSet IDs, EUR01. 3. Change the comments. 4. Save. 5. Click the Add button. Enter the following information:
Page Element SETID Description Short Description Comments Value or Status TRTST Training Test Test This is a test.

680

PeopleSoft Proprietary and Confidential

Lesson 22

Writing Data to Flat Files

6. Click Save. 7. Open the flat file in Notepad. The file SETID_OUT.txt will be located in your student folder. Results The flat file should look like this:

Sample output This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

681

Writing Data to Flat Files

Lesson 22

Review
In this lesson, you learned that: You can read from and write to plain text files using strings (WriteLine and WriteString). You can use the WriteRecord and WriteRowset methods with the File object. You use a PeopleCode action in an Application Engine program to write to flat files. Use multilevel file layouts can be used to define parent/child relationships. Each record needs a unique file record ID. The PeopleCode for multilevel files uses the record and rowset classes. File segments can be used to indicate an action, identify a file layout, or limit data. All fields for segments are manually entered.
Slide 436 ______________________________________________________________________________________________________

682

PeopleSoft Proprietary and Confidential

Lesson 23

Final Activity
Objectives
By the end of this lesson, you will be able to implement a new message that uses a component interface in the subscription PeopleCode.
Slide 438 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

683

Final Activity

Lesson 23

Activity 37:

Using a Component Interface in Subscription PeopleCode


In this activity, you will review the activity overview and: 1. Create a message. 2. Create a component interface. 3. Write the subscription PeopleCode to use the component interface. 4. Test the subscription PeopleCode. See Integration Tools: Activity Guide, lesson 23 Final Activity, Activity 37: Using a Component Interface in Subscription PeopleCode.

Slide 439 ______________________________________________________________________________________________________

Instructor Notes
This activity uses a level 0 record with no collections to make the code a little simpler. Here is an example of the completed code as with any code there are numerous ways of writing the code:
/***************Stock Item Subscription Code using Component Interface **********/ Local File &fileLog; Local ApiObject &oSession, &oStockItems; Local Message &MSG; Local Rowset &MSG_ROWSET; /*************** BEGIN FUNCTION - errorhandler **********************************/ Function errorHandler() Local ApiObject &oPSMessageCollection, &oPSMessage; Local number &i; Local string &sErrMsgSetNum, &sErrMsgNum, &sErrMsgText, &sErrType; &oPSMessageCollection = &oSession.PSMessages; For &i = 1 To &oPSMessageCollection.Count &oPSMessage = &oPSMessageCollection.Item(&i); &sErrMsgSetNum = &oPSMessage.MessageSetNumber; &sErrMsgNum = &oPSMessage.MessageNumber; &sErrMsgText = &oPSMessage.Text; &fileLog.WriteLine(&sErrType | " (" | &sErrMsgSetNum | "," | &sErrMsgNum | ") - " | &sErrMsgText); End-For; rem ***** Delete the Messages from the collection *****; &oPSMessageCollection.DeleteAll(); End-Function; /*************** END FUNCTION - errorhandler **************************************/

684

PeopleSoft Proprietary and Confidential

Lesson 23

Final Activity

/****** Main Processing ************************************************/ &MSG = GetMessage(); &MSG_ROWSET = &MSG.GetRowset(); try rem ***** Set the Log File *****; &fileLog = GetFile("Z:<student folder>\STOCK_ITEMS.log", "w", "a", %FilePath_Absolute); &fileLog.WriteLine("Begin"); rem ***** Get current PeopleSoft Session *****; &oSession = %Session; rem ***** Set the PeopleSoft Session Error Message Mode *****; rem ***** 0 - None *****; rem ***** 1 - PSMessage Collection only (default) *****; rem ***** 2 - Message Box only *****; rem ***** 3 - Both collection and message box *****; &oSession.PSMessagesMode = 1; rem ***** Get the Component Interface *****; &oStockItems = &oSession.GetCompIntfc(CompIntfc.STOCK_ITEMS); If &oStockItems = Null Then errorHandler(); throw CreateException(0, 0, "GetCompIntfc failed"); End-If; rem ***** Set the Component Interface Mode *****; &oStockItems.InteractiveMode = False; &oStockItems.GetHistoryItems = True; &oStockItems.EditHistoryItems = False; rem **** Evaluate PSCAMA record ***********************; &Action = &MSG_ROWSET(1).PSCAMA.AUDIT_ACTN.Value; rem ***** Set Component Interface Get/Create Keys *****; &oStockItems.ITEM_CD = &MSG_ROWSET(1).PSU_STOCK_TBL.ITEM_CD.Value; rem ********Evaluate Action ***************************; Evaluate &MSG_ROWSET(1).PSCAMA.AUDIT_ACTN.Value When = "C" /* Non-key data in publishing node was changed rem ***** Execute Get *****; If Not &oStockItems.Get() Then rem ***** No rows exist for the specified keys.*****; errorHandler(); throw CreateException(0, 0, "Get failed"); Else &oStockItems.CopyRowset(&MSG_ROWSET); End-If; Break; When = "A" /* New row added/inserted in publishing node rem ***** Execute Create ******; If Not &oStockItems.Create() Then rem ***** Unable to Create Component Interface for the Add keys provided. *****; errorHandler(); throw CreateException(0, 0, "Create failed"); */ */

PeopleSoft Proprietary and Confidential

685

Final Activity

Lesson 23

Else &oStockItems.CopyRowset(&MSG_ROWSET); End-If; Break; End-Evaluate; rem ***** Execute Save *****; If Not &oStockItems.Save() Then; errorHandler(); throw CreateException(0, 0, "Save failed"); End-If; rem ***** Execute Cancel *****; If Not &oStockItems.Cancel() Then; errorHandler(); throw CreateException(0, 0, "Cancel failed"); End-If; catch Exception &ex rem Handle the exception; &fileLog.WriteLine(&ex.ToString()); end-try; &fileLog.WriteLine("End"); &fileLog.Close();

Note. The project \1022_IntTools\Projects\ITEMS contains the solution. Note. This activity should take approximately 40 minutes.

Activity Overview
In this activity, you will create a new message and component interface for stock items. The subscription PeopleCode will use the component interface to validate the message before updating the database. The necessary records and components for this application are listed below:
Definition Type Record Component Definition Name PSU_STOCK_TBL PSU_STOCK

Test the subscription PeopleCode by creating a test message and running the subscription PeopleCode against the test message.

Creating a Message:
To create a message:

686

PeopleSoft Proprietary and Confidential

Lesson 23

Final Activity

1. In Application Designer, select File, New, Message. 2. Click on VERSION_1. 3. Select Insert, Child Record, PSU_STOCK_TBL. 4. Enter a description in the message properties. 5. Select TRAINING_CHNL for the message channel. 6. Save the message as ITEM_SYNC.

Creating a Component Interface.


To create a component interface: 1. Select File, New, Component Interface. 2. Select PSU_STOCK for the component. 3. Accept the defaults. 4. Enter a description in the component interface properties. 5. Save the component interface as STOCK_ITEMS. 6. Grant access to the component interface for the permission list ALLPAGES. 7. Test the component interface in PeopleSoft Application Designer by adding a new item 1111. 8. In the browser, select Order Management, Stock Items to verify that your item was successfully added.

Writing the Subscription PeopleCode to using the Component Interface.


To write the subscription PeopleCode using the component interface: 1. In Application Designer, select File, Open, Message, ITEM_SYNC. 2. Select Insert, Message Subscription. 3. Enter ItemSyncCi for the PeopleCode program name. 4. Click OK. Note. A copy of the completed PeopleCode is available in \1022_844\scripts\itemsyncci.txt. If you use this code, you must change the path for the log file to your student folder. 5. Enter declarations for the message.
Local Message &MSG; Local Rowset &MSG_ROWSET;

6. Drag the component interface STOCK_ITEMS into the PeopleCode.

PeopleSoft Proprietary and Confidential

687

Final Activity

Lesson 23

7. Modify the template. a. The function errorhandler does not require any changes. b. Add the main processing section after the errorHandler function.
/****** Main Processing ****************/ &MSG = GetMessage(); &MSG_ROWSET = &MSG.GetRowset();\

c. Add the PeopleCode to evaluate PSCAMA after the component interface mode has been set.
rem **** Evaluate PSCAMA record ***********************; &Action = &MSG_ROWSET(1).PSCAMA.AUDIT_ACTN.Value;

d. Set the component interface get/create keys based on the value in the message rowset.
rem ***** Set Component Interface Get/Create Keys *****; &oStockItems.ITEM_CD = &MSG_ROWSET(1).PSU_STOCK_TBL.ITEM_CD.Value;

e. Write the code to evaluate the action and copy the values from the rowset into the component interface.
rem ********Evaluate Action ***************************; Evaluate &MSG_ROWSET(1).PSCAMA.AUDIT_ACTN.Value When = "C" /* Non-key data in publishing node was changed If Not &oStockItems.Get() Then errorHandler(); throw CreateException(0, 0, "Get failed"); Else &oStockItems.CopyRowset(&MSG_ROWSET); End-If; Break; When = "A" /* New row added/inserted in publishing node If Not &oStockItems.Create() Then errorHandler(); throw CreateException(0, 0, "Create failed"); Else &oStockItems.CopyRowset(&MSG_ROWSET); End-If; Break; End-Evaluate; */ */

f.

Delete the Get/Set Component Interface properties (you have just coded that in the evaluate section).

688

PeopleSoft Proprietary and Confidential

Lesson 23

Final Activity

g. Uncomment the Save and Cancel. 8. Save the PeopleCode.

Testing the Subscription PeopleCode.


To test the subscription PeopleCode: 1. Right-click on VERSION_1. 2. Select Create Test message. 3. Enter the following information for the test message:
Page Element PSU_STOCK_TBL.ITEM_CD PSU_STOCK_TBL DESCR PSU_STOCK_TBL QTY_ON_HAND PSU_STOCK_TBL PRICE PSU_STOCK_TBL MIN_STOCK_LEVEL PSU_STOCK_TBL AUTO_REORDER PSU_STOCK_TBL REORDER_QUANTITY PSCAMA.AUDIT_ACTION Value or Status 1010 TEST CI CODE 100 10.00 25 Y 50 A

4. Click OK. 5. Write down the publication number. ________ 6. Click OK to dismiss the dialog box. 7. Create a second test message to test a change using the following data:
Page Element PSU_STOCK_TBL.ITEM_CD PSU_STOCK_TBL PRICE PSCAMA.AUDIT_ACTION Value or Status 1010 12.22 C

8. Write down the publication number. ________ 9. Create a third test message to test an missing required field using the following data:
Page Element PSU_STOCK_TBL.ITEM_CD PSU_STOCK_TBL DESCR PSU_STOCK_TBL QTY_ON_HAND PSU_STOCK_TBL PRICE Value or Status 1011 Leave blank 50 10.00

PeopleSoft Proprietary and Confidential

689

Final Activity

Lesson 23

Page Element PSU_STOCK_TBL MIN_STOCK_LEVEL PSU_STOCK_TBL AUTO_REORDER PSU_STOCK_TBL REORDER_QUANTITY PSCAMA.AUDIT_ACTION

Value or Status 25 Y 50 A

10. Write down the publication number. ________ Note. Before testing the PeopleCode, you may elect to set the PeopleCode debugger. 11. Right-click on the message subscription PeopleCode program. 12. Select Run PeopleCode. 13. Enter the publication number as recorded in step 5. 14. When the PeopleCode has completed, dismiss the dialog box. 15. In the browser, select Order Management, Stock Items, 1010. 16. In Application Designer, right-click on the message subscription PeopleCode program. 17. Select Run PeopleCode. 18. Enter the publication number as recorded in step 8. 19. When the PeopleCode has completed, dismiss the dialog box. 20. In the browser, select Order Management, Stock Items, 1010. 21. In Application Designer, right-click on the message subscription PeopleCode program. 22. Select Run PeopleCode. 23. Enter the publication number as recorded in step 10. 24. When the PeopleCode has completed, dismiss the dialog box. 25. In the browser, select Order Management, Stock Items. 26. Click Search. 27. Check the error log STOCK_ITEMS.log. Results The error message will be displayed in the log for STOCK_ITEMS:

690

PeopleSoft Proprietary and Confidential

Lesson 23

Final Activity

STOCK_ITEMS.log This concludes the activity. Do not continue.

PeopleSoft Proprietary and Confidential

691

Final Activity

Lesson 23

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

692

PeopleSoft Proprietary and Confidential

Lesson 24

Course Review
Objectives
In this course you learned how to: Describe the PeopleSoft integration technologies. Integrate data with PeopleSoft and third-party systems using component interfaces. Configure PeopleSoft Integration Broker. Send and receive messages using PeopleSoft Integration Broker. Create integrations requiring transformations, translations and filtering. Test connector and message processing using the Send Master utility. Integrate with third-party systems using Web Services Definition Language (WSDL) files. Use flat files to integrate PeopleSoft data with PeopleSoft and third-party systems.

Slide 441 ______________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

693

Course Review

Lesson 24

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

694

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code
Samples
This appendix contains sample code for the following: STUDENT_PROFILE component interface template. STUDENT_PROFILE component interface visual basic template. STUDENT_PROFILE component interface Java template. SCHOOL_TRANSFORM xslt.

______________________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

695

Sample Code

Appendix A

STUDENT_PROFILE Component Interface Template


The example is the PeopleCode template that was created for STUDENT_PROFILE component interface.
/* ===>This is a dynamically generated PeopleCode template to be used only as a helperto the application developer.You need to replace all references to '[*]' OR default values with references toPeopleCode variables and/or a Rec.Fields. */ Local File &fileLog; Local ApiObject &oSession, &oStudentProfile;

Error Handling
Function errorHandler() Local ApiObject &oPSMessageCollection, &oPSMessage; Local number &i; Local string &sErrMsgSetNum, &sErrMsgNum, &sErrMsgText, &sErrType; &oPSMessageCollection = &oSession.PSMessages; For &i = 1 To &oPSMessageCollection.Count &oPSMessage = &oPSMessageCollection.Item(&i); &sErrMsgSetNum = &oPSMessage.MessageSetNumber; &sErrMsgNum = &oPSMessage.MessageNumber; &sErrMsgText = &oPSMessage.Text; &fileLog.WriteLine(&sErrType | " (" | &sErrMsgSetNum | "," | &sErrMsgNum | ") - " | &sErrMsgText); End-For; rem ***** Delete the Messages from the collection *****; &oPSMessageCollection.DeleteAll(); End-Function;

Main Processing
Try rem ***** Set the Log File *****; &fileLog = GetFile("C:\temp\STUDENT_PROFILE.log", "w", "a", %FilePath_Absolute); &fileLog.WriteLine("Begin");

Get the current PeopleSoft session and set the message error mode
rem ***** Get current PeopleSoft Session *****; &oSession = %Session; rem ***** Set the PeopleSoft Session Error Message Mode *****; rem ***** 0 - None *****; rem ***** 1 - PSMessage Collection only (default) *****; rem ***** 2 - Message Box only *****; rem ***** 3 - Both collection and message box *****; &oSession.PSMessagesMode = 1;

696

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

Get the component interface and set the component interface mode
rem ***** Get the Component Interface *****; &oStudentProfile = &oSession.GetCompIntfc(CompIntfc.STUDENT_PROFILE); If &oStudentProfile = Null Then errorHandler(); throw CreateException(0, 0, "GetCompIntfc failed"); End-If; rem ***** Set the Component Interface Mode *****; &oStudentProfile.InteractiveMode = False; &oStudentProfile.GetHistoryItems = True; &oStudentProfile.EditHistoryItems = False;

Set the keys for the component interface


rem ***** Set Component Interface Get/Create Keys *****; &oStudentProfile.STUDENT_ID = [*];

Execute the get and/or create


rem ***** Execute Get *****; If Not &oStudentProfile.Get() Then rem ***** No rows exist for the specified keys.*****; errorHandler(); throw CreateException(0, 0, "Get failed"); End-If; rem ***** Execute Create ******; rem If Not &oStudentProfile.Create() Then; rem ***** Unable to Create Component Interface for the Add keys provided. *****; rem rem errorHandler(); throw CreateException(0, 0, "Create failed");

rem End-If;

Get and set the level 0 properties


rem ***** Begin: Get/Set Component Interface Properties *****; rem ***** Get/Set Level 0 Field Properties *****; &fileLog.WriteLine("&oStudentProfile.STUDENT_ID = " | &oStudentProfile.STUDENT_ID); rem &oStudentProfile.STUDENT_ID = [*]; &fileLog.WriteLine("&oStudentProfile.STUDENT_NAME = " | &oStudentProfile.STUDENT_NAME); rem &oStudentProfile.STUDENT_NAME = [*]; &fileLog.WriteLine("&oStudentProfile.CUSTOMER_ID = " | &oStudentProfile.CUSTOMER_ID); rem &oStudentProfile.CUSTOMER_ID = [*]; &fileLog.WriteLine("&oStudentProfile.SAME_ADDR_CUSTOMER = " | &oStudentProfile.SAME_ADDR_CUSTOMER); rem &oStudentProfile.SAME_ADDR_CUSTOMER = [*]; &fileLog.WriteLine("&oStudentProfile.PROJECT_ROLE = " | &oStudentProfile.PROJECT_ROLE);

PeopleSoft Proprietary and Confidential

697

Sample Code

Appendix A

rem &oStudentProfile.PROJECT_ROLE = [*]; rem ***** End: Get/Set Component Interface Properties *****; rem ***** Execute Save *****; rem If Not &oStudentProfile.Save() Then; rem rem errorHandler(); throw CreateException(0, 0, "Save failed");

rem End-If;

Execute standard and custom methods


rem ***** Execute Cancel *****; rem If Not &oStudentProfile.Cancel() Then; rem rem errorHandler(); throw CreateException(0, 0, "Cancel failed");

rem End-If; catch exception &ex rem Handle the exception; &fileLog.WriteLine(&ex.ToString()); end-try; &fileLog.WriteLine("End"); &fileLog.Close();

698

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

STUDENT_PROFILE Component Interface Visual Basic Template


Option Explicit '===> 'This is a dynamically generated Visual Basic template to be used only as a helper 'to the application developer. 'You need to replace all references to '[*]' OR default values with 'Visual Basic variables. references to

Declare the Session Object


Dim oSession As PeopleSoft_PeopleSoft.Session

Error Handling
Private Sub ErrorHandler() '***** Display PeopleSoft Error Messages ***** If Not oSession Is Nothing Then If oSession.ErrorPending Or oSession.WarningPending Then Dim oPSMessageCollection As PSMessageCollection Dim oPSMessage As PSMessage Set oPSMessageCollection = oSession.PSMessages Dim i As Integer For i = 1 To oPSMessageCollection.Count Set oPSMessage = oPSMessageCollection.Item(i) Debug.Print "(" & oPSMessage.MessageNumber & "," & oPSMessage.MessageSetNumber & ") : " & oPSMessage.Text Next i '***** Done processing messages in the collection; OK to delete ***** oPSMessageCollection.DeleteAll End If End If End Sub

Main Processing
Private Sub main() On Error GoTo ErrorHandler '***** Set Connect Parameters ***** Dim strServerName As String, strServerPort As String, strAppServerPath As String Dim strUserID As String, strPassword As String 'Get Application Server Machine Name strServerName = InputBox("Enter Application Server Machine Name: ") 'Get Application Server Port Number strServerPort = InputBox("Enter Application Server Port Number: ") 'Get PeopleSoft UserID strUserID = InputBox("Enter PeopleSoft UserID: ") 'Get PeopleSoft UserID Password

PeopleSoft Proprietary and Confidential

699

Sample Code

Appendix A

strPassword = InputBox("Enter PeopleSoft UserID Password: ") If Len(strServerName) = 0 OR _ Len(strServerPort) = 0 OR _ Len(strUserID) = 0 OR _ Len(strPassword) = 0 Then MsgBox "Connect information provided is incomplete" Exit Sub End If 'Build Application Server Path strAppServerPath = strServerName & ":" & strServerPort

Create the PeopleSoft Session Object to enable access to the PeopleSoft system
'***** Create PeopleSoft Session Object ***** Set oSession = CreateObject("PeopleSoft.Session")

Connect to the PeopleSoft application server using the Connect method


'***** Connect to the App Server ***** If Not oSession.Connect(1, strAppServerPath, strUserID, strPassword, 0) Then Err.Raise 1001, "", "Unable to connect to Application Server" Call ErrorHandler() Exit Sub End If

Get a reference to the component interface providing its name


'***** Get Component Interface ***** Dim oStudentProfile As STUDENT_PROFILE Dim ciName As String ciName = "STUDENT_PROFILE" Set oStudentProfile = oSession.GetCompIntfc(ciName) If oStudentProfile Is Nothing Then Err.Raise 1001, "", "Unable to Get Component Interface " & ciName Call ErrorHandler() Exit Sub End If '***** Set the Component Interface Mode ***** oStudentProfile.InteractiveMode = False oStudentProfile.GetHistoryItems = True oStudentProfile.EditHistoryItems = False

Set the keys for the component interface


'***** Set Component Interface Get/Create Keys ***** Dim strSTUDENT_ID As String strSTUDENT_ID = InputBox("Enter STUDENT_ID: ") oStudentProfile.STUDENT_ID = strSTUDENT_ID

700

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

The Get method retrieves data from the database, associated with the key values
'***** Execute Get ***** If Not oStudentProfile.Get() Then Err.Raise 1001, "", "No rows exist for the specified keys. Failed to get the Component Interface" Call ErrorHandler() Exit Sub End If '***** Execute Create ***** 'If Not oStudentProfile.Create() Then ' provided." ' Err.Raise 1001, "", "Unable to Create Component Interface for the Add keys Call ErrorHandler()

'End If

Get and print properties at level 0


'***** BEGIN: Set/Get Component Interface Properties *****

'***** Set Level 0 Properties ***** Debug.Print "oStudentProfile.STUDENT_ID: " & oStudentProfile.STUDENT_ID 'oStudentProfile.STUDENT_ID = [*] Debug.Print "oStudentProfile.STUDENT_NAME: " & oStudentProfile.STUDENT_NAME 'oStudentProfile.STUDENT_NAME = [*] Debug.Print "oStudentProfile.CUSTOMER_ID: " & oStudentProfile.CUSTOMER_ID 'oStudentProfile.CUSTOMER_ID = [*] Debug.Print "oStudentProfile.SAME_ADDR_CUSTOMER: " & oStudentProfile.SAME_ADDR_CUSTOMER 'oStudentProfile.SAME_ADDR_CUSTOMER = [*] Debug.Print "oStudentProfile.PROJECT_ROLE: " & oStudentProfile.PROJECT_ROLE 'oStudentProfile.PROJECT_ROLE = [*] '***** END: Set Component Interface Properties *****

Execute standard and custom methods


'***** Execute Standard and Custom Methods ***** '***** Execute Save ***** 'If Not oStudentProfile.Save() Then ' ' ' Err.Raise 1001, "", "Unable to Save Component Interface" CallErrorHandler() Exit Sub

'End If '***** Execute Cancel ***** 'If Not oStudentProfile.Cancel() Then ' ' ' Err.Raise 1001, "", "Unable to Cancel Component Interface" CallErrorHandler() Exit Sub

PeopleSoft Proprietary and Confidential

701

Sample Code

Appendix A

'End If

Disconnect from PeopleSoft application server using the Disconnect method


'***** Disconnect from the App Server ***** If Not oSession Is Nothing Then oSession.Disconnect Set oSession = Nothing End If Exit Sub ErrorHandler: Debug.Print "An error occurred: " & Err.Description If Err.Number = 1001 Then Call ErrorHandler() Else Debug.Print "VB Error: " Debug.Print "Err.Number = " & Err.number Debug.Print "Err.Description = " & Err.description End If End Sub

702

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

STUDENT_PROFILE Component Interface Java Template


//===> //This is a dynamically generated Java template to be used only as a helper //to the application developer. //You need to replace all references to '[*]' OR default values with //Java variables. references to

Declarations
//package [*]; import java.io.*; import psft.pt8.joa.*; import PeopleSoft.Generated.CompIntfc.*; public class STUDENT_PROFILE { public static ISession oSession;

Error Handling
public static void ErrorHandler() { //***** Display PeopleSoft Error Messages ***** if (oSession.getErrorPending() || oSession.getWarningPending()) { IPSMessageCollection oPSMessageCollection; IPSMessage oPSMessage; oPSMessageCollection = oSession.getPSMessages(); for (int i = 0; i < oPSMessageCollection.getCount(); i++) { oPSMessage = oPSMessageCollection.item(i); if (oPSMessage != null) System.out.println("(" + oPSMessage.getMessageSetNumber() + "," + oPSMessage.getMessageSetNumber() + ") : " + oPSMessage.getText()); } //***** Done processing messages in the collection; OK to delete ***** oPSMessageCollection.deleteAll(); } }

Main Section session connection


public static void main (String args[]) { try { //***** Set Connect Parameters ***** String strServerName, strServerPort, strAppServerPath; String strUserID, strPassword; BufferedReader inData = new BufferedReader(new InputStreamReader(System.in));

PeopleSoft Proprietary and Confidential

703

Sample Code

Appendix A

//Get Application Server Machine Name System.out.print("Enter Application Server Machine Name: "); strServerName = inData.readLine(); //Get Application Server Port Number System.out.print("Enter Application Server Port Number: "); strServerPort = inData.readLine(); //Get PeopleSoft UserID System.out.print("Enter PeopleSoft UserID: "); strUserID = inData.readLine(); //Get PeopleSoft UserID Password System.out.print("Enter PeopleSoft UserID Password: "); strPassword = inData.readLine(); if (strServerName.length() == 0 || strServerPort.length() == 0 || strUserID.length() == 0 || strPassword.length() == 0) { System.out.println("\nConnect information provided is incomplete"); return; } //Build Application Server Path strAppServerPath = strServerName + ":" + strServerPort; //***** Create PeopleSoft Session Object ***** oSession = API.createSession(); //***** Connect to the App Server ***** if (!oSession.connect(1, strAppServerPath, strUserID, strPassword, null)) { System.out.println("\nUnable to Connect to Application Server."); ErrorHandler(); return; }

//***** Get Component Interface *****


IStudentProfile oStudentProfile; String ciName; ciName = "STUDENT_PROFILE"; oStudentProfile = (IStudentProfile) oSession.getCompIntfc(ciName); if (oStudentProfile == null) { System.out.println("\nUnable to Get Component Interface " + ciName); ErrorHandler(); return;

704

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

//***** Set the Component Interface Mode *****


oStudentProfile.setInteractiveMode(false); oStudentProfile.setGetHistoryItems(true); oStudentProfile.setEditHistoryItems(false);

//***** Set Component Interface Get/Create Keys *****


String strStudentId; System.out.print("\nEnter StudentId: "); strStudentId = inData.readLine(); oStudentProfile.setStudentId(strStudentId); //***** Execute Get ***** if (!oStudentProfile.get()) { System.out.println("\nNo rows exist for the specified keys.\nFailed to get the Component Interface."); ErrorHandler(); return; }

//***** Execute Create *****


//if(!oStudentProfile.create()) { // System.out.println("\nUnable to Create Component Interface for the Add keys provided.\n"); // //} return;

//***** BEGIN: Set/Get Component Interface Properties *****


//***** Set Level 0 Properties ***** System.out.println("oStudentProfile.StudentId: " + oStudentProfile.getStudentId()); //oStudentProfile.setStudentId([*]); System.out.println("oStudentProfile.StudentName: " + oStudentProfile.getStudentName()); //oStudentProfile.setStudentName([*]); System.out.println("oStudentProfile.CustomerId: " + oStudentProfile.getCustomerId()); //oStudentProfile.setCustomerId([*]); System.out.println("oStudentProfile.SameAddrCustomer: " + oStudentProfile.getSameAddrCustomer()); //oStudentProfile.setSameAddrCustomer([*]);

PeopleSoft Proprietary and Confidential

705

Sample Code

Appendix A

System.out.println("oStudentProfile.ProjectRole: " + oStudentProfile.getProjectRole()); //oStudentProfile.setProjectRole([*]); //***** END: Set Component Interface Properties *****

//***** Execute Standard and Custom Methods *****


//***** Execute Save ***** //if (!oStudentProfile.save()) { // // // //} //***** Execute Cancel ***** //if (!oStudentProfile.cancel()) { // // // //} System.out.println("Unable to Cancel Component Interface"); ErrorHandler(); return; System.out.println("Unable to Save Component Interface"); ErrorHandler(); return;

//***** Disconnect from the App Server ***** oSession.disconnect(); return; } catch (Exception e) { e.printStackTrace(); System.out.println("An error occurred: "); ErrorHandler(); } } }

706

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

STUDENT_PROFILE.java
//===> //This is a dynamically generated Java template to be used only as a helper //to the application developer. //You need to replace all references to '[*]' OR default values with //Java variables. references to

package student_profile; import java.io.*; import psft.pt8.joa.*; import PeopleSoft.Generated.CompIntfc.*; public class STUDENT_PROFILE { public static ISession oSession; public static void ErrorHandler() { //***** Display PeopleSoft Error Messages ***** if (oSession.getErrorPending() || oSession.getWarningPending()) { IPSMessageCollection oPSMessageCollection; IPSMessage oPSMessage; oPSMessageCollection = oSession.getPSMessages(); for (int i = 0; i < oPSMessageCollection.getCount(); i++) { oPSMessage = oPSMessageCollection.item(i); if (oPSMessage != null) System.out.println("(" + oPSMessage.getMessageSetNumber() + "," + oPSMessage.getMessageSetNumber() + ") : " + oPSMessage.getText()); } //***** Done processing messages in the collection; OK to delete ***** oPSMessageCollection.deleteAll(); } } public static void main (String args[]) { try { //***** Set Connect Parameters ***** String strServerName, strServerPort, strAppServerPath; String strUserID, strPassword; BufferedReader inData = new BufferedReader(new InputStreamReader(System.in)); //Get Application Server Machine Name System.out.print("Enter Application Server Machine Name: "); strServerName = inData.readLine();

PeopleSoft Proprietary and Confidential

707

Sample Code

Appendix A

//Get Application Server Port Number System.out.print("Enter Application Server Port Number: "); strServerPort = inData.readLine(); //Get PeopleSoft UserID System.out.print("Enter PeopleSoft UserID: "); strUserID = inData.readLine(); //Get PeopleSoft UserID Password System.out.print("Enter PeopleSoft UserID Password: "); strPassword = inData.readLine(); if (strServerName.length() == 0 || strServerPort.length() == 0 || strUserID.length() == 0 || strPassword.length() == 0) { System.out.println("\nConnect information provided is incomplete"); return; } //Build Application Server Path strAppServerPath = strServerName + ":" + strServerPort; //***** Create PeopleSoft Session Object ***** oSession = API.createSession(); //***** Connect to the App Server ***** if (!oSession.connect(1, strAppServerPath, strUserID, strPassword, null)) { System.out.println("\nUnable to Connect to Application Server."); ErrorHandler(); return; } //***** Get Component Interface ***** IStudentProfile oStudentProfile; String ciName; ciName = "STUDENT_PROFILE"; oStudentProfile = (IStudentProfile) oSession.getCompIntfc(ciName); if (oStudentProfile == null) { System.out.println("\nUnable to Get Component Interface " + ciName); ErrorHandler(); return; } //***** Set the Component Interface Mode ***** oStudentProfile.setInteractiveMode(false); oStudentProfile.setGetHistoryItems(true);

708

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

oStudentProfile.setEditHistoryItems(false); //***** Set Component Interface Get/Create Keys ***** String strStudentId; //System.out.print("\nEnter StudentId: "); //strStudentId = inData.readLine(); oStudentProfile.setStudentId("NEW");

Comment out the Get


//***** Execute Get ***** //if (!oStudentProfile.get()) { // System.out.println("\nNo rows exist for the specified keys.\nFailed to get the Component Interface."); // // //} //***** Execute Create ***** if(!oStudentProfile.create()) { System.out.println("\nUnable to Create Component Interface for the Add keys provided.\n"); return; } ErrorHandler(); return;

//***** BEGIN:

Set/Get Component Interface Properties *****

Set Level 0 Properties


//***** Set Level 0 Properties ***** String strStudentName; String strCustomerID; //String strSameAddrCustomer; String strProjectRole; //System.out.println("oStudentProfile.StudentId: " + oStudentProfile.getStudentId()); //oStudentProfile.setStudentId("NEW"); System.out.println("oStudentProfile.StudentName: " + oStudentProfile.getStudentName()); strStudentName = inData.readLine(); oStudentProfile.setStudentName(strStudentName); System.out.println("oStudentProfile.CustomerId: " + oStudentProfile.getCustomerId()); strCustomerID = inData.readLine(); oStudentProfile.setCustomerId(strCustomerID); //System.out.println("oStudentProfile.SameAddrCustomer: " + oStudentProfile.getSameAddrCustomer()); oStudentProfile.setSameAddrCustomer("Y");

PeopleSoft Proprietary and Confidential

709

Sample Code

Appendix A

System.out.println("oStudentProfile.ProjectRole: " + oStudentProfile.getProjectRole()); strProjectRole = inData.readLine(); oStudentProfile.setProjectRole(strProjectRole); //***** END: Set Component Interface Properties *****

//***** Execute Standard and Custom Methods *****

Uncomment the Save


//***** Execute Save ***** if (!oStudentProfile.save()) { System.out.println("Unable to Save Component Interface"); ErrorHandler(); return; }

Uncomment the Cancel


//***** Execute Cancel ***** //if (!oStudentProfile.cancel()) { // // // //} //***** Execute my_method ***** //[*] = oStudentProfile.my_method([*]); //***** Disconnect from the App Server ***** oSession.disconnect(); return; } catch (Exception e) { e.printStackTrace(); System.out.println("An error occurred: "); ErrorHandler(); } } } System.out.println("Unable to Cancel Component Interface"); ErrorHandler(); return;

710

PeopleSoft Proprietary and Confidential

Appendix A

Sample Code

PO_TRANSFORM XSLT
<?xml version="1.0" ?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> <xsl:template match="PO_SYNC"> <SDK_PO_SYNC> <xsl:apply-templates /> </SDK_PO_SYNC> </xsl:template> <xsl:template match="PSU_PO_HDR"> <SDK_RP_PO> <xsl:attribute name="class"><xsl:value-of select="@class" /></xsl:attribute> <SDK_RP_PO_NUMBER>TR<xsl:value-of select="ORDER_NBR" /></SDK_RP_PO_NUMBER> <SDK_RP_PODATE><xsl:value-of select="ORDER_DT" /></SDK_RP_PODATE> <SDK_RP_SITENAME><xsl:value-of select="BUSINESS_UNIT" /></SDK_RP_SITENAME> <SDK_RP_VENDORNAME><xsl:value-of select="VENDOR_CD" /></SDK_RP_VENDORNAME> <PO_STATUS><xsl:value-of select="ORDER_STATUS" /></PO_STATUS> <!-here. Need this here to continue the template calling process, before it would dead end -->

<xsl:apply-templates /> </SDK_RP_PO> </xsl:template> <xsl:template match="PSU_PO_DTL"> <SDK_RP_POLINE> <xsl:attribute name="class"><xsl:value-of select="@class" /></xsl:attribute> <SDK_RP_PO_NUMBER>TR<xsl:value-of select="ORDER_NBR" /></SDK_RP_PO_NUMBER> <SDK_RP_SITENAME><xsl:value-of select="BUSINESS_UNIT" /></SDK_RP_SITENAME> <SDK_RP_LINENUM><xsl:value-of select="ORDER_LINE_NBR" /></SDK_RP_LINENUM> <SDK_RP_PARTSITE><xsl:value-of select="BUSINESS_UNIT" /></SDK_RP_PARTSITE> <SDK_RP_PARTNAME><xsl:value-of select="ITEM_CD" /></SDK_RP_PARTNAME> <SDK_RP_QUANTITIES><xsl:value-of select="QTY" /></SDK_RP_QUANTITIES> <SDK_RP_UNIT_PRICE><xsl:value-of select="PRICE" /></SDK_RP_UNIT_PRICE> </SDK_RP_POLINE> </xsl:template> <!-This will copy a node/attribute and its children -->

<xsl:template match="node() | @*"> <xsl:copy> <xsl:apply-templates select="node() | @*" /> </xsl:copy> </xsl:template>

PeopleSoft Proprietary and Confidential

711

Sample Code

Appendix A

<!--

Ignore these fields

-->

<xsl:template match="processing-instruction() | BUSINESS_UNIT | ORDER_NBR | ORDER_DT | VENDOR_CD | STATUS_DT | DELIVER_METHOD | ORDER_STATUS | ADDED_BY | APPR_STATUS | APPR_INSTANCE | ORDER_LINE_NBR | ITEM_CD | QTY | PART_NBR | ITEM_COLOR | PRICE"> <!-do nothing --> </xsl:template> <xsl:template match="FieldTypes"> <FieldTypes> <SDK_RP_PO class="R"> <SDK_RP_PO_NUMBER type="CHAR" /> <SDK_RP_PODATE type="DATE" /> <SDK_RP_SITENAME type="CHAR" /> <SDK_RP_VENDORNAME type="CHAR" /> <PO_STATUS type="CHAR" /> </SDK_RP_PO> <SDK_RP_POLINE class="R"> <SDK_RP_PO_NUMBER type="CHAR" /> <SDK_RP_SITENAME type="CHAR" /> <SDK_RP_LINENUM type="CHAR" /> <SDK_RP_PARTSITE type="CHAR" /> <SDK_RP_PARTNAME type="CHAR" /> <SDK_RP_QUANTITIES type="CHAR" /> <SDK_RP_UNIT_PRICE type="NUMBER" /> </SDK_RP_POLINE> <PSCAMA class="R"> <LANGUAGE_CD type="CHAR" /> <AUDIT_ACTN type="CHAR" /> <BASE_LANGUAGE_CD type="CHAR" /> <MSG_SEQ_FLG type="CHAR" /> <PROCESS_INSTANCE type="NUMBER" /> <PUBLISH_RULE_ID type="CHAR" /> <MSGNODENAME type="CHAR" /> </PSCAMA> </FieldTypes> </xsl:template> </xsl:stylesheet>

712

PeopleSoft Proprietary and Confidential

Appendix B

Integration Broker Troubleshooting Guide


Troubleshooting Guide
This appendix provides a troubleshooting guide for the following problems: Publication Process Subscription Process Other possible causes

______________________________________________________________________________________________________________

PeopleSoft Proprietary and Confidential

713

Integration Broker Troubleshooting Guide

Appendix B

Publication Process Problems:


Possible publication problems include:

Publication Contract not created


Possible causes: 1. No publication PeopleCode exists. 2. Publication PeopleCode is incorrect.

Publication Contact sits in NEW status


Possible causes: 1. Message Channel is paused. 2. Publication Dispatcher has crashed or has been brought down. 3. Node is paused. 4. Previous message had a status of Retry, Error, or Timeout. 5. Domain is not active. 6. Incorrect Gateway URL defined on Message Node. 7. After unsuccessful ping, a row may be added to the table PSNODESDOWN; which will hold up the message queue. Query the table PSNODESDOWN.

Publication Contract stays in RETRY status


Possible Causes: 1. The remote node cannot be pinged successfully. The publication contract will be processed when the remote node comes back up. 2. No publication handler available, either because its crashed or its been brought down.

Publication Contract sits in WORKING status


Possible Causes: 1. The publication handler processing the contract is on another machine and either the machine or the domain is down. Processing should continue when the pub/sub system on the other machine comes back up. 2. Single threading on the application server is making things slow.

714

PeopleSoft Proprietary and Confidential

Appendix B

Integration Broker Troubleshooting Guide

Publication Contract is in TIMEOUT status


Possible Causes: 1. Transaction is not setup in the target node definition. Check APPSRV.LOG file for probable cause. 2. Subscribing Node is Paused. 3. Message Node URL is incorrect in the integrationGateway.properties file. 4. No Subscription PeopleCode exists on subscribing system, or subscription PeopleCode is incorrect. 5. An exception occurred on the target application server (look in APPSRV.LOG file for details) verify the following: a. Source node defined in target database. b. Verify correct password on node, target and source (if using passwords). c. Message or Channel not defined in target database. d. Incorrectly routed reply. Check Gateway for correct machine address of target node. e. No target local node defined. f. Bad XML syntax.

Publication Contract is in ERROR status


Possible Causes: 1. Message Node URL is incorrect. 2. Subscription PeopleCode is bad.

PeopleSoft Proprietary and Confidential

715

Integration Broker Troubleshooting Guide

Appendix B

Subscription Process Problems


Possible publication problems include:

Subscription Contract not created.


Possible Causes: 1. Message Subscription is inactive. 2. Channel routing rules not set up properly.

Subscription Contract sits in NEW status


Possible Causes: 1. Application Server down. 2. Pub/Sub processes not configured on Application Server domain. 3. The Subscription Dispatcher has crashed or has been brought down. 4. Message definition not active. 5. Subscription PeopleCode is not active. 6. Message channel is paused. 7. Node is paused. 8. Previous Message had errors or timed out. 9. No row was inserted into PSAPMSGSUBPRCID, To insert a row enter the following SQL statement in your Query tool use the following statement:
insert into PSAPMSGSUBPRCID values(0)

Subscription Contract sits in STARTED status


Possible Causes: 1. Subscription Handler down. 2. Check the target component online to make sure they are valid.

Subscription Contract sits in WORKING status


Possible Causes: 1. No Subscription PeopleCode exists. 2. Subscription Handler crashed while processing message.

716

PeopleSoft Proprietary and Confidential

Appendix B

Integration Broker Troubleshooting Guide

Subscription Contract in ERROR status


Possible Causes: 1. Message channel property if Ordered will allow subscription contracts to go in random order. This will cause FULLSYNC messages to error out when the transaction was subscribed before the header. 2. Subscription PeopleCode errors. 3. Application Data errors. 4. Verify autonumber sequence.

Subscription Contract is in EDIT status


Possible Cause: Message was edited and has yet to be resubmitted for processing.

Subscription Contract is in RETRY status


Possible Causes: 1. Subscription PeopleCode is empty. 2. Message Definition on target is not active.

PeopleSoft Proprietary and Confidential

717

Integration Broker Troubleshooting Guide

Appendix B

Other Possible Problems


Other possible problems include:

Cannot find message in Message Monitor


Possible Causes: 1. User does not have security for the message channel. 2. The message monitor criteria have filtered out the message.

Messages are being processed in an incorrect order


Possible Cause: 1. The Channel has been partitioned, and the resulting subchannels do not match what was assumed for the ordering of the messages.

Message Instance not created


Possible Cause: 1. Message is inactive.

Message Instance stays in NEW status.


Possible Causes: 1. The Application server is down. 2. Pub/Sub services not configured on Application Server domain. 3. The Message Dispatcher has crashed or has been brought down. 4. The Item is not at the top of the queue. All messages with the same Channel/ Subchannel are in the same queue.

Message Instance stays in STARTED status.


Possible Causes: 1. All Message Handlers have crashed or have been brought down. Processing will resume when Message handlers come brought back up. 2. The Message dispatcher processing the message is on another machine, and either the machine or the application server domain is down.

Message Instance stays in WORKING status.


Possible Causes: 1. Message Broker Handler has crashed.

718

PeopleSoft Proprietary and Confidential

Appendix B

Integration Broker Troubleshooting Guide

2. The Message Handler processing the message is on another machine, and either the machine or the application server domain is down. The Message handler working on the message is blocked. The service will timeout, and the Message Dispatcher will retry the message.

My Publish() PeopleCode finishes successfully, but there is no message in the Message Monitor.
Possible Causes: The Message Definition is inactive.

Unable to ping a node


Possible Causes: 1. The web server for the Gateway is down. 2. The Gateway is not configured properly. 3. The app server for the node is down. 4. Verify URL is correct. Copy URL in browser address, should see: PeopleSoft Integration Gateway PeopleSoft Listening Connector Status: ACTIVE

Message Channel is PAUSED


Some message channels are delivered from PeopleSoft as paused. Change the status to Run in order for the messages to process from New to Working.

PeopleSoft Proprietary and Confidential

719

Integration Broker Troubleshooting Guide

Appendix B

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

720

PeopleSoft Proprietary and Confidential

Appendix C

Accessing CTE
Objectives
This appendix contains information about: Accessing and logging into CTE. Student logins. Workstation ports.

______________________________________________________________________________________________________________

Accessing and Logging into CTE


To access the login page and log in: 1. Open Internet Explorer and enter the Your Training URL:
https://yourtraining.jdedwards.com

2. Enter the class ID and password, and then click Sign In.

Logging into CTE

PeopleSoft Proprietary and Confidential

721

Accessing CTE

Appendix C

The welcome screen appears. This page contains useful support information if assistance is needed. 3. Click on the environment folder in the blue window.

Environments folder 4. Click on the desktop icon to access your virtual desktop.

Virtual Desktop

Student Logins
The student logins are:
Login Type Students 1 through 14 (primary) Students 1 through 14 (secondary)** User name: STA1XX STA2XX Password: (upper case) STA1XX STA2XX

**The secondary student accounts are only available on images that require them. The majority of images will not include the second set of student logins.

722

PeopleSoft Proprietary and Confidential

Appendix C

Accessing CTE

5. Enter your User name and Password, and then click OK.

Log On window

Ports
In the CTE, the ports are assigned by workstation, use the following chart:
Workstation STA101 STA102 STA103 STA104 STA105 STA106 STA107 SAT108 STA109 STA110 STA111 STA112 TCA101 Database T1B84401 T1B84402 T1B84403 T1B84404 T1B84405 T1B84406 T1B84407 T1B84408 T1B84409 T1B84410 T1B88411 T1B88412 T1B84499 Application Server Port 9010 9020 9030 9040 9050 9060 9070 9080 9090 9100 9110 9120 9990

PeopleSoft Proprietary and Confidential

723

Accessing CTE

Appendix C

Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________

724

PeopleSoft Proprietary and Confidential

Appendix D

Curriculum Map

PeopleSoft Proprietary and Confidential

725

Curriculum Map

Appendix D

Curriculum Map
Development
400 PeopleTools I 5 days Classroom 410 PeopleTools II 5 days Classroom 420 PeopleCode 5 days Classroom

KEY

Upgrade Course
405 PeopleTools Overview 2 days Classroom 411 Application Engine 4 days Classroom

1533 Integrating Processes and Reports 1 day Live WebCast

426 Workflow 4 days Classroom

1022 Integration Tools 4 days Classroom

Administration

415 Process Scheduler Administration and Report Distribution 2 days Classroom

478 Data Management Tools and Upgrade 5 days Classroom

466 PeopleSoft Security 3 days Classroom

471 PeopleSoft Server Administration 4 days Classroom

Enterprise Portal
1011 Enterprise Portal Administration (8.4) 3 days Classroom

OR
1377 Concepts in Enterprise Portal Development (8.4) 1 day Live WebCast

1011 Enterprise Portal Administration (8.8) 5 days Classroom

Reporting

430 SQR 5 days Classroom

435 PS/nVision Using Queries 4 days Classroom

455 Query/Crystal Power Combo 4 days Classroom with OnDemand 1152 Query Reporting 2 days Classroom with OnDemand

PeopleTools Curriculum Map

726

PeopleSoft Proprietary and Confidential

You might also like