Managing Service Operation Handlers

This chapter provides an overview of service operation handlers and handler implementation methods, and discusses how to:

• Add handlers to service operations.

• Implement handlers using application classes.

• Implement handlers using application engine programs.

• Implement handlers using component interfaces.

• Implement handlers using the bulk load handler.

• Implement handlers using the deprecated PeopleCode handler.

Understanding Service Operation Handlers

Messaging handlers, or handlers are associated with a service operation on the Handlers tab of the Service Operations page.

Handlers define additional programming to be used with processing the message associated with the service operation.

Service Operation Handler Types

The following are the different types of handlers:

• On Notify

• On Pre-notify

• OnPost-notify

• On Receive

• On Request

• On Response

• On Route

• On Send

Handler Types and Messaging Types

The availability of each handler type depends on the type of service operation you are using. The following tables list the message types used for each service operation type and the handler types available for use.

Table 1:

Table 2:

Note. For On Route with On Send, the message structure is a request message. For On Route with On Receive, the message structure is a response message.

The On Response handler type is used to identify the type of On Notify event to be fired. For example, assume there are four On Notify handlers that are to be fired—three are general On Notify events, that is, the message is processed as part of the request, and the fourth is a response to the original asynchronous request. The fourth one is specified with a handler type of On Response, and the application class selected is the base class OnNotify.

See Also

Adding Handlers to Service Operations

Understanding Implementing Handlers

You can implement handlers using application classes, application engine programs, component interfaces, data mover scripts or pre-PeopleTools 8.48 integration PeopleCode constructs.

The following tables list the handlers you can implement using application classes, application engine programs, component interfaces and bulk-load processing.

Table 1:

Table 2:

In addition to the implementation methods listed in the table, there is also a deprecated PeopleCode handler (DPC handler) that the system automatically creates for any integration PeopleCode that cannot be migrated to the PeopleTools 8.48 or higher systems.

The handler implementation methods listed in the tables are discussed in greater detail in subsequent sections of this chapter.

See Also

Implementing Handlers Using Application Classes

Implementing Handlers Using Application Engine Programs

Implementing Handlers Using Component Interfaces

Implementing Handlers Using Bulk Load Processing

Implementing Handlers Using Deprecated PeopleCode Handlers

Adding Handlers to Service Operations

This section describes how to:

• Add a handler to a service operation.

• Set handler processing sequence.

Understanding Adding Handler Definitions to Service Operations

When you create a handler definition you supply basic information about the handler, then define information specific to the implementation method for the handler.

You can create and use multiple handlers for a service operation. In addition you can set the sequence in which the system performs handler processing.

Handler Processing Sequence

The Sequence field enables you to select the order in which PeopleSoft Integration Broker performs handler processing. A handler with a sequence value of 1 is processed first, followed by that with a value of 2, and so on.

If multiple notification handlers exist and are active, but no sequence is set, the system processes handlers alphabetically.

If an error occurs in a notification, all subsequent handler processing stops until the error is corrected, the service operation is resubmitted, and the handler runs successfully.

In an error situation, the Service Operation Monitor shows a status of Error for the handler with the error, and all remaining handlers to be processed are in a status of New.

Adding a Handler to a Service Operation

The following example shows the Service Operations-Handlers page (IB_SERVICEHDLR) that you use to create handler definitions:

To create a handler definition:

1. Access the Service Operations–Handlers page (PeopleTools, Integration Broker, Integration Setup, Service Operations. Click the Handlers tab.)

2. In the Handlers section, enter a handler name in theName field.

   Note that for OnRequest, and OnRoute handlers, you need not enter a name. The system adds a handler name after you provide the handler details.

3. From the Type drop-down list box, select the handler type.

   The service operation type determines the handler types that are available to choose.

   See Handler Types and Messaging Types.

   The valid values are:

4. In the Sequence field, enter a number to specify the order of processing for the handler.

   The Sequence field appears only when there are multiple notification handlers defined and active for the service operation.

5. From the Implementation drop-down list box, select the method to use to implement the handler.

   The handler type determines the available implementation methods.

   See Understanding Implementing Handlers.

