4 Modifying Catalog Files

Oracle Access Manager makes extensive use of catalog files to configure various system attributes and behaviors. Catalog files are those files ending with param.xml or msg.xml. These files control Oracle Access Manager behavior and message content, respectively. This chapter describes some of the many changes that can be made to these files. Topics include:

• Multibyte Data Support

• Setting Overall and Attribute Specific Date Formats

• Setting the Date Range for the Year List

• Changing the Color of the Configure Attributes Panel

• Changing Top Navigation Bar Application Name

• Changing User Name and Password Text on Login Page

• Changing Parameter Catalogs to Control Operation

• Changing Message Catalogs and MouseOver Text

See also:

A description of the param.xml file structure and contents, and a discussion of how to change them, is provided in "Oracle Access Manager Parameter Files".

4.1 Multibyte Data Support

UTF-8 encoding and support is provided automatically, whether you have a new 10.1.4 installation or upgrade an older installation to Oracle Access Manager 10.1.4. You do not need to make any changes to your environment. As with previous releases, data in the directory server is stored with UTF-8 encoding.

Note:

All of your directory data is UTF-8 format. Oracle Access Manager does not support a mix of data types in the directory.

For more information about globalization, localization, and multibyte support, see the Oracle Access Manager Introduction and the discussion in "XML Encoding".

4.1.1 XML Encoding

This discussion outlines the encoding schemes you will see in XML message files, and what to specify if you customize these files.

ISO-8859-1 Encoding: For pure English text, there is no difference between ISO-8859-1 encoding and UTF-8 encoding. For this reason, the encoding scheme for English language XML message and XSL files remains ISO-8859-1. The following example shows an XML message file (auditmsg.xml), from an English directory (\lang\en-us):

\IdentityServer_install_dir\identity\oblix\lang\en-us\auditmsg.xml

<?xml version="1.0" encoding="ISO-8859-1" ?> 
- <MessageCtlg xmlns="http://www.oblix.com" CtlgName="auditmsg">
...

Note:

XML files in earlier product releases may continue to specify encoding="ISO-8859-1", while earlier LST files that are converted to XML during the upgrade use UTF-8 encoding.

UTF-8 Encoding: For non-English languages, XML message files have encoding set as UTF-8, because ISO-8859-1 encoding cannot represent all characters in all languages. The following sample file is from the German language directory \IdentityServer_install_dir\identity\oblix\lang\de-de\auditmsg.xml:

<?xml version="1.0" encoding="UTF-8" ?> - <MessageCtlg xmlns:oblix="http://www.oblix.com" CtlgName="">  <Message MsgTag="ExAuditInitHandler">ExçêpäìÖÑExç ÖççürrêdÖçç ìÑì ähêä AüdìäAü MÖdülêMÖ ìÑìäìàlìzàäìÖÑìÑìäì. ThêT êxçêpäìÖÑêxç säàçksä ìsì: %1.</Message>  
...

It is worth mentioning that even within the English language directory  (\lang\en-us) some files state UTF-8 encoding because this encoding scheme is universal. For example, the following is the English version of data_types.xml:

<?xml version="1.0" encoding="UTF-8" ?>- <MessageCtlg xmlns="http://www.oblix.com" CtlgName="data_types.xml">  <Message MsgTag="OB_BIN">Binary</Message>   <Message MsgTag="OB_DN">Distinguished Name</Message>   <Message MsgTag="OB_TEL">Telephone</Message> 
...

In other language directories, German for example, the same file appears as:

<?xml version="1.0" encoding="UTF-8" ?> - <MessageCtlg xmlns:oblix="http://www.oblix.com" CtlgName="">  <Message MsgTag="OB_BIN">BìÑàryBì</Message>   <Message MsgTag="OB_DN">DìsäìÑgüìshêdDìsä NàmêN</Message>   <Message MsgTag="OB_TEL">TêlêphÖÑêTêl</Message> ...

Note:

When customizing XML message files, you can choose either encoding="ISO-8859-1" or encoding="UTF-8". In either case, the Oracle Access Manager XML parser reads the encoding tag in the file for correct processing.

See also:

For more information about XSL stylesheets and wrapper files, see "Designing the GUI with PresentationXML".

4.2 Setting Overall and Attribute Specific Date Formats

Problem: When you install Oracle Access Manager for the first time, a default format is used for all attributes that are configured to use a display type "Date". This default display format cannot be changed during installation. Later, you may need to change the default format, or set it differently for different attributes.

Solution: Change date formats in either of two ways, described in this section:

