How the connector works

This section describes:

Interacting with the PeopleSoft application

At startup, the connector creates a session object through which it connects to the PeopleSoft Application Server. Connecting to the Application Server gives the connector access to the APIs for all the Component Interfaces that correspond to its supported business objects. The server also provides access to the PeopleCode and the Application Designer objects included with the adapter for event notification.

Each Component Interface (and its associated Business Component, Records, Fields, Scrolls, and PeopleCode) contains all the information required by the connector to process a hierarchical WebSphere business object for PeopleSoft. Because each Component Interface encapsulates its Business Component's data and processing logic, the connector does not replicate this processing logic. For example, the connector need not explicitly handle duplicate record checks, edit-table validations, or security.

If an error occurs within the connector or during its online processing within the PeopleSoft application, the connector's application-specific component sends the FAIL return code to the connector framework, which sends it to the integration broker. If the connector loses its connection to the Application Server, the connector's application-specific component sends the return code of APPRESPONSETIMEOUT, and then the terminate() method is invoked on it.

For information on how the connector processes data in a business object, see Understanding business objects for the connector

Processing business object requests

When the connector receives a business object request to change data in the application, the connector processes hierarchical business objects recursively. In other words, the connector processes each child business object until it has processed data for all levels in the Component Interface associated with the business object.

When processing a business object request from the integration broker, the connector calls PeopleSoft APIs from the session object in the following order:

  1. The connector uses the getComponent("ciName") method to return the Component Interface associated with the business object. The Component Interface's name is stored in the application-specific information property at the business-object level of each business object.
  2. If the business object requests data creation or modification, the connector inserts or changes values in the application. If the business object requests data retrieval, the connector obtains values from the application.

    For information on how the connector processes data in a business object, see Understanding business objects for the connector. For information on connector-specific properties, see Appendix B. Connector specific properties.

  3. After processing a Create or Update request for an entire business object, including all its child business objects, the connector invokes the Component Interface's Save() method. If successful, the Save() method executes a single COMMIT statement. If the business object's application-specific information defines setInteractiveMode as false, invoking the Save() method triggers all FieldEdit business logic associated with the records and fields of the underlying component. All PeopleCode errors are published to the PSMessage collection queue.
  4. If the PeopleSoft system generates the unique identifiers (IDs) during a Create request, the connector uses standard PeopleSoft auto-numbering functionality (that is, built-in functions) to retrieve the most recently used ID, and populate the business object with a new one.
  5. The connector's processing uses all the business logic that is provided in the associated Component Interface.

If a connection error is detected when the connector is processing a business object request, the connector's application-specific component logs a fatal error and sends the return code of APPRESPONSETIMEOUT to trigger email notification. The connector is then terminated.

The following sections describe request verb processing:

Processing create requests

When the integration broker sends a business object request with the Create verb, the connector uses PeopleSoft's Create() method to create a new instance of the Component Interface. If the instance passes all PeopleSoft business logic as the transaction proceeds, it is saved in the application. The object created in the application contains all values contained in the business object, including all child business objects.

For more information about processing a create operation, see Create operations.

Processing retrieve requests

When the integration broker sends a business object request with the Retrieve verb, the connector uses PeopleSoft's Get() method to verify that a unique instance of the corresponding Component Interface exists. This Get() method instantiates the Component Interface, allowing the connector to load its values into the business object. The business object that the connector returns to the integration broker exactly matches the instance of the Component Interface.

In other words, the value of each simple attribute of the business object returned to the integration broker matches the value of the corresponding Property Field in the Component Interface. Also, if the returned business object is hierarchical, the number of individual business objects in each of its arrays matches the number of levels or collections in the Component Interface for that array.

For more information about processing a retrieve operation, see Retrieve operations.

Processing update requests

When the integration broker sends a business object request with the Update verb, the connector modifies an existing instance of the Component Interface. If the instance passes all PeopleSoft business logic as the transaction proceeds, it is saved in the application.

The object updated in the application exactly matches the request business object. The connector updates all simple Property Fields except those whose corresponding attribute in the request business object contain the value CxIgnore. It inserts all child business objects contained in the request business object. Depending on the value of its KeepRelationship application-specific information parameter, the connector either deletes or retains child business objects that do not exist in the request business object.

For more information about processing an update operation, see Update operations.

Processing delete requests

Because PeopleSoft does not support deletion of transactions, the connector does not either. The standard behavior for processing a logical delete is to use the Update verb to change the status of the business object's EffectiveStatus attribute to "I" (Inactive).

However, to cause the connector to support a delete of an entire object, do the following:

  1. Create a user-defined PeopleCode method that performs deletion within PeopleSoft.
  2. Expose the method through the appropriate Component Interface.

