2.3 Installing the PSA Sample Project

Complete the following tasks to install the sample project for testing and configuration purposes:

2.3.1 Installing the PSA Files

If you did not install the PSA during the initial driver installation, locate the product CD or download, go to the PeopleSoft application server, and run install.exe. You should see the following PSA files on your target server:

  • DIRXML_PSA50_TOOLS81.exe

  • DIRXML_PSA50_TOOLS84.exe

These files are self-extracting zip files that contain the PSA project folder and files for the respective 8.1 x and 8.4 x versions of PeopleTools. Extract the appropriate file onto the file system of your PeopleSoft Application Designer host ( c:\psa). Use the DIRXML_PSA50_TOOLS81.EXE file for 8.2 x PeopleTools deployments.

To ensure that the PSA can be imported into the PeopleSoft Application server, make sure that the PSA files have write access enabled. For example, in Windows*, you should turn off read-only file properties.

2.3.2 Importing the PSA Project into the PeopleSoft Database

After the PSA files have been installed in an accessible file system location, they must be imported into the PeopleSoft Database via the PeopleSoft Application Designer tool.

For PeopleSoft 8.1 x and 8.2 x

  1. Connect to the PeopleSoft database as administrator in two tier mode.

  2. In the Application Designer, select File > Copy Project From File.

  3. Click Browse, then select the PSA project directory: c:\psa\psa-psa8.

  4. Click Open.

  5. With all object types selected, click Copy to copy all project components into the PeopleSoft database.

For PeopleSoft 8.4 x

  1. Connect to the PeopleSoft database as administrator in two tier mode.

  2. In the Application Designer, select Tools > Copy Files> From File.

  3. Click Browse and select the PSA project directory: c:\psa\DIRXML_PSA50_TOOLS84.

  4. Click Open.

  5. With all object types selected, click Copy to copy all project components into the PeopleSoft database.

2.3.3 Building Project Record Definitions

After you have imported the project into the PeopleSoft database, you should build project record definitions and project views.

  1. Log in to PeopleSoft Application Designer using an administrator username that has administrative and development rights.

  2. In the Application Designer, select Build > Project.

  3. From Build Options, click Create Tables and Execute SQL Now. After project tables are created, click Close to close the Build Progress window.

  4. Click Build to create sample project tables.

    You must create project tables before creating the views. Views are created using information from table fields.

  5. In the Application Designer, select Build > Project.

  6. In Build Options, click Create Views and Execute SQL Now.

  7. Click Build to create the sample project views. After views are created, click Close to close the Build Progress window.

2.3.4 Applying Security to the PSA

In order for the driver to access PeopleSoft transaction tables, you need to apply security to the PSA. You accomplish this by creating the DirXML Administrator role and then assigning it to the administrative user. You can assign the role to an existing account or create a new account specifically for PSA security.

For PeopleSoft 8.1 x and 8.2 x

  1. In the Application Designer, click Go > PeopleTools > Maintain Security.

  2. Click Use > Roles > General > Add.

  3. In the Add Role field, type DirXML Administration, then click OK.

  4. In the Description field, type DirXML Administration.

  5. Click the Permission Lists tab, then click the drop-down arrow.

  6. For the Permission List value, type DirXML, then click OK.

    The Description field populates automatically.

  7. Click Save.

  8. Click Use > User Profiles > General > Update/Display.

  9. Type your administrative user username as the User ID, then click OK.

  10. Click the Roles tab, then click in the last row to add data.

  11. Add the DirXML Administration 4 role to this user, then click Save.

  12. Close and restart the PeopleSoft clients and applications.

For PeopleSoft 8.4

  1. Log in to the PeopleSoft portal.

  2. Click PeopleTools > Security > Permissions & Roles > Roles.

  3. Click Add a New Value, then specify a role name (for example, DirXML Administrator).

  4. Type a description for the role.

  5. (Optional) Type a long description for the role.

  6. Click the Permissions List tab.

  7. Search for and select the DirXML® permissions list, then click Save.

  8. Assign DirXML Administrator role to your administrative user by clicking PeopleTools > Security > User Profiles > User Profiles.

  9. Click Search to locate the User Profile that you want to add the DirXML Administrator role to, then click the User ID.

  10. Click the Roles tab, then click one of the “+” buttons to add a new role.

  11. Search and select the role, click DirXML Administrator to add it, then click Save.