• Change the universal default value. This format is automatically used when attributes are configured to use display type "date".

  or,

• Change the value stored in the directory for each attribute. The stored format is used instead of the default format.

Oracle Access Manager supports the date display type formats in Table 4-1 to control handling of month (M), day (D), and year (Y). Use the format name shown in the data type column to make dates display in the format shown in the Example column. You can also specify a date separator to be used between the MDY values. The date separator can be any of the values "/". "-", or "" (no separator).

Table 4-1 Date formats

dateType Value	Example	Description
ObIntegerDate	946080000	Number of seconds after midnight of December 31, 1970
ObMDYDate	12/31/1999	mm/dd/yyyy
ObDMYDate	31/12/1999	dd/mm/yyyy
ObDMonthYDate	31-Dec-1999	dd-MMM-yyyy
ObMonthDYDate	Dec-31-1999	MMM-dd-yyyy
ObISO8061Date	19993112	yyyyddmm

4.2.1 Modifying Default Date Display

You need to modify the obDateSep and obDateType parameters in the globalparams.xml file, as described in the following procedure.

To modify the default date display type for the system

1. Open the globalparams.xml file using a text editor.

   IdentityServer_install_dir/identity/oblix/apps/common/bin/globalparams.xml file
   

2. Locate the lines to be changed (dash (-) and slash (/) are supported date separators).

   For example:

   <SimpleList>
     <NameValPair
        ParamName="obDateSep" Value="/"></NameValPair>
   </SimpleList>
   <SimpleList>
     <NameValPair
         ParamName="obDateType" Value="ObMDYDate" /></NameValPair>
   </SimpleList>
   

3. Change the value for the obDateType parameter, as needed, using one of the obDateType values from the table, then change the value for the obDateSep parameter.

   For example, the changed lines might look like this:

   <NameValPair ParamName="obDateSep" Value="-" /> 
         <NameValPair ParamName="obDateType" Value="ObMonthDYDate"/   >
   

4. Save your changes and close the file

5. Stop and start the Identity Server.

4.2.2 Modifying Date Display by Attribute

Date formats can also be set for specific attributes.

To modify the date display by attribute

1. From the Identity System Console, select Common Configuration.

2. On the Common Configuration page, select Object Classes, then select the class whose attribute is to be modified.

3. On the View Object Class page, select Modify Attributes.

   For any attribute of display type Date, you are shown two fields: the Date Type and the Date Separator.

4. Change the content of these fields to match the values you want to use.

4.3 Setting the Date Range for the Year List

By default, Oracle Access Manager provides a list of years ranging from 1993 to 2012. This is reasonable when the dates entered are those for badge issue or expiration dates, but is not useful if the date calls for a bigger range, such as one to include a birth date. You can extend the year date range that is carried in the basic.xsl stylesheet.

For a more detailed explanation of why this works, see "Designing the GUI with PresentationXML".

Note:

The standard Oracle Access Manager XSL files define only this one dropdown year date range. The method described here will have a global effect. The changes described in the following procedure must be made to both of these files.

To set the date range for the year list

1. Locate the basic.xsl stylesheet in the following directory:

   IdentityServer_install_dir/identity/oblix/lang/shared/basic.xsl
   

2. Copy the stylesheet to your custom directory to overwrite the wrapper file there.

   For example:

   IdentityServer_install_dir/identity/oblix/lang/langTag/Custom_Dir/basic.xsl
   

3. In the stylesheet in your custom directory, locate the templates for ObDateYear.

4. Locate the lines in the templates that begin and end the definition of the year list.

   - <xsl:template name="ObDateYear">... - <xsl:if test="@obyear">  - <option value="{@obyear}" selected="true">     <xsl:value-of select="@obyear" />    </option>  </xsl:if>  <option value="">----</option>   <option value="1993">1993</option>   <option value="1994">1994</option>   <option value="1995">1995</option> 
     ...
     <option value="2012">2012</option>
    </select>
   </xsl:template>
   

   where IdentityServer_install_dir is the directory where the Identity Server is installed, langTag is a language tag (en-us for example) in RFC 1766 format.

5. Copy, paste, and edit the pattern to extend the year date range.

   For example, the year list is defined by the following lines: (xsl:template name="ObDateYear"):

   <option value="">----</option>
         <option value="1992">1992</option>
            <option value="1993">1993</option>
   

   To extend dates beyond 2012, you would insert lines as follows:

   <option value="2012">2012</option>
         <option value="2013">2013</option>
            </select
            </xsl:template>
   

