Skip Headers
Oracle® Fusion Applications Developer's Guide
11g Release 1 (11.1.1.5)

Part Number E15524-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

7 Defining and Using Message Dictionary Messages

This chapter provides a detailed overview of Message Dictionary messages and discusses how to use them in Oracle Fusion Applications.

This chapter contains the following sections:

7.1 Introduction to Message Dictionary Messages

The Message Dictionary stores translatable Error and Warning messages for Oracle Fusion Applications. These types of messages provide information about business rule errors, such as missing or incorrect data, and how to resolve them, warn about the consequences of intended actions, inform about the status of an application, pages, or business objects, and indicate that processes and actions are performing or are completed.

All other messages can be stored in resource bundles, with the exception of strings and messages that need to be accessed by C or PL/SQL programs (resource bundles only can be accessed by Java programs). These exceptions can be stored in the Message Dictionary as Informational and UI String messages. Resource bundles also can be used to store job output or log file messages for Oracle Enterprise Scheduler (ESS) Java programs and test output messages for Java Diagnostic Testing Framework tests.

The Error, Warning, Information, and UI String message types are described in detail in Section 7.2, "Understanding Message Types."

Note:

Because the messages are stored in Application Object Library FND_MESSAGE_% tables, these types of messages are sometimes referred to as FND messages.

By using the messages in the Message Dictionary, you can define standard messages that you can use in all your applications, provide consistency for messages within and across all your applications, define flexible messages, and change or translate the text of your messages without regenerating or recompiling your application code.

Note:

Non-message strings, such as labels, report headings, and message fragments are typically stored in Oracle Application Development Framework (ADF) resource bundles. However, because Oracle ADF resource bundles only can be accessed by Java programs, you can store these types of strings in the Message Dictionary if C or PL/SQL programs need to access them.

Message Dictionary messages are composed of several message components, which enable you to author different messages for different audiences, such as the end user or help desk personnel, and for different conditions, such as when an action must be performed before the user can continue. For more information, see Section 7.3.4, "About Message Components."

Messages can be displayed to the UI and written to logs and incidents. Incidents are collections of information about system errors for which end users might require assistance from help desk personnel. An incident contains information about the state of the system at the time the problem occurred. Help desk personnel can use incidents to supply internal support personnel or Oracle support personnel with information about problems that need to be resolved.

You can set up a Message Dictionary message such that an incident and an associated log entry are created automatically. This is referred to as implicit incident creation.

For information on to how to generate incidents and log entries from Message Dictionary messages, see Section 7.5, "Understanding Incidents and Diagnostic Logs with Message Dictionary." For information about how incidents and log entries can be used, see the "Managing Oracle Fusion Applications Log Files and Diagnostic Tests" chapter and the "Introduction to Troubleshooting Using Incidents, Logs, QuickTrace, and Diagnostic Tests" chapter in the Oracle Fusion Applications Administrator's Guide.

You use the Manage Messages task in the application's Setup and Maintenance work area to create and maintain Message Dictionary messages. For more information, see the Oracle Fusion Applications Common Implementation Guide.

Oracle Fusion Applications provide some common messages in the Message Dictionary with message names that begin with FND_CMN_. You should ensure that you do not modify or replace these messages.

7.2 Understanding Message Types

All messages must have a message type. The message type indicates which message components are applicable, determines whether implicit logging and incident creation occurs, and determines the logging level if the message is logged. For information about message components, see Section 7.3.4, "About Message Components." For information about logging and incident creation, see Section 7.5, "Understanding Incidents and Diagnostic Logs with Message Dictionary."

The valid values for message types are fixed and therefore cannot be customized.

Error Messages

Use the Error message type for messages that alert the user to data inaccuracies when completing a field, submitting or saving a page, navigating from the page, or when an application or unknown failure occurs. An error message requires attention or correction before the user can continue with their task.

Warning Messages

Use the Warning message type for messages that inform users about an application condition or a situation that might require their decision before they can continue. Warning messages describe the reason for the warning and potential consequence of the selected or intended action by users. The warning requires the attention of users, and a standard question might be posed with the warning, or the warning can take the form of a statement.

