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” application object data. Schema objects represent all the necessary fields and methods that need to be exposed for data synchronization to the driver. These objects also enable the driver to update PeopleSoft data.
Each driver uses only one Transaction CI to access transactions. Every transaction is assigned to one default Schema CI. In the driver’s parameters, you must specify the Transaction 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:
Figure 2-2 Transaction Table C1
In addition to the Transaction CI name, the driver configuration contains a parameter that can specify a particular subset of the transactions that are available for processing. This allows a single Transaction CI to interface with multiple drivers, which may be synchronizing different sets of object data or different object types. This subset identifier is maintained in the DIRXML_DRIVER field of the Transaction CI.
The following figure represents the CI for a Schema Component:
Figure 2-3 Schema Component
The PeopleSoft developer can specify these values when configuring the PeopleCode function calls to trigger a transaction online, or when creating transactions via a batch process. The PSA provides PeopleCode function DirXML_Trans and is responsible for generating transaction events. The PSA contains several function calls which you may use to guide customization.
The PeopleCode DirXML_Trans schema calls should always be placed in the SavePostChange PeopleCode on the record definitions. This ensures that the data is committed prior to the transaction being generated.
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.
Use the standard ALL-CAPS format to avoid any field name issues.
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:
Figure 2-4 SQL View of 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 are 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
option after making any modifications to the SQL definition of the View Record.NOTE:Because 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.
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 Metadirectory 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 Metadirectory 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 a Transaction CI and a Schema CI to process transactions. For more information on calling the PeopleSoft function that creates transaction records, please refer to Customizing the PSA by Triggering Transactions.
The Transaction Component interface 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 object 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 (DIRXML_EVENT), which it uses to create an Add, Modify, or Delete XML document. The driver uses the Schema ID (DIRXML_SCHEMA) and the Associate ID (DIRXML_ASSOC_ID) values to access the appropriate CI Schema and appropriate record information associated with the object.
After the transaction has been processed by the Metadirectory engine, the driver updates the status of the transaction (DIRXML_STATUS) and updates the Comment field (DIRXML_DESCR) if an error or warning message is applicable.
Figure 2-5 DirXML Transaction01
The Schema Component interface 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 (DIRXML_ASSOC_ID) and Schema name (DIRXML_SCHEMA), it accesses the appropriate Schema object.
The driver also uses Schema CI as a Class identifier for object type matching. When the driver accesses the Schema CI, it uses the value it received in the Association ID (DIRXML_ASSOC_ID) as the key value to retrieve the data from the PeopleSoft environment. It also uses this CI to update PeopleSoft records.
For example, assume you want to process transactions for an employee with the DIRXML_ASSOC_ID field (key) value = P000001. The driver accesses the Schema CI with a key value of P000001. It retrieves all of the configured component elements that have been defined for that employee. The driver then converts the data collection into XML documents to be consumed by the Metadirectory engine. If there is a write-back command processed, or when data is written on the Subscriber channel, the driver uses this CI to update the staging table with the appropriate information into PeopleSoft for this particular employee.
The Component Tester program ( CITester.class) is included as part of the driver package. The program validates the proper installation, configuration, and revision of the PeopleSoft PeopleTools client software on the computer hosting the Identity Manager Driver for PeopleSoft. The program also validates a selected Transaction CI and Schema CI. Therefore, successful operation of CITester helps ensure the 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.
*If you are not using the default Schema CI, it is necessary to build the APIs for the desired CI. See Section 4.2, Changing the Driver by Changing the Data Schema Component Interface for information on building custom CI API JAR files.
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 from the PeopleTools distribution.
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 - CITester.class, psjoa.jar and dixmlcomps.jar files and any required custom CI API JAR files.
option on the Java command line to include theIt 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.
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.
If the test program establishes a session with the PeopleSoft client, you will see the following message:
** PeopleSoft client session established successfully.
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Table 2-1 Phase I Errors and Solutions
Specify the Application Server Name or IP address. Forward slashes are required when entering the Application Server Name (for example, //255.255.255.255).
Specify the Application Server “Jolt” Port Number.
Specify the PeopleSoft UserID
Specify 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.
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Table 2-2 Phase II Errors and Solutions
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 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.
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Table 2-3 Phase III Errors and Solutions
The Schema CI defines the application data that is to be synchronized via the driver. The specified Schema CI must contain a primary 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 see the following message:
** Retrieval of Schema Component Interface "DIRXML_SCHEMA01" succeeded. - Property ’ASSOC_ID’ is present and validated as key field. - Property ’STATUS’ is present. - Property ’FULL_NAME’ is present. - Property ’FIRST_NAME’ is present. - Property ’MIDDLE_NAME’ is present and validated as key field. - Property ’LAST_NAME’ is present. - Property ’BIRTH_DATE’ is present. - Property ’DEPT_ID’ is present. - Property ’DEPT_LONG_DESCR’ is present. - Property ’DEPT_DN’ is present. - Property ’TITLE_ID’ is present. - Property ’TITLE_SHORT_DESCR’ is present. - Property ’TITLE_LONG_DESCR’ is present. - Property ’MANAGER_ID’ is present. - Property ’MAIL_DROP’ is present. - Property ’ADDRESS1’ is present. - Property ’CITY’ is present. - Property ’STATE’ is present. - Property ’POSTAL’ is present. - Property ’MANAGER’ is present. - Property ’COMMON_NAME’ is present. - Property ’DISTINGUISHED_NAME’ is present. - Property ’DESCRIPTION’ is present. - Property ’EMAIL_ID’ is present. - Property ’PHONE_BUSN’ is present. - Property ’PHONE_CELL’ is present. - Property ’PHONE_HOME’ is present. - Property ’PHONE_PGR’ is present.
** Schema Component Interface element validation succeeded.
** All expected platform support is verified correct.
You might encounter the following errors during the test. Suggestions for resolving errors are provided below.
Table 2-4 Phase IV Errors and Solutions
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 : ASSOC_ID Transaction CI Name : DIRXML_TRANS01