Managing Error Handling, Logging, Tracing, and Debugging

This chapter provides an overview of integration gateway error handling and discusses how to:

Manage integration gateway message and error logging.
Manage application server logging and tracing.
Debug integrations.

Understanding Error Handling, Logging, Tracing and Debugging

Error handling, logging, tracing, and debugging with PeopleSoft Integration Broker can occur on an integration gateway, application server, or application engine, depending on the type and location of processing.

Understanding Integration Gateway Error Handling

Error handling is an integration gateway service that assists connectors to manage errors that occur during processing. Errors on the integration gateway are handled by target connectors and listening connectors.

This section discusses:

Target connector error handling.
Listening connector error handling.
Integration gateway exception types.

Target Connector Error Handling

The Target Connector Interface (TCI) specifies the methods that target connectors must implement for the integration gateway to manage them. These methods include a set of standard exceptions that target connectors generate when they experience errors during processing.

Listening connectors or the gateway manager catch these exceptions and provide an appropriate implementation for each. When the source of the message is an integration engine, the gateway manager catches the exceptions. Otherwise, listening connectors are responsible for handling exceptions that are generated during processing.

Listening Connector Error Handling

Unlike target connectors, listening connectors are not managed by the gateway manager and, therefore, do not adhere to any interface. However, a listening connector must invoke the gateway manager to pass a message from the integration gateway to the integration engine.

The gateway manager has predefined exceptions.

In general, exceptions are thrown in a target connector and caught by a listening connector. As a result, a listening connector must catch these exceptions and handle them as appropriate. Typically, the listening connector generates an error message and sends it back to the requester.

Integration Gateway Exception Types

This section discusses integration gateway exception types.

Standard Exceptions

The following standard error and exception types are handled by the integration gateway, target connectors, and listening connectors:

Exception Type	Description
DuplicateMessageException	A target connector attempted to process a message that has already been processed. This is usually discovered based on an error that is attained from the external system that is being contacted. Of the connectors that are delivered with the PeopleSoft software, only the PeopleSoft 8.1 target connector (PSFT81TARGET) can generate this exception. Target connectors are not required to generate this exception.
ExternalApplicationException	The message reached its intended destination but could not be processed. Determining that the destination could not process a message requires significant knowledge of the destination system, which a target connector might not have. Whenever possible, a target connector should attempt to determine this situation; otherwise this task must be decentralized and handled outside of the integration gateway. For example, the HTTP target connector (HTTPTARGET) generates this exception when the external system returns an HTTP system code of 500.
ExternalSystemContactException	The target connector cannot establish a connection with the intended destination. This is one of the most common exceptions. When this exception is thrown during an asynchronous transaction, PeopleSoft Integration Broker tries to resend the message until successful.
GeneralFrameworkException	A general error occurred.
InvalidMessageException	A connector or the gateway manager determined that the message cannot be processed because of missing or erroneous information in a request or response.
MessageMarshallingException	A gateway service’s attempt to get information from an IBRequest or IBResponse failed. This can occur when the gateway services attempt to access a content section of a document by using an out-of-range index from one of the following methods: GetContentSectionAt(index) GetContentSectionInfoAt(index) RemoveContentSectionAt(index) If you try to access IBRequest or IBResponse with an out-of-range index by using any of these methods, this exception is thrown automatically and processing is interrupted.
MessageUnmarshallingException	A gateway service’s attempt to build an IBRequest or IBResponse failed. Failure can occur when: Instantiating an IBRequest or IBResponse from a Multipurpose Internet Mail Extensions (MIME) format where the message that was sent does not comply with the PeopleSoft MIME format. Instantiating an IBRequest by using the PS_XML format and passing an invalid PS_XML message. This is typically from the HTTP listening connector. Setting invalid values to methods, such as setTransactionID or setMessageType. These failures cause the integration gateway to generate this exception automatically and processing is interrupted.

Java Exceptions

Target connectors and listening connectors can handle miscellaneous Java exceptions, such as NullPointerException and ArrayOutOfBoundsException.

Managing Integration Gateway Message and Error Logging

This section provides an overview of message and error logging and discusses how to:

Set up message and error logging.
View non-English characters in integration gateway log files.
Manage message logging.
Manage error logging.

