For information on the visual treatment and interaction of messages supported by the Application Developer Framework (ADF) components and Rich Client User Experience (RCUX) specifications, see the Fusion Message Pattern Set. There are no design patterns for product-specific messaging or for back-end messages.

Fusion Applications supports these five message types:·

• Error messages
• Warning messages
• Information messages
• Processing messages
• Confirmation messages

The following examples illustrate the five message types:

Error Messages

Figure 1: Page-level Error Message

The error message type tells users about incorrect data or formats when they complete a field, save a page, or perform actions that trigger validation. Error messages tell users how to correct the situation so that they can continue with their task.

Error messages also tell users about any serious problem with the application or process that they cannot recover from without help desk intervention.

Message authors use different combinations of message components to deliver the right information. This combination depends on the nature of the error and whether end users can resolve the error on their own (the User components) or require help desk intervention (the Admin components).

In many cases, error messages are easily actionable by end users themselves. The message author writes such a message using the Message Text component. Most messages will fall into this category. For example:

The actual completion date must be later than or equal to the goal plan period start date.

- Or -

You cannot specify a task without specifying the project.

- Or -

The Profile Option setting requires that goals must be included in performance documents.

In other cases, additional, more detailed information, or the cause of the error is supplied as well as the action that end users or the help desk must take. In these cases, more components are used:

• Message Text is always required.
• Message User Detail and Message Admin Detail are optionally used if a longer explanation is needed for end users or for the help desk.
• Message Cause can optionally be provided, if the reason for the error is not obvious from the components already used.
• Message User Action or Message Admin Action is provided when Message Cause is used, telling end users or the help desk what action to take to resolve the error condition.

See the section on Message Components for more information.

Examples

A revenue rate was not found for the planning transaction using the resource class bill rate schedule that is linked to the project.

Cause There is no revenue rate defined for planning resource {RESOURCE_NAME} as of the planning date {START_DT} in the resource class bill rate schedule {RATE_SCHEDULE} of the project.

Action Review the rate schedules assigned in the planning options and make sure that the defined rates include the dates used in the planning lines.

- Or -

You cannot change the costing method because the labor costing rule is referenced in one or more labor costing overrides.

Changing a costing rule that has been assigned to labor costing overrides does not automatically update existing transactions that use the rule. You must recalculate the cost on existing transactions in order for them to use the new rule.

Warning Messages

Figure 2: Page-level Warning Message with Confirmation

The warning message type tells users about a data validation or application situation that requires their acknowledgement or decision before they can continue. The warning message describes the reason for the warning and any potential consequence of proceeding. Warnings are especially important for any situation that could be potentially destructive orirrecoverable, resulting in a loss of productivity or data.

A question may be posed with the warning, or the warning can take the form of a statement. The message author writes the question along with the warning text, shown in a dialog, and gives the users a choice of action buttons to respond with, coded by the applications development team. In Fusion 2.0, teams may compose their own questions and action button responses. For warnings, the components that can be used are:

Message Text is always required. The Message Text itself may provide sufficient information for end users to respond and continue with their task.

Message User Detail and Message Admin Detail can also optionally be provided if a longer, more detailed explanation of the warning is needed for end users or the help desk.

Message Cause can optionally be provided, if the reason for the warning is not obvious from the components already used.

Message User Action and Message Admin Action are provided when Message Cause is used, telling end users or the help desk what action to take to resolve the warning condition.

See the section on Message Components for more information.

Examples

Active role assignment end dates will be updated to the resource end date. Do you want to continue?

(Dialog action buttons are Yes and No)

- Or -

The selected organizations and their usages will be deleted. Do you want to continue?

(Dialog action buttons are Yes and No)

- Or -

Any documents you remove are returned to the source product. To be paid, these documents must be resubmitted in a new payment process request.

(Dialog action buttons are Remove Documents and Cancel)

- Or -

A compensation pattern was not defined for orchestration process {PROCESS_NAME}, step {STEP_NAME}. The default undo and cancel services are being used instead.