Information Messages

The Information message type is intended for the following types of strings:

UI String Messages

Use the UI String message type for non-error and non-warning strings that need to be stored in the Message Dictionary but are not complete messages, such as prompts, titles, or translated fragments. For example, "Upload Process Parameters." Note that UI String messages are processed exactly as Information messages.

You either can use the Information type for all non-error and non-warning messages, or you can choose to store complete messages as Information messages and fragments as UI String messages. For example, if your messages must pass a review process, you might choose to use the UI String message type for messages that do not need to conform to message guidelines.

7.3 Understanding Message Content

Messages must have unique message names. Although message numbers are not required, you should use them for error messages in order to make it easier for users to identify the precise error in logs, and to enable users to find more information about the error in various help sources, including those in different languages.

Translation Notes are not required, but can be used to store notes about context and use of the message. Translation notes can also be used to provide information to help translators understand how the message is used and thus provide a more accurate translation.

Different combinations of information are provided depending on the nature of the message and the intended audience, such as end user or help desk personnel. This is accomplished using message components.

Tokens are also an important part of messages. Tokens are the programmatic parts of message text that allow the substitution of other text or values into the message at run time. They are used as a way include variable information in the same message. In Oracle Fusion Applications, tokens are used for dates, numbers, and specific types of text.

7.3.1 About Message Names

Every message must have a unique name. You should include a unique prefix that makes it easier to find your custom messages and that helps to avoid name conflicts with non-custom messages. Names that begin with FND_CMN_ are reserved for Oracle Fusion Applications common messages.

7.3.2 About Message Numbers

A unique and persistent message number can be included with each message. The message range 10,000,000 to 10,999,999 has been allocated for customers' own messages.

When displayed, the number takes the format of (Application Shortname-Number). For example:

Descriptive flexfields do not support unit of measure enabled segments. (FND-2774)

If the message does not have a message number, the formatted number is not displayed.

7.3.3 About Translation Notes

A translation note (message context) is a descriptive note to developers, translators, and message customizers describing where and how the message is used. The note is not translated and cannot contain tokens. It is never displayed to end users or help desk personnel. The maximum size of this field is 4000 characters.

7.3.4 About Message Components

Message components enable you to define messages for different audiences and address additional information needs. All messages require a value for the Message Text component, the other components are optional.

Both help desk personnel and end users see the message text and cause components. For the other components, you can use the Message Mode profile option to configure whether the end user or help desk personnel (or both) see each type of component. For example, you can set the profile option to enable a particular user to see the Message Admin Detail component. You use the Manage Profiles task in the application's Setup and Maintenance work area to set the profile option.

Note:

Incidents contain all message components. For more information about incidents, see Section 7.5, "Understanding Incidents and Diagnostic Logs with Message Dictionary."

Message Text

Message text is required. This is a brief statement of the operation attempted and the problem that occurred as a result, or information that the user needs to know. The text is included in log and incident creation messages. The content in this field is customizable and the text can contain tokens. The maximum field size for messages stored in the Message Dictionary is 240 characters.

If the entire message, after tokens have been substituted, exceeds the 240 character limit, the message text is truncated. To allow room for expansion in other languages, the US version of any translated column should be no more than 70% of the maximum possible length. (For example, 240 character short text becomes 160 characters in US).

Caution:

Tokens are just values substituted into the message at runtime. Tokens must come from a translated source unless it is a number, seed data, technical information, or a name that is not translated. Extreme care must be taken with tokens when substituting translatable data. You must make sure that it makes sense at run-time

For more information, see Section 7.3.5, "About Tokens."

The text appears in bold at the top of the message window region. In addition, the message text is the only message component displayed in limited real estate UIs, such as pagers and phones. Therefore, the message text should be clear enough to be understood alone when used in this context.This is a required field for all message types.

Message User Detail