2.3.5 Understanding the Architecture of the PSA Sample Project

The PSA Sample project is intended to provide recommended PeopleSoft integration scenarios through the use of very comprehensive direction and examples. The various elements of the PSA are completely independent of any existing PeopleSoft application software, so there is no risk of data table corruption, extension, or modification.

The objects of the PSA include:

  • Field definitions

  • Record definitions

  • Page definitions

  • Component definitions

  • Component Interface definitions

  • Menu definitions

  • SQL code

All of these objects are named with a prefix of DIRXML_ so that they cannot be confused with existing objects.

Sample Application

This application is intended to simulate the data and functions of an HR or other type of Person provisioning application. The base Record definitions for the application are:

  • DIRXML_S_PERS: Provides basic HR field data

  • DIRXML_S_DEPT: Sample Department codes table

  • DIRXML_S_PHONES: Phone Numbers table

The data is accessed using the DIRXML_ADMINISTRATOR menu options. The menu provides access to a DirXML Sample People component and a DirXML Sample Department component. These applications simulate the standard methods for adding and updating Department and Person data into the PeopleSoft database. The driver default configuration does not directly access any of these tables or components. Additionally, the data provided by this application is not passed directly to the driver from these components. The actual transfer of data takes place through staging table components.

Staging Table

The staging table interface is designed to insulate the PeopleSoft Application data from direct manipulation by the driver. This allows an interface to be designed to:

  • Combine access to the data from multiple data tables and applications through a single interface.

  • Prevent the driver from viewing or modifying sensitive application data.

  • Provide storage for external data that does not easily fit into standard PeopleSoft applications.

The Record definition that represents all of the data that can be published or subscribed by the driver is called DIRXML_STAGE01. This record aggregates most of the data fields from the three Application data records into a single access point. There are also additional fields not in the Application records that are used to contain references to the synchronized eDirectory objects.

For PeopleSoft users, the data in the staging table can be accessed via the DirXML Schema 01 component of the DIRXML_ADMINISTRATOR menu. The driver accesses the data via the DIRXML_SCHEMA01 Component Interface.

Transaction Table

Every time a modification is made to the Application Data Records, transaction records are placed in the DIRXML_TRANS01 table. The PSA places identifiers indicating the key of the data row being modified, the time of the event, the type of event, and various other pieces of transaction related data. Any change made to a data row via the DIRXML_ADMINISTRATOR application interfaces is recorded with an NPSDriver1P identifier that shows the data is being published by a PeopleSoft administrator. Changes made via the Component Interface API are recorded with an NPSDriver1S identifier that shows the data was subscribed into the application tables programmatically.

In addition to providing an audit trail of database modifications, the transaction table is utilized by the driver to facilitate Publisher channel activities. The driver polls the transaction table for records in the Available state, reads the related application data record, and processes the data through the Publisher channel. The transaction records are then updated with the processing status.

In addition to the transaction tables and interfaces, the PSA includes utilities to monitor, maintain, archive, and remove transaction records.

PSA Best Practices

Data moves between the various PeopleSoft Components and tables through PeopleCode. Each of the application data records in the PSA contains PeopleCode that performs the basic functions of moving data between the Staging table and Application tables, ensuring the integrity of the data and data transfers, and generating Transaction table records at the appropriate time and with the appropriate data. PeopleCode is very powerful and is capable of performing a wide variety of tasks, some of which are potentially destructive to your data.

IMPORTANT:Only personnel who have completed PeopleTools and PeopleCode training should modify the elements of the PSA.

