Integration Tools

Component Interfaces

 A way for external applications, internal message handling, and other application environments to access PeopleSoft logic and data.  Provide access to PeopleSoft data in a ways that is completely independent of specific pages.  Properties  Data items that describe a Component Interface and map to the data in the page buffer associated with the component.  Can be either fields or collections – these correspond to component record fields and scrolls, respectively.  Methods  Perform functions on a Component Interface such as creating a new purchase order, approving a purchase order, saving a purchase order, etc.  Standard methods and user-defined methods Component Interface Architecture

Integration Tools

March 2003

Page 1 of 42

 Defining Component Interfaces  Built in AppDesigner  Based on a single component  When you create a new Component Interface, you will be prompted for default properties (i.e., records and fields)  If you answer Yes, all of the default properties will be included in your Component Interface. You still have the opportunity to choose which properties you would like to expose by manually deleting everything else.

Integration Tools

March 2003

Page 2 of 42

 If you answer No, you will pick and choose what to expose.

 Component View shows exactly the same hierarchical record structure that you would see if you had the component open in AppDesigner.  Add individual objects or groups of objects to the Component Interface View by dragging and dropping objects from the Component View into the Component Interface View.  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 on the Component. However, only the objects in the Component Interface View will be exposed to the calling program at run-time.  Component Interface View displays a tree in which each object type is represented by a unique icon.

Integration Tools

March 2003

Page 3 of 42

 There are five columns at the top of the Component Interface View  Name: The name of a specific element on a Component Interface (such as the name of a property or method).  Record: The name of the underlying record upon which a specific element is based.  Field: The name of the field to which a Component Interface property points.  Read Only (Y/N): Displays whether a specific property or collection has been marked read-only.  Comment: Displays any comments that exist in the Edit Property dialog for the selected key, property, or collection.  Elements of a Component Interface  Component Interface Name  Keys  Keys define the values that uniquely identify an instance of a Component Interface  Can have three types of keys: • Get Keys: Map to fields marked as Srch in the component’s search record. If the component has a search record with fields marked as Srch, these will automatically be generated as Get Keys for the Component Interface. You cannot change the Get Keys. • Create Keys: If the Use tab on the Component Properties dialog allows the Add action, then Create Keys are generated for the Component Interface automatically. If the component has an Add mode search record, then the Component Interface uses that search record for the Create Keys. Otherwise, the search record is used to generate the keys. You cannot change the Create Keys.

Integration Tools

March 2003

Page 4 of 42

Find Keys: Map to fields marked as both Alt and Srch in the component search record. You may remove Find Keys that you do not wish to make available for searching.  Properties and Collections  Properties are individual data items (fields) that describe a Component Interface. Each property maps to a single field in the Component Interface’s underlying component.  A Collection is similar to a property, but instead of mapping to an individual field, it points to a scroll area.  Two main types of properties • Standard properties are common across all Component Interfaces and are provided automatically when a Component Interface is created. ♦ CreateKeyInfoCollection: Returns a set of items that describes the Create Keys ♦ GetKeyInfoCollection: Returns a set of items that describes the Get Keys ♦ FindKeyInfoCollection: Returns a set of items that describes the Find Keys ♦ PropertyInfoCollection: Returns a set of items that describes properties ♦ InteractiveMode: 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. However, if you are using a particular Component Interface as part of a batch process in which thousands of rows are to be inserted, performance may be improved by not running in interactive mode. ♦ GetHistoryItems: Controls whether the Component Interface runs in Update/Display mode or Correction mode. Applies only to getting a Component Interface, not to creating a Component Interface ♦ EditHistoryItems: Property to specify what data is accessed and whether you can edit that data:  If EditHistoryItems is false (default) and GetHistoryItems is true, you access the data in the Component Interface in a similar manner as if you were accessing a component in Update/Display All mode. This means 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 in a similar manner as if you were accessing a component in the Correction mode.  If GetHistoryItems is false, you access the data in the Component Interface in a similar manner as if you were accessing a component in Update/Display mode. The EditHistoryItems has no effect when GetHistoryItems is false. ♦ Default properties are Update/Display (GetHistoryItems is false) and Interactive mode.

Integration Tools

March 2003

Page 5 of 42

User-defined properties come from a Component Interface’s associated component and must be added manually.  Methods  A method is an object that performs a very specific function on a Component Interface at run-time.

Integration Tools

March 2003

Page 6 of 42

Standard Methods • Available on all Component Interfaces. • Automatically generated upon the creation of a new Component Interface and provide the basic functions required of any Component Interface. • Ability for a user to invoke any standard method is controlled by security (at the Permission List level) so your Component Interface should contain all appropriate methods since all you are doing is identifying the potential standard methods that may be authorized through security. User-defined methods • Can be created to meet the requirements of an individual Component Interface. • Simply a PeopleCode function that you wish to make accessible through the Component Interface. • Each method maps to a single PeopleCode function. • Also granted through security.

 Setting Component Interface Security  Access must specifically be granted before a Component Interface is available for use at run-time by any user.  Two ways to secure Component Interfaces:  Individual properties can be marked “read only” using AppDesigner. Any property can be marked “read only” in the Component Interface design.  Grant authorizations on a Permission List  Component Interface Tester  Choose Tools, Test Component Interface from the menu or Right-click anywhere in the Component Interface View and select Test Component Interface.  The Test Component Interface dialog displays the key structures (in the left-hand column) defined as part of the Component Interface. The right-hand column provides a place for you to enter sample key values for testing.  Implementing a Component Interface