- Or -

This goal will be made inactive and will no longer be visible except to HR specialists.

Information Messages

Figure 3: Page-level Information Message

The information message type tells users about changes in in the application, a page, or a business object. These messages are not triggered by the same users, and no immediate action from them is required in response. The message is entered in the Message Text component. 

Examples

A Federal I-9 submission is available for review.


- Or -

New opportunities are available for this territory.

- Or -

No life events have been started or processed for this employee.

Processing Messages

Figure 4: Page-level Indeterminate Processing Message

The processing message type tells users that an action they requested or that the application had scheduled is currently in progress. The message is entered in the Message Text component.

Examples

Process {PROGRAM_NAME} has started but will take some time to complete. You will receive a confirmation message when it is complete.

- Or -

Geography mapping and validation information is being saved.

- Or -

Orchestration process setup is being validated.

- Or -

Connection to Microsoft Project is being established.

Confirmation Messages

Figure 5: Page-level Inline Confirmation Message

The confirmation message type tells users that an action they performed, or requested, has completed. The message is entered in the Message Text component.

Examples

Project was submitted for approval.

- Or -

Selected lines have been canceled.

- Or -

Financial plan type has been deleted.

- Or -

Progress was published. Published actual dates are available for third-party scheduling purposes.

 

Every message must have a unique name within a product area. The name takes the format of <APPLICATIONSHORTNAME>_<LBA/SUB-LBA>_<MESSAGE DESCRIPTION >. Use the following guidelines:

• Use the Application Shortname (FND, AP, GL, and so on) as the initial part of the message name.
• Next, add either the LBA or sub-LBA.
• Then, add a description that summarize the purpose of the message.
• Use no more than 30 characters, with the following breakdown:
  
  

  Application shortname + underscore	4 characters maximum
  LBA code + underscore	6 characters maximum
  Message description	20 characters maximum

• Use all uppercase letters; no symbols.
• Do not include spaces within the name, or at the start or end of the name. Use underscore characters to separate parts of the message name.
• Do not include message numbers in the name. 

Examples

• ZCC_360IF_TRANSACTION_FAILED
• MOO_OPTY_EXCEED_MAX_LENGTH
• PJC_ACCT_USER_RATE_NOT_DEFINED
• PJF_CURR_PC_NO_USER_RATE
• INV_ABC_COMPILE_VALUE_NEGATIVE
• INV_SUBINV_DEST_LOCATOR
  
  
  

The possible message components by message type are shown in the following table:

* If you specify a Message Cause component, then specify a Message User Action, a Message Admin Action, or both.

Component Concepts

• Define one, not two different messages (that is, one intended for the end user and another one intended for the help desk) for the same event. A single event triggers each message, so use the User and Admin components in the same message.
• Text components in a message are additive. The end user sees all User components, whereas the help desk sees all User components and Admin components in the message.
• Generally, use either a Detail component or Cause and Action component, not both. Try to avoid using all these components together, because the resulting message will be long and it will be difficult for users to interpret what action they need to take, especially when shown at the component level.
• Do not repeat information in two different components for the same message (either verbatim or by restating the same thing in different words).
• Tokens can be declared by the message author in a message and can be used in all message components, except Translator Notes. See the section on Declaring and Using Tokens for more information.

The message components entered as text by the message author are:

Message Text

This component is a statement, generally a single sentence, of the error or warning that has occurred, or information that application users need to know in order to know what action to take or to understand what is happening.

Message authors must always provide a Message Text for all message types. Message Text is always seen both by end users and the help desk. Most messages will use only the Message Text component.

Examples

Your preferences cannot be updated because you do not have access permission.

(Error)

- Or -

You specified a start date after the end of the fiscal year.

(Warning)

- O r -

Expense report IEW12345 for 750 USD has been approved.

(Confirmation)

Message User Detail

This component is a more detailed explanation of Message Text, stating why the message occurred, or communicating additional information useful only to end users in understanding how to resolve the issue themselves. Message User Detail text may consist of more than one sentence.

