Sun Identity Manager Deployment Guide

Advantages of Custom Message Catalogs

Custom message catalogs provide the following benefits:

Reduced maintenance in a clustered environment. Maintaining a separate message catalog means that you do not have to edit multiple copies of the WPMessages.properties file.
Simplified version control. It is easier to track changes and back up revisions if the customized messages are located in one place.
Upgrades to the product message catalog will not clash with any changes made to the customized entries.

How Identity Manager Retrieves Message Catalog Entries

Identity Manager retrieves message catalog entries in the following order:

User-defined message catalog (Only one user-defined message catalog is permitted.)
System-defined defaultCustomCatalog message catalog
config/WPMessages.properties file
WPMessages.properties file in the idmcommon.jar file

Message Catalog Format

In the WPMessages.properties file, entries are defined in the format KeyName=MessageText. In a customized message catalog, each entry is specified in a separate Msg element. The KeyName is specified in the id attribute, while the MessageText is text between the <Msg> and </Msg> tags. The following example illustrates a message catalog entry:

<Msg id=’UI_REMEMBER_PASSWORD’>Remember to set your password.</Msg>

The message text can contain HTML tags to control how the text is rendered, although this is not recommended. If you need to use HTML tags, use codes such as < and > instead symbols such as < and >.

Message text can also contain variables for data that Identity Manager will insert into the string when the string is displayed. The following example is the default message for the AR_CORRELATED_USER key:

Correlated account with user {0}.

The rendered version could appear as

Correlated account with user jdoe.

Creating a Customized Message Catalog

The following procedure describes how to create a user-defined message catalog.

To Create a User-Defined Message Catalog

If you are overriding default message catalog entries, locate the appropriate error message keys in the WPMessages.properties file. These keys must be specified in the customized message catalog.

If you are creating new messages, confirm that the keys do not appear in the WPMessages.properties file

Create an XML file or block with the following structure:

<?xml version=’1.0’ encoding=’UTF-8’?>
<!DOCTYPE Configuration PUBLIC ’waveset.dtd’ ’waveset.dtd’>
<Configuration name=’CatalogName’>
  <Extension>
    <CustomCatalog id=’CatalogName’ enabled=’true’>
      <MessageSet language=’en’ country=’US’>
        <Msg id=’KeyName’>MessageText</Msg>
        <Msg id=’KeyName’>MessageText</Msg>
        ...
      </MessageSet>
    </CustomCatalog>
  </Extension>
</Configuration>

where:

CatalogName is the name of the message catalog. This value will also be used to define the catalog in the System Configuration object.

KeyName is the message key name.

MessageText is a string that will be displayed on the graphical user interface. This text can contain HTML tags and variables.

If you are supporting a locale other than en_US, change the language and country attributes. If you are supporting multiple locales, create a separate MessageSet element for each locale.

See the Example section for a working sample.

Import the file or block into Identity Manager.

Load the System Configuration object and add the following line within the <Configuration><Extension><Object> element:

<Attribute name=’customMessageCatalog’ value=’CatalogName’/>

Save the changes to the System Configuration object.

Restart the application server. The new message catalog entries are now available to the system.

Example Message Catalog

The following example creates a customized message catalog named myCustomCatalog. It replaces the label and help text for the Import Exchange File subtab.

Example 8–1 Creating Customized `myCustomCatalog` Message Catalog

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE Configuration PUBLIC 'waveset.dtd' 'waveset.dtd'>
<Configuration name='myCustomCatalog'>
  <Extension>
    <CustomCatalog id='myCustomCatalog' enabled='true'>
      <MessageSet language='en' country='US'>
        <Msg id='UI_SUBNAV_CONFIGURE_IMPORT_EXCHANGE'>Import XML File</Msg>
        <Msg id='UI_SUBNAV_CONFIGURE_IMPORT_EXCHANGE_HELP'>Loads the specified XML file.</Msg>
      </MessageSet>
    </CustomCatalog>
  </Extension>
</Configuration>