6. From the Status drop-down list box, select a status for the handler.

   Values are:

   • Active. (Default.) Select to make the handler active.

   • Inactive. Select to make the handler inactive.

7. Click the Save button.

Repeat these steps to add additional handlers to the service operation.

Specifying General Handler Details

The details you enter for a handler depend on the implementation method of the handler.

This section describes general handler detail information you must specify for implementing handlers using application classes and component interfaces.

There are additional details you must define for these implementation methods, as well as for application engine and data mover script implementation methods. See the sections for each implementation method for additional information you must specify.

Note. You do not enter handler details for handler implementations using a deprecated PeopleCode handler.

To add general handler details:

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

   The Action Details page appears.

2. In the Description field, enter a description for the handler. By default, the system populates this field with the name of the service operation associated with the handler.

3. (Optional.) In the Comments field, enter comments about the handler.

4. (Optional.) In the Handler Owner field, enter the name of the person or group that owns or maintains the handler.

See Also

Implementing Handlers Using Application Classes

Implementing Handlers Using Application Engine Programs

Implementing Handlers Using Component Interfaces

Implementing Handlers Using Bulk Load Processing

Implementing Handlers Using Deprecated PeopleCode Handlers

Implementing Handlers Using Application Classes

This section provides an overview of implementing handlers using application classes and discusses how to:

• Develop an application class for implementing a handler.

• Specifying application class implementation details.

Understanding Implementing Handlers Using Application Classes

You can specify an application class as a handler for a service operation. This is the most typical implementation of a handler.

The process for implementing a handler using an application class is:

1. Develop an application class for implementing the handler.

   This process is discussed in this section.

   See Developing Application Classes for Implementing Handlers.

2. Add a handler to the service operation.

   This process is discussed elsewhere in this chapter.

   See Adding a Handler to a Service Operation.

3. Specify general handler details.

   This process is discussed elsewhere in this chapter.

   See Specifying General Handler Details.

4. Specify application class details for the handler.

   This process is discussed in this section.

   See Specifying Application Class Implementation Details.

Developing Application Classes for Implementing Handlers

This section discusses how to develop application classes for implementing service operation handlers.

After you create the application package, you must specify the application package, class and method in the service operation definition as part of the handler details.

Understanding Interfaces and Deriving Application Classes

For each handler type, the following table lists the interface from which to derive the application class. The interfaces are located in the PS_PT application package:

Understanding Input and Output Parameters

For application class handlers, the names that populate the drop-down used for selecting the appropriate method must have the exact signature required for the method.

For the On Route handler type, if you select a method that returns as integer, the handler type is On Route Send. If you select a method that returns as Boolean, the handler type is On Route Receive.

Developing an Application Class for Implementing a Handler

To develop an application class for implementing a handler:

1. Select the Integration Broker method that you want to implement based on the type of service operation you are creating.

2. Create a new application class, and import the appropriate Integration Broker application class. For example:

   import PS_PT:Integration:INotificationHandler;

3. Define a class that implements the Integration Broker application class.

4. Define the method that implements the Integration Broker method, with the appropriate signature. In the following example, the OnNotify method would be available as a handler method.

   class RESPONSE_NOTIFICATION implements PS_PT:Integration:INotificationHandler    
   
   method RESPONSE_NOTIFICATION();    
   method OnNotify(&MSG As Message);     
   
   end-class;

5. In the definition of the class, create the program-specific code to be used for this handler.

Specifying Application Class Implementation Details

Before specifying application class implementation details for a handler, you must first create the application class to implement the handler, add a handler to the service operation definition, and specify general handler details.

To specify application class implementation details:

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

   The Handler Details page appears.

2. Complete the following fields:

   Package Name	Enter the package name that contains the class that you want to specify, or use the Lookup button to search for and select one.
   Path	Enter the name or names of any subpackages that contain the application class that you want to specify, or use the Lookup button to search for and select one.
   Class ID	Enter the name of the application class that contains the method that you want to specify, or use the Lookup button to search for and select one. Only application classes that implement an appropriate base class are shown. The base class is dependent on the handler type.
   Method	From the Method drop-down list box, select the method from the selected application class that you want to specify. Only methods with the correct signature for the current handler type are shown.