Examples

This invoice has adjustments pending from another transaction. Before you cancel this invoice, you must resolve all pending supplier invoice adjustments.

- Or -

Interest is currently due on this invoice. Include the invoice in a payment batch to calculate the interest.

If specified, the Message User Detail text is seen both by end users and the help desk.

Message Admin Detail

This component is a more detailed explanation of Message Text, stating why the message occurred, or communicating additional information useful only to the help desk in understanding how to resolve the issue so that end users can proceed. Message Admin Detail text may consist of more than one sentence.

Examples

The amount of time required for the submission of the invoice exceeded the configured timeout value.

- Or -

The application is not responding because of insufficient memory or network bandwidth to meet the requirements of this process.

If specified, only the help desk sees the Message Admin Detail text.

Message Cause

This component is a concise explanation of what caused an error or warning message. Message Cause provides the reason why the message is seen, for example a prerequisite that was not met by the user, incorrect data inputs made, an anticipated but incorrect action, and so on. It may consist of more than one sentence.

The Cause heading is prefixed automatically to the beginning of the Message Cause text at run time. Message authors do not enter the word Cause.

Examples

Cause The table does not exist or you do not have permission to insert data into the table.

- Or -

Cause The setup process cannot read the configuration file because another process is accessing this file, or the file does not exist.

Message Cause text is seen both by end users and the help desk.

Message User Action

This component states the response that end users must perform in order to be able to continue and complete their tasks in response to an error or warning message. Message User Action text may consist of more than one sentence.

The Action headingis prefixed automatically to the beginning of the Message User Action text. Message authors do not enter the word Action.

Examples

Action You must enter a value for the national identifier as the employee number generation is based on this value.

- Or -

Action On the approval item record, select the employee recipient and send the approval item.

If specified, only the help desk sees the Message Admin Action text.

Message Admin Action

This component states the response that the help desk and administrators perform in order for end users to be able to continue to complete their tasks in response to an error or warning message. Message Admin Action text may consist of more than one sentence.

The Action heading is prefixed automatically to the beginning of the Message Admin Action. Message authors do not enter the word Action.

Examples

Action Change the timeout parameter in the business process step to be greater than the response time. You must recompile and redeploy the process after modification.

Contact the network administrator to verify that the load between the source and target systems is within the expected range. Add the required system memory or network bandwidth to the systems.

- Or -

Action Determine the processes that are using memory on the system. On Windows systems, use the Task Manager. On Linux systems, run the ls or top command. Stop any unnecessary process to allocate more memory to the approval process.

If specified, the Message Admin Action text is seen by the help desk only.

Translator Notes

Translator notes are intended to help translators understand the run-time context of the message text, should a translator query arise. The Translator Notes component text is not seen by end users or the help desk.

This contextual information is also veryuseful to internal application developers and reviewers of message content.

Use Translator Notes text to help clarify how and whe n the message is shown, tokens, untranslatable words, or other points that might not be obvious anyone who must look at the message text and try and understand its use without the benefit of a run-time application.

Examples

This error appears during upload of transactions using web services. The transaction fails validation because the expenditure type value is missing.

- Or -

This error appears in the Manage Unreleased Expenditure Batches UI when a transaction is created or modified with a zero quantity. Expenditure Item Quantity cannot be zero, but can either be less than zero or more than zero.

- Or -

Message is displayed in log file when the purge cycle count program fails to update the cycle count interfaces table.

It is recommended that the following types of messages provide translator notes:

• Back-end messages or page-level messages that make no reference to the user interface (UI).
• Back-end messages using short text or fragments.
• Messages that include words that you know must not be translated.
• Messages that use tokens.
  
  If you are using tokens in your message components, and it is not clear what the token is for, then you should enter a specific translator note for both the message and the token.
  
  
• Generally confusing messages. For example, if a product manager or information developer does not understand the message just by looking at the text, then add the context for translation too.