Integration Tools

March 2003

Page 7 of 42

 The usual actions that you perform with a Component Interface are:  Create a new instance of data  Get an existing instance of data  Retrieve a list of instances of data  Create a new instance of data  Get a Session Object – Before you can get a Component Interface, you have to get a session object which controls access to the Component Interface, provides error tracing and allows you to set the run-time environment. Sample PeopleCode: &SESSION = GetSession(); If &SESSION.Connect(1, “EXISTING”, “”, “”, 0) <> True Then /* Error Handling Routine */ End-If; Get a Component Interface – Use the GetComponent method with a session object to get the Component Interface. You must specify a Component Interface definition that has already been created or you will receive a run-time error. &CI = &SESSION.GetCompIntfc(CompIntfc.PSU_STUDENT_PROFILE); If None(&CI) Then Error (“Component Interface does not exist!”); End-If;

Integration Tools

March 2003

Page 8 of 42

Set the Create Keys – These key values are required to open a new instance of the data. If the values you specify aren’t unique, that is, the instance of the data already exists in the database with those key values, you will receive a run-time error. &CI.STUDENT_ID = “NEW”;

Get the Instance of the Component Interface – After you set the key values, you have to use the Create Method to populate the Component Interface with the key values you set. &CI.Create();

Populate the rest of the fields – Assign values to the other fields. &CI.STUDENT_NAME = PERSONAL_DATA.NAME; &CI.CUSTOMER_ID = “PSFT”; &CI.SAME_ADDR_CUSTOMER = “Y”; &CI.PROJECT_ROLE = “BSA”;

Save the component – when the Save method is executed, a new row of data will be saved to the database. &Save = &CI.Save(); If &Save = False Then Error (“Component Interface update has failed.”) End-If; Note: The Save method returns a True if the save was successful or False if it failed.

 Activating the Component Interface  Like SQLExec PeopleCode, Component Interfaces are used to update data outside of the component buffer.  Typically you will see the PeopleCode that triggers a Component Interface in the SavePostChange event. Errors and warnings generated in SavePostChange cause the component to be cancelled and all uncommitted SQL to be rolled-back. So if the Component Interface update fails so will the update of the source component, which prevents tables from getting out of synch.

Integration Tools

March 2003

Page 9 of 42

Component Interface API
(Using Component Interfaces with external systems)  Building PeopleSoft APIs  After creating a Component Interface, you need to create an API which will build the dynamic link libraries, classes, and registry settings necessary to allow a third party application to communicate with PeopleSoft.  These files reside on the client machine; the web server for ASP and the machine running the Java program for Java. The registry file may also need to be executed to update the registry with the new libraries.  Only external applications, such as COM or C/C++ programs, require a Component Interface API. PeopleCode programs do not require a Component Interface API.  Every time you create or modify a Component Interface that will be used for external integration, you must rebuild the PeopleSoft APIs.  COM Bindings – when deploying Component Interfaces on a local client machine or web server with COM bindings, you must have:  The third party COM application  The PeopleSoft application server and database  The Java Virtual Machine (JVM) supplied with Sun Microsystems’ JDK 1.3.1  A copy of the type library called Peoplesoft_Peoplesoft.tlb that you generated during the Build PeopleSoft API Bindings process. This type library is not specific to a single database instance – it is specific to those database objects.  A copy of the registry file called Peoplesoft_Peoplesoft.reg that you generated during the Build PeopleSoft API Bindings process. This registry file is not specific to a single database instance – it is specific to those database objects.  Client Setup: 1. Install the PeopleSoft Server. 2. Install Sun’s JDK 1.3.1 to enable the JVM (if it is not already installed). 3. Set the environment variable PATH to include the following: a. The directory containing jvm.dll (typically c:\bea\jdk131\jre\bin\classic) b. PeopleTools client installation directory (typically <PS_HOME>\bin\client\winx86) 4. Set the environment variable CLASSPATH to include the file psjoa.jar (typically <PS_HOME\class\psjoa.jar). 5. For Microsoft Visual Basic: a. Open the Visual Project File pscitester.vbp or sdk_bus_exp.vbp in Microsoft Visual Basic b. Select Project, References and add the type library  Third Party Applications  Copy the type library and registry files to the directory containing the external API on each client machine from which you want to use the COM API.  Apply the API registry settings by double-clicking Peoplesoft_Peoplesoft.reg

Integration Tools

March 2003

