Oracle Applications use messages to communicate with users. Typical messages include warnings and error messages, brief instructions, and informative messages that advise your user about the progress of concurrent requests, work done, and anything else of interest or helpful to users. Forms-based applications display messages on the user's screen; applications also print messages to output and log files.
Messages are part of the product, and should be treated with the same amount of care and attention to the user interface as a form. These message standards help you write messages that are brief, clear, and informative. When you follow these standards and use Message Dictionary, your application provides messages that are easy to understand, document, edit, and translate into other languages, resulting in an application that is easy to support and enhance.
A message type classifies your message as an Error, Prompt, and so on. Generally speaking, error messages display information about problems, while hint messages display helpful information that appears during the normal use of your form.
An error message contains substantive information about your application that a user should consider and acknowledge. An error message does not always indicate a malfunction or user mistake. It may simply be a warning.
Most commonly, an error message informs your user of an invalid entry or action, or it reports a function that is not operating correctly.
A message name is an internal identifier for a message in your application. A message name can be up to 30 characters long.
A message name, together with your application name and language name, uniquely identifies your message. You specify the message name when you call Message Dictionary from a form or program module.
A message prefix is a short code that automatically precedes your message number and text for those messages that have numbers. The standard message prefix is APP:<application short name>.
A message number is a number that precedes your message when your message is displayed to users. A message number is not changed by translators. The message number also helps your user determine which application generates a message, and helps your user to locate a message in the documentation.
If you define a message number for your message, Message Dictionary automatically precedes your message with the Oracle message standard "APP:<application short name>-nnnnn", where APP is a standard message prefix for Oracle Applications and nnnnn is your message number. Your message number may be up to 5 digits long. For example, your user might see "APP:SQLGL-0032 Please enter ..." for an Oracle General Ledger message.
The Description field in the Messages form describes your message for other developers and translators. You can enter up to 230 characters of text in your message description. Typically this field contains information for translators about the context of your message.
A variable token, also called a substitute token, acts as a placeholder when you define message text. When Message Dictionary displays a message, it substitutes a developer-specified value for each variable token, allowing you to create dynamic messages.
Boilerplate is any fixed text contained in a form. Boilerplate includes form titles, zone titles, region titles, and field prompts.
The following suggested standards provide a consistent naming convention for message names.
Message names are hardcoded into forms and programs and should never change.
Use descriptive words and make your message names meaningful to other developers. Your name should clearly summarize the content or purpose of the message.
Message names can contain no more than 30 characters.
Make message names all uppercase. Although message names are case insensitive, this provides consistency so that messages can be searched for easily.
Do not use spaces in message names; use underscore characters instead to separate words.
Message names should not contain message numbers (or prefixes), because message numbers may change over time.
Include your two-to-three-character application short name or abbreviation as the first word in each message name (optional).
Include a group identifier that indicates the functional area or organizational function that your message addresses. Your group identifier should correspond to the group identifier you use in your form names, which helps break your set of messages into smaller, manageable chunks.
| Right: | FND_FLEX_SEGMENT_NOT_REGISTERED [group identifier is FLEX, for Flexfields] |
| Right: | FND_MD_MESSAGE_NOT_FOUND [group identifier is MD, for Message Dictionary] |
| Wrong: | FND_MESSAGE_NOT_FOUND |
Some examples of message names are:
INV_UOM_REQUIRED
AP_MATCH_BAD_SEGMENT
SPEC_INFO_IN_USE
MAND_PARAMETER_NULL
ZOOM_BAD_FIELD
AFDICT_HISTORY_BUTTON
Oracle Applications products all have assigned message number ranges. These ranges, and messages that have non-zero numbers appear in the Oracle Applications Messages Manual. Messages without numbers are not included.
Use a number for all errors and warnings, but not hints, notes or questions.
All errors and warnings now have message numbers to help developers trace a message if the problem comes from an installation running in a language other than English.
Message Dictionary displays message numbers with the message prefix. The message prefix is APP:<application short name>-.
The application short name makes messages easier to trace, especially after messages have been translated
If your message number is less than 1000, Message Dictionary extends your number to four places with leading zeros.
A zero (0) message number is equivalent to a null (blank) message number and does not display (the prefix does not display either).
Messages with a null message number that have been loaded into Message Dictionary from a file will have the message number changed to zero.
Do not put the message prefix or a message number in your message text.
Here are some guidelines to help you decide whether to use a number.
If the answers to any of the following questions are yes, the message probably needs a number:
Is this a message that someone such as a support representative might want to look up in a manual (for example, a user might call a support representative, say "I got an APP-12345 error", and expect the representative to know what the message means)?
Is this a message that requires someone to get assistance (from a system administrator, for example) to solve the problem?
Is this a message where correcting the problem may require reading the message more than once or writing the message down?
If the answers to any of the following questions are yes, the message probably does not need a number:
Is this a text fragment such as a token translation?
Is the message merely explanatory and informative (for example, "Your concurrent request number is 86477")?
For custom applications and third-party products not included in the published message number ranges, we recommend that you avoid using message numbers 0-2999. Those are Oracle Application Object Library messages that appear in cross-product features such as flexfields and concurrent processing, and they may appear in your own applications.
In general, it may be useful to avoid duplicating any numbers that appear in Oracle Applications products even though there is no technical requirement to avoid duplication. Keeping your custom messages numerically separate from Oracle Applications messages may help users distinguish whether a problem stems from an Oracle Applications product or a custom application, and help them decide where they should seek assistance for problems.
If you want to avoid clashing with numbers that Oracle Applications products use or may use in the foreseeable future, we recommend that you number messages using 400000 (400,000) and up (the largest possible message number is about 2 billion).
Message type is used primarily for translation purposes. The correct message type (Error, Title, and so on) allows translators to distinguish between text that can be translated without worrying about length expansion, such as error messages, and text that has strict expansion limits, such as field prompts for a form. Note that for Oracle Applications Release 12 messages in English, one character is equivalent to one byte, but in other languages one character may require more than one byte.
| Error | Type is ERROR in script file. Use for error and warning messages. Messages with the Error type can be up to 1260 characters long in English and allow a translation length expansion up to a maximum length of 1800 bytes (at least 30% allowed expansion). Messages with the Error type should have a message number. |
| Note | Type is NOTE in script file. Use for informational or instructional messages (typically messages displayed using FND_MESSAGE.SHOW). Messages with the Note type can be up to 1260 characters long in English and allow a translation length expansion up to a maximum length of 1800 bytes (at least 30% allowed expansion). Messages with the Note type should usually not have a message number. |
| Hint | Type is HINT in script file. Use for informational or instructional messages (typically messages displayed using FND_MESSAGE.HINT). Messages with the Hint type can be up to 190 characters long in English and allow a translation length expansion up to a maximum length of 250 bytes (at least 30% allowed expansion). |
| Title | Type is TITLE in script file. Use for window titles, report titles, report group titles, graph titles, and so on. Messages with the Title type can be up to 61 characters long in English and allow a translation length expansion up to a maximum length of 80 bytes (at least 30% allowed expansion). |
| 30% Expansion Prompt | Type is 30_PCT_EXPANSION_PROMPT in script file. Use for field prompts, report column labels, graph labels, and so on, where space has been allowed for up to 30% expansion during translation (allowing for a mimimum of 10 bytes after translation, except for approved phrases and abbreviations). For example, a 23-character field prompt in English would be allowed to expand to 30 bytes when translated. Most prompts and boilerplate should use this type. However, if you have more expansion space available on your form or layout, use the appropriate type (50% or 100% Expansion Prompt), especially for short prompts. |
| 50% Expansion Prompt | Type is 50_PCT_EXPANSION_PROMPT in script file. Use for field prompts, report column labels, graph labels, and so on, where space has been allowed for up to 50% expansion during translation (allowing for a mimimum of 10 bytes after translation). For example, a 10-character field prompt in English would be allowed to expand to 15 bytes when translated. |
| 100% Expansion Prompt | Type is 100_PCT_EXPANSION_PROMPT in script file. Use for field prompts, report column labels, graph labels, and so on, where space has been allowed for up to 100% expansion during translation (allowing for a mimimum of 10 bytes after translation). For example, a 6-character field prompt in English would be allowed to expand to 12 bytes when translated. |
| Menu Entry | Type is MENU in script file. Use for menu entries, such as choices on the Special menu, especially where such entries have accelerator keys (keyboard equivalents) denoted by a double ampersand (&&). Ideally, menu entries should be less than about 25 characters long in English (for aesthetic reasons). The maximum length for a menu entry message is 46 bytes in English (60 bytes after translation). |
| Token | Type is TOKEN in script file. Use for messages that are used as token values in other messages. This type is for backwards compatibility only, and should not be used for new messages (new messages should not use tokens that require translation). You must include a message description that contains the name of the message that uses the token and any translation length restrictions. |
| Other | Type is OTHER in script file. Use for text not covered by any other type. You must include a message description explaining the message and its translation requirements (for example, if the message should not be translated or has a specific maximum length). |
Use the description field to tell translators and other developers the purpose of the message, where it is used, and how it is used. For example, if you define a message to use as a label for a Special menu entry, you should mention that in the description field for your message. The message description is especially important for short pieces of text that will be translated, so that translators have some idea of how the text would appear.
Even if your message is unambiguous, translators may need to know where it occurs so that they can match their translations of your message to their translations of other text in related areas of your application.
Include a message description for any of the following cases:
Table and column names in the message
Uppercase or lowercase values in the message (indicating whether values should be translated)
Any uppercase words in the message, or if the entire message is uppercase
Any words other than tokens that contain underscores ( _ )
Tokens that represent sentence fragments
include what text is expected to replace the token.
If your message contains a nonobvious variable token name, use your notes field to tell translators what your token represents.
Very short messages or text fragments
include where and how the message is used (button label, form message, boilerplate, etc.). If it is a text fragment used to build another message (as a token value), include the text defined for the target message and the target message name so the translator can see the expected context of the fragment.
Ampersands ( & ) other than those preceding tokens (for example, for menu accelerator keys, especially where the ampersand is in the middle of a word)
Messages where the text must match the translated text in some other part of the application, such as field names, profile option names, menu paths, and so on
Messages defined as Oracle Application Object Library messages that do not belong to Oracle Application Object Library
include name of product using the message, where and how the message is used (button label, forms message, menu entry, boilerplate, etc.).
Enter your message notes using the following format:
This message appears context.
where context is when and where your message appears. (You can use any format to explain token names, as long as your notes are clear and well-written).
| Example: | This message appears only when making new entries in the Enter Journals form. |
| Example: | This message appears in the Invoice Register report to indicate division by zero. |