Formatters and UI Macros

Formatters & UI Macros in ServiceNow – A Complete Guide for the CAD Exam

Introduction: Why Formatters and UI Macros Matter

Formatters and UI Macros are essential components in ServiceNow's application user interface layer. They allow developers and administrators to extend the default behavior and appearance of forms and lists beyond what standard fields and form layouts provide. Understanding these concepts is critical for the ServiceNow Certified Application Developer (CAD) exam because questions frequently test your ability to distinguish between formatters and UI macros, know when to use each, and understand how they integrate into the broader UI framework.

What Are Formatters?

A Formatter is a special type of element that can be added to a form layout using the Form Designer or Form Layout editor. Unlike regular fields that display data from a column in a table, formatters render a specific UI element or widget on the form. They do not correspond to a field in the database — instead, they inject pre-built or custom-rendered content into the form.

Common examples of out-of-box formatters include:
- Activity Formatter – Displays the activity stream (journal entries, work notes, comments) on a form.
- Process Flow Formatter – Shows a visual process flow bar at the top of a form, indicating stages or phases.
- Parent Breadcrumbs Formatter – Displays breadcrumb navigation for parent records.
- CI Relations Formatter – Shows related Configuration Items in a visual relationship diagram.

Formatters appear in the form layout section alongside fields but are distinguished because they are not actual columns on the underlying table. They are added to the form layout via System UI > Formatters or directly through the Form Designer.

What Are UI Macros?

A UI Macro is a reusable piece of Jelly (XML-based templating language used in ServiceNow) or HTML/CSS/JavaScript code that generates UI content. UI Macros are the underlying mechanism that powers many formatters and other UI elements. They can be thought of as reusable UI components or templates.

UI Macros are defined in System UI > UI Macros and consist of:
- A Name – Used to reference the macro.
- XML content – The Jelly/HTML/CSS/JavaScript template that defines what the macro renders.
- An optional Description.

UI Macros can be invoked from UI Pages, other UI Macros, or associated with formatters to render custom content on forms.

How Formatters and UI Macros Work Together

The relationship between formatters and UI macros is fundamental:

1. A Formatter acts as a placeholder on the form layout. It tells the system where to render something on the form.
2. A UI Macro defines what to render. The formatter references a UI Macro by name to determine the content to display.

When you create a custom formatter, you typically:
1. Create a UI Macro – Write the Jelly/HTML code that generates your desired content.
2. Create a Formatter record – In System UI > Formatters, create a new record that references the UI Macro name. You specify the table and the name of the formatter (which must match the UI Macro name).
3. Add the Formatter to the Form Layout – Using the Form Designer or configuring the form layout, drag or add the formatter to the desired position on the form.

When a user opens the form, ServiceNow evaluates the form layout, finds the formatter, looks up the associated UI Macro, executes the Jelly/HTML code, and renders the output inline on the form.

Key Characteristics of Formatters

- Formatters are not actual fields — they do not store data in the database.
- They appear in the form layout editor under available items, typically in a special section.
- They are table-specific — a formatter is associated with a particular table.
- Formatters can span the full width of the form or be placed in a specific section.
- They are rendered server-side using Jelly (in the classic UI) or can incorporate client-side scripts.

Key Characteristics of UI Macros

- UI Macros use Jelly, an XML-based scripting language, as their templating engine (in the classic/non-Service Portal environment).
- They are reusable — the same UI Macro can be referenced by multiple formatters or UI Pages.
- They can include HTML, CSS, JavaScript, and Jelly tags.
- Common Jelly tags include <j:if>, <g:evaluate>, <g2:evaluate>, and more.
- UI Macros are primarily used in the classic UI (non-Service Portal) environment.

When to Use Formatters vs. Other UI Options

- Use Formatters + UI Macros when you need to embed custom, non-field content directly on a form (e.g., a custom widget, visual display, or embedded content).
- Use UI Policies or Client Scripts when you need to manipulate existing fields on a form (show/hide, make mandatory, set values).
- Use UI Actions when you need buttons, links, or context menu items that perform actions.
- Use UI Pages when you need standalone pages, not embedded form content.