Page 10 of 42

 C Header Bindings – when deploying Component Interfaces on a local client machine with C++ bindings, you must have:  The third party C++ application  The PeopleSoft application sever and database  The Java Virtual Machine (JVM) supplied with Sun Microsystems’ JDK 1.3.1  Your compiler, configured for the C++ project  Client Setup: 1. Install the PeopleSoft Server. 2. Install Sun’s JDK 1.3.1 to enable the JVM (if it is not already installed). 3. Set the environment variable PATH to include the following: a. The directory containing jvm.dll (typically c:\bea\jdk131\jre\bin\classic) b. PeopleTools client installation directory (typically <PS_HOME>\bin\client\winx86) 4. Set the environment variable CLASSPATH to include the file psjoa.jar (typically <PS_HOME\class\psjoa.jar). 5. Set the environment variable PS_HOME to point to the installed PeopleSoft PeopleTools directory (for example, c:\pt840)  Third Party Applications  Function names generated by the Build APIs process can be quite long. You may want to consider creating classes within your C++ code to mask this length throughout your program.  When you create your installation for your C or C++ program, make sure you include the setup of the path to the psapiadapter.dll.  C Header File – when you do the Build API process in the Component Interface Designer, it creates one peoplesoft_peoplesoft_i.h file for all of the objects in the PeopleSoft database. This C header file is not specific to a single database instance – it is specific to those database objects.  Java Bindings – when deploying Component Interfaces on a local client machine or web server with Java bindings, you must have:  The third party Java application  The PeopleSoft application sever and database  The Java Virtual Machine (JVM) supplied with Sun Microsystems’ JDK 1.3.1  Client Setup: 1. Install Sun’s JDK 1.3.1 to enable the JVM (if it is not already installed). 2. Set the environment variable PATH to the directory containing jvm.dll (typically c:\bea\jdk131\jre\bin\classic) 3. Set the environment variable CLASSPATH to include: a. the file psjoa.jar (typically <PS_HOME\class\psjoa.jar). b. the target directory selected during the Build API process (<PS_HOME>\class)

Integration Tools

March 2003

Page 11 of 42

File Layouts and Data Interchange
 A file layout is a definition that represents the data structure of a flat (text) file to be processed.  When reading from or writing to a flat file, your PeopleCode can use a file layout as a template to identify and correctly process the file’s records and fields.  File layouts work with hierarchical and non-hierarchical data and can handle files that combine data records with non-data (audit or control) records.  You can employ file layouts to move data between a 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 automatically generate an AppEngine program to perform the data import (rel 8.4).

 Data may be imported by combining different technologies:  Read the data directly into the database (SQL Insert)  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

Integration Tools

March 2003

Page 12 of 42

 File Types  Fixed Position (FIXED): Each field has a starting position and a length. This is the default for new file layouts.

 Sequence Positional or Comma Separated Values (CSV): Fields are located in the file by their sequence and separated from each other by either a separator, a delimiter or both.

 XML Tagged (XML): A field is located not by its position or sequence within a record, but by the named XML tags surrounding it.

Integration Tools

March 2003

Page 13 of 42

 File Layout Record Properties File Record Name File Record Name associated with this File Record. This name will be used when accessing the File Record from PeopleCode. Every File Record in a File Layout must have a unique name. ID Seq No. For records of type CSV, the sequence number of the field that contains the File Record ID identifier. Max Rec Length The default maximum length of the combined field sizes of the record. This value isn’t incremented automatically. If you add fields to a record, you will need to change this value to account for the new or changed field(s). You also need to change this value if you insert a segment then add fields to that segment. Warning: Any inbound or outbound data will be truncated beyond this value. A group of numbers used to identify the File Record. Each File Record ID must be unique in the File Layout. You can use this number in processing the file. This number is automatically written to the file if you use the WriteRecord or WriteRowset methods and the file type is FIXED or CSV. The column or starting position in the File Record where the File Record ID starts. The length of the File Record ID. This number is automatically generated when you enter the File Record ID. You can specify a number larger than the number of characters in a File Record ID, but you can’t specify a number smaller than the number of characters in the File Record ID. For File Layouts of CSV, the qualifier is used for the File Record ID and the default for fields when no field qualifier is specified. This value overrides the Definition Qualifier specified in the File Layout properties dialog box. When you first create a File Layout, this property is blank. For File Layouts of type CSV, the delimiter is used for all fields in the File Record. This overwrites the Definition Qualifier specified on the File Layout properties dialog box. For File Layouts of type XML, the XML Tag Name for this File Record. This defaults to the File Record name. A description of the record. This is for documentation purposes only.

File Record ID

ID Start Position ID Length

Default Qualifier

File Delimiter Record Tag Record Description

Integration Tools

March 2003

