Chat now with support
Chat with Support

Enterprise Single Sign-On 9.0.2 - Enterprise Access Management Customization Guide

Customizing Error Messages

Customizing Error Messages


You can customize error messages thanks to a file containing these messages.


The file is filled-in by the E-SSO administrator with one message per line, such as: <message number><Tab><message text>.
Example: 0x82002015 <tab> this is the customized text!

However, you can associate one message with several error codes, such as:
first message number>-<last message number><Tab><message text>.

Moreover, you can write a message text on several lines in the file (this will make the file easier to build and read rather than using \n in the text message). In that case, the syntax of the first line does not change. The next lines must follow this syntax: \+<rest of the text>.


0x82002001-0x8200208F Authentication error!
\+--Access is denied.

For more information on error codes, refer to One Identity EAM Console - Guide de l'administrateur.


The following conditions are mandatory:

  • The customized message files cannot contain message numbers that are unknown to EAM.
  • The customized messages files must be encoded with ANSI characters.
  • The text of the message is separated from its number by a tab character.
  • Each line that does not correspond to this format is ignored.
  • Each line starting with // is considered as a comment.
  • The text of the message can contain \t (tabulation) and \n (carriage return) characters for the display.

NOTE: If the customized text of the message number cannot be retrieved from the file, the default message corresponding to the resource is used.


Localizing and Naming the Message File


To define the message file, you must set:

  • Registry values in one of the following registry keys:
    • With GPO: HKEY_LOCAL_MACHINE\\Software\\Enatel\\
    • Locally: HKEY_LOCAL_MACHINE\\Software\\Policies\\
  • The MessageFileUsed value to 1 to activate the customized message file.

There are two cases to localize and name the message file. When you have:

  • No predefined language: set the EssoMessageFilePath value containing the full pathname of the message file such as C:\folder\file.txt.
  • One file per language: the message file is created by the administrator in the E-SSO installation directory. The file must be located in the folder set in one of the following registry keys:
    • InstallDirectory. OR
    • EssoMessage file Path

The search order of a message file is as follows (.<le> is the language extension):

  1. An ESSOMessageFile.<le> file in the directory indicated by FrameWork\Config\InstallDirectory
  2. The file indicated by FrameWork\Config\ESSOMessageFilePath
  3. An ESSOMessageFile.<le> file in the repository indicated by FrameWork\Config\ESSOMessageFileInstallDir
  4. An ESSOMessageFile.<le> file in the application’s current directory.

The <language extension> is the Windows number (two-digit hexadecimal value: 09, 0C, 01...) corresponding to the E-SSO installation language.

The following <language extension> list is supported:

  • 01: Arabic
  • 07: German
  • 09: English
  • 0A: Spanish
  • 0B: Finnish
  • 0C: French
  • 10: Italian
  • 11: Japanese
  • 13: Dutch
  • 19: Russian
  • 1D: Swedish


Encoding the Messages File

The customized messages files must be encoded with ANSI characters. However, you can use files encoded with UTF-8 characters by setting the following registry value: FrameWork\Config\EssoMessageFileUTF8 (REG_DWORD)

The possible values you can set are:

  • 0 (default): the message files contain ANSI text strings.
  • 1: the message files are UTF-8 encoded.


Managing a Cache


To display an error message, E-SSO performs a sequential search until it finds the customized message associated with the provided error code. If no customized message is set, the default message is used.


To speed up the search and display of an error message, you can activate the error message caching. When the message caching is activated, E-SSO:

  • Loads the contents of the customized message file into the memory.
  • Performs an indexed memory search to retrieve a customized message.
  • Updates the memory cache when the customized message file is modified.

To activate the message caching, set the REG_DWORD EssoMessageCacheUsed registry value to 1 under the E-SSO configuration registry keys.


Related Documents