PeopleTools 8.51 PeopleBook: Integration Broker Testing Utilities and Tools

Using the Handler Tester Utility

This chapter provides an overview of the Handler Tester utility and discusses how to:

Accessing the Handler Tester utility.
Select service operations.
Select handler to test.
Populate message data.
Save message test data.
Clone and delete record structures.
Override target connector properties
Run handler tests.
View handler test results.
Clear test data.

Understanding the Handler Tester Utility

The Handler Tester allows you to test handlers defined for rowset-based and nonrowset-based service operations from within the PeopleSoft Pure Internet Architecture. You can test handlers without setting up a routing, without having pub/sub booted on your application server, and without impacting other developer activity on the system.

To use the Handler Tester utility you should have a solid knowledge of Integration Broker messaging, as well as a knowledge of programming integration events and interpreting event results.

Warning! When you use the Handler Tester any PeopleCode associated with the handler is executed and production data is affected accordingly.

Consider the following points when using the Handler Tester utility:

The Handler Tester does not function with messages formatted with multiple level 0 records.
The Handler Tester does not re-initiate global variables between tests.

Integration Events to Test Using the Handler Tester

You can test the following integration events using the Handler Tester:

OnSend.
OnRequest.
OnRouteReceive.
OnRouteSend.
OnAckReceive.
OnNotify.

Testing Application Engine Handlers

You can test application engine handlers only when the data used for the test is transaction data from the application database. (This is the DB Operation Transaction option when populating data.)

Otherwise the application handler will fail due to no transaction ID being available to the application engine program.

Testing Bulk Load Handlers

You cannot use the Handler Tester Utility to test bulk load handlers.

Process Overview

To test integration events using the Handler Tester:

Select the service operation and version to use in the test.
Select the handler type and handler name to test.
Populate the message with data.
Run the test.

In addition to providing procedures for each step in the process, this chapter also describes how to save message data, clone and delete record structures, override connector properties, and view test results.

Common Elements Used in This Chapter

Service Operation	The service operation to use for the test.
Default Version	The Handler Tester tests the default version of a service operation. If you are testing a non default version, the transform version page will be displayed.
Handler Type	Click the drop-down list to select a handler type to test. The list displays only those handler types currently defined for the selected service operation. The options can include: OnSend. OnRequest. OnRouteReceive. OnRouteSend. OnAckReceive. OnNotify.
Handler Name	Click the drop-down list to select an handler name to test. The list displays only those handler names currently defined for the selected service operation and handler type.
Use DB Operation Transaction	Use this button to populate the input message with an existing database transaction.
Provide XML	Click the button to input XML or upload XML data from a file.
New Tree Structure	Click the button to clear the record and field values in the tree structure.
Convert Tree to XML	Click the button to convert data stored in the tree structure into XML format.
IB Info Values	Click the link to override target connector properties.
Execute Event	Click the button to execute the selected event.
View Returned IB Info Values	Displays the IBInfo values that were returned from the test.
Returned Message/Result	The returned message or results from the test. Displays when you click the Execute Event button.

Accessing the Handler Tester Utility

The Handler Tester utility is located in the Handler Tester component (IB_EVENTTESTER).

Use the Handler Tester page (IB_EVENTTESTER) to perform handler tests. To access the Handler Tester page, select PeopleTools, Integration Broker, Service Utilities, Handler Tester. The following example shows the Handler Tester page:

Selecting Service Operations and Service Operation Versions

This section discusses how to select a service operation and version to use for a handler test using the Handler Tester Search page (IB_EVENTSEARCH).

Selecting Service Operations

To select a service operation for the test:

Access the Handler Tester Search page (PeopleTools, Integration Broker, Service Utilities, Handler Tester).
In the search dialog box enter a search criteria in the Service Name field, click the Lookup button, and select a service definition.
Click the Search button and select the service operation.

Note. Service Operation security does not control what appears in the grid. All Service Operations are shown that match the search criteria.

Select the service operation and version to test.

If a non-default version is selected, the handler tester page will display a transform button.

When you select a rowset-based message, the structure of the message appears in tree-format at the bottom of the page. The records and fields contain no values until you populate the message with data.

When you select a nonrowset-based message, an Input Message text box displays. Use this box to populate the message definition with data by typing it in or by uploading from a file.

Selecting Handlers to Test

To select an event to test:

On the Handler Tester page, from the Handler Type drop-down list box, select a handler type.

Only handler types defined on the service operation display in the drop-down list.

The Message and Message Version fields are populated with the message definitions on the service operation.
From the Handler Name drop-down list box, select the handler to test.

Only handler names defined on the service operation display in the drop-down list.

Populating Message Data

This section discusses the methods to populate message data in the Handler Tester utility.

Note. The Handler Tester does not function with messages formatted with multiple level 0 records.