Message authors must write message text as concisely as possible. Tokens should and must be used in our applications, as they allow for efficient application development by replacing the tokens with variable information in the message text at run-time. This also facilitates re-use of the message text itself.

Message authors must declare (enter) the tokens used in each message. All message components, with the exception of Translator Notes, support the use of one or more tokens.

Use tokens when your message needs to include variable information for:

• Dates
• Numbers
• Text

Creating a Token

Message authors and application developers decide if the token is used to replace at run time a varying date, number, or text for a server name, file name, program name, system username, environment variable, field label, and so on. This saves the need to write a different message to accommodate every possible variant of the date, number, or text.

Enter the token name between curly brackets {} in the APM messages collaborative worksheet or MRT, following the token naming convention:

• Begin the token name with a { character and end it with a } character.
• Enter a descriptive name where possible, summarizing the use of the token, using all upper case letters.
  
  In some cases token names may need to follow other conventions, if the message integrates with WebCenter or other other technologies, for example. Check with your development team.
• Do not use any spaces within the name or at the start or end of the name.
• Use the underscore character to separate parts of the name.
• Use 30 characters or less in total. Remember that the token name count is used up in the overall message component length allowance, so shorter is better than longer, but do not shorten it so much that it becomes cryptic.
• Specify the token type. Each token must be either a date, number, or text type.
• Enter the token description for the named token, for example: "Text token for system environment variable." or "Employment start date token." or "Number of records found in this query token." and so on.
• Finally, in the message component text, enter the token name exactly as you declared it. Tokens can be shared throughout the components of the same message but not across messages.

Examples

• {PROFILE_EFFECT_DATE}
• {PAYROLL_RUN_START_DATE}
• {CUST_ID}
• (PROC_ORDER)
• {FILENAME}
• {ENV_VAR_LOGICAL}

Token Translation Issues

Because of the varying grammatical rules of different languages, message authors must take care when constructing any message with a token.

Different gender, possessive, and singular and plural rules for languages mean that unless care is taken, it is impossible to translate the English message and token replacement text so that the complete message makes sense at run time.

Text tokens that work in English can be very problematic when used as text in other languages. For example, take an error message with the token {OBJECT_TYPE} representing different nouns and the token {PERFORM_ACTION} representing a verb.

This is not acceptable because {OBJECT_TYPE} could be replaced by a masculine or feminine noun when translated. The word that will replace {PEFORM_ACTION} must then agree with the gender form of {OBJECT_TYPE} (that is, it takes different endings for masculine and feminine). Tokens must not be used to replace translated words such as these in a message.

Follow these rules when using tokens:

• Always use tokens for replacing dates and number variables at run-time.
• Complete the translator notes component and description field for the message and the token unless the entire message is is completely clear.
• Ensure that any text substituted by the token at run time comes from a translatable multilingual support (MLS)-enabled source. Check with your development team.
• The text intended to replace the token in the message must never be a verb or used for a noun that could be singular or plural. As a general rule, use the plural only. If this is not possible, then write a message for each case.
• Avoid using possessives with tokens. Instead of using your, use the definite article.
• Do not append a possessive 's (apostrophe s) after the token or an (s) to make the token replacement text plural.
  
• Write a full sentence (including a period), instead of putting the tokens after a colon. For example, use:

You cannot enter a value because the {FIELD_NAME} field is disabled.

Instead of:

You cannot enter a value because the following field is disabled: {FIELD_NAME}

Note: That approach will not always be possible with back-end messages. In such cases, putting the token after a colon is acceptable. For example:

Number of transactions deleted: {DLTD_TRXNS_NUM}.

If you need to list out a series of tokens, for example used for attributes in a back-end message, then you may do so using commas, with a period at the end. For example:

The dimension cannot be imported because the following territories are invalid: {EMEA_TERR_1}, {APAC_TERR_1}, and {AMER_TERR_1}. Remove the invalid territories and import the dimension again.