These guidelines might prove helpful when implementing changes to the PSA.

  • Whenever possible, always provide a Component Interface to affected data tables. In the PSA, the DIRXML_S_PERS data rows are created and updated with PeopleCode via the DIRXML_TST_PERS Component Interface. The Component Interface guarantees the integrity of the data as defined by the designer of the application. It ensures valid Translate values, proper data format, required fields are present. Most importantly, the Component Interface can restrict the data fields that can be accessed on a particular record or record set. This is a very important aspect of data security.

  • The DIRXML_SCHEMA01 Component Interface has been extended with a Delete method that enables removal of data schema records via the driver’s Subscriber channel. Use of this functionality is not required. The method can be removed from the CI or the driver can be configured to not use it.

  • Make sure that the staging table record contains the same required fields that exist on the target Application records. This helps ensure successful record data synchronization.

  • It is important to generate transactions whenever the application data table records are created or updated, even if the changes are made by the driver. Although data loopback can occur, the generation process ensures that Translate table values and related field values generated by the changes are properly synchronized.

  • If you are using SQLExec() statements to update tables or create records, use great care to ensure that you are not violating the logic and rules of the applications overlying the tables. SQL is the easiest and most powerful, and therefore most destructive, method for updating data.

  • Do not generate Transaction records until after you have successfully updated the application tables.

  • If desired, it is possible to completely bypass the staging table interface in your synchronization scenario. The driver can be directed to interact with any Component Interface. Make sure that the PeopleCode generating the transaction records is updated to specify the new Application data CI and is triggered appropriately. Also ensure that the same CI methods are implemented and enabled.

  • The driver is delivered with a Java archive (JAR) file that contains the compiled Java interfaces for all of the Component Interfaces defined in the PSA. If the driver is to be configured to use different application CIs, it is necessary to build and JAR those interfaces. For more information, refer to Section 3.0, Installing and Configuring the Driver.

  • Test everything thoroughly.

2.3.6 Testing Sample PeopleSoft Applications

You can test to ensure that transactions are created by entering a new person using the PeopleSoft Identity Manager sample application. This example uses Departments, so you need to create a sample department and then add a person (assigning him or her to that department) to validate that the application works. The following information explains how to test your sample applications.

For PeopleSoft 8.1 x and 8.2 x

  1. In the Application Designer, select Go > DirXML Administrator.

  2. In the DirXML Administrator menu, select Use > DirXML Sample Department.

  3. Click an empty Department field row to add sample department and description values.

  4. Click Save to add the Department.

  5. From the DirXML Administrator menu, select Use > DirXML Sample People > Add.

  6. Type data into the various fields for the new person, then click Save.

    Asterisks represent required fields.

  7. Verify that an ADD transaction was created by selecting Use > DirXML Transaction 01.

  8. Click the Search button.

  9. Verify that the transaction was created and select the transaction.

    DirXML Transaction01

  10. Click Use > DirXML Schema 01 > DirXML Schema01A.

  11. Verify the Schema data on the first tab ( Schema 01 A).

  12. Verify that you can update the fields on the second tab ( DirXML Schema 01 B).

  13. Click Use > DirXML Trans by Associations and verify that you can view the data.

    DirXML Trans by Associations

  14. Click Use > DirXML Driver Defaults and verify that you can view the sequence of transactions.

  15. Verify that other Transaction table applications work by clicking Use > DirXML Transaction 02 ( 03, 04, etc.), and DirXML Trans Maintenance.

    You can create additional transaction tables (Transaction 05, Transaction 06, and so forth.) The delivered sample application is configured to use only Transaction01.

For PeopleSoft 8.4 x

  1. Log in to the PeopleSoft portal.

  2. Click DirXML Administrator from the left menu.

    If the DirXML Administrator menu doesn’t appear, you should delete the Application Server cache and reboot the Application Server.

  3. Click DirXML Sample Department.

    DirXML Sample Department

  4. Specify a sample department, then click Save.

  5. Click DirXML Sample People.

  6. Enter values for a sample user, then click Save and verify that the user's data appears in the Transaction01 table. You do this by searching in the DirXML Transaction01 application.

  7. Verify that other delivered applications work by selecting them from the DirXML Administrator menu.