This is a more detailed explanation of the problem identified in the short message and its audience is the end user. This field includes the details that are appropriate and meaningful to the end user and should outline exactly what caused the error to occur. For example, in the case of an incident creation error message, this field can be used to provide the user with information about the type of error. The content in this field is customizable and the text can contain numerous tokens. The maximum field size is 4000 characters.

The text appears in normal letters just below the short message. This field is optional.

Message Admin Detail

Message Admin Detail text provides a detailed explanation of the problem identified in the short message. This information is never seen by the end user. This field is for technical details that are not meaningful to an end user. The content in this field is customizable and the text can contain numerous tokens. The maximum field size is 4000 characters.

Although this component is optional, it should be used for errors that require help desk processing, and should contain information to assist the help desk personnel to resolve the issue, such as the technical background.

Message Cause

The message cause text provides for the end user a concise explanation of why the error occurred. It lists reasons for the failure such as a prerequisite that is not met, incorrect inputs, an anticipated but incorrect action, and so on. The content in this field is customizable and the text can contain numerous tokens. The maximum field size is 4000 characters.

The word Cause (in bold) is prefixed automatically to the beginning of the cause text. This text appears below the user detail, if available. This component is optional and is only applicable for messages of type Error and Warning. The components Cause and User Action are mutually required, meaning if you enter one you must enter both.

Message User Action

This component is for messages that state the action that the user must perform in order to continue and complete the task. This is intended for and seen by the end user. The content in this field is customizable and the text can contain tokens. The maximum field size is 4000 characters.

The word Action (in bold) is prefixed automatically to the beginning of the action text. This text appears below the cause text. This component is optional and is only applicable for messages of type Error and Warning.

Message Admin Action

Message Admin Action messages state the action that must be performed in order to resolve the error condition. This should contain the information that the help desk personnel requires to resolve the error. The content in this component is customizable and the text can contain tokens. The maximum field size is 4000 characters.

The word Action: (in bold) is prefixed automatically to the beginning of the action text. This text appears below the cause text and is only applicable for messages of type Error and Warning. This component is only enabled if Cause and User Action are entered. If this is NULL and User Action information is available, then the User Action information is displayed.

7.3.5 About Tokens

Tokens are identified in the message text by their use of curly brackets and all uppercase letters. The token values are supplied at runtime by the code that raises the message. For example, the following token {MATURITY_DATE} is replaced by a date when the user receives the error message on their screen:

"Enter an effective date that is the same as or later than {MATURITY_DATE}".

Becomes:

"Enter an effective date that is the same as or later than 25-APR-2010".

7.4 About Grouping Messages by Category and Severity

You can group messages by category and by severity. These groups are used to define logging and incident policies. Otherwise, category and severity have no affect. Category and severity values do not appear in logging entries, incidents, or the UI.

7.5 Understanding Incidents and Diagnostic Logs with Message Dictionary

Incidents are collections of information about system errors for which the customer might require assistance from help desk personnel. An incident contains information about the state of the system at the time the problem occurred. Help desk personnel can monitor and respond to incidents and send them to Oracle if further assistance is necessary. For more information about how customers use incidents, see the "Managing Oracle Fusion Applications Log Files and Diagnostic Tests" chapter and the "Introduction to Troubleshooting Using Incidents, Logs, QuickTrace, and Diagnostic Tests" appendix in the Oracle Fusion Applications Administrator's Guide.

Implicit incident creation and logging occurs when the Message Dictionary message is retrieved in PL/SQL and C code, or when it is formatted in Java code, and the message has the following settings:

Note:

Implicit incident creation occurs when logging is enabled. Implicit logging only occurs if the SEVERE log level is enabled.

You use the Message Dictionary APIs to retrieve a Message Dictionary message. The PL/SQL methods are in the FND_MESSAGE package and the Java methods are in the messageService package. For C code, you use methods in the fddutl package.

For more information about the Message Dictionary APIs, see the "Message Dictionary" chapter in the Oracle E-Business Suite Developer's Guide. You can download this soft-copy documentation as a PDF file from the Oracle Technology Network at http://www.oracle.com/technetwork/indexes/documentation/

