Implementing Handlers Using Bulk Load Processing

This section provides and overview of implementing handlers using the bulk load processing and discusses how to:

  • Enable transactional rollback.

  • Enable table truncation.

  • Specify XML attributes for nonrowset-based messages.

  • Add data structures to nonrowset-based messages.

You can bulk load large amounts of data (large messages) into a local table using the bulk load handler.

Note: Bulk load handlers are allowed only on asynchronous service operations and only one bulk load handler is allowed per service operation.

When you implement a handler using a data mover script use the OnNotify event. When the OnNotify event is fired, the message data is inserted into the tables. Bulk load handlers do not perform any data validation.

Bulk Load Handler Message Types

You can use bulk load handlers for service operations that contain the following types of asynchronous messages:

  • Rowset-based messages.

    For service operations that contain rowset-based messages, the message structure determines processing.

  • Nonrowset-based messages.

    For service operations that contain nonrowset-based messages, you define the structure for processing by mapping data to PeopleSoft records and providing attribute names and values.

  • Container messages that contain rowset-based messages parts.

    For service operations with container messages that contain rowset-based message parts, the bulk load handler uses the message structure of the message parts to determine processing.

Transactional Rollback

Bulk load handler processing is destructive load processing, meaning that the handler deletes existing data from the table and then bulk inserts the new data.

PeopleSoft Integration Broker provides an optional transaction rollback feature that enables you to rollback the database to the pre-bulk insert state if needed.

Transactional rollback is dependent on the bulk size of the data to be updated. Therefore, when you select the rollback option, a Rollback Size field appears where you specify a rollback value. The default value is 32 kilobytes.

Table Truncation

By default, the bulk load handler truncates table data before performing any processing.

PeopleSoft Integration Broker enables you to disable table truncation.

Nonrowset-Based Messages and the Bulk Load Handler

If a service operation contains a nonrowset-based message, you must add a data structure to define the message content, thereby allowing non-PeopleSoft data to map to the records and fields in the database.

In addition, you can provide an XML attribute name/value pair to distinguish record and field nodes on incoming XML content.

Process Overview for Implementing Handlers Using Bulk Load Handlers

The process for implementing a bulk load handler is:

  1. Add a bulk load handler to the service operation on the target system.

    This procedure is discussed elsewhere in this topic.

    See Adding a Handler to a Service Operation.

  2. Specify general handler details.

    This procedure is discussed elsewhere in this topic.

    See Specifying General Handler Details.

  3. (Optional.) Enable transactional rollback and the rollback size.

    This procedure is discussed in this section.

  4. (Optional.) Specify XML record attributes.

    This procedure is discussed in this section.

  5. Add the data structure for the message contained in the service operation.

    The step is required only when a nonrowset-based message is contained in the service operation.

    This procedure is discussed in this section.

The Bulk Load Handler page (IB_SERVICEHDL5_SEC) features a Rollback Non-Destructive Load option that you can set to enable transaction rollback.

Image: Bulk Load Handler page

This example illlustrates the Bulk Load Handler page. The example shows the page when the service operation contains a nonrowset-based message.

Bulk Load Handler page

The previous example shows the Bulk Load Handler page that displays when the service operation contains a nonrowset-based message.

If the service operation contains a rowset-based message, the page does not display the XML attribute fields or the data tree structure controls.

Image: Bulk Load Handler page

This example illlustrates the Bulk Load Handler page. The example shows the page when the service operation contains a rowset-based message.

Bulk Load Handler page

Note: Transactional rollback is not supported if message segments are used. Transactional rollback will automatically be disabled if the message being processed contains more then one message segment.

To enable rollback processing:

  1. On the Service Operations – Handlers tab, in the Handlers section, click the Details link.

    The Bulk Load Handler page appears.

  2. Select the Rollback Non-Destructive Load check box.

    The Rollback Size field appears.

  3. In the Rollback Size field, enter a rollback size value, in kilobytes.

    The amount of data that you can rollback is depends on your database.

    The default is 32.

    Warning! Before you specify a rollback size value, verify the rollback size configured for your database. If the rollback size value specified in the PeopleSoft Pure Internet Architecture is greater then the transactional rollback size configured on the database, then transactional rollback will be disabled for that particular transaction, thereby causing destructive load processing to take place. To avoid destructive load processing, modify the rollback size configured for your database so that it is greater than the value you specify on the Bulk Load Handler page.

  4. Click the Save button.

