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 project name is CW_EVENT_Vx, where Vx identifies the version number.

  2. Open PeopleSoft's Application Designer and select: Copy Project From File... from the File menu.
  3. In the menu that appears, select the import directory into which the project was unzipped. Figure 3 illustrates the screen within PeopleSoft.

    Figure 3. Importing the project


  4. Click Copy and verify the list of components with those listed in "Event-processing components".

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

    Figure 4. 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 5 illustrates the screen within PeopleSoft.

    Figure 5. 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 declaration and function call".
    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 declaration and function call".

Code for processing application events

The adapter includes the cw_publish_events() function in the FUNCLIB_CW function library. This function inserts events into the connector's event table. This section describes the function and the sample code that calls it.

cw_publish_events() Function

The cw_publish_events() function takes four parameters, all of type String:

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 declaration and function call

The adapter includes a sample of the PeopleCode declaration and function call in the savepostchg.txt file in the connector's samples directory. Replace the business object's name and keys with the correct information for your business object and then copy and paste the code directly 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.

The following code is the sample that the adapter provides:

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

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 Event priority (0 is highest, n is lowest), which the connector uses to get events on a priority basis. NUMBER Not null
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.

Copyright IBM Corp. 1997, 2003