For Java code, implicit incident creation and logging occurs for qualifying messages when the appropriate formatting methods are called from the MessageServiceAMImpl class and the MessageServiceAM interface, such as the getUserXML(..), formatMap(..), formatUserTextMap(..), or formatAdminTextMap(..) methods. See the MessageServiceAM and MessageServiceImpl Javadoc for information about which methods to call for implicit logging.

When implicit logging and incident creation occurs, additional information is appended to the message, as follows:

To learn more about the information that is included with incidents and associated log entries, see the "How the Diagnostic Framework Works" section in the Oracle Fusion Middleware Administrator's Guide.

7.6 Using Message Dictionary Messages in Oracle ADF Java Code

You can use messages in the Message Dictionary in Java code to raise exceptions using Oracle Fusion Middleware Extensions for Applications exception classes. You can also retrieve the message text programmatically.

7.6.1 How to Raise Exceptions Using Oracle Fusion Middleware Extensions for Applications Exception Classes

Exceptions from messages in the Message Dictionary should be raised using wrapper classes that are provided in the oracle.apps.fnd.applcore.message package. Wrappers that are provided correspond to the most commonly used Oracle ADF exception classes. See Table 7-1.

Table 7-1 Oracle ADF Exception Classes vs. Message Dictionary Classes

Exception Class Message Dictionary Class

JboException

oracle.apps.fnd.applcore.messages.ApplcoreException

RowValException

oracle.apps.fnd.applcore.messages.ApplcoreRowValException

AttrValException

oracle.apps.fnd.applcore.messages.ApplcoreAttrValException


In each of these classes, the message name is expected to be passed in the format: APP_NAME:::MESSAGE_NAME (application short name, followed by exactly 3 colons, followed by the message name). For example: "FND:::FND_CMN_POSITIVE".

Message tokens passed to most Message Dictionary Java APIs are expected to be supplied as Map<String, Object> or as an array of alternating String/Object pairs. With either style, the String is the name of the message token and the following Object is an object representing the value of that token. The type of the Object is expected to match the type of the token as shown in Table 7-2.

Table 7-2 Message Tokens and Data Types

Token Type Token Value Object Type

TEXT

java.lang.String

NUMBER

java.math.BigDecimal

DATE

java.sql.Timestamp


Exceptions that are raised using JboException or one of its subclasses with a severity level of SEVERITY_ERROR, which is the default, or any java.lang.RuntimeException, are treated as system errors, and the following occurs:

  • The error message is replaced with a generic message, such as "An application error occurred. Your help desk was informed"

  • An incident is created for the system error

  • A stack trace is written to the log file for the system error

If you do not want the JboException to be treated as a system error, do one of the following:

  • Convert the exception type to ApplcoreException

  • Set the severity level to other than SEVERITY_ERROR, such as SEVERITY_RECOVERABLE_ERROR.

Tip:

If you need to see the original error message, you can run the application with the -DAFERROR_MODE=debug parameter, as described in Section 7.9, "Diagnosing Generic System Error Messages."

You should use the wrappers wherever possible. However, it is possible to also use native Oracle ADF exceptions directly if there isn't a wrapper that exactly suits your needs. If you do this, you must specify the FndMapResourceBundle resource bundle class, and format tokens correctly.

Example 7-1 shows sample code that raises an ApplcoreException exception. Example 7-2 shows an example of raising ApplcoreRowValException exception. Use of the ApplcoreAttrValException exception is shown in Example 7-3. Example 7-4 illustrates how to throw a native JBOException.

Example 7-1 ApplcoreException

import oracle.apps.fnd.applcore.messages.ApplcoreException;

// Construct and populate HashMap with token values
Map<String, Object> tokens = new HashMap<String, Object>();
tokens.put("TEXT_TOKEN", "text token value");
tokens.put("NUMBER_TOKEN", new BigDecimal(10));
Calendar cal = Calendar.getInstance();
cal.set(1999, Calendar.DECEMBER, 31, 0, 0, 0);
tokens.put("DATE_TOKEN", new Timestamp(cal.getTimeInMillis()));
 