3. Click the OK button.

4. Click the Save button.

Implementing Handlers Using Application Engine Programs

This section provides and overview of implementing handlers using application engine programs and discusses how to:

• Specify application engine implementation details.

• Retrieve service operation content from application engine programs.

• View subscription contract status.

Understanding Implementing Handlers Using Application Engine Programs

Application engine handlers are available for notification events (OnNotify) and schedule an application engine program to run within PeopleSoft Process Scheduler to process service operation content. This handler is a good alternative for long-running programs or service operations that have large amounts of data to process, since processing is performed by PeopleSoft Process Scheduler and not in the PeopleSoft Integration Broker runtime environment.

After the service operation is invoked, you can track the process by viewing the subscription contract in the Service Operations Monitor.

When you implement a handler using an application engine program, you must retrieve the transaction ID that you use to get message data from within the application engine program. The run control record PSIBRUNCNTL is populated with the transaction ID prior to scheduling the actual application engine program. Note that it is not required to retrieve the transaction ID, therefore any application engine program can be scheduled that does not require initialization parameters via a run control table.

The process for implementing a handler using and application engine program is:

1. Develop the application engine program.

   Developing application engine programs is discussed elsewhere in PeopleBooks.

   See Creating Application Engine Programs.

2. Add a handler to the service operation.

   This process is discussed elsewhere in this chapter.

   See Adding a Handler to a Service Operation.

3. Specify general handler details.

   This process is discussed elsewhere in this chapter.

   See Specifying General Handler Details.

4. Specify application engine handler implementation details.

   This process is discussed in this section.

   See Specifying Application Engine Handler Implementation Details.

5. Retrieve service operation content from the application engine program.

   This process is discussed in this section.

   See Retrieving Service Operation Content from Application Engine Programs.

6. View subscription contract status.

   This process is discussed in this section.

   See Viewing Subscription Contract Status.

Specifying Application Engine Handler Implementation Details

Before specifying application engine handler implementation details, you must first create the application engine program to process the service operation, add a handler to the service operation definition, and specify general handler details.

To specify application class implementation details:

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

   The Action Details page appears.

2. In the Program Name field, click the Lookup button to locate the name of the application engine program to use.

3. Click the OK button.

4. Click the Save button.

Retrieving Service Operation Content from Application Engine Programs

This section discusses how to:

• Retrieve a transaction ID from an application engine program.

• Instantiate a Message object using a transaction ID.

Understanding Retrieving Service Operation Content from Application Engine Programs

Within the application engine program, you can retrieve the transaction ID and thereby get an instantiated Message object to retrieve the content data respectively.

Retrieving Transaction IDs from Application Engine Programs

Use the GetIBTransactionIDforAE method on the %IntBroker object to get the transaction ID or simply write the SQL to retrieve the ID.

The following examples show how to get the transaction ID from an application engine program and instantiate a Message object.

Method from %IntBroker Object:

StrTransaction = %IntBroker.GetIBTransactionIDforAE
(string OperID, string Run Control ID);

&MSG = %IntBroker.GetMessage(StrTransaction, %IntBroker_SUB);

Or, you can write code within a SQL step similar to the following:

%SelectInit(IBTRANSACTIONID) 
 SELECT IBTRANSACTIONID 
  FROM PSIBRUNCNTL 
 WHERE OPRID = %Bind(OPRID) 
AND RUN_CNTL_ID = %Bind(RUN_CNTL_ID)

Or, you can perform a simple SQLExec as follows:

SQLExec("select ibtransactionid from psibruncntl where oprid = :1 and
 run_cntl_id = :2",

j_book_aet.oprid, j_book_aet.run_cntl_id, &ibtransid);

Instantiating Message Objects Using Transaction IDs

The following pseudocode provides an example of instantiating a Message object using the transaction ID from an application engine program:

&MSG = %IntBroker.GetMessage(J_BOOK_AET.IBTRANSACTIONID, %IntBroker_SUB);

Viewing Subscription Contract Status

