Bookshelf Home | Contents | Index | PDF     

Oracle® Business Intelligence Presentation Services Administration Guide > Customizing the Oracle BI Presentation Services User Interface >

Customizing the Oracle BI Presentation Services User Interface Using XML Message Files

This section explains how to customize text elements in message files to manage the default appearance and behavior of the Oracle BI Presentation Services user interface using XML strings.

NOTE:  The intent of this section is to allow organizations that have XML expertise to perform additional customization. If you do not have this expertise, enlist the assistance of a third party to help you with customization.

This section contains the following topics:

NOTE:  Other topics in this guide describe additional customizations that you can perform by customizing text elements in message files, such as Configuring Answers Pivot Table Settings.

About the Oracle BI Presentation Services User Interface XML Message Files

You can customize many of the text elements that appear in Answers, Delivers, and on dashboard pages. Examples of text elements include the content of text strings, the text for prompts such as the names of links and buttons, and the text of error and informational messages that are displayed to users as the result of an action.

These text elements are contained in external message files that are distributed with Oracle BI Presentation Services. The message files are in XML format. Language-specific messages are located in the folder SAROOTDIR\web\msgdb\l_xx\messages, where SAROOTDIR is the installation directory and xx is the language identifier of the selected locale (for example, for english-usa, the identifier is en). Language-independent messages are located in the folder SAROOTDIR\web\msgdb\messages, where SAROOTDIR is the installation directory.

You should not edit the message files directly because any changes would not be retained when you install newer versions or service releases. For more information, read Customizing Oracle BI Presentation Services XML Messages.

How Oracle BI Presentation Services XML Message Files Are Structured

The name of a particular message file indicates the kind of content that it holds. For example, messages in the file logonmessages.xml hold message content related to the act of logging on and off the application. Within each XML file, the WebMessage name= elements define the names of the messages. These elements are called message identifiers.

A particular message may also reference the content of another message by using a MessageRef element. For example, the following message in the file logonmessages.xml references the value of another message:

<WebMessage name="kmsgAuthenticateNotLoggedOnToLogOnClickHere">
 <HTML>
  You are not currently logged in to the
  <MessageRef name="kmsgProductServer" />

The entry <MessageRef name="kmsgProductServer" /> in the previous message indicates that the name of the server is taken from the value of the kmsgProductServer message identifier. This message is located in the file productmessages.xml, and its value is Oracle BI Server:

<WebMessage name="kmsgProductServer" CRC="nnnnnnnnnnnnnnnnnnnn">

 <TEXT>Oracle BI Server</TEXT>

Some messages, such as those that contain copyright information and product names, are protected and cannot be changed. If you read the file productmessages.xml, there is text preceding the WebMessage elements indicating that the associated names cannot be changed.

Customizing Oracle BI Presentation Services XML Messages

This section explains how to change the content of unprotected messages and provides several examples. The intent is to show you how to alter the text of messages, and not to teach you XML.

To customize messages

  1. Create message identifiers with similar names and customize their text.
  2. Create a custom messages folder named customMessages.

    NOTE:  Organizations that have Oracle Business Intelligence applications may already have a file present in this folder. This file enables Oracle Business Intelligence support for Oracle Business Intelligence applications, and should not be modified, moved, or deleted.

  3. Place the messages in one or more XML files in the customMessages folder, and then place the customMessages folder in this location:

    SADATADIR\web\msgdb\l_xx

    where SADATADIR is the data directory, and xx is the language identifier of the selected locale (for example, for english-usa, the identifier is en).

    If you are not concerned with multiple languages, place the folder in the l_en folder. Messages default to l_en if a language-specific version is not found. You need to create the l_xx folder in the SADATADIR\web\msgdb folder.

  4. Restart Oracle BI Server.

You can create multiple XML files in the customMessages folder, or create a single XML file that holds customized messages, for example, custommessages.xml. This is because the application goes through the customMessages folder and reads every file that has an XML extension, regardless of the file's name. If you create many customized messages you may prefer to organize them into separate files.

NOTE:  If you intend to support multiple languages, place control messages (which are messages that are not translated) into one file named customcontrolmessages.xml. Place messages that are translated into another file named, for example, customuimessages.xml. This places localized versions of the customuimessages.xml file in each language folder as appropriate, such as \OracleBIData\web\msgdb\l_de\customMessages, \OracleBIData\web\msgdb\l_fr\customMessages, and so on.

Links are a special case. Modifications made to link messages display as expected in dashboards and delivers. To make these same modifications display in Answers, you must modify the kuiAnswersMainBar message.

To edit a custom message file

  1. Make a backup of the original file in a separate folder.
  2. Make a development copy in a different folder.
  3. Edit the development version of the file in a text or XML editor.
  4. Replace the original file in the customMessages folder with the newly edited file.
  5. Test the new file.
  6. (Optional) Delete the backup and development copies.

Resolution of Oracle BI Presentation Services XML Message Name Elements