throw new ApplcoreException("MYAPP:::MY_MESSAGE_NAME", tokens);

Example 7-2 ApplcoreRowValException

import oracle.apps.fnd.applcore.messages.ApplcoreRowValException;
 
// Construct and populate HashMap with token values
Map<String, Object> tokens = new HashMap<String, Object>();
tokens.put("TEXT_TOKEN", "text token value");
tokens.put("NUMBER_TOKEN", new BigDecimal(10));
Calendar cal = Calendar.getInstance();
cal.set(1999, Calendar.DECEMBER, 31, 0, 0, 0);
tokens.put("DATE_TOKEN", new Timestamp(cal.getTimeInMillis()));
 
Key key = new Key(new Object[] { "Primary Key" });
 
ApplcoreRowValException ex = new ApplcoreRowValException("MYAPP:::MY_MESSAGE_NAME", "MyEODefName",key, tokens);

Example 7-3 ApplcoreAttrValException

import oracle.apps.fnd.applcore.messages.ApplcoreAttrValException;
 
// Construct and populate HashMap with token values
Map<String, Object> tokens = new HashMap<String, Object>();
tokens.put("TEXT_TOKEN", "text token value");
tokens.put("NUMBER_TOKEN", new BigDecimal(10));
Calendar cal = Calendar.getInstance();
cal.set(1999, Calendar.DECEMBER, 31, 0, 0, 0);
tokens.put("DATE_TOKEN", new Timestamp(cal.getTimeInMillis()));
 
ApplcoreAttrValException ex = new ApplcoreAttrValException("MYAPP:::MY_MESSAGE_NAME",
                                "MyEODefName","AttrName", "AttrValue", tokens);

Example 7-4 Native JBOException

import oracle.apps.fnd.applcore.messages.ApplcoreException;

// Construct and populate HashMap with token values
Map<String, Object> tokens = new HashMap<String, Object>();
tokens.put("TEXT_TOKEN", "text token value");
tokens.put("NUMBER_TOKEN", new BigDecimal(10));
Calendar cal = Calendar.getInstance();
cal.set(1999, Calendar.DECEMBER, 31, 0, 0, 0);
tokens.put("DATE_TOKEN", new Timestamp(cal.getTimeInMillis()));

JboException ex = new JboException(FndMessagesUtil.getFndMapResourceBundleDef(),
                                   "MYAPP:::MY_MESSAGE_NAME", null);
ex.setErrorParametersMap(tokens);
throw ex;

7.6.2 How to Retrieve Message Text Programmatically

You can use static methods in the oracle.apps.fnd.applcore.messages.Message class to retrieve translated, token substituted message text without raising exceptions. APIs are provided to retrieve the fully formatted text of the user message, the administrator message, or to retrieve the parts of the message (short message, cause, action, and so on) individually, as shown in Example 7-5.

Example 7-5 Retrieving Messages

// Construct and populate HashMap with token values
Map<String, Object> tokens = new HashMap<String, Object>();
tokens.put("TEXT_TOKEN", "text token value");
tokens.put("NUMBER_TOKEN", new BigDecimal(10));
Calendar cal = Calendar.getInstance();
cal.set(1999, Calendar.DECEMBER, 31, 0, 0, 0);
tokens.put("DATE_TOKEN", new Timestamp(cal.getTimeInMillis()));
 
// Get the token substituted message short text. 
String shortText = Message.getShortText("MYAPP", "MY_MESSAGE", tokens);
 
// Get the token substituted full user message, in plain text format. 
String userText = Message.getUserText("MYAPP", "MY_MESSAGE", tokens);
 
// Get the token substituted full user message, in HTML format. 
String userHTML = Message.getUserHTML("MYAPP", "MY_MESSAGE", tokens);
 
// Get the token substituted full admin message, in plain text format. 
String adminText = Message.getAdminText("MYAPP", "MY_MESSAGE", tokens);
 
// Get the token substituted full admin message, in HTML format. 
String adminHTML = Message.getAdminHTML("MYAPP", "MY_MESSAGE", tokens);