6. Copy the stylesheet to your custom style directory on the WebPass.

   WebPass_install_dir/identity/oblix/lang/langTag/Custom_Dir/basic.xsl
   

7. Stop and start the Identity Server and WebPass

4.4 Changing the Color of the Configure Attributes Panel

If you need to change foreground and background colors for the Configure Attributes panel, you can change the RGB values that control these colors in the oblixadminparams.xml file.

To change the Configure Attributes panel color

1. Locate the oblixadminparams.xml file in the directory:

   IdentityServer_install_dir/identity/oblix/apps/common/bin/oblixadminparams.xml
   

   where IdentityServer_install_dir is the directory where the Identity Server is installed.

2. Locate the entries:

   <NameValPair ParamName="config_meta_attr_applet_bg" Value="cccccc" /> <NameValPair ParamName="config_meta_attr_applet_fg" Value="000000" />
   

   The parameter bg controls background color, fg controls foreground. Values following the colon are RGB hex values for color.

3. Change the RGB values to set the new colors.

4. Save and close the file.

5. Restart your Identity Server for the changes to take effect.

4.5 Changing Top Navigation Bar Application Name

To change the mouseover text used for Identity System top Navigation Bar buttons, you edit the oblixbaseparams.xml file.

To change the top navigation bar application name

1. Locate the oblixbaseparams.xml file in the directory:

   IdentityServer_install_dir/identity/oblix/apps/common/bin/oblixbaseparams.xml
   

   where IdentityServer_install_dir is the directory where the Identity Server is installed.

2. In this file, locate the controlling text for any of the modules.

   For example, the text for Group Manager:

   </ValNameList>
   <ValNameList ListName="groupservcenter_application_info">
     <NameValPair ParamName="VERSION" Value="10.1.3" /> 
     <NameValPair ParamName="CODE" Value="GM1013" /> 
     <NameValPair ParamName="ID" Value="groupservcenter" /> 
     <NameValPair ParamName="PROGRAM" Value="../../groupservcenter/ bin/groupservcenter.cgi" /> 
     <NameValPair ParamName="DESCRIPTION" Value="Group Manager" /> 
     <NameValPair ParamName="NAVBAR_GIF" Value="T1TABgroupmanager" /> 
     <NameValPair ParamName="NAVBAR_GIF2" Value="T1TABgroupmanager" /> 
     <NameValPair ParamName="NAVBAR_GIFDIR" Value="../../common/ui/ style0/" /> 
     <NameValPair ParamName="WORKFLOW_ALLOWED" Value="true" /> 
     </ValNameList>
   

   The text following DESCRIPTION is the information that displays when you place the mouse pointer over the Group Manager button.

3. Change the text entry to the content needed.

4. Save and close the file.

5. Restart your Identity Server for the change to take effect.

4.6 Changing User Name and Password Text on Login Page

You can change the text on the default login page. By default, this page shows two text fields, Username and Password. You can change those text labels to a different value; for example, to show UID rather than Username as the login name, by editing the oblixbasemsg.xml file.

To change user name and password text on the Logon screen

1. Locate and open the oblixbasemsg.xml file in the directory:

   IdentityServer_install_dir/identity/oblix/lang/langTag/oblixbasemsg.xml
   

   where IdentityServer_install_dir is the directory where the Identity Server is installed and langTag is a language tag (en-us, for example) in RFC 1766 format.

   The oblixbasemsg.xml file contains paired sets of data, in the form:

   <Message MsgTag="message name">Message text</Message>
   

   Oracle Access Manager uses "message name" to locate the text that is to be displayed.

   Note:

   Do not change the "message name".

   Oracle Access Manager displays Message text, which is variable text and can be changed.

2. Locate the Message text that you want to change.

   For example:

   <Message MsgTag="MUsername">Username </Message>
   <Message MsgTag="MPassword">Password </Message>
   

3. Change the message text:

   For example, to change MUsername to UID:

   <Message MsgTag="MUsername">UID</Message>
   

4. Save and close the file.

5. Restart your Identity Server for the change to take effect.

4.7 Changing Parameter Catalogs to Control Operation

You can change Oracle Access Manager operation in ways that are not specifically called out in this guide. Oracle Access Manager is controlled primarily by hard-coded logic. At some points, generally at the user interface, the content of certain text files guides operation. You can change the content of some of these files.

See also:

A description of configurable parameter catalogs and their contents is provided in "Oracle Access Manager Parameter Files".

4.8 Changing Message Catalogs and MouseOver Text

You can revise mouseover text, or change the content of a displayed error message, by changing text in the message catalog.

