Customizing Error Handling Behavior

The Page Configuration file provides an <errors> node with child <error> nodes that can be used to override the default error-handling mechanism on a specific error-by-error basis. A generic <error> node is structured in the following manner:

• code— Unique error code from IDSSErrorCode interface. The following list describes where various error code definitions are stored:  

  Source of error code	Definition of error	Additional information
  Application Layer	com.microstrategy.web.app.EnumWebAppErrorCodes	Refer to the API Reference for definitions and descriptions.
  Web Beans Layer	com.microstrategy.web.beans.EnumBeanErrorCodes	Refer to the API Reference for definitions and descriptions.
  XML API Layer	com.microstrategy.utils.localization.WebAPIErrorCodes	For each error there is an associated error message defined in the WebAPIErrors message bundle in com.microstrategy.utils.localization Although theWebAPIErrorsmessage bundles contain error message definitions, Intelligence Server sends an error ID and description in the XML it returns. The error message definition returned by Intelligence Server is the error message actually displayed to the user. If you want to customize the error message that the user sees, you should customize theerrors.xmlfile, rather than theWebAPIErrorsmessage bundles. You do this by modifying the appropriate error message definition with the Web Customization Editor.

• displayError— Set value as true to display the error contents, or false not to (if you wish to perform a re-direction, for example, but not provide a specific error message) 

• showContactInfo— If value is set to "true", provides note to contact the administrator as defined in Project Preferences. 

• target— If the name of a <page> is provided, the user is redirected to that page. 

• useOriginalMessage— Set value to "true" to include the message defined and associated with the error ID caught. Set to false if you do not wish to include this message. 

• <message> child node— Provide your own custom error message using the desc and/or localized desc-id attributes.

Configuration Classes Involved in Error-Handling

This section provides background information into processes going on in the back end when the Web application handles errors.

The following configuration classes are involved in the page execution flow for error handling.

• ErrorInfo—Each <error> node defined in the <errors> node of the Page Configuration file is translated into an ErrorInfo structure, which contains the associated error ID, the target page, and the message that should be displayed.

• ErrorInfoList—This contains the list of ErrorInfo classes as mentioned in the errors.xml.

The ErrorInfoList is used by the Servlet or ASP.NET file-controller combination to indicate the steps to be followed if no other component handles an exception. It serves the following specific purposes:

• It provides information to the controller about the page to be rendered in case of an error. Each error can define a target attribute in the Page Configuration file which indicates the page that should be displayed in case a specific error occurs. For example, in case of an error where the session gets lost, the login page should be displayed.

• It overrides the back-end error message to display a friendly message to the user. Sometimes back-end errors are very technical for the user to understand. In such a case, if the error is defined and has an msgId (message ID) associated, a message corresponding to that message ID is displayed.

If an exception is raised all the way to the Servlet or ASP.NET file-controller combination, the controller checks if there is an error associated with the exception. If an error exists, it redirects to the corresponding page and sets the ErrorInfo on the page to a new object with the corresponding error message. If there is no error associated with the exception, execution continues on the same page and the ErrorInfo is set based on the message of the exception.