7.7 Associating Message Dictionary Messages with Oracle ADF Validation Rules

The easiest way to create and manage validation rules is through declarative validation rules. Declarative validation rules are defined using the overview editor for the entity object, and once created, are stored in the entity object's XML file. These are known as declarative validation rules on entity objects.

For information about defining validation rules on entity objects, see the "Defining Validation and Business Rules Declaratively" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Oracle ADF provides built-in declarative validation rules that satisfy many of your needs. You can also base validation on a Groovy expression, as described in Section 6.2, "Using Groovy Scripting Language".

When you add a validation rule, you supply an appropriate error message. You can also define how validation is triggered and set the severity level.

These messages can contain named message tokens for retrieving and displaying context sensitive values.

Tip:

When raising exceptions with the ADF Business Components validation rules, the tokens must be formatted as {TOKEN_NAME} and not (TOKEN_NAME).

7.7.1 How to Associate Error Messages with Oracle ADF Entity Object Validation Rules

To associate an error message with your validation rule:

  1. Go to the Failure Handling tab of your declarative validation rule when you have finished defining your rule. In the Validation Failure Severity field, Select Error.

  2. Click the Select Message button to open the Select Text Resource dialog. Choose Application Messages from the Resource Picker dropdown list.

  3. Use the Search area to filter your search results. For example, enter "fnd_view" in the search text area to filter your results to messages whose key begins with FND_VIEW.

    Note:

    You can only search messages by the message key. All other types of searches have been disabled. Also notice from the results that message keys are prepended with the application short name.
  4. Select the required error message from the list of results. The Select Text Resource dialog closes and the selected error message displays in the Failure Message Text area on the Failure Handling tab.

    Note:

    If the selected message contains tokens, a row for each token is added into the Error Message Expressions table.
  5. If your message contains tokens, bind them to Groovy expressions to retrieve context sensitive values. Groovy script is a Java-like scripting language. For more information about Groovy script, see Section 6.2, "Using Groovy Scripting Language".

    A validation rule's error message can contain embedded expressions that are resolved by the server at runtime. To access this feature, simply enter a named token delimited by curly braces (for example, {TOKEN_NAME} or {ERRORPARAM}) in the error message text where you want the result of the Groovy expression to appear.

    The Token Message Expressions table at the bottom of the dialog displays a row that allows you to enter a Groovy expression for the token. Figure 7-2 shows the failure message for a validation rule in the PaymentOptionEO entity object that contains message tokens.

    Figure 7-2 Using Message Tokens in a Failure Message

    Using Message Tokens in a Failure Message

Declarative validation is different from programmatic validation, which is stored in an entity object's Java file. For more information about programmatic validation, see the "Implementing Validation and Business Rules Programmatically" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

7.8 Raising Error Messages Programmatically in PL/SQL

Because they make calls to the database, both PL/SQL and C code require that the message is stored in the Message Dictionary. PL/SQL and C code cannot reference Java-based resource bundles. You can use PL/SQL to:

7.8.1 How to Raise Exceptions Programmatically in PL/SQL

There are three packages that you can use to handle errors in PL/SQL using messages in the Message Dictionary:

  • FND_MESSAGE — This package includes basic APIs to set messages on the error stack, set tokens, retrieve token substituted message text, and so on.

  • APP_EXCEPTION — This package includes utilities to raise SQL exceptions with messages in the Message Dictionary as the exception text.

  • FND_MSG_PUB — This package includes utilities to set messages on the error stack. In Oracle Fusion Applications, the error stack also exists natively in the FND_MESSAGE package; this package is primarily used for backward compatibility with existing code. PL/SQL code that in EBS was primarily called from Framework usually uses this method.

For more information about these packages, see the package headers.

7.8.2 How to Raise Errors in PL/SQL

The FND_MESSAGE PL/SQL package allows you to set one message and its tokens, as shown in Example 7-6. It also allows you to set multiple messages in the stack by explicitly pushing the current message onto the stack, as shown in Example 7-7. When you need to retrieve the message from the stack, an explicit pop() is required, as shown in Example 7-8.