During initialization, the Oracle BI Presentation Services replaces the WebMessage name default text with text from equivalently named elements in any customized XML file, based on the following precedence order, from highest to lowest:

  • XML in SADATADIR\web\msgdb\l_xx\customMessages folder (language- specific folders), where SADATADIR is the data directory.
  • XML in SADATADIR\web\msgdb\l_en\customMessages folder (for language-specific user logons if WebMessage name elements reside here, but are not in language-specific files).
  • XML in SADATADIR\web\msgdb\customMessages folder.
  • XML in SAROOTDIR\web\msgdb\l_xx\messages folder, where SAROOTDIR is the installation directory.
  • XML in SAROOTDIR\web\msgdb\messages folder.

As an example, when Oracle BI Presentation Services starts up, it first reads the messages in the folder SAROOTDIR\web\msgdb\l_xx\messages in the installation directory, and then reads the messages in the folder SADATADIR\web\msgdb\l_xx\customMessages. It replaces the default text for those messages with the customized text. If you attempt to alter the text of a protected message, a message is displayed in its place indicating that you attempted this.

Sample Oracle BI Presentation Services XML Template

The following is a sample template for a custommessages.xml file in the folder SADATADIR\web\msgdb\l_xx\customMessages, where SADATADIR is the data directory. An example custommessages.xml file follows the template.

Every message begins with a <WebMessage name=> element and ends with a
</WebMessage> element. The message text that you can customize is contained between <TEXT> elements or <HTML> elements. To suppress the display, delete the text between the elements.

    <?xml version="1.0" encoding="utf-8"?>
    <WebMessageTables>

         <WebMessageTable system="Custom Messages">
         <!-- The name of a message must match the name of the message you are overriding. -->
         <WebMessage name="kmsgExampleOverrideMessage">

         <!-- A message can have TEXT and/or HTML versions of it. It is not necessary to have both. (TEXT will be automatically converted to HTML when necessary). -->

         <TEXT>Example message.</TEXT> <!-- Format used in a text only output -->
         <HTML><b>Example message with bold HTML tags.</b></HTML> <!-- Format used in an HTML output -->

    </WebMessage>
</WebMessageTable>

</WebMessageTables>

To create a sample template

  1. Replicate the sample template in a text editor.
  2. Name the file custommessages.xml (or any name you choose).
  3. Place the file into the customMessages folder you have created in the appropriate SADATADIR\web\msgdb\l_xx folder.

Sample Oracle BI Presentation Services custommessages.xml File

The following example shows four customized messages placed in the custommessages.xml file.

    <?xml version="1.0" encoding="utf-8"?>
    <WebMessageTables>

   <WebMessageTable system="Custom Messages">

    <!-- First message -->
         <WebMessage name="kmsgAuthenticateRemembermyIDandpassword">
         <TEXT>Remember my signon name and password.</TEXT>
    </WebMessage>

    <!-- Second message -->
         <WebMessage name="kkmsgPrivilegeDisplayerAccountUnknown">
         <TEXT>Unknown Account (<Param insert="1"/>). Call the Help Desk at extension 9999 to set up a new account.</TEXT>
    </WebMessage>

    <!-- Third message --
         <WebMessage name="kmsgWelcomeFrameCreateNewRequest">
         <HTML>Create a <b>new request</b> by clicking on a Subject Area below. After creating the request, click on the <b>Done</b> button at the bottom of the page.</HTML>
    </WebMessage>

    <!-- Fourth message -->
         <WebMessage name="kmsgUIAdmin">
         <HTML></HTML>
    </WebMessage>

</WebMessageTable>

</WebMessageTables>

  • The message identifier of the first message being customized is "kmsgAuthenticateRemembermyIDandpassword". The default text for this message is located in the file logonmessages.xml in the folder SAROOTDIR\web\msgdb\l_xx\messages, where SAROOTDIR is the installation directory.
  • The message identifier of the second message being customized is "kmsgPrivilegeDisplayerAccountUnknown". The default text for this message is located in the file viewmessages.xml in the folder SAROOTDIR\web\msgdb\l_xx\messages, where SAROOTDIR is the installation directory. This message contains a variable,
    ( <Param insert="1"/> ).

    NOTE:  If you are customizing a message that contains a variable, do not alter the variable. In the UNIX environment, be careful to preserve the case of the message name being customized.

  • The message identifier for the third message being customized is "kmsgWelcomeFrameCreateNewRequest". The default text for this message is located in the file searchsysmessages.xml in the folder SAROOTDIR\web\msgdb\l_xx\messages, where SAROOTDIR is the installation directory. This message is in HTML format and uses an HTML tag ( <b> ) to display text in bold letters.
  • The message identifier for the fourth message being customized is "kmsgUIADMIN". The default text for this message is located in the file uimessages.xml in the folder SAROOTDIR\web\msgdb\l_xx\messages, where SAROOTDIR is the installation directory. This message is in HTML format. This message identifier displays the Admin link at the top of each Answers, Delivers, or dashboard page. Deleting the Admin text between the <HTML> and </HTML> tags suppresses the display of the link.
  
Oracle® Business Intelligence Presentation Services Administration Guide Copyright © 2007, Oracle. All rights reserved.