Localized Messaging Using gs.getMessage() - ben-vargas/servicenow-wiki GitHub Wiki

gs.getMessage() is a server-side API function in ServiceNow that retrieves localized messages from the platform’s message dictionary. By using message keys and optional placeholder values, you can display user-friendly, context-aware information—often in the user’s preferred language—directly in the user interface.

This helps maintain consistent and easily translated messages, rather than hard-coding text directly into scripts.

• Localization Support:
  gs.getMessage('<key>') looks up a message based on a key. If your instance is configured with translations, it returns the localized message text for the current user’s language.

• Placeholders and Arrays:
  You can pass an array of values as the second parameter. The message string can contain placeholders like {0}, {1}, etc., which will be replaced by the corresponding elements of the array at runtime.

• Consistent UI Messaging:
  Using message keys and localization tables allows administrators and translators to manage messages centrally, rather than editing code whenever changes to the message text or translations are needed.

// Array to hold values replacing placeholders in the message
var msg_array = [];

// Push dynamic values or strings into this array
// For example, if your message key is defined as:
// "User {0} has been assigned to ticket {1}"
// You could do:
msg_array.push('John Doe');    // replaces {0}
msg_array.push('INC0010001');  // replaces {1}

// Retrieve the localized message using the key and array
var send_msg = gs.getMessage('<key>', msg_array);

// Display the message to the user as an informational banner
gs.addInfoMessage(send_msg);

Key Points in the Example:

• Message Key:
  Replace <key> with the identifier of the message you’ve defined in ServiceNow’s system messages (e.g., user_assigned_to_incident).

• Placeholder Substitution:
  The msg_array elements will sequentially populate {0}, {1}, etc. in the message.

• Displaying the Message:
  gs.addInfoMessage() inserts a message at the top of the user’s current page. There are also gs.addErrorMessage() and gs.addWarningMessage() for different severity levels.

1. Navigate to Messages Table:
   Go to System UI > Messages in the Application Navigator.

2. Create a New Message Record:

   • Key: A unique identifier (e.g., user_assigned_to_incident).
   • Message: The default message text, with placeholders if needed (e.g., User {0} has been assigned to ticket {1}).

3. Translations (Optional):
   If you support multiple languages, add translations for the same key in the appropriate language. The platform automatically returns the correct translation based on the user’s language settings.

• Reuse Keys:
  By using message keys in multiple scripts, you ensure consistency of language and phrasing. If the message needs updating, just edit the message record rather than changing code.

• Keep Messages Separate from Logic:
  Storing messages in the message dictionary rather than in code makes it easier for administrators and translators to update UI text without modifying scripts.

• Use Meaningful Keys:
  Choose descriptive keys that reflect the meaning of the message, making it easier for translators and administrators to understand context.

• ServiceNow Documentation:
  Refer to GlideSystem API - getMessage for official documentation and more detailed examples.

• Localization & Translation Setup:
  Explore System Localization to understand how to set up and manage translations for different languages.

Using gs.getMessage() allows you to separate message text from business logic, enabling better localization and maintainability. By working with message keys and placeholders, you provide a scalable and user-friendly approach to displaying informative messages, ensuring that both administrators and translators can easily adapt the platform’s messaging to evolving requirements.