Creating a Custom Formatter – Step by Step

1. Navigate to System UI > UI Macros and click New.
2. Enter a Name (e.g., my_custom_widget).
3. Write the XML/Jelly/HTML code in the XML field. For example:
<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:g2="glide">
  <div style="background-color:#f0f0f0; padding:10px;">
    <b>Custom Information Block</b>
    <p>This is a custom formatter.</p>
  </div>
</j:jelly>
4. Save the UI Macro.
5. Navigate to System UI > Formatters and click New.
6. Set the Name to match the UI Macro name exactly (e.g., my_custom_widget).
7. Set the Table to the target table (e.g., Incident).
8. Save the Formatter.
9. Navigate to the target form, open the Form Layout or Form Designer, and add the new formatter to the layout.
10. Save the form layout and verify the custom content renders on the form.

Important Exam Concepts

- Formatter Name = UI Macro Name: The formatter references the UI Macro by name. They must match.
- Formatters do not store data: This is a commonly tested concept. They are display-only elements.
- Jelly is the templating language: UI Macros use Jelly scripting. Know that Jelly is XML-based and is used for server-side rendering in the classic UI.
- Formatters are table-specific: They are defined for a specific table.
- Out-of-box formatters: Be familiar with Activity Formatter and Process Flow Formatter, as these are commonly referenced.
- UI Macros vs. UI Scripts: UI Macros are server-side rendered Jelly templates; UI Scripts are client-side JavaScript/CSS libraries that can be included in pages.

Exam Tips: Answering Questions on Formatters and UI Macros

1. Read the question carefully for keywords: If a question mentions adding non-field content to a form, think Formatter. If it mentions reusable Jelly/HTML templates, think UI Macro.

2. Remember the relationship: A Formatter is the container/placeholder on the form; a UI Macro is the content generator. They work together. If a question asks what defines the rendering logic, the answer is UI Macro. If it asks what is placed on the form layout, the answer is Formatter.

3. Know the navigation paths: Formatters are managed under System UI > Formatters. UI Macros are managed under System UI > UI Macros. Questions may test whether you know where to find these.

4. Distinguish from other UI components: Exam questions often present multiple options (UI Policy, Client Script, UI Action, Formatter, UI Macro, UI Page). Formatters are specifically for embedding custom rendered content on a form. UI Pages are standalone. UI Actions are buttons/links. UI Policies control field behavior. Know these distinctions cold.

5. Elimination strategy: If a question asks about adding a visual element or widget to a form that is NOT a standard field, eliminate UI Policy (field behavior), Client Script (field manipulation/alerts), and UI Action (buttons). The answer likely involves a Formatter or UI Macro.

6. Activity Formatter is the most common example: If you see a question about displaying activities, journal fields, or work notes in a stream format on a form, the answer is the Activity Formatter.

7. Process Flow Formatter: If a question references a visual progress bar or stage indicator on a form, think Process Flow Formatter.

8. Jelly knowledge: You may not need to write Jelly code on the exam, but know that UI Macros use Jelly as their templating language and that it is XML-based. This distinction helps in questions about the technology behind formatters.

9. Classic UI context: Formatters and UI Macros are primarily associated with the classic/standard UI (backend). In the Service Portal, custom widgets serve a similar purpose but use a different technology stack (AngularJS, HTML, CSS, client/server scripts). If a question specifies Service Portal, formatters and UI Macros are typically not the correct answer.

10. Practice scenario-based questions: Many CAD exam questions are scenario-based. Practice identifying when a scenario calls for a formatter by asking yourself: Does this require non-field, custom-rendered content on a form? If yes, formatter + UI Macro is likely the answer.

Summary

Formatters and UI Macros are powerful tools for customizing the ServiceNow form experience. Formatters serve as placeholders on form layouts that reference UI Macros — reusable Jelly/HTML templates — to render custom content. For the CAD exam, focus on understanding the relationship between formatters and UI Macros, knowing when to use them versus other UI components, recognizing common out-of-box formatters (Activity, Process Flow), and remembering that formatters do not store data. Master these concepts, and you will be well-prepared to answer any exam question on this topic.