Page 14 of 42

 Importing Data  Provide the import data in a properly formatted flat file.  Create a File Layout definition to match the record and field structure of your data. Insert the appropriate record definitions into your File Layout, then reposition the file records and file fields to match the record and field positions in your file.  Preview and troubleshoot the input data format and content.  Generate the data import AppEngine program and PeopleCode.  Run the AppEngine program to import the data.  Including and Excluding Fields  The fields in your data file’s records can be a subset of the database record’s fields – define your File Layout with only the file fields you expect to receive.  The fields in your data file’s records can be a superset of the database record’s fields -you must define your File Layout to suppress or ignore the extra fields.  For FIXED files, don’t define a field at the corresponding position in your File Layout.  For CSV files, the file layout must have the same number of fields in each record as there are in the corresponding file record – for each field you don’t want to import, define a field in the file layout at that position that doesn’t correspond to any field in that database record.  For XML files, any extra fields are ignored automatically.  Record Hierarchy  In theory, you can ignore rowset hierarchy when importing file data because the PeopleSoft database stores each record independently for the others and rowsets aren’t used in the import process. However, many records are designed with hierarchical dependencies in mind. The input file might omit inherited field values or order the data records in a way that reflects such dependencies.  If your input file omits inherited field values, make sure the inheriting fields’ records in the file layout are children of the ones from which they inherit their values and make the appropriate Field Inheritance settings.  If the records to be imported contain key fields that reflect a rowset hierarchy, they might be in an order in the file that also reflects the hierarchy. Make sure your File Layout reflects that hierarchy as well.  Your completed File Layout must have exactly one file record at the root level; all other file records must be below that level.

Integration Tools

March 2003

Page 15 of 42

 Previewing Data The following table shows some examples of input data errors: Symptom Possible Reason The preview grid does The input file’s format does not not appear. match the file layout format you specified in the File Layout Definition Properties dialog box. A CSV file doesn’t use the definition qualifier you specified in the File Layout Definition Properties dialog box. Only the first column A CSV file doesn’t use the of the preview grid is definition delimiter you specified in populated. the File Layout Definition Properties dialog box. The preview grid The file’s record IDs for the appears for some missing records don’t match their records, but not for file record IDs specified in the File others Layout Segment Properties dialog box. Data for a field With a FIXED file, the field length appears truncated in you specified in the File Layout the preview grid. Field Properties dialog box is too short to accommodate the field data. A field appears to start With a FIXED file, the start in the middle of the position you specified in the File data. Layout Field Properties dialog box is too great to include the start of the field data. Solution Change the file layout to match the input format. Change the definition qualifier to match the one used in the input file. Change the definition delimiter to match the one used in the input file. Specify file record Ids that match the input file records.

Increase the field length to accommodate the input data.

Decrease the start position and adjust the field length to match the input data start position and length.

Integration Tools

March 2003

Page 16 of 42

Integration Tools

March 2003

Page 17 of 42

 File Object  Used to provide the methods necessary to read from and write to files.  Once it is instantiated, it can be associated with a File Layout and the file methods can be used to read and write.  Can only be instantiated from PeopleCode  Can be used anywhere you have PeopleCode  File is passes as a reference  File object can be used with plain text files or File Layouts.

Integration Tools

March 2003

Page 18 of 42

 File Class – provides the functions, methods, and properties to allow us to read and write to flat files. Class Name Functions, Methods and Properties Returns File Functions FileExists(filename [, pathtype]) Boolean FindFiles(filespec_pattern [, pathtype]) Array object GetFile(filename, mode [, charset] [,pathtype]) File object File Methods Close() CreateRowset() Rowset object Open(filename, mode [, charset] [,pathtype]) ReadLine(string) Boolean ReadRowset() Rowset object SetFileid(fileid, position) SetFileLayout(FILELAYOUT.filelayoutname) Boolean SetPosition(position) WriteLine(string) WriteRecord(record) Boolean WriteRowset(rowset) Boolean WriteString(string) File Properties CurrentRecord String, RO GetPosition Number, RO IgnoreInvalidid Boolean IsError Boolean, RO IsNewField Boolean, RO IsOpen Boolean, RO Name String, RO RecTerminator String  You can use the GetFile built-in function to access an external file, but each execution of GetFile instantiates a new file object. If you plan to access only one file at a time, you only need one file object. Use GetFile to instantiate a file object for the first external file you access, then use Open to associate the same file object with as many different external files as you want. You’ll need to instantiate multiple file objects with GetFile only if you expect to have multiple files open at the same time.  GetFile(filespec, mode [, charset] [, pathtype])  filespec  mode Mode R W Specify the name, and optionally, the path, of the file you want to open. A string indicating the manner in which you want to access the file. The mode can be one of the following: Description Read mode: opens the file for reading, starting at the beginning Write mode: opens the file for writing. When you specify Write mode, any existing content in the file is discarded and will be overwritten. March 2003 Page 19 of 42

Integration Tools

A U

E N  charset  pathtype