• When you use a token for translatable text (for example, an object or UI label), then put the token in a sentence so that the translator has some additional context about what the run-time version of the complete message will say. Qualify each translatable token with a noun. For example, the noun document:

The application cannot open the document {FILENAME} for updating.

• Where a token will be replaced by text that could be a complicated or unusual sort of value, place a qualifying noun before the token, so that the reader is prepared for what the token value represents in advance. For example, use:
  
  

  
  An unexpected SQL error has occurred in statement {SQLSTATE}.
  
  Works number {WORK_NUMBER} is already in use.

  Instead of:
  
  
  An unexpected SQL error has occurred in {SQLSTATE} statement.
  
  The {WORK_NUMBER} works number is already in use.

Examples

Decision Table About How to Use Tokens

The number takes the format of Application Shortname+Number and is placed within parentheses after the Message Text component text for error and warning message types messages. For example:

Descriptive flexfields do not support unit of measure-enabled segments.

Support teams use these numbers to look up reference information in knowledge bases. The number remains the same in translated versions of the message, so international support analysts can search for solutions in English, too.

An incident number is automatically generated every time an incident is raised for a particular message. Every time the message is raised an incident number is generated. This number is not entered by the message author, but created when an incident is raised.

Incidents and diagnostic logging are described for application developers in the Oracle Fusion Applications Developer's Guide section on Supportability: Logging and Diagnostics in a Development Environment. The information in this guideline is intended for use during the design phase using the APM collaborative messages workbook and MRT.

Incidents

An incident must be created when users experience an error that they cannot resolve without help desk intervention. Incident creation relies on the application and platform technology diagnostics to automatically collect the necessary information associated with the incident and to inform the help desk (figure 6).

Figure 6: Help Desk Management View of Incidents and Diangostic Log Creation

Based on the incident information and associated diagnostics, the help desk can then diagnose the issue. When the help desk cannot solve the root cause of the incident directly, it can be sent to Oracle Support, forming a service request.

Note: In Fusion applications, use the term incident, not alert, when referring to the informing the help desk about issues with applications.

From a message authoring perspective, incidents require no special considerations once the content guidelines for components and for phrasing are followed. However, product managers must also set the loggable_alertable flag, message type, severity and category attributes in the APM collaborative messages workbook or MRT, and coordinate with the application developer and supportability point of contacts (POCs) to ensure that the application code creates the incident as required, either implicitly or explicitly.

Incidents can be created implicitly or explicitly:

• Implicit: The APPLCORE message dictionary API creates the incident.
• Explicit: The application developer explicitly calls an API (for example, incidentAppsLogger.createIncident [if Java] or LOG_INCIDENT_VAR variable [if a BPEL process]).

In both cases, an authored FND message type of Error, Warning, or Information is needed. Set the message attributes as follows for each type of incident.

For an implicit incident:

• LOGGABLE_ALERTABLE=Y
• TYPE=ERROR
• MESSAGE SEVERITY=HIGH
• MESSAGE CATEGORY=SYSTEM or PRODUCT or SECURITY

For an explicit incident:

• LOGGABLE_ALERTABLE=Y
• TYPE=ERROR or WARNING or INFORMATION
• MESSAGE SEVERITY=Not applicable
• MESSAGE CATEGORY=Not applicable
  

Diagnostic Logging

Diagnostic logging occurs when a message is delivered in a formatted ODL diagnostic log file (figure 7). The Fusion Applications administrator, who can determine the logging level or module using profile options, controls diagnostic logging. These diagnostic logs enable the help desk to diagnose and debug any Fusion application failures.

Figure 7: Test Diagnostic Log Showing Incident, Error, Warning, and Information Messages

As with incidents, the messages are authored according to guidelines. Product managers again must also set the loggable_alertable flag, message type, severity and category attributes in the APM collaborative messages workbook or MRT, and coordinate with the application developer and supportability POCs to ensure that the application code creates the diagnostic log as required, either implicitly or explicitly.

Logs can be created implicitly or explicitly:

