Integration Tools: Component Interfaces

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.

 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.

 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.

•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.

•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.

 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

 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;

 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.

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

 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
 Your compiler, configured for the C++ project
 Client Setup:
1. Install the PeopleSoft Server.
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
 Client Setup:
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)

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

 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.

 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.
File Record ID 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.
ID Start Position The column or starting position in the File Record where the File
Record ID starts.
ID Length 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.
Default Qualifier 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.
File Delimiter 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.
Record Tag For File Layouts of type XML, the XML Tag Name for this File
Record. This defaults to the File Record name.
Record Description A description of the record. This is for documentation purposes
only.

 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.

 Previewing Data
The following table shows some examples of input data errors:

Symptom Possible Reason Solution
The preview grid does The input file’s format does not Change the file layout to
not appear. match the file layout format you match the input format.
specified in the File Layout
Definition Properties dialog box.
A CSV file doesn’t use the Change the definition
definition qualifier you specified in qualifier to match the one
the File Layout Definition used in the input file.
Properties dialog box.
Only the first column A CSV file doesn’t use the Change the definition
of the preview grid is definition delimiter you specified in delimiter to match the one
populated. the File Layout Definition used in the input file.
Properties dialog box.
The preview grid The file’s record IDs for the Specify file record Ids that
appears for some missing records don’t match their match the input file records.
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 Increase the field length to
appears truncated in you specified in the File Layout accommodate the input data.
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 Decrease the start position
in the middle of the position you specified in the File and adjust the field length to
data. Layout Field Properties dialog box match the input data start
is too great to include the start of position and length.
the field data.

 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.

 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 Specify the name, and optionally, the path, of the file you want to open.
 mode A string indicating the manner in which you want to access the file. The
mode can be one of the following:
Mode Description
R Read mode: opens the file for reading, starting at the beginning
W Write mode: opens the file for writing. When you specify Write mode, any
existing content in the file is discarded and will be overwritten.

A Append mode: opens the file for reading or writing, starting at the end. Any
existing content is retained.
U 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.
E Conditional “exist” read mode: opens the file for reading only if it exists,
starting at the beginning.
N Conditional “new” write mode: opens the file for writing, only if it doesn’t
already exist.
 charset 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”.
 pathtype 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.

 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.

/********************************************************
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;

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.

 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.

 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.

 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.

 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:

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

 PeopleCode action
 Codeset repository
 Advanced administrative elements:
 Relationship definition
 Transaction modifier
 Advanced message routing:
 OnRoute Send
 OnRoute Receive
 Transaction Process Flow
Transaction Type Actions

Outbound Asynchronous 1. Your application generates and sends a request message.
2. One or more target nodes receive and process the request
message.
Outbound Synchronous 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.
Inbound Asynchronous 1. A source node generates and sends a request message.
2. Your application receives and processes the request
message.
Inbound Synchronous 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.
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.

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

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.

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

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.

 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>

 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”.

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:
• 3rd-party systems Use an Input File project to communicate to the
• PeopleSoft 8.1 systems 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.
Communications from a PeopleSoft Input File
8.1 system to a PeopleSoft 8.4
system
Sending SOAP (Simple Object Input File
Access Protocol) messages to a
PeopleSoft 8.4 system
Target connectors that sit on the Integration Broker
Integration Gateway
Listening connectors that use Input File or Integration Broker.
HTTP(S) to communicate
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.
Communications from a third-party Input File
system to Integration Broker


Integration Tools: Component Interfaces

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Integration Tools: Component Interfaces

Enviado por

Direitos autorais:

Formatos disponíveis

Integration Tools

Component Interface Architecture

Integration Tools March 2003 Page 1 of 42

Integration Tools March 2003 Page 2 of 42

Integration Tools March 2003 Page 3 of 42

 Elements of a Component Interface

Integration Tools March 2003 Page 4 of 42

Integration Tools March 2003 Page 5 of 42

Integration Tools March 2003 Page 6 of 42

 Setting Component Interface Security

 Component Interface Tester

 Implementing a Component Interface

Integration Tools March 2003 Page 7 of 42

 Create a new instance of data

Integration Tools March 2003 Page 8 of 42

 Activating the Component Interface

Integration Tools March 2003 Page 9 of 42

 Building PeopleSoft APIs

Integration Tools March 2003 Page 10 of 42

Integration Tools March 2003 Page 11 of 42

 Data may be imported by combining different technologies:

Integration Tools March 2003 Page 12 of 42

Integration Tools March 2003 Page 13 of 42

Warning: Any inbound or outbound data will be truncated beyond

Integration Tools March 2003 Page 14 of 42

 Including and Excluding Fields

Integration Tools March 2003 Page 15 of 42

The following table shows some examples of input data errors:

Integration Tools March 2003 Page 16 of 42

Integration Tools March 2003 Page 18 of 42

 GetFile(filespec, mode [, charset] [, pathtype])

Integration Tools March 2003 Page 19 of 42

If you don’t specify a path, the file is assumed to be in one of two

 Reading from a File

 Handling File Errors

Integration Tools March 2003 Page 20 of 42

Integration Tools March 2003 Page 21 of 42

&SQL1 = CreateSQL(“%SelectAll(:1) where DURATION_DAYS > 10”,

Integration Tools March 2003 Page 22 of 42

 PeopleSoft’s Integration Broker is comprised of four key elements

Integration Tools March 2003 Page 23 of 42

 Supports both bi-directional synchronous and asynchronous messaging.

 Some of the Enterprise Integrations Points using Application Messaging in PeopleSoft 8:

 Component Interface technology is used in PeopleSoft 8 to address API-based synchronous

Integration Tools March 2003 Page 24 of 42

 Examples of how file processing can be used:

 Enable you to perform component-based, real-time integration from PeopleSoft to external

 Should be used for synchronous messages with dynamic parameters.

Enterprise Integration Points (EIPs)

Integration Tools March 2003 Page 25 of 42

Integration Tools March 2003 Page 26 of 42

 Integration Broker Engine

 Elements of Basic Integration

Integration Tools March 2003 Page 27 of 42

 Elements of Advanced Integration

Integration Tools March 2003 Page 28 of 42

 Transaction Process Flow

Transaction Type Actions

Integration Tools March 2003 Page 29 of 42

Integration Tools March 2003 Page 34 of 42

For the Overview page, additional filtering options are available:

Integration Tools March 2003 Page 35 of 42

more tab options here?