Using the Error Handling Utility

This chapter provides an overview of the Error Handling utility and discusses how to:

• Set up and maintain message errors.

• Correct message errors.

Note. The Error Handling Utility is now superseded by the Services Operations Monitor that is part of PeopleSoft Integration Broker.

Understanding the Error Handling Utility

The Error Handling utility is a PeopleTools application that you use to view and correct messages that are received by the subscriber. You can also use this utility to correct data that is stored in staging tables.

Note. The Service Operations Monitor, available in the PeopleTools 8.48 release in PeopleSoft Integration Broker, supercedes the Error Handling utility.

Note. If you use the Error Handling utility, you should be familiar with messaging technology.

Error Management Process

PeopleSoft applications that receive flat file data from other systems through batch processes have built-in facilities to validate and correct data prior to updating the main application tables. Likewise, before updating core PeopleSoft application tables, the subscription process detects data errors in the messages that it receives. These error messages are stored in either message queues or staging tables.

In some cases, however, errors can’t be sent back to the third party for correction (such as when data is in a flat file). In these cases, you must provide error processing on incoming data so that messages that contain information on business objects, such as items and vendors, can be corrected and reprocessed in the PeopleSoft system.

In many integration point implementations, especially those that involve huge transactions and complex data validations, subscription codes are written to run simple incoming data validations. Upon a successful outcome, the system performs these steps:

1. Writes incoming data to staging tables.

2. Runs more stringent data validation processes, usually in batch processes.

As a result of the first subscription process, entries are written to a special staging table (EO_EIP_CTL). The EO_EIP_CTL table is keyed by a single key, EIP_CTL_ID, and has messaging keys. The EO_EIP_CTL table maintains links between the source message and the staged data and ensures that the data maintenance program can identify the staging tables.

To find the particular message that you want to view:

1. Select a message by using standard selection criteria, including data maintenance programs, business unit or setID, data status, and staging table or message queue.

2. Click a detail button to access the application page related to the edited message.

3. Make your edits.

4. Save the message.

Note. Messages that are selected from a staging table are saved to the staging table. Before they're saved permanently (to the application table), the corrected messages that were selected from the message queue are assigned a status of Changed and saved to the same queue. The messages then undergo the subscription process data validation again, after which they're saved to an application table.

A data maintenance program corrects errors in data that enters the PeopleSoft system.

Note. Subscription error management does not apply to real-time data that enters the PeopleSoft system through PeopleSoft Business Interlinks.

Error management consists of the following sequential activities:

1. The PeopleSoft system receives XML messages from a third-party source.

2. Subscription processes validate the data and send the data to:

   • PeopleSoft application tables (if no errors were found).

   • Message queue (if errors were found).

   • PeopleSoft staging tables (if subscription logic requires).

3. The Error Handling utility interacts with:

   • Message queue.

   • Staging tables.

4. The user interacts with:

   • The Error Handling page (to select a message for review or correction).

   • Application pages (for editing data errors).

5. The PeopleSoft system updates:

   • Message queue (if the original message was selected from the queue).

   • Staging tables (if the original data was extracted for staging tables).

Setting Up and Maintaining Message Errors

This section discusses how to:

• Create error-correction pages and the necessary hooks to the error handling utility.

• Set up the error handling utility.

• Set up row security.

• Set up workflow notification in PeopleSoft Application Designer.

• Test the error handling utility.

Pages Used to Set Up and Maintain Message Errors

Creating Error-Correction Pages

Use PeopleSoft Application Designer to create error-correction pages and components.

Note. The Header Details page and the Error Details page are applicable only if data resides in the messaging queues. Use one Header Details page and one Error Details page for each field.

When creating error-correction pages, follow these guidelines:

• Use EO_EIP_CTL as the main header table if you use staging tables.

  Developers can use unique EIP_CTL_ID generator functions (Generate_EIP_CTL_ID and Increment_EIP_CTL_ID) available in the FUNCLIB_EOEIP.EIP_CTL_ID FieldFormula event.

• Use the generate EIP_CTL_ID function to generate a unique key value for EIP_CTL_ID, based on the subscription process instance.

  The EIP_CTL_ID function is the sole key in the EO_EIP_CTL header table.

• Hook to EO_EIP_CTL to use the Error Handling utility for staging-table-based error handling.

  See Setting Up the Error Handling Utility.

• Modify the record PeopleCode in the derived work record EO_EIP_CTL_WRK.

  The derived work record called EO_EIP_CTL_WRK contains most of the processing logic for the utility. Although most of the codes are generic, you must write application-specific codes for the return button field (EIP_RETURN_BTN).

• Add codes to return the user to the main Error Handling page.

  Use the EO_EIP_CTL_WRK derived record in your component and write component PeopleCode for the record to handle any unique requirements.

  Note. This unique code belongs only to your component and cannot be shared.

FUNCLIB_XXEIP Codes

Functions are created and stored in product-specific FUNCLIB_XXEIP records, with XX representing the product. Application developers can look up these function libraries for possible use as templates.

Common integration-related functions are placed in the FUNCLIB_EOEIP record.

EIP_DETAIL_BTN FieldFormula

Function Copy_Detail_Errors (&WRK_FIELD, &J, &WRK_ROWSET) copies edit errors to a generic error subpage.

Function BuildQueueRowset (&WRK_ROWSET1 As Rowset, &WRK_ROWSET2 As Rowset, &MSG_ROWSET As Rowset, &SCROLL, &RECORD_FROM, &RECORD_TO) generically builds the queue-based transfer page. This function is useful for single record messages.