Note. If you select a multi-segmented message from the database, only the first segment is retrieved.

This section discusses how to:

Use operation transaction data from the application database.
Manually enter field values.
Manually enter XML data.
Upload XML data from files.
Populate rowset-based message parts in container messages.

Understanding Populating Message Data

You can load message data into a message definition from the following four sources.

Operation transaction data from the application database.
Field values that you enter manually, including PSCAMA record values and audit actions.
XML that you directly input into the utility.
XML that you upload from a file.

Using Operation Transaction Data from the Application Database

This section discusses how to use operation transaction data from transactions stored in the application database.

You can use this method to populate rowset-based and nonrowset-based message definitions.

Note. Only those transactions for which the user has been granted security for the service operation are allowed.

To populate message data using transaction data from the application database, you use the Select Database Transaction page (IB_EVENTSEARCH_SEC). The following example shows the page:

To use operation transaction data from a transaction:

From the Handler Tester page (PeopleTools, Integration Broker, Service Utilities, Handler Tester).

The Select Database Transaction page appears.
From the Handler Type drop-down list, select a handler type.
From the Handler Name drop-down list, select a handler.
In the Populate Input Message section, click the Use DB Transaction button.

The Select Database Transaction page appears.
From the Queue Level drop-down list select where the XML to use in the test is located. The options are:
- Operation Instance
- Publication Contract
- Subscription Contract
From the Statusdrop-down list select the status. The options are:
- Cancelled
- Edited
- Error
- New
- Retry
- Timeout
(Optional.) In the Queue Name field, enter the name of the queue.
(Optional.) In the Publishing Node field, enter the name of the publishing node.
(Optional.) In the Queue Sequence ID field, enter the sequence ID.
Click the Search button to view the available transactions.
Click the Actionslink for the transaction to use.

If this is a rowset-based message, the message tree will be populated from the transaction you selected. If this is a non rowset-based message, the XML will be populated.

Manually Entering Field Values

This section discusses how to:

Manually enter message definition field values.
Assign PSCAMA record values and audit actions to Level 0 records.
Assign PSCAMA audit actions to Level 1 and greater records.

Understanding Manually Entering Field Values

After you specify a service operation and version for a rowset-based message, the Handler Tester displays the message definition record and field structure in a tree format.

You can populate the message definition by manually entering values for fields.

In addition you can specify PSCAMA record values and audit actions for Level 0 records, as well as PSCAMA audit actions for Level 1 and greater records.

Manually Entering Message Definition Field Values

To manually enter field values:

Access the Handler Tester page (PeopleTools, Integration Broker, Service Utilities, Handler Tester).
In the tree structure for the message definition, single-click on field name to populate.

A dialog box for the field opens that displays field length and field type information as a guide for entering values.
Enter a value for the field.
Click the OK button.

Values you enter display after the field name in the tree view. The tree shows the first 30 characters of an entered value; however, the entire field value is stored.

Assigning PSCAMA Values and Audit Actions to Level 0 Records

To assign PSCAMA values and audit actions to Level 0 records:

Access the Handler Tester page (PeopleTools, Integration Broker, Service Utilities, Handler Tester).
Populate the service operation with a rowset-based message.

See Populating Message Data.
In the tree view, click the Level 0 record.

The Select an Action page appears.
Click the Assign PSCAMA arrow to expand the section.
Enter PSCAMA values as appropriate.

Descriptions of the PSCAMA field values and audit actions are described in the PeopleSoft Integration Broker PeopleBook.

See PSCAMA.
Click the OK button.

Assigning PSCAMA Audit Actions to Level 1 and Greater Records

To assign PSCAMA audit actions to Level 1 and greater records:

Access the Handler Tester page (PeopleTools, Integration Broker, Service Utilities, Handler Tester).
Populate the service operation with a rowset-based message.

See Populating Message Data.
In the tree view, click a Level 1 or greater record.

The Select an Action page appears.
Click the Assign PSCAMA arrow to expand the section.
From the Action field drop-down list, section the appropriate audit action.

Descriptions of PSCAMA audit actions are described in the PeopleSoft Integration Broker PeopleBook.

See PSCAMA.
Click the OK button.

Manually Entering XML Data

This section describes how to:

Manually enter XML data into rowset-based message definitions.
Manually enter XML data into nonrowset-based message definitions.

Manually Entering XML Data into Rowset-Based Message Definitions

When you manually enter XML data into a rowset-based message, the tree view is not available. To work with message data in the tree view, you must populate the data using operation transaction data from the application database or manually populate field values.

To manually populate a rowset-based message definition:

On the Handler Tester page, click the Provide XML button.

The Enter XML page displays.
In the XML text box enter XML to populate the message definition.
Click the OK button.

The Handler Tester page appears and the XML you entered displays in the Input Message box.

