Version 2021

Errors Configuration File XML Structure

The errors configuration file lists all of the errors or special conditions that can occur in the application. The application uses this list to change the title and message of the error, to indicate whether the error is expected by the iframe in the event of an iframe request, or to find the page to which the user is redirected when an error occurs.

Error configuration settings are generally set in the errors.xml file, but they can also be made within pageConfig.xml. The recommended practice is to use a separate configuration file to ensure that your customizations are correctly propagated in future upgrades. You use the same XML structure whether you make the settings in errors.xml or in pageConfig.xml.

A sample of the XML structure for errors.xml is shown below, followed by a description of the elements and attributes that make up the file.

XML structure

<errors version="1.0">

    <error code="4" displayError="true" showContactInfo="false" target="" useOriginalMessage="false">

      <message XMLmerge_id="1" desc="The address name already exists. Please choose a different name." desc-id="mstrWeb.2316"/>

    </error>

    ...

    <error allowIframe="true" code="-5" displayError="true" showContactInfo="false" target="" useOriginalMessage="false">

      <title desc="Error Saving Personal Preferences." desc-id="mstrWeb.451"/>

      <message XMLmerge_id="1" desc="" desc-id=""/>

    </error>

    ...

</errors>

Description

The table below describes the XML structure of the errors configuration file. The four columns in the table include the following descriptive information:

Parent Element

  • Child Element 1

  • Child Element 2

Indicates the name of the element described in the next three columns. If this is a parent element, the names of all possible child elements are listed below the parent element.

Number of Nodes

Specifies the number of nodes that are required or allowed for the corresponding element in the Parent Element column. For example, if the value is "1", there must be only one node— no more, no less. If the value is "0 or more", the node is not required ("0"), but there is no restriction on the number of nodes that can be added ("or more"). If the value is "1 or more", the node is required ("1"), but there is no restriction on the number of nodes that can be added ("or more").  

Parent Element Attributes

Lists the separate attributes that can be used with the corresponding element in the Parent Element column. Included in parentheses beneath each attribute name are the attribute type and an indication of whether the attribute is required or implied. For example, the version attribute for the <errors> element has an attribute type of "nmtoken" (name token) and is implied. The code attribute for the <error> element has an attribute type of "cdata" (character data) and is required.

Description

Describes either a parent element in the Parent Element column or an attribute in the Parent Element Attributescolumn.

Parent Element

  • Child Element 1

  • Child Element 2

Number of Nodes Parent Element Attributes Description

<errors>

1

 

 

The <errors> element lists the errors or special conditions that can occur in the application. The application uses this list to change the title and message of the error, to indicate whether the error is expected by the iframe in the event of an iframe request, or to find the page to which the user is redirected when an error occurs. (When you use a separate configuration file, the <errors>element represents the root element of the file.)

config-src

(cdata / implied)

If the errors are defined in a separate file, the config-src attribute tells the page configuration file the location of the errors configuration file.

version

(nmtoken / implied)

If the errors are defined in a separate file, the version attribute indicates the release number of the errors configuration file. This attribute is useful for backwards compatibility because it lets the application know what features are available.

<error>

1 or more

 

The <error> element is used by the application to change the title and message of the error, to indicate whether the error is expected by the iframe in the event of an iframe request, or to find the page to which the user is redirected when the error occurs.

code

(cdata / required)

The code attribute identifies the error. This can be an error code from Intelligence Server or a value from the EnumWebAppErrorCodes interface.

displayError

(false | true  / implied)

The displayError attribute indicates whether the application should render the title, message, and contact information (if showContactInfo is set to 'true') when the error occurs.

showContactInfo

(false | true  / implied)

The showContactInfo attribute indicates whether the application should render the contact information (if available) from the Project Defaults page when error information is displayed to the user.

target

(nmtoken / implied)

The target attribute indicates the page to which the user should be redirected when the error occurs.

useOriginalMessage

(false | true  / implied)

The useOriginalMessage attribute indicates whether the application should display the original error message returned by the error object. (This is the error message generated on the back-end.)

<title>

0 or 1

 

The <title> element defines the title to be displayed in the error alert box.

desc

(cdata / implied)

The desc attribute provides the descriptor that the application should use to display the error title if the desc-id attribute is missing.

desc-id

(cdata / implied)

The desc-id attribute provides the Resource Bundle item id that the application should use to display the error title in the language of the user's locale.

<message>

0 or more

 

The <message> element defines the message to be displayed in the error alert box.

XMLmerge_id

(nmtoken / required)

The XMLmerge_id  attribute is a unique identifier that is used by the upgrade utility rather than the application.

desc

(cdata / implied)

The desc attribute provides the descriptor that the application should use to display the error message if the desc-id attribute is missing.

desc-id

(cdata / implied)

The desc-id attribute provides the Resource Bundle item id that the application should use to display the error message in the language of the user's locale.

See also