Understanding Message and Error Logging

Error and message logging is a gateway service that you use to monitor messages that flow through the integration gateway.

Logging takes place within both target and listening connectors. Connectors can log all message requests and responses. As a result, you can use logging to:

Track message flow.
Troubleshoot processing errors.

Setting Up Message and Error Logging

By default, an integration gateway logs all errors and warnings, as well as information of important, standard, and low importance.

Set up message and error logging by using the integrationGateway.properties file. Use the Logging Setting section to view or change default settings, such as the level of gateway logging, where the system writes log files, the maximum size of the log file, and the number of file backups or archives to keep.

Viewing Non-English Characters in Integration Gateway Log Files

To view non-English characters in integration gateway log files, enable UTF-8 encoding in your web browser. For example, if you are using Microsoft Internet Explorer 5.5, you can enable UTF-8 encoding by selecting View, Encoding, Unicode (UTF-8). If you are using Netscape Navigator 6.0, you can enable UTF-8 encoding by selecting View, Character Encoding, Unicode (UTF-8).

Managing Message Logging

Message logging records the following information for messages that pass through the integration gateway:

Time and date.
Message description.
Content of the passed message object.
Message level.

The default location of the integration gateway message log is <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\msgLog.html.

Change the location of the log in the integrationGateway.properties file.

Message Logging in Target Connectors

Message logging in a target connector occurs:

Before delivering the request to the external system.

The connector logs the request in the format in which the external system delivered it. For example, an HTTP target connector logs the exact HTTP output stream request. The PeopleSoft target connector logs the MIME request to be sent to the integration engine.
After it receives a response from the external system.

The connector logs the response in the format in which it receives it. For example, an HTTP target connector logs the exact HTTP input stream response. The PeopleSoft target connector logs the MIME response that it received from the integration engine.

Message Logging in Listening Connectors

Message logging in a listening connector occurs:

At the point where the request enters the system.

The connector logs the request in the format in which the sending system delivers it. For example, the HTTP listening connector logs the exact HTTP input stream request. The PeopleSoft listening connector logs the MIME request that it received from the integration engine.
Following the delivery of a response to the requestor system.

The connector logs the response in the format in which it was delivered. For example, the HTTP listening connector logs the exact HTTP output stream response. The PeopleSoft listening connector logs the MIME response that it sent back to the integration engine.

Message Logging Methods and Parameters

Invoke the logMessage method for integration gateway message logging:

logMessage(String Description, Object message, int MessageLevel)

Use the following parameters:

Parameter	Description
Description	Specify a description as a string.
Object	Specify the message object. Typically this object is an IBRequest or IBResponse. If another object is passed, the toString method is invoked for the object, and the result is logged.
MessageLevel	Set the relative importance of the information that you are logging. The ig.log.level property setting in the integrationGateway.properties file determines the log level that is currently in effect. If the MessageLevel value that is passed here is less than or equal to the ig.log.level property setting, the message is written to the log file. Values are: 3: Important information. 4: Standard information. 5: Low-importance information. The ig.messageLog.filename property in the integrationGateway.properties file determines the log file location.

Managing Error Logging

Error logging captures processing errors that occur in the integration gateway. When an error occurs, the following information is logged:

Error level.
Description.
Message catalog entry information.
Stack trace identifying the problem.
IBRequest and IBResponse (if available).

The default location of the integration gateway error log is <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\errorLog.html

Change the location of the log in the integrationGateway.properties file.

Error Logging Methods and Parameters

Invoke the logError method for integration gateway error logging:

logError (String Description, IBRequest, IBResponse, int ErrorLevel, Throwable)

Use the following parameters:

Parameter	Description
Description	Specify a description as a string.
IBRequest	Specify the IBRequest for this transaction, if available. If not available, pass Null.
IBResponse	Specify the IBResponse for this transaction, if available. If not available, pass Null.
ErrorLevel	Specify whether the log is written to permanent storage. This determines the severity of the error. The ig.log.level property in the integrationGateway.properties file determines the log level that is currently in effect. If the ErrorLevel value that is passed here is less than or equal to the ig.log.level property setting, the error is written to the log file. Values are: 100: Language exception. 1: Standard gateway exception. 2: Warning. The ig.errorLog.filename property in the integrationGateway.properties file determines the log file location.
Throwable	Specify the Java exception or error that is associated with the error. This is used to log the stack trace that is associated with the error.