• Implicit: The APPLCORE message dictionary API creates the log.
• Explicit: The applications developer explicitly calls the API (for example, AppsLogger.write [if Java,] LOG_MESSAGE_VAR variable [if a BPEL process,] FND_LOG.MESSAGE [if PL/SQL] or aflogmsg [if C]).

In both cases, an authored FND message type of Error, Warning, or Information is needed if the logging coding level is set to SEVERE, WARNING or INFO (other levels do not use FND_MESSAGE content and are not translatable.) Set the message attributes as follows for each type of log created:

For implicit logging:

• LOGGABLE_ALERTABLE=Y
• TYPE=ERROR
• MESSAGE SEVERITY=HIGH or MEDIUM or LOW
• MESSAGE CATEGORY=SYSTEM or PRODUCT or SECURITY
  

For explicit logging:

• LOGGABLE_ALERTABLE=Y
• TYPE=ERROR or WARNING or INFORMATION
• MESSAGE SEVERITY=Not applicable
• MESSAGE CATEGORY=Not applicable

The following section provides information on the message severity and message category attributes, needed for incident-related and diagnostic log messages.

Severity

Message authors select one of the following values:

• High: An error is so severe that it stops the process.
• Medium: An error is severe, but user can still complete the business process, or there is a workaround.
  
• Low: The system or user can proactively resolve the error.

Category

An administrative category must also be set. Message authors select one of the following values:

• Product: Refers to application functionality, setup, and maintenance. Product messages are typically routed to functional administrators or product super users in the help desk.
• System: Refers to the system, database, tech stack, and so on. System messages are typically routed to technical users such as system administrators or DBAs in the help desk.
• Security: Refers to issues concerning permissions, access, compliance, passwords and so on. Security messages are typically routed to security administrators in the help desk.

Examples

When the Help Desk Is Notified

Implicit Incidents

When an implicit incident message is triggered for an error level failure, in addition to the Message Text specified, the end user sees the following text, automatically generated and appended to the formatted message in each case:

If an implicit incident is created in the middle tier (if Java, BPEL or C):

An application error has occurred. Your help desk was notified. For more information your help desk may refer to incident {incident number},
{application server name}, {application server domain name}.

If an implicit incident is created in the database tier (if PL/SQL):

An application error has occurred. Your help desk was notified. For more information your help desk may refer to incident {incident number_SID}, {database server name}, {database instance name}.

Message authors do not need to add this text.

Explicit Incidents

When an explicit incident message is triggered for an error level failure the developer must append the following notification to the original message:

An application error has occurred. Your help desk was notified. For more information your help desk may refer to incident {incident number}, {application server name}, {application server domain name}.

Alternatively you may consider adding this text as part of the original message. Application development teams are responsible for the raising of the relevant token values.

References to Help Desk

When something goes wrong, do not explicitly tell users to contact a system administrator, or that a system administrator was informed. Instead, use the incident creation framework to do that for them (figure 8).

Figure 8: Application Error Message with Incident Text

Use the term help desk instead of support representative,  service desk, Oracle Support, Global IT, and so on.

Although rare, if a message makes reference to a functional user being contacted as a way of resolving a problem (for example, a benefits administrator), then make sure that the role applies to your product and that it is a role that can take corrective action. Roles are written in lower case.

See the Use the Supportability Framework and Phrases section of this guideline for more information.

Use the following principles and content guidelines in when designing messages using the Applications Process Model (APM) collaborative messages workbook or the MRT. Remember to:

• Use the content guidelines during design. These are guidelines, not standards, and are designed to be flexible to enable you to author messages that best fit your user experience requirements.
• Read the Message Usage Guideline and understand how and when messages can appear. Understanding what is provided by ADF and RCUX by default and what application developers must do otherwise will help you write the best messages for users.
• Check to see if there is an ADF Validator or Converter message that would work for your business rule. Then check the MRT to determine if there is a common message in existence that you can use for your business or UI rule.
• Read the Message Text Pattern Guideline and understand how to compose simple messages that follow a common pattern before you write a new one.
• Avoid hard-coding or specifying links to other content, such as the Oracle Fusion Applications Help, My Oracle Support, OTN information, and so on. Enhancements have been logged to enable users to access additional information from messages. Contact Apps-UX for more information.
• You may use the Message Review Checklist to review the main points of message design when you are done.

