Enabling the application for the connector

Before you can use the connector with your PeopleSoft application, you must:

This section describes:

Installation operations required to process application events

This section describes required operations that must be performed when you use the connector to process application events. Perform this installation before you use the connector for the first time.

Installing event-processing components involves the following processes:

Importing the project

  1. Run the file that unzips the Application Designer project files into the designated folder. From the %ProductDirS%\connectors\PeopleSoft\dependencies directory, select the EventNotificationInstall.exe file.
    Note:
    This file is available only on Windows.

    Running this file with the default values creates a Projects directory within the dependencies directory. The directory contains two projects. Use one of the two projects based on the version of PeopleTools that you are using:

  2. Open PeopleSoft's Application Designer and select: Copy Project From File... or Copy From File: Select Project... from the File menu.
  3. In the menu that appears, select the import directory into which the project was unzipped. Figure 2 illustrates the screen as it appears in some versions of PeopleTools.
    Figure 2. Importing the project
  4. Click Copy and verify the list of components with those listed in Event-processing components.
Note:
If you are using the database event DB2, you must change the datatype for the field CW_EVENT_NOT from a character to a number, and ensure that the size is 15

Building required objects

To build the event and archive tables and the function library:

  1. Build the tables by selecting Project... from the Build menu.
  2. In the dialog box that appears, verify that the CW_EVENT_TBL, FUNCLIB_CW and CW_ARCHIVE_TBL appear as illustrated in Figure 3.
    Figure 3. Building the tables
  3. Select the build options "Create Tables" and "Execute SQL now". Also, click the Settings button and, in the window that displays, verify that "create table if it already exists" and "recreate index if it already exists" are selected.
  4. Click Build.
  5. Log on to a SQL editor using an ID with appropriate database privileges. The default ID is SYSADM/SYSADM.Initialize the CW_EVENT_NOT Field on the FUNCLIB_CW Record with a value of zero. To do so, run the following statement:
    INSERT INTO PS_FUNCLIB_CW (CW_EVENT_NOT) VALUES ('0');

Building the API files

To build the CW_EVENT_CI API files (required when the connector processes only events) or the Component Interface API files (required when the connector processes both events and requests):

  1. Open the Component Interface CW_EVENT_CI from the project window and select PeopleSoft APIs from the Build menu.
  2. In the Java Classes panel:
  3. From the "Select APIs to Build:" field, select CWEVENT_CI and its associated collection. Figure 4 illustrates the screen within PeopleSoft.
    Figure 4. Building APIs
  4. Click OK.
  5. Compile any API files that you generate, and add them to PSFTCI.jar (if it exists) or create this file if it does not exist.
    Note:
    The start script or batch file is configured to search for these API files in a file named PSFTCI.jar in the \connectors\PeopleSoft\dependencies directory. After you compile these API classes, make a jar file that you name PSFTCI.jar. If you put this jar file in a different directory, change the start script or batch file to point to the correct location of these API classes.
  6. Place the cw_publish_events() function declaration and function call in the SavePostChg() PeopleCode for each Component associated with an event. For more information, see Sample PeopleCode declarations and function calls.
    Note:
    The function must be placed in the SavePostChg() of the Component and not of the Record.
  7. Define all parameters used in the function call and insert PeopleCode to check whether the Component has changed before making the function call. This code eliminates unnecessary calls to the function. Also add a check for %userid to prevent the connector from ping-ponging (that is, creating an endless loop in which the connector interprets a data change from a request as a new application event). For an example, see Sample PeopleCode declarations and function calls.

Code for processing application events

The adapter includes the cw_publish_event() function and the cw_publish_future_dated_events()function in the FUNCLIB_CW function library. These functions perform similarly to insert events into the connector's event table. The difference between them is that cw_publish_future_dated_events()enables publishing events with a future effective-date to the event table, and cw_publish_event() does not. If you use events with a future-effective date, use the cw_publish_future_dated_events()function.

This section describes the functions and provides an example of the code that calls them.

cw_publish_event() and cw_publish_future_dated_events() Functions

The cw_publish_event() function takes four parameters, and the cw_publish_future_dated_events() function takes five parameters:

Important:
You must define these parameters, in proper form, before or during the function call.

Using the values specified for its parameters and the information currently available in the Component Buffer, the function gathers the required information from the Component and inserts the event in the event table. The function performs the following:

Sample PeopleCode declarations and function calls

This section provides examples of the PeopleCode declarations and function calls for each of the two functions. Based on the function you use, insert one of the following code examples into the PeopleCode editor.