Manually Entering XML Data into Nonrowset-Based Message Definitions

To manually populate a nonrowset-based message definition, on the Handler Tester page, enter XML directly into the Input Message box.

Note that you can also click the Provided XML button and enter XML in the XML text box for a nonrowset-based message definition.

Uploading XML Data from Files

This section describes how to upload XML data from files to populate rowset-based and nonrowset-based message definitions.

Prerequisites for Uploading XML Data from Files

To successfully upload files into the Handler Tester the following environment variables must be set:

PS_FILEDIR
PS_SERVDIR

Note. PS_SERVDIR is set when you run PSAdmin. Before running PSAdmin, set the PS_SERVDIR environment variable.

This section describes how to set the PS_FILEDIR variable in Windows and UNIX environments.

To set the PS_FILEDIR variable in Windows:

Close any open DOS windows.
On your desktop, right-click the My Computer icon and click Properties.

The System Properties dialog appears.
Click the Advanced tab.
In the Environment Variables section, click the Environment Variables button. The Environment Variables dialog box appears.
In the User variables for <user name> section, click New.

A New User Variable dialog box displays.
In the Variable Name field enter PS_FILEDIR.
In the Variable Value field, enter c:\<path>.

The path you specify is the location from where the system will upload files.
Click OK to exit the Environment Variables dialog box.
Click OK again to exit the System Properties dialog box.

To set the PS_FILEDIR variable in UNIX use one of the following commands as appropriate for your UNIX environment:

export PS_FILEDIR = <PS_HOME>/file
setenv PS_FILEDIR = <PS_HOME>/file

The path you specify is the location from where the system will upload files.

Note. Use the same procedure to set PS_SERVDIR.

Uploading XML Files

To upload XML data from a file to populate message definition data:

Access the Enter XML page.
From the File Encoding drop-down list, select the file encoding of the file you are uploading. The options are:
- Non-encoded.
- UTF-8.
- UTF-16.
Click the Upload XML from File button.
Click the Browse button to locate the XML file to upload.
Click the Upload button.
Click the OK button to return to the Handler Tester page to run the event.

Populating Rowset-Based Message Parts in Container Messages

The Handler Tester utility enables you to populate rowset-based message parts in container messages.

When you select a container message with which to work in the Handler Tester utility, a Container Message Builder link appears on the Handler Tester page. The following example shows the Handler Tester page with a service operation select that contains a container message that contains rowset-based message parts:

The example shows that the service operation IB_EX_MP_ROWSET_SYNC is selected to test. The service operation contains the message IB_EX_ROWSET_CONTAINER, which is a container message comprised of rowset-based message parts.

When you select the Container Message Builder link, the Container Message Page (IB_MSGCONTAINER) appears, as shown in the following example:

The example shows the first message part contained in the message container, IB_EX_ROWSET_PART1.V1. At the bottom of the page is the familiar tree structure for building out rowset-based messages. You use the same pages as you would to build out any rowset-based message.

Use the backward and forward arrows to navigate to the different message parts in the message.

In between the navigation arrows, the system displays the part on which you are working, and the total number of parts in the container message. This example shows that the Container Message Builder page is displaying message part one and that a total of two parts comprise the container message.

The procedures for creating and modifying rowset-based messages is described in detail elsewhere in PeopleBooks.

See Managing Rowset-Based Messages.

Saving Test Data

This section discusses how to:

Save data located in the tree view.
Save manually-entered XML data.

Saving Data Located in Tree Views

To save test data loaded or entered into a tree view:

From the Handler Tester page, click the Convert Tree to XML button.

The Handler Tester converts the data to XML format and displays it in the Input Message window.
Cut and paste the XML into an editor or your choice and save the file.

You can later import the data back into the Handler Tester by uploading the XML file back into the utility.

Note. You can also use this method to create and save a test message to use with other integration testing utilities such as Send Master.

Saving Manually-Entered XML Data

To save XML test data that you have manually entered into the utility:

From the Handler Tester page, cut or copy the XML data in the Input Message box and copy it into an editor or your choice.
Save the file.

You can later import the data back into the Handler Tester by uploading the XML file back into the utility.

Cloning and Deleting Record Structures

This section discusses how to:

Clone record structures.
Delete record structures.

Cloning Record Structures

In some cases, you will want to add additional nodes to a record/field tree structure.

For example, if you are testing a purchase order, the records in the tree might be ORDER_HEADER and ORDER_LINE. If you want to test with two or more lines, you can click the first occurrence of the record name ORDER_LINE to duplicate that portion of the tree and all child records and nodes.

To clone a record structure:

On the Handler Tester page in the tree view, single-click the record to clone.

The Select An Action dialog box appears.
Select Clone Record Structure.
Click the OK button.