The following table lists the possible contract statuses that may display in the Service Operations Monitor when implementing a handler using an application engine program:

Note. In the Service Operations Monitor the Submit status has the same behavior as the Working status, thus proper queue partitioning behavior is maintained. Therefore, intelligent queue partitioning should be taken into account for service operations using the application engine handler.

A Subscription Contract processing an application engine handler cannot be cancelled or resubmitted from the Service Operations Monitor, but rather must be done in the Process Monitor. Once you resubmit or cancel the program in the Process Monitor, the status is updated for the subscription contract. Refresh the Service Operations Monitor page to view the updated status. Note that there could be a delay from when the time you cancel or resubmit the application engine program in the Process Monitor and when the update is seen in the Service Operations Monitor. In addition, at least one Pub/Sub domain must be active for this status update to happen.

Implementing Handlers Using Component Interfaces

You can implement a component interface as a handler to access extant business rules and processes to be used with the service operation data.

Understanding Implementing Handlers Using Component Interfaces

This section provides an overview of implementing handlers using component interfaces.

You can only use a component interface for On Notify, On Request and On Response handler types.

Component interfaces can be used as handlers for asynchronous and synchronous service operations. Asynchronous service operations should only be used with component interface methods that do not require a response, such as Update or Insert.

You must define a component interface as a service before you can implement any of the component interface methods as handler actions.

See Creating Component Interface-Based Services.

The standard methods for a component interface (such as Find, Get, Save, Update, and so on) are automatically available for a handler. However, if you want to use a user-defined method, you must include the keyword Doc as part of the signature.

The process for implementing a handler using a component interface is:

1. Define the component interface as a service.

   This procedure is discussed elsewhere in this chapter.

   See Creating Component Interface-Based Services.

2. Add a handler to the service operation.

   This procedure is discussed elsewhere in this chapter.

   See Adding a Handler to a Service Operation.

3. Specify general handler details.

   This procedure is discussed elsewhere in this chapter.

   See Specifying General Handler Details.

4. Specify component interface handler implementation details.

   This process is discussed in this section.

   See Specifying Component Interface Handler Implementation Details.

Specifying Component Interface Handler Implementation Details

Before specifying component interface handler implementation details, you must first create a service from the component interface, add a handler to the service operation definition, and specify general handler details.

To specify component interface implementation details:

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

   The Action Details page appears.

2. In the Name field enter the component interface name, or use the Lookup button to search for and select one.

3. From the Action drop-down list box, select an action.

4. Click the OK button.

5. Click the Save button.

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.

Understanding Implementing Handlers Using the Bulk Load Handler

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

   See Adding a Handler to a Service Operation.

2. Specify general handler details.

   This procedure is discussed elsewhere in this chapter.

   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.

Enabling Transactional Rollback

The Bulk Load Handler page (IB_SERVICEHDL5_SEC) features a Rollback Non-Destructive Load option that you can set to enable transaction rollback. The Bulk Load Handler page is shown in the following example:

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. The following example shows the Bulk Load Handler page when the service operation contains a rowset-based message:

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. Check the Rollback Non-Destructive Load 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.

Enabling Table Truncation

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 clear 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. Click the Handlers tab. Click the Details link for the bulk load handler.)

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

   • To enable table truncation, check the box.

   • To disable table truncation, clear the box.

3. Click the OK button.

Specifying XML Record Attribute Values

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

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

Adding Data Structures for Nonrowset-Based Messages

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 this PeopleBook 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.

The following example shows the Insert into Project page used to insert a service operation handler definition and related message definitions into a project:

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.

Implementing Handlers Using Deprecated PeopleCode Handlers

During the upgrade process, the PeopleSoft system creates a deprecated PeopleCode handler (DPC handler) for any integration PeopleCode that cannot be migrated from a PeopleTools 8.47 or earlier system to a PeopleTools 8.51 system. Deprecated handlers enable you to run PeopleTools 8.47 and earlier PeopleCode (subscription or OnRequest). However, PeopleSoft recommends that you correct the PeopleCode and migrate the code into an Application Class type handler for use in PeopleTools 8.51 systems.