Processing application events

Event notification involves three main processes:

Event publication

To publish events to the connector's event table, the PeopleSoft application uses PeopleCode and Application Designer objects included with the adapter. For information about these objects, see Event-processing components.

The event publication process uses eithe the cw_publish_event() or the cw_publish_future_dated_event()function, which are stored in the FieldFormula event of the FUNCLIB_CW record. You must declare and call one of these functions from the SavePostChg() PeopleCode of the component involved in the event.

Note:
This procedure does not use a Component Interface.

For more information, see cw_publish_event() and cw_publish_future_dated_events() Functions.

Event polling

The connector polls the event table at a regular, configurable interval. It searches for events first by status, then by the value of the connector property ConnectorID. If this value is null or blank, the property will not be used for the search. When the connector processes an event, it immediately updates the status to INPROGRESS (a value of 3). Any pending INPROGRESS events are reset to READYFORPOLL (a value of 0) during the connector's initialization.

The connector uses the CW_EVENT_CI Component Interface's Find() method to poll the event table. This method returns a Collection of events with the status READYFORPOLL. The connector loops through the Collection, obtaining the name of every business object listed in the CW_EVENT_TBL.

The connector uses the API to set and get property values, gathering event information for each event returned in the Collection. The connector checks to determine which business objects are subscribed. For subscription information specific to your integration broker, see the broker's implementation guide.

For more information, see Event and archive tables.

Event archiving

While the CW_EVENT_CI Component Interface is instantiated, the connector calls the cw_archive_events() user-defined method for each event it processes. This method, which is in the form of PeopleCode, sets the Archive flag to Y. Setting this flag causes the SavePostChg() PeopleCode to archive the event when the user invokes the Save() method. The archive table also records the date and time the event was processed.

Note:
The SavePostChg() PeopleCode is included with the Project.

You can use the archive table to query for event history or to troubleshoot problems in event processing. For example, all unsubscribed events have a status of unsubscribed.

Because there are potential failure points associated with the processing of events, the event management process does not delete an event from the event table until it has been inserted into the archive table.

Event notification process flow

The following steps describe the event notification process:

  1. When a user saves a change online in a Component, the SavePostChg() method calls either the cw_publish_event() function or the cw_publish_future_dated_events() function.
  2. The cw_publish_event() function, which has four parameters, does the following:
    Note:
    The cw_publish_future_dated_events() function performs similarly to the cw_publish_event()function, except that it uses an additional parameter. Use this function if you want to pass the any date attribute (usually the effective date) of the component being saved so that events with future dates are polled only when the date arrives. If the effective date is in the future, the event status is set to 99 and the event date is set to the future date. If not, the status is set to 0 and the date is set to the system date.

    For more information, see cw_publish_event() and cw_publish_future_dated_events() Functions.

  3. The connector polls the event table for events at the interval specified by its PollFrequency configuration property, picking up no more than the number of events specified by its PollQuantity configuration property. To do the polling, the connector instantiates the CW_EVENT_CI Component and invokes the Find() method.
    Note:
    The connector uses a different thread from the one used for request processing.
  4. For each record retrieved from the event table, the connector checks whether it subscribes to the event data.

    If the data is not subscribed, the connector moves the event record from CW_EVENT_TBL to CW_ARCHIVE_TBL with a status of unsubscribed.

  5. If the data is subscribed, the connector uses the event record's key fields to instantiate the appropriate Component Interface, from which it retrieves complete data for the event.
  6. After retrieving complete event data from the Component Interface, the connector instantiates the appropriate application-specific business object.
  7. The connector sends the application-specific business object to the integration broker.
  8. The connector calls the cw_archive_events() function, which sets the Archive flag to Y and sets the status and processing time appropriately. Setting the Archive flag causes the SavePostChg() PeopleCode to copy the event information to the archive table and delete the event from the event table.

Processing locale-dependent data

The connector has been internationalized so that it can support double-byte character sets, and deliver message text in the specified language. When the connector transfers data from a location that uses one character code to a location that uses a different code set, it performs character conversion to preserve the meaning of the data.

The Java runtime environment within the Java Virtual Machine (JVM) represents data in the Unicode character code set. Unicode contains encodings for characters in most known character code sets (both single-byte and multibyte). Most components in the WebSphere business integration system are written in Java. Therefore, when data is transferred between most integration components, there is no need for character conversion.

To log error and informational messages in the appropriate language and for the appropriate country or territory, configure the Locale standard configuration property for your environment. For more information on configuration properties, See Appendix A. Standard configuration properties for connectors.

Copyright IBM Corp. 1997, 2004