Append mode: opens the file for reading or writing, starting at the end. Any existing content is retained. Update mode: opens the file for reading or writing, starting at the end. Any existing content is retained. Use this mode to maintain checkpoints of the current read/write position in the file. In Update mode, any write operation will clear the file of all data that follows the position you set. Conditional “exist” read mode: opens the file for reading only if it exists, starting at the beginning. Conditional “new” write mode: opens the file for writing, only if it doesn’t already exist. A string indicating the character set you expect when you read the file, or the character set you want to use when you write to the file. You can abbreviate ANSI to “A” and Unicode to “U”. If you have prepended a path to the filename, use this parameter to specify whether the path is an absolute or relative path. The valid values for this parameter are: • %FilePath_Relative (default) • %FilePath_Absolute If you don’t specify a path, the file is assumed to be in one of two locations, depending on where you PeopleCode program is executing. • When your program is executing on the client, the location is the directory specified by the TEMP environment variable. • When your program is executing on the server, the location is the “files” directory under the directory specified by the PeopleSoft PS_SERVDIR environment variable.

 Reading from a File  ReadRowset()  File method used to instantiate a PeopleCode rowset object based on the file layout definition, then populate the rowset with one transaction from the file. A transaction is considered to be one instance of level zero 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 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.  Handling File Errors  If any error occurs on any field in any record of the rowset object populated with the ReadRowset method, the rowset object’s IsEditError property will return True. For example, you can use the method ExecuteEdits on a record to verify the data in the record is valid. Integration Tools March 2003 Page 20 of 42

To determine which field has the error, you must examine the EditError property of every field in the rowset to find the one returning True. &REC.ExecuteEdits(); If &REC.IsEditError Then For &I = 1 to &REC.FieldCount If &REC.GetField(&I).EditError Then LOG_ERROR(): /* application specific pgm */ End-If; End-For; End-If;

 Writing to a File  WriteRecord(record)  File Layout method that writes the contents of the record object record, to the output file. (Remember, a record object contains only one row of data from an SQL table).  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.  WriteRowset(rowset)  File Layout method that writes the contents of a rowset object, rowset, to the output file associated with the file object executing this method. Regardless of whether the rowset contains just one or more than one transaction (level 0 row), executing this method once will write the entire contents of the rowset to the output file.  SQL Class  CreateSQL(sqlstring [, paramlist])  Instantiates a SQL object from the SQL class and opens it on the given sqlstring and input values. sqlstring is a PeopleCode string value giving the SQL statement.  Any errors in the SQL processing cause the PeopleCode program to be terminated with an error message.

Integration Tools

March 2003

Page 21 of 42

/******************************************************** The following PeopleCode selects all employees from the Absence History who have more than 10 absences and copies those rows into another table called AbsenceStg. ********************************************************/ Local Record &ABS_HIST; &ABS_STG; Local SQL &SQL1, &SQL2 &ABS_HIST = CreateRecord(Record.ABSENCE_HIST); &ABS_STG = CreateRecord(Record.ABSENCE_STG); &SQL1 = CreateSQL(“%SelectAll(:1) where DURATION_DAYS > 10”, &ABS_HIST); &SQL2 = CreateSQL(“%INSERT(:1)”); While &SQL1.Fetch(&ABS_HIST); &SQL2.Execute(&ABS_STG); End-While;

Integration Tools

March 2003

Page 22 of 42

PeopleSoft Integration Broker

 PeopleSoft’s Integration Broker is comprised of four key elements  Packaged Connectors All messages entering and 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.  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.  Transformation Transformation is required to translate a message between different systems. The Integration Broker takes a system message and converts the data from one system’s format into another’s.

Integration Tools

March 2003

Page 23 of 42

 Development and Monitoring Environment The development environment is used by programmers to map the complex relationships between systems. 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. In release 8.1x, this is done entirely in AppDesigner. In release 8.4, this is done using both AppDesigner and the web browser.

Application Messaging
 Completely server-based allowing PeopleSoft applications to interact with web services in response to the invocation of business events within the Component Processor.  Messages are published in XML format and delivered to subscribing systems over a secure HTTP connection.  Supports both bi-directional synchronous and asynchronous messaging.  Synchronous message can be used for invoking web services in other systems and returning the results into a PeopleSoft page before continuing with a process, or for exposing PeopleSoft business logic as a web services to calling systems.  Asynchronous messaging is used to guarantee delivery of data between PeopleSoft and other applications without having to halt a business process because of a subscribing system being unavailable.  Some of the Enterprise Integrations Points using Application Messaging in PeopleSoft 8:  Setup Table Replication: A number of setup tables within PeopleSoft applications (e.g., Department, Account, Vendor, Customer, etc.) where Application Messaging is used to replicate the contents of the tables between PeopleSoft systems and third-party systems  Customer/Address/Contact Data: Used in Customer Relationship Management (CRM) to synchronize customers and contact with Human Resources (HRMS) and Financials (FDM).  Personal Data: PeopleSoft HRMS maintains employee information that many third-party systems need. Application Messaging synchronizes this data with the third-part systems.  Cross Release Messaging (rel 8.4)

Component Interfaces
 Component Interfaces make the business logic and data of a Component available as an object that is accessible externally from the application or within a PeopleCode environment.  An external system can invoke PeopleSoft Components over HTTP(S)/XML or it can invoke the Component Client using Java, COM, or C/C++ bindings.  Component Interface technology is used in PeopleSoft 8 to address API-based synchronous integration from third-part applications to PeopleSoft applications, as well as a means to apply business logic to an application message. Integration Tools March 2003 Page 24 of 42

 Some of the Enterprise Integration Points with Component Interfaces in PeopleSoft 8:  Setup Table Interface: PeopleSoft exposes a large number of setup tables through Component Interfaces. These interfaces can also be used to import setup data into the PeopleSoft system if the master copy of that data is maintained in a different system.  Customer and Contact Creation: When a lead is created, a Component Interface in the Sales application of CRM is used to create a customer or contact corresponding to the lead. Similarly, another Component Interface is used when a lead is converted into an opportunity.  Process Scheduler API: Allows a third party to manipulate the process scheduler tables and control batch job submission.  Expense Sheet: Allows third-party systems to access expense sheet data within PeopleSoft Expenses.