Follow these specific guidelines when writing messages:

1. Keep Within the Allowed Lengths for Each Message Component
2. Write a Complete Sentence with Approved Words
3. Write for the Intended Audience
4. Use User Interface References When Necessary
5. Use the Active Voice Where Appropriate
6. Avoid Unapproved Symbols, Abbreviations and Acronyms, and other "Shortcuts"
7. Reserve "You Must" for Mandatory Actions/Required Fields
8. Use the Supportability Framework and Phrases

1. Keep Within the Allowed Lengths for Each Message Component

The development process enforces the following length restrictions, so keep these lengths in mind when composing and reviewing text:

2. Write a Complete Sentence with Approved Words

• Write a complete sentence using US English.

Note: Exceptions, where applicable, to the complete sentence guideline, should be made for back-end messages. These messages may not be complete sentences, need a delimiter, and so on. Inform reviewers of any exceptions required.

• Begin the sentence with a capital letter and end it with a period or question mark.

Note: Back-end messages may be exceptions to this guideline. For example, back-end processing messages intended to indicate processing, shown in text files , may end with an ellipsis (...). Fragments may not require a delimiter.

• Do not exceed 25 words in length for each sentence.

• Do not drop articles (some exceptions for back-end messages.)
• Address the user as you and not his/her, the user, and so on. However, for back-end messages using you may not be possible as the application or some other software is acting.
  
  
• Do not use all UPPERCASE words in the sentence unless a) you want that word to remain untranslated (for example, a table or program name), or b) the word is an approved acronym or abbreviation.
  
  Acronyms and abbreviations do not need to be spelt out in messages. Use the Fusion Applications Help nonembedded hep glossary to spell them out and explain their meaning.
  
  
• Use the present tense.
  
  Past or future tense is acceptable where present tense cannot convey a sequence of events or tasks performed or downstream consequences yet to happen. The use of has been or have been instead of the simple past tense is acceptable in confirmation messages.
  
• Avoid the use of semicolons, and use a colon and serial commas instead. However, if there are many options in the text, then consider using a bulleted list format instead as this is more readable. Work with your MRT contact on how to format the list.
• Do not attempt to combine fragments, or phrases together at run-time. This technique (known as concatenation) leads to serious translation errors: For example, the following messages must not be concatenated together to form one message.
  
  Message 1: Suspense posting is not allowed for the target ledger,
  Message 2: therefore, if this balance transfer's accounts are out of balance,
  Message 3: it will not run for this balance transfer.
  
  Instead, write a complete message.
• Avoid locale-specific examples. Instead, rely on the examples provided in the ADF validators and converters hints. If specifying dates in message text, then use the globa-friendly format of DD-Mon-YYYY (for example, 24-Aug-2010).
  

Examples

3. Write for the Intended Audience

Message authors determine whether a message is intended for end users or the help desk. Remember the differences in the nature of the message content that these two different audiences need:

• End users need to know precisely what they must do in order to complete tasks on their own using only what is available to them in the user interface.
• Do not blame or accuse end-users because an error or warning has appeared. Instead help users resolve the issue.
• Avoid using the word please or apologizing for the message.
• End users cannot re-configure the application, and should not be told about complex technical details, code functions, tech stack errors, parameters, arguments, filenames, table names, and so on. Such details may even intimidate them. For example, end users should never see tech stack error messages.
• The help desk, on the other hand, needs the provision of more detailed and technical information to resolve problems so that the end user may continue. This includes the names of specific processes, programs, tables, filenames, or tech stack errors, as well as troubleshooting steps, methods of diagnosis, and so on.

Examples

4. Use User Interface References When Necessary