Example 7-6 Getting Message and its Tokens

-- setting INVALID_USER as the current message
fnd_message.set.name('FND', 'INVALID_USER');
-- setting token value for NAME
fnd_message.set_token('NAME', '<USER>');
..........
-- get the current translated and token substituted message
-- then clear the message
msg := fnd_message.get;

Example 7-7 Receiving a Message Record and Clearing Message

-- setting INVALID_USER as the current message
fnd_message.set_name('FND', 'INVALID_USER');
-- setting token value for NAME
fnd_message.set_token('NAME', 'TESTUSER');
.......
-- receive a message record which contains everything about the
-- current message. The record contains message number, message category
-- message severity and translated and token substituted message text,
-- translated and token subsituted user message, user action, ...
-- Getting message record for current message will NOT clear the message
msg_rec := fnd_message.get_message_record;
-- clear the message
fnd_message.clear;

Example 7-8 Retrieving message from the Stack

-- setting INVALID_USER as the current message
fnd_message.set_name('FND', 'INVALID_USER');
-- setting value for token NAME for INVALID_USER message
fnd_message.set_token('NAME', 'TESTUSER');
-- saving the current message onto stack
fnd_message.push;
-- setting LOGIN_FAILED as the current message
fnd_message.set_name('FND', 'LOGIN_FAILED');
-- saving the current message onto stack
fnd_message.push;
.......
-- poping one message out of stack and set it as the current message
fnd_message.pop;
-- get the translated and token subsituted LOGIN_FAILED message
-- then clear the current message
msg := fnd_message.get;
-- poping one message out of stack and set it as the current message
fnd_message.pop;
-- get the translated and token subsituted INVALID_USER message
-- then clear the message
msg := fnd_message.get;

7.8.3 How to Retrieve Errors when PL/SQL is Called from Java

You can use the OAExceptionUtil.CheckErrors() API to check for error messages after calling PL/SQL from Java. The CheckErrors() API looks for errors on both the new FND_MESSAGE and FND_MSG_PUB stacks, raises a bundled exception for each error found on both stacks, and then clears both PL/SQL error stacks.

Where the call to OAExceptionUtil.CheckErrors() depends on which style of error handling your PL/SQL code uses:

  • If your PL/SQL code uses FND_MESSAGE with FND_MSG_PUB, then errors will be left on the PL/SQL error stack without raising any exceptions. The call to OAExceptionUtil should go immediately after the PL/SQL call.

  • If your PL/SQL code uses APP_EXCEPTION.RAISE_EXCEPTION, or FND_MESSAGE.RAISE, then errors will cause SQL exceptions to be raised. The call to OAExceptionUtil.CheckErrors() should be in a SQLException catch block.

  • If you do not know what style of error handling your PL/SQL code uses, or there could be a mixture of both, then you should include calls to OAExceptionUtils.CheckError() in both places, as shown in Example 7-9.

    Example 7-9 Calls to OAExceptionUtils.CheckError() — Unknown Error Handling Style

    import oracle.apps.fnd.applcore.common.OAExceptionUtils;
      ...
    
      try
      {
        // Create and execute a plsql statement
        String mystmt = "BEGIN MY_PLSQL_PACKAGE.MY_PROCEDURE(); END;";
    
        DBTransaction txn = getDBTransaction();
        CallableStatement mystmt = txn.createCallableStatement(mystmt, 1);
    
        myStmt.executeUpdate();
    
        // Check for errors left on message stack without raising exception
        OAExceptionUtils.checkErrors(txn);
      }
      catch(SQLException sqlE)
      {
        // Check for FND Messages exception.
        // FND Messages exception always has error code -20001.
        if (sqlE.getErrorCode() == 20001)
        {
          OAExceptionUtils.checkErrors(txn);
        }
        else
          // Not a FND Messages exception, re-raise.
          throw sqlE;
      }
    

7.9 Diagnosing Generic System Error Messages

If you see an error message similar to one the following messages, it is because a system error was raised and the original error message was replaced with a generic message:

An application error occured. Your help desk was informed.

