Component Interfaces
- Accessing Transactions and Data through Component Interfaces
- Configuring the Transaction Record SQL Date/Time Format
- Configuring PeopleCode to Trigger Transactions
Accessing Transactions and Data through Component Interfaces
The driver accesses transactions waiting to be processed from the transaction table via the Component Interface (CI) object that is defined within PeopleTools. Each Component Interface maps to a particular component. Components are built in order to access transaction tables and schema data. Schema objects represent all the necessary data that needs to be exposed for a data type according to the Associated ID. These objects also enable the driver to update PeopleSoft data.
The driver uses only one Transaction CI in order to access transactions. Every transaction is assigned to one default Schema CI, although processing that is defined within a policy might request a query to other Schema CIs that are defined in the driver's Schema Mapping policy.
In the driver's parameters, you must specify the CI object name as defined in PeopleSoft. This CI object maps to a predefined component that enables the driver to access transactions from one transaction table. The following represents the CI for a transaction table:
The following figure represents the CI for a Schema Component:
The driver uses a defined parameter to determine the subtype of transactions it needs to process. As a PeopleSoft developer, you determine this value when configuring a PeopleCode function call to trigger a transaction online, or when creating a transaction via a batch process. If the parameter does not exist, the driver processes all transactions available through the CI. If the parameter exists, the driver limits processing to the transaction type specified in the subtype string.
The PeopleCode DIRXML_TRANS function calls should always be placed in the SavePostChange PeopleCode on the record definition. Also, remember to declare the function prior to calling it.
Changes to Field Names in PeopleSoft 8.41
With new releases of PeopleTools, changes are made to the policies regarding field names. With PeopleTools 8.41, there were two significant changes:
- Spaces are no longer allowed in Component Interface field names.
- There are now case sensitivity issues in the CI API. Field names and field name values no longer align because of case-sensitive sorting. For example, a field named CN is sorted prior to a field named City. The result of trying to access the value of City returns the value for CN. The default schema of the Component Interfaces used by the driver now uses naming conventions that eliminate this unusual sorting error. This issue is particularly important for any field name modifications or additions customized for a prior implementation of the driver.
Configuring the Transaction Record SQL Date/Time Format
The proper functioning of the driver depends on the Date/Time strings in the Transaction View record to determine processing availability and relative event order of Transaction data rows. The Date/Time fields in the Transaction data rows are converted to formatted strings in the Transaction Views using the PeopleCode Meta-SQL %DateTimeOut function. The following image shows the default SQL View code for the DIRXML_TRANS01V record:
Unfortunately, the format of the strings presented by %DateTimeOut might differ depending on the underlying DBMS software. To make sure a date and time string is generated in a consistently increasing lexicographic format, the following format is recommended:
- The date should be presented first in YYYY-MM-DD format.
- The time should be presented in 24-hour form with HH:MM:SS format (Additional information concatenated to this string, such as <milliseconds> is acceptable)
- These two strings should be placed together in "date-time" format.
The characters used to delimit the numerical values is not important as long as they are consistent! Examples of a well-formed, lexicographically ordered format are:
2004-08-26-14.44.33.000000 (ODBC Canonical style 121)
or
2004/08/26-14:44:33 (Generic)
The fields used by the driver are DIRXML_DTTM_ST and DIRXML_CURRDTTM_ST. These fields represent the Date/Time that the Transaction data row was created and the current processing Date/Time of the transaction.
If you are using a driver trace level of 2 or above, the driver traces the CurrDate and ActionDate of each Transaction row that it processes. If the format shown does not match the criteria specified, edit the SQL of the desired Transaction View record to perform the appropriate conversions on these fields. Make sure that you use the Build > Create Views option after making any modifications to the SQL definition of the View Record.
NOTE: Since the configuration of the Date and Time format varies depending on the DBMS being utilized, changing this format should be done by the DBMS/PeopleSoft Database Administrator or other qualified personnel.
Configuring PeopleCode to Trigger Transactions
The PSA contains a number of PeopleTools objects that enable PeopleSoft to trap events into a transaction table. The driver then accesses the transaction tables through Component Interface objects. The driver periodically requests transactions that need to be processed based on their driver subtypes. It processes only those transactions that have a transaction date or time less than or equal to the current date or time value, along with an available status. Also, the driver processes transactions one at a time from the transaction table before getting a new transaction.
The driver then constructs an XML document from the data it retrieved and passes this to the DirXML engine for processing. It updates the transaction status and any applicable messages on the transaction table inside of PeopleSoft after processing is completed by the DirXML engine. When events occur within eDirectory, the driver connects to the appropriate CI and updates the PeopleSoft staging table as appropriate.
You trigger transactions using PeopleCode within the PeopleSoft application.This document assumes that you know how to write PeopleCode. If you need further assistance, refer to PeopleSoft documentation for more information.
The driver requires the Transaction and Schema Component to process transactions. For more information on calling the PeopleSoft function that creates transaction records, please refer to Customizing the PSA by Triggering Transactions.
Transaction Component
The Transaction Component enables the driver to request transactions by driver subtype, date and time, and event type. The driver requests a single transaction for processing and obtains the association ID for the record being processed.
When the driver selects the first transaction to process, it sets the status of the transaction to In Process. The driver then retrieves the Event Name, which it uses to create an Add, Modify, or Delete XML document. The driver uses the Schema ID and the Association ID values to access the appropriate CI Schema and appropriate record information associated with the Association ID object.
After the transaction has been processed by the DirXML engine, the driver updates the status of the transaction and updates the Comment field (if an error or warning message is applicable.)
Schema Component
The Schema Component lets the driver retrieve data for a particular record and update the PeopleSoft staging table for that record. After the driver retrieves the Association ID and Schema CI name, it accesses the appropriate Schema object.
When the driver accesses the Schema Component, it uses the value it received in the Association ID and the Key value to retrieve the data from the PeopleSoft environment. It also uses this component in order to update PeopleSoft for the record owned by the Associated Key Value.
For example, assume you want to process transactions for employees with the Data Record ID field and key value = P000001.
The driver accesses the Schema Component with a key value of P000001. It retrieves all of the component elements that have been defined for that employee. The driver then converts the data collection into XML documents to be consumed by the DirXML engine. If there is a write-back command processed, or when an event is subscribed to on the Subscriber channel, the driver uses this component to update the staging table with the appropriate information into PeopleSoft for this particular employee.
When the driver creates a new object, it creates an association value that contains the Association ID. When Schema CIs are loaded by the driver, each Schema CI is treated as a schema class. The Mapping policy uses the class mapping as appropriate. This allows the driver to know what Schema object in PeopleSoft is used for any particular element, and how to update data back into PeopleSoft.
Testing Component Interfaces
The Component Tester program (CITester.class) is included as part of the download. This program ensures that your PeopleTools client software is installed and configured properly on the computer hosting the driver.
The program validates the proper installation, configuration, and revision of the PeopleSoft PeopleTools client software on the computer hosting the DirXML Driver for PeopleSoft. The program performs all of the validation procedures in the same manner as the driver. Therefore, successful operation of CITester ensures proper client functionality for the driver.
The CITester completes the following checks during four phases:
- Phase I: Ensures that a PeopleSoft client session can be created.
- Phase II: Ensures that connection and authentication parameters to the PeopleSoft Application Server are correct.
- Phase III: Verifies that the Transaction CI required fields and keys are present.
- Phase IV: Verifies that the Schema CI required fields and keys are present. *
There might be variations of the error message data depending on the PeopleTools release. The CITester program runs all platforms supporting Java 1.3.1 or later and uses the Java PeopleSoft Component Interface (PSJOA.jar) package for PeopleTools 8.4x.
*If you are not using the default Schema CI, it will be necessary to build the APIs for the desired CI. See Changing the Driver by Changing Data Schema Component Interface for information on building custom CI API JAR files.
Important Considerations
When running this test you must either:
- Set the CLASSPATH environment variable to include the path of the CITester.class, psjoa.jar and dirxmlcomps.jar files. If a custom CI API JAR files is required, include it in CLASSPATH.
- Set the -classpath option on the java command line to include the CITester.class, psjoa.jar and dixmlcomps.jar and any required custom CI API JAR files.
It is also important to note that the java.exe for JRE/JDK version 1.3.1 or later must be installed and accessible via the PATH environment variable or be explicitly called out from the java command line.
How Do I Run the Test?
From a command shell, execute the CITester.class test file. A sample CITester.bat file is provided as a reference that indicates the correct syntax and class files required to execute the test and the driver. To accept the test's default values, press Enter. In Phase II, you are required to enter a value for the Application Server Name.
The test writes output to the screen and to CITesterOutput.txt. The output file is written to the location where CITester.class resides.
Phase I: Creating a PeopleSoft Client Session
If the test program establishes a session with the PeopleSoft client, you will see the following message:
** PeopleSoft client session established successfully.
Phase I Errors
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Phase II: Authenticating to the PeopleSoft Client
-
Enter the Application Server Name or IP address. Forward slashes are required when entering the Application Server Name (for example, //255.255.255.255).
-
Enter the Application Server Port Number.
-
Enter the PeopleSoft UserID
-
Enter the PeopleSoft UserID Password.
If the test program verifies the connection and authentication parameters, you will see the following message indicating success:
** The Connection and Authentication Parameters are verified to be correct.
Phase II Errors
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Phase III: Authenticating to the PeopleSoft Client
The driver uses a Component Interface to access application modification transaction records from the Application Server. The field definitions of this interface must be identical to the DIRXML_TRANS01 Component Interface delivered with the driver. This test phase validates the field definitions of the named Transaction Component Interface.
Enter the Transaction Component Interface name or press Enter to validate DIRXML_TRANS01.
If the test program retrieves and validates that all required fields and elements are present, you will see the following message:
** Retrieval of Transaction Component Interface "DIRXML_TRANS01" succeeded.
- Property 'DIRXML_ASSOC_ID' is present.
- Property 'DIRXML_CURRDTTM' is present.
- Property 'DIRXML_DESCR' is present.
- Property 'DIRXML_DRIVER' is present and validated as key field.
- Property 'DIRXML_DTTM' is present.
- Property 'DIRXML_EVENT' is present.
- Property 'DIRXML_FIELDKEY' is present.
- Property 'DIRXML_FIELDNAME' is present.
- Property 'DIRXML_INST' is present and validated as key field.
- Property 'DIRXML_PROCESSED' is present.
- Property 'DIRXML_SCHEMA' is present.
- Property 'DIRXML_STATUS' is present.
- Property 'DIRXML_VALUE' is present.
** Transaction Component Interface element validation succeeded.
Phase III Errors
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Phase IV: Retrieving the Schema Component Interface
The Schema CI defines the application data that is to be synchronized via the driver. The specified Schema CI must contain a key field that is specified via the Data Record ID field name.
To test the Schema CI, type the Schema Component Interface name or press Enter to retrieve DIRXML_SCHEMA01. Enter the Data Record ID field name. If the test program retrieves and validates that all required fields and elements are present, you will see the following message:
** Retrieval of Schema Component Interface "DIRXML_SCHEMA01" succeeded.
- Property 'AssocID' is present.
- Property 'Status' is present.
- Property 'FullName' is present.
- Property 'FirstName' is present.
- Property 'MiddleName' is present and validated as key field.
- Property 'LastName' is present.
- Property 'BirthDate' is present.
- Property 'DeptID' is present.
- Property 'DeptLongDescr' is present.
- Property 'DeptDN' is present.
- Property 'TitleID' is present.
- Property 'TitleShortDescr' is present.
- Property 'TitleLongDescr' is present.
- Property 'ManagerID' is present.
- Property 'MailDrop' is present.
- Property 'Address1' is present.
- Property 'City' is present.
- Property 'State' is present.
- Property 'Postal' is present.
- Property 'Manager' is present.
- Property 'CommonName' is present.
- Property 'DistinguishedName' is present.
- Property 'Description' is present.
- Property 'Email' is present.
- Property 'BusinessPhone' is present.
- Property 'CellPhone' is present.
- Property 'HomePhone' is present.
- Property 'Pager' is present.** Schema Component Interface element validation succeeded.
** All expected platform support is verified correct.
Phase IV Errors
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Summary
At the completion of the test, the program provides a summary containing the results of the test. The validated parameters are shown below in the summary.
Component Interface Test Summary
--------------------------------
Full Component Interface Functionality has been verified.
The following parameters may be used for PeopleSoft 5.0 Driver Configuration
Authentication ID : PSADMIN
Authentication context : //255.255.255.255:9000
Application Password : PSADMIN
Schema CI Name : DIRXML_SCHEMA01
Data Record ID Field : AssocID
Transaction CI Name : DIRXML_TRANS01