File Interfaces
 PeopleSoft delivers the File Layout designer for graphically defining where data should be located in the file. The File Layout definition becomes a metadata object that is accessible from AppEngine for batch processing of file data and invoking PeopleSoft business logic.  Examples of how file processing can be used:  Read file data and map it to a Component Interface  Read file data and publish an Application Message  Read file data and insert it directly into PeopleSoft tables  Query PeopleSoft tables and write the results to a file  Subscribe to an Application Message and write the data from that message to a file  Storing a file attachment

Business Interlinks
 Deprecated feature in PeopleTools rel 8.4…meaning that new development is not encouraged (replaced by more robust Application Messaging). However, Business Interlinks are still used within the PeopleSoft system for synchronous integration with 3rd part systems.  Enable you to perform component-based, real-time integration from PeopleSoft to external systems.  Should be used for synchronous messages with dynamic parameters.

Enterprise Integration Points (EIPs)
 A connection between a PeopleSoft system or application and an external system or application.  Seamlessly connects the two systems or applications, enabling one- or two-way data transfer in order to accomplish a specific business purpose.

Integration Tools

March 2003

Page 25 of 42

 EIP catalog is an online compendium of all EIPs delivered with PeopleSoft 8. It’s current location is:
http://www.peoplesoft.com/corp/en/products/line/app_integration/integration/eip_maps_index.asp

Integration Broker Architecture
 Integration Broker is composed of two high-level subsystems  Integration Gateway  A platform that manages the actual receipt and delivery of messages passes among the systems through the Integration Broker  Provides support for the leading TCP/IP protocols used today  Provides extensible interfaces for the development of new connectors for communication with legacy, Enterprise Resource Planning (ERP) and Internet-based systems  Primarily a conduit that receives and sends messages among integration participants’ systems.  Contains the following components: • Web Server Container – WebLogic • Gateway Connectors ♦ Listening Connectors receive incoming messages and hand the incoming requests to the Gateway Manager ♦ 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. ♦ Same architecture is used for both listening and target connectors. They are servlets that listen on a URL for HTTP Posts and HTTP Gets from an external service. Various Java programs can send or request messages via HTTP, SMTP, POP3, and JMS or by custom connectors. ♦ Integration Gateway Connector SDK is available to assist you in creating your own custom connectors. Included in the SDK:  Java classes required to create connectors  JavaDocs detailing all of the java classes required to build your own custom connectors  Sample Listening Connector  Sample Target Connector • Gateway Manager ♦ Dispatcher for messages that flow through the Integration Gateway. ♦ Uses handles on the messaging objects, IBRequest and IBResponse, to determine how to route each message ♦ Uses a number of Gateway Services to perform operations  Error Handling – 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 – IBRequest and IBResponse. These objects are central to the system as they represent the request and response that go in and out of the Integration Broker. Integration Tools March 2003 Page 26 of 42

 XML Parsing – 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.  Message Validation – 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 – composite of several smaller services the Integration Gateway implements to manage connectors.  Error and Message Logging – standard logging interface that most components in the system use…most notably the connectors.

 Integration Broker Engine  Integration Service – First entry point into the PeopleSoft application, it received 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 process asynchronously or synchronously.  Integration Profile – contains the routing logic and authenticator information.  Asynchronous Request Handler – invokes the message definition’s Subscription PeopleCode.  Synchronous Request Handler – invokes the message definition’s OnRequest PeopleCode.  Transformation Engine – invokes any associated transform programs.  Error Handling – standard error handling interface that is exposed to each connector.  Elements of Basic Integration  Basic development elements: Integration Tools March 2003 Page 27 of 42