FUNCLIB_EOEIP.EIP_CTL_ID FieldFormula

You need an EIP_CTL_ID every time that you process a message to maintain error handling. Use Function Generate_EIP_CTL_ID and Increment_EIP_CTL_ID to create EIP_CTL_IDs based on a new subscription process instance. For the Generate_EIP_CTL_ID function, invoke method 4 from the list of process instances.

Note. Although in some cases a random number generator is used for creating a new EIP_CTL_ID by calling Generate_EIP_CTL_ID(1), you should use the subscription process instance if possible. Generate_EIP_CTL_ID(4) uses the message subscription process identifier number. Remember to activate this on the message subscription properties by selecting the Generate Subscription Process Instance check box.

Warning! The Generate_EIP_CTL_ID and Increment_EIP_CTL_ID functions call other functions in FUNCLIB_ININTFC (an FDM record). You must recreate these additional functions whenever you use Generate_EIP_CTL_ID and Increment_EIP_CTL_ID within applications.

Setting Up the Error Handling Utility

Access the Data Maintenance page.

Queue Based and Stage Table	PeopleTools messages are queue-based; bulk data or application data is usually staged.
Business Unit and SetID	Select a business unit or setID on which to base the data.
Component Name	Select the name of the component for accessing the Error Handling/Data Maintenance page (EO_EIP_CTL_MAINT). This is the component that the user opens for error-correction activities. You should select EIP_DTA_CTL. This component uses the same fonts and images for all incoming data maintenance or error-correction activities within PeopleSoft for non-real-time integration.
Prompt Table	Follow the navigation path to use the Error Handling utility, and select a prompt table for the data maintenance program (EIP_PROGRAM). The PeopleSoft system includes a common error handling menu structure that points to the main component EIP_DTA_CTL. Based on user privileges, the Error Handling utility prompts from a selected list of data maintenance programs.
Panel Transfer Code	Select Next Panel to receive a transfer panel name prompt, which gives you a selection of pages that are part of the main data maintenance component that you selected in the Main Data Maint Panel Group field. Select one page. Selecting either Transfer or Modal opens additional fields.
Role Name	Select a name to set up workflow notification and to notify all role users listed.
User ID	Select to notify only specific role users.
Flag1, Flag2, Flag3, Flag4, and Flag5	Users often won't see these check boxes. Application developers use them for extra coding flexibility. Developers must create documentation for these check boxes to use them.

Setting Up Row Security

Access the Workflow/Security page.

Row Security Permission List

Assign a row security class to the transaction type that you're setting up.   Note. The value that you select determines which user can see the given transaction type. You can enter multiple row security classes.

Setting Up Workflow Notification in PeopleSoft Application Designer

You can set up an EO_WF_ERR Application Engine process to scan the EO_EIP_CTL table periodically to look for rows with ERROR status. When the system finds errors, it generates workflow notifications and routes them to the role users that you designated in the User ID field on the Data Maint Setup1 page. Clicking the worklist item in the workflow notification transfers the user to the Error Handling/Data Maint (error handling/data maintenance) page.

To set up workflow notification:

1. Open an instance of PeopleSoft Application Designer.

2. Select File, Open.

3. Select Business Process from the Definition drop-down menu.

4. Open business process EC_MANAGE_ERRORS.

5. Right-click the MANAGE ERRORS icon and select View Definition.

6. Double-click the Correct Errors icon to open the Step Definition dialog box.

7. Click the Attributes button to open the Step Attributes dialog box.

8. Complete the required navigation information to the error correction page in the Step Attributes dialog box and click OK.

Testing the Error Handling Utility

Access the EO EIP Data Maint page.

Queue Based and Stage Table	Select whether the errors you want to check are queue-based or stored in a staging table.
Status	Select from Cancelled, Complete, Error, Hold, In Process, Incomplete, New, and Reprocess.
	Click the Show Detail Entry button to transfer to the application page for necessary error-correction activities.

Correcting Message Errors

This section discusses how to correct message errors.

Understanding the Workflow Notification Process

Workflow error notification involves:

1. A process-scheduled Application Engine program scans data errors in the staging tables (or in the Subscription Contract Message queues) at a given interval.

   Note. You can also run a separate Workflow Notification Application Engine program for messaging queues.

2. When the Application Engine program finds errors in the actual message queue or the staging summary table, it opens respective component interfaces that invoke the designated temporary components for inserting error data into the underlying temp tables.

3. Saving the temporary page (through component interface calls) triggers workflow PeopleCode to send worklist notifications to designated users, depending on the role name or user ID that you selected on the Data Maint Setup1 page.

   Note. The Application Engine program traps only the first error for each field, but it can trap multiple errors for each record.

Correcting Message Errors

To correct message errors:

1. Access the Data Maint Setup1 page to open the worklist.

2. Open the worklist.

   You are transferred to the Error Correction/Data Maint page (EO_EIP_CTL_MAINT) to correct the errors.

3. Find the error rows by using a combination of search criteria, such as transaction type, business unit or setID, and error status.

4. Click the Search icon.

5. Click the Show Detail Entry icon (to the left of each row) to select a specific transaction that represents a single message or a single row of header-level record from the staging table.

6. Correct the data.

7. Click the Return button to return to the Error Handling Summary page (EO_EIP_CTL_MAINT) and continue the session with other transactions.

Note. In this scenario, the corrected data does not update core PeopleSoft tables. Instead, it updates the message queue or staging tables.