Before making the actual function call, use a simple logic test to verify that the Record or Component actually changed. If it did not change, the connector does not call the function, which enhances performance. Also verify that the %userid is not CW. Doing so prevents the connector from interpreting a data change from a request as a new application event.

Code example for cw_publish_event:

/* Place this code in Component's SavePostChg() and define the four */
/* parameters used in the function call */

Declare Function cw_publish_event PeopleCode FUNCLIB_CW.CW_EVENT_NOT 
 FieldFormula; 
Component String &BONAME1;
Component STring &KEYLIST1;
Component String &CWPRIORITY1;
Component String &CONNID1;

   &BONAME1 ="Psft_Dept";
   &KEYLIST1 = "DEPT_TBL.SetId:DEPT_TBL.DeptId";
   &CWPRIORITY = 2;
   &CONNID1 ="PeopleSoftConnector";

/* Check if Component Changed before calling function */
If ComponentChanged() and
    %userid <> "CW" then

   /* Publish this event to the IBM WebSphere 
   CW_EVENT_TBL for polling */
   
   cw_publish_event(&BONAME1,&KEYLIST1,&CWPRIORITY1,&CONNID1);
   
End-if;

Code example for cw_publish_future_dated events:

/* Place this code in Component's SavePostChg() and define the four */
/* parameters used in the function call */

Declare Function cw_publish_future_dated_events PeopleCode FUNCLIB_CW.CW_EVENT_NOT 
 FieldFormula; 
Component String &BONAME1;
Component STring &KEYLIST1;
Component String &CWPRIORITY1;
Component String &CONNID1;
Component String &EFFDATE;

   &BONAME1 ="psft_CW_TEST_CI";
   &KEYLIST1 = "CW_PARENT_TBL.CW_PARENT_KEY1";
   &CWPRIORITY = 2;
   &CONNID1 ="PeopleSoftConnector";
   &EFFDATE = CW_PARENT_TBL.CW_PARENT_DTTM";

/* Check if Component Changed before calling function */
If ComponentChanged() and
    %userid <> "CW" then

   /* Publish this event to the IBM WebSphere 
   CW_EVENT_TBL for polling */
   
   cw_publish_future_dated_events(&BONAME1,&KEYLIST1,&CWPRIORITY1,&CONNID1,
&EFFDATE);
   
End-if;

Event and archive tables

The connector uses the event table to poll events for pickup. For each event, the connector gets the business object's name, verb, and key from the event table. The connector uses this information to retrieve the entire entity from the application. If the entity was changed after the event was first logged, the connector gets the initial event and all subsequent changes. In other words, if an entity is created and updated before the connector gets it from the event table, the connector gets both data changes in the single retrieval.

The following three outcomes are possible for each event processed by a connector:

If events are not deleted from the event table after the connector picks them up, they occupy unnecessary space there. However, if they are deleted, all events that are not processed are lost and event-processing cannot be audited. Therefore, the adapter provides the archive table to store events deleted from the event table.

Table 3 describes the columns in the event and archive tables.

Table 3. Event and archive table schema
Name Description Type Constraint
CW_EVENT_ID Internal identifier of the event A unique key field that identifies each event generated from within PeopleSoft NUMBER Primary key
CW_CONNECTOR_ID Unique ID of the connector for which the event is destined. This value is important when multiple connectors poll the same table. VARCHAR
CW_OBJ_KEYS Keys of the business object, specified in name-value format. When defining parameters for a function call (such as cw_publish_events), the name consists of the table name and field name separated by a period. Multiple keys are separated with a colon or other configurable delimiter, for example: DEPT_TBL.SetId:DEPT_TBL.DeptIdFor more information, see EventKeyDelimiter. VARCHAR Not null
CW_OBJ Name of the business object VARCHAR Not null
CW_VERB Verb associated with the event. A PeopleCode function included with the adapter determines the value (Create, Retrieve, Update, Delete) based upon the %Mode system variable used by PeopleSoft VARCHAR Not null
CW_PRIORITY Not used.
CW_DTTM Date and time the event or archiving occurred STRING Default current date/time (for archive table, actual event time). PeopleSoft treats the datatype for DATE fields as STRING and returns the same.
CW_STATUS -2 (Error sending event to integration broker) VARCHAR Not null
-1 (Error processing event)
0 (Ready for poll)
1 (Sent to integration broker)
2 (No Subscriptions for the business object)
3 (In Progress) This status is used only in the event table and not in the archive table.
99 (Future effective-dated events) This status is used only in the event table and not in the archive table.

Copyright IBM Corp. 1997, 2004