The gateway manager and delivered listening connectors feature built-in error logging that invokes the logError method. The delivered target connectors do not feature built-in error logging, and instead generate errors to the gateway manager or listening connectors, where they are handled or logged.

Managing Application Server Logging and Tracing

Use the PeopleSoft Application Server Administration menu to:

View application server and BEA Tuxedo log files.

See Editing Configuration and Log Files.
Trace Structured Query Language (SQL) and PeopleCode on your domains.

See Trace Options.
Set the level of network tracing (log fence).

See Domain Settings.
View the certificate authentication logs, including information about mismatched distinguished names and certificates that are not in the database.

This information is contained in the APPSRV.LOG file.

You can also use the tracing functionality in PeopleSoft Application Engine, which enables you to monitor the performance of transforms in your implementation of PeopleSoft Integration Broker.

Debugging Integrations

This section discusses how to:

Debug handler PeopleCode.
Handle common issues.

Debugging Handler PeopleCode

Use the Handler Tester utility to debug service operation handler PeopleCode.

The Handler Tester utility enables you to use the PeopleSoft Pure Internet Architecture to test any of the following handler types:

OnSend.
OnRequest
OnRouteReceive
OnRouteSend.
OnAckReceive
OnNotify.

You can test handlers without setting up a routing definition, without having pub/sub booted on your application server, and without impacting other developer activity on the system.

Handling Common Issues

Use this table to handle common issues in PeopleSoft Integration Broker:

Area or Suspected Issue	Debugging Suggestion
Application server exceptions.	Check the application server log: <PS_HOME>\appserv\<Domain>\LOGS\ appsrv.log
Message handlers are not running.	Check the application server domain status or queue status in the PeopleSoft Application Server Administration menu (PSADMIN). Select Domain Status, Server Status or Domain Status, Queue Status.
Integration gateway.	Check the integrationGateway.properties file and verify the property settings. The default file location is <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\WEB-INF\integrationGateway.properties.
Integration gateway.	Check the integration gateway message log. The default file location is <PS_HOME>\webserv\<DOMAIN>\applications\peoplesoft\PSIGW\msgLog.html.
Queues are paused.	Check the Service Operations Monitor. Select PeopleTools, Integration Broker, Service Operations Monitor, Administration, Queue Status.
A node is paused.	Check the Service Operations Monitor. Select PeopleTools, Integration Broker, Service Operations Monitor, Administration, Node Status.
Incorrect gateway uniform resource locator (URL).	Check the Gateways component to verify that the integration gateway URL is correct. Select PeopleTools, Integration Broker, Configuration, Gateways.
Node inactive.	Check the node definition. Select PeopleTools, Integration Broker, Integration Setup, Nodes.
Subscription PeopleCode is missing or incorrect.	Check the Service Operations Monitor. Select PeopleTools, Integration Broker, Monitoring, Asynchronous Services, Subscription Contracts..
A service operation is inactive.	Check the service operation definition in the PeopleSoft Pure Internet Architecture. Select PeopleTools, Integration Broker, Integration Setup, Service Operations.
There are transform problems.	Check the Application Engine object in PeopleSoft Application Designer. For before and after images, check the Service Operations Monitor. For asynchronous service operations, , select PeopleTools, Integration Broker, Service Operations Monitor, Monitoring, Asynchronous Details. Click the View XML link for the publication contract or subscription contract. For synchronous service operations, select PeopleTools, Integration Broker, Service Operations Monitor, Monitoring, Synchronous Details. Use the Log Type dropdown list box to select Request Transformed or Response Transformed, and then click View XML. Verify that the TraceAE flag in the following directory equals 8192: <PS_HOME>\appserv\<Domain>\psappsrv.cfg Setting the TraceAE flag in the psappsrv.cfg file instructs the application server to generate a transformation trace log with the .aet extension, written to the following directory: <PS_HOMEy>\appserv\<Domain>\LOGS\ <operID>_<machine name>.AET The log file contains: The original XML structure as it entered the transformation engine. The output of the XML as it passed through each step of the transform program.