Professional Documents
Culture Documents
Instructor Guide
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
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
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
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
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
Appendix B
vii
Integration Tools
Contents
Other Possible Problems .................................................................................................718 Appendix C Appendix D Accessing CTE ...............................................................................................................721 Curriculum Map ...........................................................................................................725
viii
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)
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:
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
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 ________________________________________________________________________________________________________
Course Overview
Lesson 1
Slide 4 ________________________________________________________________________________________________________
Instructor Notes
This section describes: CTE Instructions for Integration Tools Course Manual Instructions for Training Database. Activity Dependencies
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.
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.
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
Lesson 1
Course Overview
Lesson 5 6
Activity 3 4
1&2
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
12 & 14 & 15
15 16
21 22
16 17
23 24 22
PSFT_EP ORDER_STATUS
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
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
Lesson 1
Course Overview
Slide 5 ________________________________________________________________________________________________________
Course Overview
Lesson 1
Slide 6 ________________________________________________________________________________________________________
Lesson 1
Course Overview
Slide 7 ________________________________________________________________________________________________________
Course Overview
Lesson 1
Slide 8 ________________________________________________________________________________________________________
10
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 _______________________________________________________________________________________________________
11
Technology Overview
Lesson 2
Process
Integration Broker
PeopleSoft Applications
Legacy Environments
Data
Enterprise Warehouse
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
Lesson 2
Technology Overview
13
Technology Overview
Lesson 2
Slide 12 _______________________________________________________________________________________________________
14
Lesson 2
Technology Overview
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.
15
Technology Overview
Lesson 2
Slide 14 _______________________________________________________________________________________________________
Instructor Notes
The Integration Broker is the central point for all PeopleSoft integrations.
16
Lesson 2
Technology Overview
PeopleSoft Applications
Legacy Systems
Custom
Technical architecture
Slide 15 _______________________________________________________________________________________________________
Student Notes
The PeopleSoft Integration Broker is comprised of four key elements: Connectors Intelligent routing Transformation Development and monitoring environment
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.
19
Technology Overview
Lesson 2
Outbound Async Connectors Inbound Async Consumer Sync Provider Sync CSV
ERP Application MQ Series Legacy Application Trading Partner Application WSDL Line of Business Application
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
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
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.
21
Technology Overview
Lesson 2
Slide 18 _______________________________________________________________________________________________________
22
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.
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
Lesson 2
Technology Overview
Slide 21 _______________________________________________________________________________________________________
25
Technology Overview
Lesson 2
EIP
Application Engine
Subscription PeopleCode
Component Interface
Read File
File
SQL Insert
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
Lesson 2
Technology Overview
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.
27
Technology Overview
Lesson 2
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.
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.
This chapter provides an overview of integration administration and discusses how to: Configure nodes. Configure transactions.
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
Lesson 2
Technology Overview
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.
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.
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.
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.
29
Technology Overview
Lesson 2
Note. Context-sensitive help is constrained to non-application specific pages in the technical database.
30
Lesson 2
Technology Overview
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.
31
Technology Overview
Lesson 2
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.
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
Lesson 2
Technology Overview
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.
33
Technology Overview
Lesson 2
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
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 _______________________________________________________________________________________________________
35
Technology Overview
Lesson 2
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
36
Lesson 3
Slide 29 _______________________________________________________________________________________________________
37
Lesson 3
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
Lesson 3
PS
Student Notes
Components combine multiple pages.
39
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
Lesson 3
API
Online Users
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.
41
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
Lesson 3
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).
43
Lesson 3
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.
Instructor Notes
This section discusses the PeopleSoft Component Interfaces architecture.
44
Lesson 3
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).
45
Lesson 3
Slide 34 _______________________________________________________________________________________________________
Student Notes
Each component interface definition is based on a single component, as shown in this example:
Instructor Notes
This section discusses the four main elements of a component interface definition.
46
Lesson 3
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.
47
Lesson 3
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
Lesson 3
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.
49
Lesson 3
Slide 36 _______________________________________________________________________________________________________
50
Lesson 3
Slide 37 _______________________________________________________________________________________________________
Instructor Notes
The next two slides explain user-defined and standard properties.
51
Lesson 3
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
Lesson 3
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.
53
Lesson 3
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
Lesson 3
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).
55
Lesson 3
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
Lesson 3
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).
57
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
Lesson 4
Slide 43 _______________________________________________________________________________________________________
59
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
Lesson 4
Slide 45 _______________________________________________________________________________________________________
Student Notes
This diagram shows the business process for adding employees and enrolling them in training courses:
Personnel Administrator
Add Employee
Yes
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:
61
Lesson 4
Personnel Administrator
Add Employee
Training Coordinator
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
Lesson 4
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.
63
Lesson 4
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
Lesson 4
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.
65
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
Lesson 4
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.
67
Lesson 4
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
Lesson 4
Note. The instructor-led course called Mobile Technologies explains how to develop and code synchronizable component interfaces.
69
Lesson 4
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
70
Lesson 4
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.
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.
71
Lesson 4
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
Lesson 4
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).
73
Lesson 4
Activity 1:
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
Lesson 4
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
Yes
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
Training Coordinator
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.
75
Lesson 4
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
76
Lesson 4
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:
77
Lesson 4
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
Lesson 4
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).
79
Lesson 4
Student Notes
The Component Interface Tester tool enables you to test the standard methods:
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
Lesson 4
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
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
81
Lesson 4
82
Lesson 4
Activity 2:
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
83
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?
84
Lesson 4
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.
85
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
Lesson 5
Slide 61 _______________________________________________________________________________________________________
87
Lesson 5
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
Lesson 5
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.
89
Lesson 5
1. GetCompIntfc(name)
3. Find()
6. Save()
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
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)).
91
Lesson 5
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
Lesson 5
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 *****;
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:
93
Lesson 5
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
Lesson 5
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.
95
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
Lesson 5
Slide 68 _______________________________________________________________________________________________________
Student Notes
The session parameters for external systems are covered later in this course. See lesson 7, Building Component Interface APIs.
97
Lesson 5
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
Lesson 5
Slide 70 _______________________________________________________________________________________________________
99
Lesson 5
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
Lesson 5
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 = [*];
101
Lesson 5
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
Lesson 5
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;
Instructor Notes
In the example, you take the name from the Personal Data table. The other values are hard-coded.
103
Lesson 5
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
Lesson 5
1. True 2. False Answer The answer is 1 (true). You must uncomment the Save and Cancel methods to execute them.
105
Lesson 5
Activity 3:
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);
106
Lesson 5
<* If Not &oStudentProfile.Get() Then rem ***** No rows exist for the specified keys.*****; errorHandler(); throw CreateException(0, 0, "Get failed"); End-If; *>
107
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
108
Lesson 5
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; */
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;
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";
109
Lesson 5
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.
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.
110
Lesson 5
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:
111
Lesson 5
112
Lesson 5
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 _______________________________________________________________________________________________________
113
Lesson 5
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
114
Lesson 6
Slide 79 _______________________________________________________________________________________________________
115
Lesson 6
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:
Instructor Notes
The left side shows the following component structure:
116
Lesson 6
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.
117
Lesson 6
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
Lesson 6
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).
119
Lesson 6
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
Lesson 6
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
121
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
Lesson 6
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();
Note. To show all history for an effective-dated collection, you must set GetHistoryItems to True before you populate the component.
123
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
Lesson 6
Activity 4:
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;
125
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
Explaining How to Update a Row in a Collection The following example shows the activity solution for this section:
126
Lesson 6
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.
127
Lesson 6
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
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
Lesson 6
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
129
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:
Lesson 6
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:
131
Lesson 6
Course enrollment after course is canceled This concludes the activity. Do not continue.
132
Lesson 6
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 _______________________________________________________________________________________________________
133
Lesson 6
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
134
Lesson 7
Slide 88 _______________________________________________________________________________________________________
135
Lesson 7
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
Lesson 7
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
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
Lesson 7
Student Notes
The template file is generated in the directory specified by the TEMP or TMP system environment variable on your client machine:
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.
139
Lesson 7
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
1. Visual Basic 2. C++ 3. Java 4. All of the above Answer The answer is 4 (all of the above).
141
Lesson 7
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
Lesson 7
143
Lesson 7
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:
144
Lesson 7
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.
145
Lesson 7
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
Lesson 7
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.
147
Lesson 7
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
Lesson 7
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
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.
149
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
Lesson 7
: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.
151
Lesson 7
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
Lesson 7
: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=
153
Lesson 7
Activity 5:
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
Lesson 7
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
155
Lesson 7
Code 02 03 04 05 06 07 08
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
Lesson 7
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
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.
157
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
3. Select 1)Get. 4. Accept the defaults for Interactive mode, GetHistoryItems and EditHistoryItems. 5. Enter employee ID 6602. 6. Select (9) InsertItem.
158
Lesson 7
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.
159
Lesson 7
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
Lesson 7
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.*;
161
Lesson 7
Instructor Notes
Comments in Java are denoted by //.
162
Lesson 7
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 <*>.
163
Lesson 7
Activity 6:
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
Lesson 7
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 ***** 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; }
165
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; }
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.
166
Lesson 7
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.
167
Lesson 7
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
Lesson 7
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.
169
Lesson 7
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
170
Lesson 8
171
Lesson 8
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
Lesson 8
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.
173
Lesson 8
Student Notes
The coversheet is used to provide information about the workbook and the process steps:
ExcelToCI spreadsheet
174
Lesson 8
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).
175
Lesson 8
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
Lesson 8
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).
177
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.
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
Lesson 8
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).
179
Lesson 8
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
Lesson 8
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.
Student Notes
The Create template icon prompts for login information.
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.
181
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
Lesson 8
Student Notes
The template for the component interface is displayed with all of the levels and fields displayed:
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.
183
Lesson 8
Student Notes
Selected cells will be displayed in pink and fields selected for submission displayed in blue on the worksheet:
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
Lesson 8
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.
185
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.
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
Lesson 8
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.
187
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.
Student Notes
When the data is submitted to the database, the status is returned:
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
Lesson 8
Student Notes
Corrections are made on the data input worksheet and staged for submission:
Resubmitted data
189
Lesson 8
Activity 7:
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.
190
Lesson 8
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
191
Lesson 8
Page Element Course Code Session Number Business Unit Start Date End Date Maximum Enrollment Session Status Instructor Training Location Classroom
Page Element Course Code Session Number Business Unit Start Date End Date Maximum Enrollment Session Status Instructor Training Location Classroom
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
Lesson 8
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:
193
Lesson 8
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
Lesson 8
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.
195
Lesson 8
196
Lesson 8
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.
197
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.
198
Lesson 9
199
Lesson 9
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
Lesson 9
Integration Engine
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).
201
Lesson 9
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
Lesson 9
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).
203
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.
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
Lesson 9
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.
205
Lesson 9
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
Lesson 9
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
207
Lesson 9
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
Lesson 9
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).
209
Lesson 9
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
Lesson 9
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.
211
Lesson 9
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
Lesson 9
JOLT
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
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
213
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
Lesson 9
Application Server
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
215
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
Lesson 9
Application Server
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.
217
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
Lesson 9
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.
219
Lesson 9
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
220
Lesson 10
221
Lesson 10
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
Lesson 10
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.
223
Lesson 10
Gateway Manager Application Server(s) and Database Application Server(s) and Database
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
Lesson 10
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.
225
Lesson 10
Note. The default local node for the Financials database is PSFT_EP.
Slide 150 ______________________________________________________________________________________________________
226
Lesson 10
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.
227
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
Lesson 10
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.
229
Lesson 10
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
Lesson 10
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.
231
Lesson 10
Student Notes
Here is an example showing a default application server:
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
Keep in mind that the default application server in this environment is set to the instructors application server.
233
Lesson 10
Student Notes
In the classroom, all the nodes have been defined, as shown here:
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
Lesson 10
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.
235
Lesson 10
Activity 9:
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.
Lesson 10
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.
237
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.
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
Lesson 10
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.
239
Lesson 10
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
Lesson 10
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.
241
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
Lesson 10
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
243
Lesson 10
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
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
Lesson 10
245
Lesson 10
246
Lesson 10
Activity 10:
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.
247
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
Lesson 10
249
Lesson 10
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
Lesson 10
Activity 11:
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 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
251
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
Lesson 10
Page Element Node Type Routing Type Authentication Option Password Confirm Password Connector ID
253
Lesson 10
Results from successfully pinging a local node This concludes the activity. Do not continue.
254
Lesson 10
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.
255
Lesson 10
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
256
Lesson 11
257
Lesson 11
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
Lesson 11
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.
259
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
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
Lesson 11
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).
261
Lesson 11
Student Notes
Note. The PeopleSoft system is delivered with predefined message definitions and message channels.
262
Lesson 11
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
263
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
Lesson 11
Student Notes
The following fields are available for partitioning on all message channels: MSGNAME MSGNAMEDETAIL PUBLISHER PUBPROC
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.
265
Lesson 11
Node A
8508 Data 1
Node B
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
Lesson 11
8630 Data 1
8508 Data 1
Node A
Node B
8101 Data 2
8101 Data 1
Error
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.
267
Lesson 11
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
Lesson 11
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.
269
Lesson 11
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
Lesson 11
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).
271
Lesson 11
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
Lesson 11
273
Lesson 11
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.
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
Lesson 11
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.
275
Lesson 11
276
Lesson 11
Student Notes
Use the Message Properties dialog box to define properties:
277
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
Lesson 11
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
279
Lesson 11
280
Lesson 11
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:
281
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
Lesson 11
Activity 12:
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.
283
Lesson 11
4. Click OK. 5. Write down the publication number. 6. Click OK. 7. Close the message definition.
284
Lesson 11
285
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.
286
Lesson 12
287
Lesson 12
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
Lesson 12
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).
289
Lesson 12
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.
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
Lesson 12
If the student did not set the channel to Pause, and the publication contact was created, the student cannot edit the XML.
291
Lesson 12
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
Lesson 12
293
Lesson 12
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
Lesson 12
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.
295
Lesson 12
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
Lesson 12
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>
297
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
Lesson 12
299
Lesson 12
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
Lesson 12
<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.
301
Lesson 12
Student Notes
If there is an error in a message, use the Edit XML page to edit the XML and correct the message:
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
Lesson 12
Activity 13:
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.
303
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>
304
Lesson 12
SCHOOL_SYNC message displays as edited This concludes the activity. Do not continue.
305
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.
306
Lesson 13
307
Lesson 13
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
Lesson 13
309
Lesson 13
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
Lesson 13
Student Notes
Note. PeopleCode written to populate or access a message looks similar to PeopleCode written to populate or access the component buffer.
311
Lesson 13
GetMessage ()
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
Lesson 13
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
313
Lesson 13
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
Lesson 13
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.
Update ([versionlist])
315
Lesson 13
316
Lesson 13
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:
317
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
Lesson 13
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.
319
Lesson 13
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
Lesson 13
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.
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.
5. Save the record. 6. Close the PeopleCode editor. This concludes the activity. Do not continue.
321
Lesson 13
Student Notes
The following example contains asynchronous 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
Lesson 13
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 */ * * */ */ * */
323
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
Lesson 13
Student Notes
Use the Message Subscription Properties dialog box to activate a message:
325
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
Lesson 13
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.
327
Lesson 13
Activity 15:
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
Lesson 13
* 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.
329
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
Lesson 13
331
Lesson 13
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
Lesson 13
Student Notes
The following examples show a response record and a response message:
TRN_REPLY record
COUNTRY_REPLY message
333
Lesson 13
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;
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
Lesson 13
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.
335
Lesson 13
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
Lesson 13
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).
337
Lesson 13
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
Lesson 13
Student Notes
The following example shows adding an outbound asynchronous transaction:
339
Lesson 13
Student Notes
The following example shows an outbound synchronous transaction:
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
Lesson 13
Activity 16:
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).
341
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:
342
Lesson 13
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.
343
Lesson 13
Activity 17:
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.
Lesson 13
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.
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
345
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
346
Lesson 13
347
Lesson 13
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
Lesson 13
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.
349
Lesson 13
350
Lesson 13
351
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.
352
Lesson 13
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.
353
Lesson 13
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
354
Lesson 14
355
Lesson 14
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
Lesson 14
Student Notes
A tab is available for each status page:
Instructor Notes
This section discusses how to: Explain message flow. Question: Describe Integration Broker Monitor.
357
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
Lesson 14
3 Message Broker
Success
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.
359
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
Lesson 14
Integration Broker
Message Queue
6 3
Message Broker
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:
361
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
Lesson 14
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.
363
Lesson 14
Edited Cancelled
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
Lesson 14
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
365
Lesson 14
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
Lesson 14
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.
367
Lesson 14
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
Lesson 14
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.
369
Lesson 14
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
Pub Contracts page Use the Sub Contracts page to view subscription contracts:
370
Lesson 14
Note. The system does not create publication contracts for routing to the local node.
371
Lesson 14
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
Lesson 14
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
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.
373
Lesson 14
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
Instructor Notes
This section discusses how to: Pause nodes. Schedule pause times. Ping nodes. Test Node
374
Lesson 14
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.
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.
375
Lesson 14
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
Lesson 14
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.
377
Lesson 14
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
Lesson 14
379
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.
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
Lesson 14
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.
381
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.
382
Lesson 14
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.
383
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
Lesson 14
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:
385
Lesson 14
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
Lesson 14
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
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.
387
Lesson 14
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
Lesson 14
389
Lesson 14
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)
390
Lesson 14
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.
391
Lesson 14
Student Notes
This page shows an example of statistics for the publication contract handler.
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
Lesson 14
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.
393
Lesson 14
394
Lesson 14
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.
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.
395
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
Lesson 14
Student Notes
Use the Error Notification page to run batch error notification:
Page Name Error Notification Navigation PeopleTools, Integration Broker, Monitor, Error Notification
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.
397
Lesson 14
398
Lesson 14
Activity 19:
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.
399
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
400
Lesson 14
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.
401
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.
402
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.
403
Applying Transformations
Lesson 15
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
Lesson 15
Applying Transformations
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.
405
Applying Transformations
Lesson 15
Instructor Notes
Transaction modifiers will be discussed later in this lesson.
406
Lesson 15
Applying Transformations
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.
407
Applying Transformations
Lesson 15
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
Lesson 15
Applying Transformations
Student Notes
Note. All participating nodes must agree on a format or employ transformations to accommodate the variations.
409
Applying Transformations
Lesson 15
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>
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
Lesson 15
Applying Transformations
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.
411
Applying Transformations
Lesson 15
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"/>
412
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).
413
Applying Transformations
Lesson 15
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
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
414
Lesson 15
Applying Transformations
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.
415
Applying Transformations
Lesson 15
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
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
417
Applying Transformations
Lesson 15
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"/>
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
Lesson 15
Applying Transformations
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
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.
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
Lesson 15
Applying Transformations
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.
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
Lesson 15
Applying Transformations
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
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
Lesson 15
Applying Transformations
Activity 20:
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>
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
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
428
Lesson 15
Applying Transformations
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
429
Applying Transformations
Lesson 15
430
Lesson 15
Applying Transformations
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.
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
Lesson 15
Applying Transformations
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/">
433
Applying Transformations
Lesson 15
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
Lesson 15
Applying Transformations
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);
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
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:
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
Lesson 15
Applying Transformations
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/>
437
Applying Transformations
Lesson 15
438
Lesson 15
Applying Transformations
Activity 21:
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.
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:
440
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.
441
Applying Transformations
Lesson 15
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
442
Lesson 16
443
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.
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
Lesson 16
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).
445
Lesson 16
446
Lesson 16
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.
447
Lesson 16
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
Lesson 16
Student Notes
Step 2 specifies the sender message information:
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.
449
Lesson 16
Student Notes
Step 3 specifies the transform program:
450
Lesson 16
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).
451
Lesson 16
Student Notes
Step 5 displays the summary information:
452
Lesson 16
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.).
453
Lesson 16
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
Lesson 16
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.
455
Lesson 16
Activity 22:
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
Lesson 16
Definition Type Receiving Node Sender node Request Message Request Transformation Receiver node Request Message
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
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.
457
Lesson 16
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
458
Lesson 16
Results The integration point summary will be displayed, ensure it is correct before clicking Finish:
3. Save the purchase order. 4. Check the Integration Broker Monitor for the status of the message.
459
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
460
Lesson 16
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
461
Lesson 16
Results The integration point summary will be displayed, ensure it is correct before clicking Finish:
462
Lesson 16
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.
463
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.
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
Lesson 16
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.
465
Lesson 16
Student Notes
Use the Relationships page to manually create new relationships:
Page Name Relationships Navigation PeopleTools, Integration Broker, Relationships, Add a New Value
Instructor Notes
Question: Maintaining Relationships Relationships can be deleted. 1. True 2. False
466
Lesson 16
467
Lesson 16
Activity 23:
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.
6. Select Save.
468
Lesson 16
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
469
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.
470
Lesson 17
471
Lesson 17
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
Lesson 17
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).
473
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.
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
Lesson 17
475
Lesson 17
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
Lesson 17
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.
477
Lesson 17
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
Lesson 17
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:
479
Lesson 17
Student Notes
Some codeset groups may not contain any data:
480
Lesson 17
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
Instructor Notes
The translating node may be a hub node where the message is routed before reaching its final destination.
481
Lesson 17
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
Lesson 17
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.
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.
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.
483
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
Lesson 17
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
485
Lesson 17
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
Lesson 17
Activity 24:
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
Based on this criteria, create a codeset group, codeset and codeset values. Remember to associate the codeset group with the specific nodes.
487
Lesson 17
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
Lesson 17
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
489
Lesson 17
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
Lesson 17
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.
491
Lesson 17
Student Notes
See PeopleTools 8.44 PeopleBook: PeopleCode Reference, PeopleCode Built-in Functions.
492
Lesson 17
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
493
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
Lesson 17
Activity 25:
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>
495
Lesson 17
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
Lesson 17
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.
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.
497
Lesson 17
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
Lesson 17
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;
499
Lesson 17
Instructor Notes
Review the actions in the code:
500
Lesson 17
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.
4. Select Save. 5. Select the Trans Modifiers tab. 6. Select Add Transaction Modifier. 7. Enter the following information:
PeopleSoft Proprietary and Confidential 501
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
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
Lesson 17
Error message generated when the message does not meet the filter criteria
503
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
Lesson 17
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.
505
Lesson 17
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
506
Lesson 18
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.
507
Lesson 18
Student Notes
The properties are defined on the connectors tab for the node definition:
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
Lesson 18
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).
509
Lesson 18
Activity 27:
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.
510
Lesson 18
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:
511
Lesson 18
File created in student temp folder This concludes the activity. Do not continue.
512
Lesson 18
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.
513
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
Lesson 18
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).
515
Lesson 18
Student Notes
Send Master has three main sections:
Send Master
516
Lesson 18
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
517
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
Lesson 18
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).
519
Lesson 18
Activity 28:
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 transform programs used with this message are SYNC_XFRM and SYNC_XFRMRSP.
520
Lesson 18
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.
521
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
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.
522
Lesson 18
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
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.
523
Lesson 18
524
Lesson 18
Student Notes
The Input Information section allows you to enter the header information:
525
Lesson 18
Activity 29:
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
Lesson 18
8. Click Save.
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)
8. Click POST. 9. You can select to view Raw Data, Metadata or Section 1. Try each of these.
528
Lesson 18
529
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
Lesson 18
SCHOOL_ASYNC project
531
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.
532
Lesson 19
533
Lesson 19
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
Lesson 19
Instructor Notes
Standards for web services are set by the World Wide Web Consortium (W3C). For more information, visit http://WWW.W3.ORG.
535
Lesson 19
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
Lesson 19
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).
537
Lesson 19
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
Lesson 19
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
539
Lesson 19
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.
540
Lesson 19
Instructor Notes
Once you have started SOAPswitch, you will see the icon on the toolbar to indicate that it is running.
541
Lesson 19
542
Lesson 19
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:
543
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
Lesson 19
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.
545
Lesson 19
546
Lesson 19
Student Notes
Actional Documentation is provided online:
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.
547
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
Lesson 19
Student Notes
Each system requires a unique identifier:
Instructor Notes
In this case we are naming our system PSFT_TEST.
549
Lesson 19
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
Lesson 19
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).
551
Lesson 19
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
Lesson 19
Student Notes
Completed 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:
553
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
Lesson 19
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.
Instructor Notes
Once routing data has been created, you will see a delete next to the service.
555
Lesson 19
Student Notes
The wizard displays the steps:
Instructor Notes
In the activity, students will set up the routing data using a new node and message definition.
556
Lesson 19
Student Notes
The routing data creates the appropriate transaction detail overrides for the connector:
Instructor Notes
The connector information shown on this page was created by the routing data wizard.
557
Lesson 19
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
Lesson 19
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:
559
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
Lesson 19
Activity 30:
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.
561
Lesson 19
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
Lesson 19
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
563
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
Lesson 19
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:
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
565
Lesson 19
Page Element Request Message Name Request Version Response Message Response Version
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
Lesson 19
Service details page Note. Note the endpoint and Soap Action for CustomerServerImpl1.
567
Lesson 19
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
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
Lesson 19
Page Element Transaction Type Result Node Request Message Name Target Request Message Version
569
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
Lesson 19
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:
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.
571
Lesson 19
The name entered for the WSDL is that name that will be available in the WSDL Repository.
572
Lesson 19
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.
573
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
Lesson 19
575
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.
576
Lesson 19
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.
577
Lesson 19
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
578
Lesson 20
579
Lesson 20
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
Lesson 20
581
Lesson 20
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
Lesson 20
Student Notes
The WSDL link displays the generated WSDL:
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.
583
Lesson 20
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:
Instructor Notes
Question: Generating WSDL From Component Interfaces and Messages WSDL can be generated for any PeopleSoft component interfaces or messages. 1. True
584
Lesson 20
585
Lesson 20
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
Lesson 20
Answer The answer is 2 (false the same message SOAPTOCI is used for all component interfaces).
587
Lesson 20
Student Notes
Example connector tab for a third-party node using component interface WSDL for integration:
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
Lesson 20
Student Notes
Inbound and outbound synchronous transactions for SOAPTOCI are included in the node definition:
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).
589
Lesson 20
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
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
Lesson 20
591
Lesson 20
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
Lesson 20
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
593
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
Lesson 20
Activity 31:
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>
595
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.
596
Lesson 20
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:
597
Lesson 20
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
Lesson 20
Send Master test for Find method on STU_PROFILE_2 This concludes the activity. Do not continue.
599
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.
600
Lesson 21
601
Lesson 21
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
Lesson 21
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.
603
Lesson 21
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
Lesson 21
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.
605
Lesson 21
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
Lesson 21
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.
607
Lesson 21
608
Lesson 21
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.
609
Lesson 21
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
Lesson 21
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.
611
Lesson 21
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.
612
Lesson 21
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.
613
Lesson 21
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
Lesson 21
615
Lesson 21
Student Notes
The page below shows an example of mapping:
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
Lesson 21
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.
Decrease the start position and adjust the field length to match the input data start position and length.
617
Lesson 21
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.
618
Lesson 21
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).
619
Lesson 21
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
Lesson 21
&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;
621
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
Lesson 21
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
623
Lesson 21
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
Lesson 21
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 .
625
Lesson 21
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)
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
Lesson 21
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
Lesson 21
628
Lesson 21
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.
629
Lesson 21
XML
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
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
Lesson 21
Student Notes
This example shows the run request:
Instructor Notes
The system assigns the default run control RUN01. You can change the run control if you want.
631
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
Lesson 21
Student Notes
The following examples show a log file and an error log file:
Instructor Notes
The error file is located in the same directory as the input file.
633
Lesson 21
Activity 32:
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
Lesson 21
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
635
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.
Lesson 21
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
637
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
638
Lesson 21
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.
639
Lesson 21
Results
Error log indicating invalid translate values This concludes the activity. Do not continue.
640
Lesson 21
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.
641
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
Lesson 21
Activity 33:
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.
643
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
644
Lesson 21
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.
645
Lesson 21
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
646
Lesson 22
647
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)
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
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 write mode with an absolute path.
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.
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
649
Lesson 22
650
Lesson 22
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
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
Lesson 22
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
Instructor Notes
This section discusses how to: Explain the CreateSQL function. Review the sample program. Question: Write to files defined by a file layout.
653
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;
/*
/*
and write the rowset to file */ While &SQL1.Fetch(&recl) &MYFILE.WriteRecord(&rec1); End-While; /* Close the file */
&MYFILE.Close();
654
Lesson 22
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).
655
Lesson 22
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
Lesson 22
Activity 34:
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.
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:
658
Lesson 22
659
Lesson 22
Student Notes
The following example shows a multilevel file layout:
660
Lesson 22
Instructor Notes
In PeopleSoft, data is stored in a relational database. Rather than writing separate files, we want to combine these files.
661
Lesson 22
Student Notes
The following illustration shows the toolbar arrows:
Toolbar arrows
662
Lesson 22
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.
663
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
Lesson 22
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.
665
Lesson 22
&Order = "00000001"; &SQL1 = CreateSQL("%selectall(:1)where ORDER_NBR = :2 ", &recl, &Order); &SQL2 = CreateSQL("%selectall(:1)where ORDER_NBR = :2 ", &rec2, &Order);
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
Lesson 22
667
Lesson 22
Activity 35:
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 */
668
Lesson 22
&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();
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.
669
Lesson 22
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.
670
Lesson 22
671
Lesson 22
672
Lesson 22
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:
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 */
673
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
Lesson 22
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
675
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:
Note. If you use the FileField command, you must manually enter all the field attributes.
676
Lesson 22
Activity 36:
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.
677
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
Lesson 22
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 ******/
679
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.
680
Lesson 22
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:
681
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
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 ______________________________________________________________________________________________________
683
Final Activity
Lesson 23
Activity 37:
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
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"); */ */
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
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.
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
Lesson 23
Final Activity
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
689
Final Activity
Lesson 23
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
Lesson 23
Final Activity
691
Final Activity
Lesson 23
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
692
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.
693
Course Review
Lesson 24
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
694
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.
______________________________________________________________________________________________________________
695
Sample Code
Appendix A
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
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;
rem End-If;
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;
rem End-If; catch exception &ex rem Handle the exception; &fileLog.WriteLine(&ex.ToString()); end-try; &fileLog.WriteLine("End"); &fileLog.Close();
698
Appendix A
Sample Code
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
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")
700
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
'***** 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 *****
'End If '***** Execute Cancel ***** 'If Not oStudentProfile.Cancel() Then ' ' ' Err.Raise 1001, "", "Unable to Cancel Component Interface" CallErrorHandler() Exit Sub
701
Sample Code
Appendix A
'End If
702
Appendix A
Sample Code
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(); } }
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; }
704
Appendix A
Sample Code
705
Sample Code
Appendix A
System.out.println("oStudentProfile.ProjectRole: " + oStudentProfile.getProjectRole()); //oStudentProfile.setProjectRole([*]); //***** END: Set Component Interface Properties *****
//***** Disconnect from the App Server ***** oSession.disconnect(); return; } catch (Exception e) { e.printStackTrace(); System.out.println("An error occurred: "); ErrorHandler(); } } }
706
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();
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
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");
//***** BEGIN:
709
Sample Code
Appendix A
System.out.println("oStudentProfile.ProjectRole: " + oStudentProfile.getProjectRole()); strProjectRole = inData.readLine(); oStudentProfile.setProjectRole(strProjectRole); //***** END: Set Component Interface Properties *****
710
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>
711
Sample Code
Appendix A
<!--
-->
<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
Appendix B
______________________________________________________________________________________________________________
713
Appendix B
714
Appendix B
715
Appendix B
716
Appendix B
717
Appendix B
718
Appendix B
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.
719
Appendix B
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
720
Appendix C
Accessing CTE
Objectives
This appendix contains information about: Accessing and logging into CTE. Student logins. Workstation ports.
______________________________________________________________________________________________________________
2. Enter the class ID and password, and then click Sign In.
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
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
723
Accessing CTE
Appendix C
Notes
______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________ ______________________________________________________________________
724
Appendix D
Curriculum Map
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
Administration
Enterprise Portal
1011 Enterprise Portal Administration (8.4) 3 days Classroom
OR
1377 Concepts in Enterprise Portal Development (8.4) 1 day Live WebCast
Reporting
455 Query/Crystal Power Combo 4 days Classroom with OnDemand 1152 Query Reporting 2 days Classroom with OnDemand
726