The original record is duplicated, along with child nodes and all entered field values. If you clone a record in error, single-click the record again and delete the record structure.

Deleting Record Structures

To delete a record structure:

On the Handler Tester page in the tree view, single-click the record to delete.
Select Delete Record Structure.
Click the OK button.

Specifying Target Connectors and Target Connector Properties

This section discusses how to:

Specify target connectors.
Specify target connector properties.

Specifying Target Connectors

You can specify a target connector and target connector properties you have defined at the connector, node and routing definition level when you run event tests.

For example, suppose that there are different query string arguments that would normally come into the system in the URL of an HTTP Get. The PeopleCode that handles the incoming service operation would have to obtain the query string arguments from the message's IB Info object. In the Handler Tester, the user would supply these values on this page.

To select a target connector:

Click the IB Info Values link.
In the Connector Property Defaults section, select the target connector. The options are:
- Connector. Click the Lookup button and select the connector ID.
- Node. Click the Lookup button and select the node.
- Routing. Click the Lookup button and select the routing from which to load connector properties.
Click the Load Connector Properties button.

Properties you have defined display in the bottom portion of the page.

Specifying Connector Properties

After you load the defined connector properties you can modify and add new values for testing purposes.

Connector properties you add or modify here do not override the properties you may have defined at the gateway, or node levels. However, when you run a handler test, the PeopleCode runs based on the values you define here and the Handler Tester writes the results to the database—and all PeopleCode database changes are permanent.

You can modify and add values for the following items:

Connector Name	Specify the proper name of the target connector to invoke to send the message.
Connector Class Name	Specify the class name of the target connector to invoke.
Remote Framework URL	Specify the URL (as a string) to which to send a message. This value overrides the server URL.
Path Info	Specific to incoming HTTP requests. This is the path information extracted from the request.
Cookies	Specific to incoming HTTP requests. This is cookie string found when the request was received by the HTTP listening connector.
App Server Domain	Enter the name of the application server domain to use.
Synch Server Timeout	Specify the timeout period (in seconds) for a transaction at runtime. The default synchronous timeout period is 300 (five minutes).
Property Name/Value/Property Type	Add or modify connector property names, values and types.
Name/Value	Add or modify parameter names and values to send to the target system in the URL, if the external system can use query string parameters as input.

Running Handler Tests and Viewing Test Results

This section discusses how to:

Execute event tests.
View test results.

Executing Handler Tests

After you have set up the integration metadata and selected the handler to test, you can run the handler test.

To run a handler test, on the Handler Tester page, click the Execute Event button.

Viewing Test Results

The Handler Tester returns test results on the Returned Message/Result section of the Handler Tester page and in the Returned IB Info page.

Viewing Results in the Return Message/Results Section

The following table lists the results the Handler Tester returns in the Return Message/Results section on the Handler Tester page:

Event	Returns	Return Value
OnNotify	String	The return values are: Done. Exit(1).
OnSend	Message Structure	Tree or XML
OnRequest	Message structure or string	If OnRequest code runs to completion, the message structure or tree is returned. If there is a user thrown exception, an exception string is returned.
OnRouteReceive	Boolean	The return values are: Inbound message is accepted. Inbound message is rejected.
OnRouteSend	String	The return values are: Outbound message target node list is accepted. Outbound message target node list is rejected. Outbound message sent to the following node(s) — <node_name>, <node_name>, <node_name>
OnAckReceive	String	The return values are: Error. Done. Retry.
Component Interface type on a synchronous service operation	Message Structure	Tree or XML.
Component Interface type on an asynchronous service operation	String	String returned by the handler.
Deprecated PeopleCode handler On Request	Message Structure	Tree or XML.
Deprecated PeopleCode handler OnNotify	String	The return values are: Done. Exit(1).

A reply message displays for the OnRequest and OnSend events. If the reply message is rowset-based, it displays in a tree format to the right of the Input Message section. If the returned message is nonrowset-based, a display-only edit box will display with its contents.

Viewing Results in the Returned IB Info Page

If you specified target connector properties, you can view returned IBInfo information. To do so, on the Handler Tester page, click the View Returned IB Info Values link.

Depending on the input values for an event test and the PeopleCode content, some or all of the fields contain test data.

The fields on that display on this page are described earlier in this chapter.

See Specifying Target Connectors and Target Connector Properties.

Clearing Test Data

This section describes how to:

Clear rowset-based message data.
Clear nonrowset-based message data.

Clearing Rowset-Based Message Data

To clear rowset-based message data:

Access the Handler Tester page.
Click the New Tree Structure button.

All values for the input message are cleared from the message definition, and you can repopulate it as desired.

Clearing Nonrowset-Based Message Data

To clear nonrowset-based message data:

Access the Handler Tester page.
In the Input Message box, delete the XML.

You can repopulate the message definition as desired.