Message Channel definition – groups of message definitions, help sequence messages properly, enhance scalability, and provide a simple way to define processing characteristics of many similar messages as a single group. Message Channels must have the identical object name in all nodes that use them.  Message definition – fundamental building blocks of the PeopleSoft Messaging architecture. Store the information about how a single message is constructed. Message Definitions must have the identical definition name in all nodes that use them unless you create a transformation program to identify the message to the remote node. • Message Structure ♦ Define simple (single level) or complex (multi-level) data structures ♦ Include multiple records that are not related ♦ Include or suppress fields from being published ♦ Define “aliases” for dissimilar field names across databases ♦ Define multiple versions (i.e., content formats) • Message Subscription: (PeopleCode) ♦ Used to manipulate data in the subscribing node and update the appropriate tables ♦ Executed automatically by Tuxedo domain services in the subscribing system ♦ Can be executed manually in 2-tier using the Run PeopleCode menu item • Message Routing: (PeopleCode) ♦ In the publishing node, determines which nodes to send (route) the message to ♦ In the subscription node, determines if a received message should be accepted ♦ Executed automatically by Tuxedo domain services in the publishing and subscribing systems  Sending PeopleCode (Publish) – Used to trigger a message to be sent. The PeopleCode can be placed on an existing Record, Component, or AppEngine program.  Subscription PeopleCode – Used to receive a message asynchronously, create an entry in the Message Subscriptions section of the message structure view, and enter your PeopleCode into its associated Subscription PeopleCode event.  OnRequest PeopleCode – Used to receive a message synchronously, enter your PeopleCode into the existing OnRequest PeopleCode event associated with the root of the message structure.  Basic administrative elements:  Gateway definition  Node definition  Transaction   Elements of Advanced Integration  Advanced development elements:  Transform program  XSLT action Integration Tools March 2003 Page 28 of 42

 PeopleCode action  Codeset repository  Advanced administrative elements:  Relationship definition  Transaction modifier  Advanced message routing:  OnRoute Send  OnRoute Receive  Transaction Process Flow Transaction Type Outbound Asynchronous Outbound Synchronous Actions 1. Your application generates and sends a request message. 2. One or more target nodes receive and process the request message. 1. Your application generates and sends a request message. 2. Your application suspends activity and waits for a response message. 3. A single target node receives and processes the request message, then generates and sends a response message. 4. Your application resumes its activity, receives and processes the response message. 1. A source node generates and sends a request message. 2. Your application receives and processes the request message. 1. A source node generates and sends a request message. 2. The source node suspends activity and waits for a response message. 3. Your application receives and processes the request message, then generates and sends a response message. 4. The source node resumes its activity, receives and processes the response message.

Inbound Asynchronous Inbound Synchronous

Note: For any transaction type, your application must invoke PeopleCode to generate and send a message, or to receive and process a message. When Integration Broker sends a message, the receiving system sends a low-level reply message back to the sender. This differs from the response message which is the second half of a synchronous transaction. A reply message serves only a “handshaking” purpose, to notify the sending system of the transmission status of the request or response message. It’s processed automatically by the application server, which uses that status information to update the Integration Broker Monitor.

Integration Tools

March 2003

Page 29 of 42

Integration Tools

March 2003

Page 30 of 42

Integration Tools

March 2003

Page 31 of 42

Integration Tools

March 2003

Page 32 of 42

Integration Tools

March 2003

Page 33 of 42

In release 8.1, this is called the “Application Messaging Gateway”

Integration Tools

March 2003

Page 34 of 42

Integration Broker Monitor
 Similar to Process Monitor in the Process Scheduler  Provides status information on the delivery of messages and aids in error processing and resolution.  All the tables in the Message Monitor deal with asynchronous messages except one, the Synchronous Message tab.  Message Monitor has general filtering options that apply to each page where filtering applies: Criteria Description Publish Node Every message is stamped with the node that publishes it. This control provides a drop-down list containing all the nodes defined in your system. The message monitor only allows you to view information for the local system (database). But the local database may have in its queues messages published not only by the local node, but also remote nodes. There is only one local node for a database. Last Enter a numerical value and select Days, Hours, or Minutes from the associated drop-down list. By selecting None, you receive all messages currently in the system. Archived The Archived check box is a toggle switch that enables you to specify a search on your archived message data or your “live” message data. For the Overview page, additional filtering options are available: Criteria Description Queue Type Specify the particular queue in which you are interested in monitoring. Your options are Message Instance, Publication Control, or Subscription Contract. Group By Use this option to view by Channel or Message. After clicking refresh, notice that the label of the following section changes to reflect the option you selected from this drop-down list.  Message Status Regardless of what Queue Type you are monitoring, the columns in the Message Name/Channel Name list remain the same. Possible status messages that you may encounter are: Status Description Error An error occurred during processing. Manual intervention is required. New Either the item has been written to the database but has not been dispatched yet or the item has just been resubmitted. Started The dispatcher is in the process of passing the item to a handler, but the handler has not received it yet. Working The handler has accepted the item and is currently processing it. Done The handler successfully processed the item. Depending on the type of process you are monitoring, this status indicates different outcomes. Message Instance: All contracts have been created. Integration Tools March 2003 Page 35 of 42

Retry Timeout Edited Cancelled

Publication Contracts: The publication has been successfully received by the subscribing node. Subscription Contracts: The subscription process ran successfully. The system encountered an intermittent error during processing. The system retries messages with the status automatically. Before a message transaction could be completed successfully, the system timed out. The publication data for the item has been edited. Processing will not resume until you resubmit the item. The item has been cancelled. The system can’t process the item until you resubmit.

more tab options here?

Integration Tools

March 2003

Page 36 of 42