An application error occurred. See the incident log for more information.

When you receive these types of errors, you can look at the log file entry to find the original error message.

Note:

When generic errors are raised, you will see oracle.apps.fnd.applcore.messages.ExceptionHandlerUtil class information at the top of the call stack. This is the code that is replaced the unhandled exception with the generic error and should not be mistaken for the original error from the Message Dictionary.

You can also set one of the following debug options to allow you to see the error more directly, without having to view the log file entry:

For information about finding the cause of an error and its corrective action and for information about viewing and managing log files, see the "Managing Log Files and Diagnostic Data" chapter and the "Introduction to Troubleshooting Using Incidents, Logs, QuickTrace, and Diagnostic Tests" appendix in the Oracle Fusion Middleware Administrator's Guide.

7.10 Formatting Message Dictionary Messages for Display in Oracle ADF Applications

When raising an exception or attribute validation error by retrieving a message from the Message Dictionary using a resource bundle interface, the exception message returns in XML format.

You can convert XML formatted messages to HTML or plain text for display in Oracle ADF applications, as shown in Figure 7-3.

Figure 7-3 Error Message Example

Error Message Example

This can be done in one of two ways:

7.10.1 How to Programmatically Convert XML Messages

When directly handling Oracle Fusion Applications resource bundle exceptions in Java code, you can convert XML messages to HTML or plain text using utility APIs. The utility APIs are found in oracle.apps.fnd.applcore.messages.model.util.Util.

Sample code is shown in Example 7-10.

Example 7-10 Converting XML Messages to HTML or Plain Text

Exception ex =
      new ApplcoreException("FND:::MY_TEST_MESSAGE");
 
    // Retrieve the HTML short message
    String htmlShort = Util.formatHTMLMessage(ex);
 
    // Retrieve the HTML message details.
    String htmlDetails = (Util.formatHTMLDetailMessage(ex)).getHTMLText();
 
    // Retrieve the plain text messge details
    String textDetails = (Util.formatHTMLDetailMessage(ex)).getText();
 
     // Retrieve the full plain text message
    String textMsg = Util.formatTextMessage(ex);

7.10.2 How to Convert XML Messages by Configuring the Error Format Handler

You can convert XML messages to HTML or plain text by configuring the error format handler in the DataBindings.cpx file.

To convert XML messages to HTML by configuring the error format handler:

  1. Under the user interface project, open the DataBindings.cpx file.

    Tip:

    JDeveloper names the user interface project ViewController by default.
  2. In the Property Inspector, set the ErrorHandlerClass field to the value shown in Example 7-11 and Figure 7-4.

    Example 7-11 The Value of the ErrorHandlerClass Field

    oracle.apps.fnd.applcore.messages.MessageFormatHandler
    

    Figure 7-4 Setting the Value of the ErrorHandlerClass Field in the Property Inspector

    Property Inspector - Setting the ErrorHandlerClass

7.11 Integrating Messages Task Flows into Oracle Fusion Functional Setup Manager

Every Oracle Fusion application registers task flows with a product called Oracle Fusion Functional Setup Manager. These task flows are available from the application's Setup and Maintenance work area and enable customers and implementers to set up and configure business processes and products. For more information, see the Oracle Fusion Applications Common Implementation Guide.

Function Security controls your privileges to a specific task flow, and users who do not have the required privilege cannot view the task flow. For more information about how to implement function security privileges and roles, see Chapter 49, "Implementing Function Security."

Table 7-3 lists the task flows and their parameters.

Table 7-3 Messages Task Flows and Parameters

Task Flow Name Task Flow XML Parameters Passed Behavior Comments

Manage Messages

/WEB-INF/oracle/apps/fnd/applcore/messages/ui/flow/ManageMessagesTF.xml#ManageMessagesTF

mode='search' [moduleType] [moduleKey]

mode='edit' messageName applicationId [pageTitle]

Search mode launches the search page, with optional parameters to restrict to a particular module.

Edit mode launches the edit page for a particular message. The messageName and applicationId parameters are mandatory as they specify the message to edit.

NA.