• For component-level errors, do not refer directly to the UI component label name.
  
  Users can locate the error or warning using a red or yellow border on the components. The ADF messaging framework and RCUX visual designs also allows for the component name to be automatically shown (along with a link) in lists that combine the component-level messages together in a dialog or at the top of the page (see the Fusion Message Design Pattern Set).
  
  
• In other message cases, the UI element must be named as it will help users get to the location of the message and act on it.
  
  Page-level and back-end messages fall into the category of messages which should include UI references when necessary to help users identify the source of the issue quickly. Limitations in the table row, tabs, and train stop messaging are other interactions that may require message authors to explicitly mention the component by name.
  
  
• When naming a UI component in a message, qualify the name of the component, stating whether it is a field, tab, and so on.
• Do not make references to navigation and menu paths. These can vary with implementation.
• Do not offset UI references with single or double quote marks. Such marks make the message 'choppy' and difficult to read and also cause translation issues.

Examples

5. Use the Active Voice When Appropriate

When appropriate , use the active voice. If the message refers to a specific person (such as the end user) having to act, then the message should actively refer to that person. When writing about system or application-performed actions, however, use the passive voice (for example, "Profile was updated.").

You do not need to use the word application (or equivalent) to avoid using the passive voice if it is clear that the application (or relevant part of the technology stack) is acting or has acted.

Note: In the case of back-end messages that report on application or system activity and so on, or if it's clear the application is acting in response to a user action, it is acceptable to use passive voice as the user is not acting.

Examples

6. Avoid Unapproved Symbols, Abbreviations and Acronyms, or other "Shortcuts"

• Do not add HTML syntax or HTML entities in an attempt to emphasize or add format to your text, or to provide links to more content. The run-time formatting of the message is sufficient.
  
  If you do need to include HTML syntax in a code example, then you may need to apply for an exception from a QA check run by central teams.
  
  See the Fusion Message Pattern Set.
  
  
• Do not use contractions (can't, don't, and so on) as a way to save space. An ellipsis (entered as three ASCII dot characters) may be used to indicate processing in a back-end message.
• Do not use (s) as a way of indicating a choice of singular and/or plural. Use the plural form only.
  
• Do not use Latin words such as e.g., etc.,, and et al. Use example, and so on, and and others instead.
• Do not use a slash character (/) instead of or or and unless it approved in an approved term or in a code sample.
  
• Do not use single or double quotation marks to set-off complex phrases, proper nouns, or other elements in the message. This makes the message 'choppy' to read. Tokens should be set-off by using qualifying nouns where possible, and not by using single or double quotation marks.
  
  Note that code samples may use these kinds of punctuation marks, if necessary (however, you may need to apply for an exception from a QA checks run by central teams).
  
• Do not add alphas (a., b. c., or other variants) or numbers (i., ii, iii. or variants) as a way of listing out options within your text. Instead rely on list formatting in the message itself, as this is more readable. Formatting will be applied automatically at run time. List formatting is supported in Fusion 2.0. Contact your MRT POC on how to format lists.
• Do not use the new line character (/n), tab character (/t), underscores, hyphens or spaces to achieve formatting such as line breaks or for lists.
• Messages must never use one letter as codes on their own. The full term must be spelled out in the message after the letter.

Examples

7. Reserve "You Must" for Mandatory Actions/Required Fields

• Do not use you must if the user has a choice about whether or not to take the action, for example, when the user has entered an invalid value, but that field is optional. Instead, phrase the message in terms of what the value must be like if it is entered, such as "The amount must be less than..."
• Use you must in messages only if it is mandatory for users to take the action, to emphasize to users that they must perform the action. For example, for a mandatory field where the user hasn't entered a value,  phrase the message as "You must enter...".
• A user will not be able to leave the page until all mandatory fields are complete and correct. Mandatory fields are indicated by * symbols.
  

Examples

• Fusion Message Pattern Set
• ADF Validator and Converter Hints and Messages
• Fusion Message text Pattern Guideline
• Fusion Message Usage Guideline