Advanced Messaging
 When exchanging message with third-party applications, there will be inherent differences in the messages.  AppEngine transform programs are used to apply transformation, data translation and filtering on either inbound or outbound messages.  Transform programs can:  Apply a transformation to a message to make its structure comply with the target system’s requirements. Example: A field is called Purchase Order on a target system and called PO in PeopleSoft. The transform program will interpret the XML tags to be consistent with the target.  Perform a data translation on a message so its data is represented according to the target system’s conventions. Simple translation might be required if the two systems use different values to represent the same information for a given field. Complex translation might involve augmenting or replacing groups of fields with a completely different structure and encoding. Example: The values for Course Type on PeopleSoft are “PT”, “FIN”, and “HR” on the target system these same codes are represented as “T”, “F”, and “H”.  Determine whether to pass a message through to its target, but filtering bases on its content. Example: If the Business Unit = “USA”, then the message will be passed to the target.  Transformation  Preferred method is an AppEngine program with Extensible Stylesheet Language Transformation (XSLT) steps. XSLT is a well-recognized standard language perfectly suited to manipulation XML structures so it’s highly recommended for implementing transformations.  Each transform program step operates on the message content that results from the previous step, so you can break your transform program into a sequence of discrete steps. Multiple transform actions within a step can produce unwanted effects, so be sure to insert each XSLT or PeopleCode action in its own step.  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.  Each XSLT program must be enclosed in the following wrapper: <?xml version=”1.0”?> <xsl:stylesheet xmlns:xsl=http://www.w3.org/1999/XSL/Transform version=”1.0”> … </xsl:stylesheet> Note: Third-party XSLT development tools may generate a wrapper that specifies a different URL. Make sure the URL in your program is exactly as above or your program may not work as expected. Integration Tools March 2003 Page 37 of 42

Integration Tools

March 2003

Page 38 of 42

 A Transformation AppEngine program is automatically invoked by the Integration Engine based on the relationship set up between nodes for a specific transaction. The relationship is defined in the database that will be performing the transformation.  Specify the two nodes to which this relationship applies. Never enter the name of the default local node.  Only transactions included in the selected nodes’ definitions can be used by this relationship.  You can specify the same node name twice, which still constitutes a pair as far as a relationship is concerned. The node names (Initial and Result) would only be different if the message was making a stop along the way (i.e., independent hub integration broker).  Data Translation  Best suited for modifying message content rather than structure  Most appropriate when the sending and receiving systems use different field values or different combinations of fields and their values to represent the same information Example: 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 and includes the middle name as part of the First field. Application C uses only one field – Accounted. One Integration Broker node can store in its codeset repository the equivalent fields and values used by another node. When it receives a message from the other node containing a customer name, it can use its codeset repository to translate the information into the form it prefers. It can likewise reverse the process for messages it sends to the other node.  Elements of a Data Translation  Codeset Group – contains a list of significant data fields and their values that a particular node might send in an initial message  Codeset – contains a specific set of match/name value pairs selected from the existing codeset group  Codeset Values – contains the named value you predefine as the Return value  Development Sequence  The codeset group must exist before you can define a codeset based on it.  A codeset and two groups must exist so you can define values associated with them.  A codeset and associated codeset values must exist before you can invoke them in your translation program.  To invoke a codeset, add the following code to your XSLT step in the AppEngine Transform program: <TYPE> <psft_function name=”codeset” codesetname=”TYPES”> <parm name=”TYPE”><xsl:value-of select=”COURSE_TYPE”/></parm> <value name=”RET_TYPE” select=”.”/> </psft_function? </TYPE> Integration Tools March 2003 Page 39 of 42

 Filtering  To properly filter out a message, the Transformation Engine must see two things when leaving a step:  The Status flag on the TransformData object must be set to 1.  The XmlDoc object must contain one node with its value containing the reason for failing the filter. For standard reasons, it is recommended to call this root node “Filter”.

Integration Tools

March 2003

Page 40 of 42

Messaging with Third Parties
 For third party integration, you will probably use the JMS or HTTP connectors.  The FILEOUTPUT connector is used to output your message to a flat file.  PeopleSoft supplies a utility to test sending message to third parties – Send Master.  The Input File project enables you to test servers that are expecting XML data over HTTP(S).  The Integration Broker project type also enables you to test servers that are expecting MIME data in PeopleSoft format over HTTP(S). To Test… …use this project type in Send Master Using Integration Broker to send Integration Broker PeopleSoft 8.4 message to: • Other PeopleSoft 8.4 systems (cross-node communication) • Remote PeopleSoft gateways Connector introspection Integration Broker Communication to an Integration Input File or Integration Broker Gateway via connectors: Use an Input File project to communicate to the • 3rd-party systems Integration Gateway by a connector that is expecting XML • PeopleSoft 8.1 systems (for example, the HTTP Listening or the 8.1 Listening Connector). Use an Integration Broker project to pass information to the PeopleSoft Listening Connector. Input File Input File Integration Broker Input File or Integration Broker. Use an Input File project to communicate to the Integration Gateway by a connector that is expecting XML (for example, the HTTP Listening or the 8.1 Listening Connector). Use an Integration Broker project to pass information to the PeopleSoft Listening Connector. Input File

Communications from a PeopleSoft 8.1 system to a PeopleSoft 8.4 system Sending SOAP (Simple Object Access Protocol) 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 Integration Tools

March 2003

Page 41 of 42

Integration Tools

March 2003

Page 42 of 42

Sign up to vote on this title
UsefulNot useful