As discussed elsewhere, multiple languages are available. Messages that were once in stylesheets are language dependent and are now defined separately as variables in message catalogs. The Oracle Access Manager directory structure consolidates all message catalogs for JavaScript files, XSL, and HTML.

• Any language-specific files are located in \lang\langTag.

• Any non-language specific objects are located within \lang\shared.

All the stylesheets have a language-specific wrapper in \lang\langTag\style0 which includes the main language-neutral version stylesheet in \lang\shared. This new wrapper segregates the main stylesheet functionality, which is language independent, from language-specific messages.

Language-specific messages are referred to through variables in message catalog files, as discussed in the following topics:

• Handling Language-Specific stylesheet Messages

• Handling Language-Specific Messages for JavaScript

4.8.1 Handling Language-Specific stylesheet Messages

The messages for stylesheets are defined in the message catalog:

\IdentityServer_install_dir\identity\oblix\lang\langTag\msgctlg.xsl

You need to ensure that all displayable strings in your older version stylesheets are placed in the 10.1.4 stylesheet message catalog. For example, suppose you have customized a version 6.1 stylesheet, navbar.xsl, in:

\IdentityServer_install_dir\identity\oblix\apps\common\ui\style0\navbar.xsl

where a message reads as:

<xsl:text> &lt;&lt; Click here to return to the previous application(s). </xsl:text>

In the 10.1.4 version of the stylesheet:

\IdentityServer_install_dir\identity\oblix\lang\shared\navbar.xsl

you need to modify the message to read:

<xsl:text> &lt;&lt; <xsl:value-of select="$MPrevAppln"/> </xsl:text>

and ensure that MPrevAppln is defined in the 10.1.4 message catalog:

\IdentityServer_install_dir\identity\oblix\lang\langTag\msgctlg.xsl

as follows:

<xsl:variable name="MPrevAppln">Click here to return to the previous application(s). </xsl:variable>

To handle language-specific message catalogs for XSL stylesheets

1. Locate the stylesheet containing the message.

   For example:

   \IdentityServer_install_dir\identity\oblix\lang\shared\navbar.xsl
   <xsl:text> &lt;&lt; Click here to return to the previous application(s). </xsl:text>
   

2. Copy the stylesheet to the custom style directory.

   For example:

   \IdentityServer_install_dir\identity\oblix\lang\langTag\Custom_dir\navbar.xsl

3. Modify the message in the stylesheet to use the appropriate message catalog parameter.

   For example:

   <xsl:text> &lt;&lt; <xsl:value-of select="$MPrevAppln"/> </xsl:text>
   

4. Locate the language-specific message catalog.

   \IdentityServer_install_dir\identity\oblix\lang\langTag\msgctlg.xsl
   

5. Ensure that the message parameter is properly defined.

   <xsl:variable name="MPrevAppln">Click here to return to the previous application(s). </xsl:variable>
   

6. Restart your Identity Server to have any changes to take effect.

4.8.2 Handling Language-Specific Messages for JavaScript

Pop-up messages in JavaScript files are also replaced by variables. The message catalog for JavaScript files is located in:

\WebPass_install_dir\identity\oblix\lang\langTag\msgctlg.js

Each language-specific message catalog is divided into sections that show the messages for specific JavaScript files, several of which are named as follows:

misc.js 
miscs.js
monitorwf.js 
personselector.js 
proxyadmin.js 
selector.js 
atickets.js 
wfqs.js 
deactivateuser.js
confirm.js

You need to ensure that all displayable strings are placed in the message catalog and the message catalog must be referenced through the I18N_GetMsg function.

For example, the code in the JavaScript file:

\WebPass_install_dir\identity\oblix\lang\shared\admin.js

that pops up a message:

alert("Room must have a name.")

appears as:

alert(I18N_GetMsg('MRoomNameReq'))

where MRoomName is defined in:

\WebPass_install_dir\identity\oblix\lang\langTag\msgctlg.js

as:

MESSAGE_CATALOG[ 'MRoomNameReq' ] = "Room must have a name.";

Note:

Oracle recommends that you retain the files in \shared as a reliable backup and instead copy the file to be customized into your custom style directory first

To handle language-specific message catalogs for JavaScript files

1. Ensure that all displayable strings for JavaScript files are placed in the message catalog:

   \WebPass_install_dir \identity\oblix\lang\langTag\ msgctlg.js

2. Ensure that the message catalog is referenced through the I18N_GetMsg function located in (automatically loaded):

   \WebPass_install_dir\identity\oblix\lang\shared\i18n.js
   

3. Restart your Identity Server and WebPass to have any changes to take effect.