The Bulk Load Handler page features a Truncate Table(s) option that you can set so that the system truncates the database table(s) prior to handler processing. The option is located under the Non-Destructive Load option on the Bulk Load Handler page.

By default, the Truncate Table(s) option is enabled and the PeopleSoft system performs table truncation. However, if you do not wish to perform table truncation you can deselect the option to disable table truncation.

To enable/disable table truncation:

  1. Access the Bulk Load Handler page (PeopleTools > Integration Broker > Integration Setup > Service Operations and click the Handlers tab. Click the Details link for the bulk load handler).

  2. On the Truncate Table(s) check box perform one of the following options:

    • To enable table truncation, select the check box.

    • To disable table truncation, deselect the check box.

  3. Click the OK button.

Use the XML Record Indicator Attribute check box on the Bulk Load Handler page to distinguish and specify records and fields on incoming XML content of nonrowset-based messages.

Image: Bulk Load Handler page

This example illustrates a partial view of the Bulk Load Handler page. The example shows the XML Record Indicator Attribute section of the page that you use to specify an attribute name and value for nonrowset-based messages.

XML Record Indicator Attribute box

When you specify an attribute name and value, the system recognizes content with that name and value as a record. Content placed in the message after that attribute name/value pair is considered child data.

When the service operation contains a nonrowset-based message, you must specify an attribute name and attribute value. If you do not supply values for these fields, an error message appears. These fields are optional when the service operation contains a rowset-based message.

To specify XML record attribute values:

  1. Access the Bulk Load Handler page (PeopleTools > Integration Broker > Integration Setup > Service Operations and click the Handlers tab. Click the Details link for the bulk load handler).

  2. In the Attribute Name field, enter the attribute name that the system should recognize as the record.

    For example, Class.

  3. In the Attribute Value field, enter the value for the attribute name.

    For example, R.

  4. Click the Save button.

This section discusses how to:

  • Build data structures for nonrowset-based data structures.

  • Insert nonrowset-based messages in project definitions.

Building Nonrowset-Based Data Structures

The Bulk Load Handler details page provides a data tree, similar to that found in the Messages component, that you use to build the structure of the nonrowset-based message.

You must define a minimum of one record to save the handler definition.

For building the data structure you use the same graphical user interface and procedures that you would for managing rowset-based messages in the Messages component.

By clicking the Add Record to Root link you can begin to create the data structure by adding a root record. As with the Messages component, you can select to include or exclude fields and specify field aliases. One unique difference here, however, is that you can build structures with multiple level 0 records. At save time, the system builds a message for each level 0 record found in the structure.

Note that message references are not allowed.

Message structures you create on the Bulk Load Handler details page are not accessible in the Messages component and appear only as part of the bulk load handler.

The message names start with ~IB_M_DMS~.

See the documentation elsewhere in the product documentation for managing rowset-based messages for creating the data structure. Again, even though here you are building the structure of a nonrowset-based message, you will use the same graphical user interface and procedures as those for working with rowset-based messages.

See Managing Rowset-Based Messages.

Inserting Nonrowset–Based Messages in Project Definitions

You must assign nonrowset-based messages you create using the Bulk Load Handler page to a bulk load handler. To accomplish this task, in PeopleSoft Application Designer when you insert a service operation handler definition into a project, you must include the message(s) as a related definition.

Image: Insert into Project page

This example illustrates the Insert into Project page.

Insert into Project page

To insert a service operation handler definition and related message definitions into a project:

  1. In PeopleSoft Application Designer, from the Insert menu, select Definitions info Project.

    The Insert into Project page appears.

  2. From the Definition Type drop-down list box, select Service Operation Handlers.

  3. Click Insert to view all service operation definitions and handlers in the system.

  4. Click the name of the service operation and handler to insert into the project.

  5. In the Related Definition section, click Messages.

  6. Click the Insert button to insert the service operation, handler, and related messages into the project.