1 — Create the UI Macro
The UI Macro holds your actual HTML content — the styled guidance block with the 5 WHY questions.
Step 1: Navigate to System UI → UI Macros (or type sys_ui_macro.list in the navigator filter).
Step 2: Click New.
Step 3: Fill in the fields:
| Field |
Value |
| Name |
rca_five_why_guidance |
| Active |
Checked |
| Description |
Displays 5 WHY Root Cause Analysis guidance on the Problem Task form |
Step 4: In the XML field, paste the following code:
<?xml version="1.0" encoding="utf-8" ?>
<j:jelly trim="false"
xmlns:j="jelly:core"
xmlns:g="glide"
xmlns:j2="null"
xmlns:g2="null">
<div style="
background-color: #e8f4fd;
border-left: 4px solid #0073e6;
border-radius: 4px;
padding: 16px 20px;
margin: 8px 0 16px 0;
font-family: SourceSansPro, 'Helvetica Neue', Arial, sans-serif;
font-size: 13px;
color: #333;
line-height: 1.6;
">
<div style="
font-size: 14px;
font-weight: 600;
margin-bottom: 10px;
color: #0053a0;
">
5 WHY Root Cause Analysis — Guidance
</div>
<div style="margin-bottom: 6px; color: #555;">
Use the questions below to guide your root cause investigation.
These are for reference only — answering them individually is not mandatory.
Capture your final analysis in the <strong>Root Cause Summary</strong> field below.
</div>
<ol style="
margin: 10px 0 0 0;
padding-left: 22px;
color: #333;
">
<li style="margin-bottom: 8px;">
<strong>Why did this problem occur?</strong>
<br/>
<span style="color: #666; font-size: 12px;">
Identify the immediate cause.
</span>
</li>
<li style="margin-bottom: 8px;">
<strong>Why did that cause happen?</strong>
<br/>
<span style="color: #666; font-size: 12px;">
Identify the underlying factor.
</span>
</li>
<li style="margin-bottom: 8px;">
<strong>Why was that factor present or not prevented?</strong>
<br/>
<span style="color: #666; font-size: 12px;">
Look for process or system gaps.
</span>
</li>
<li style="margin-bottom: 8px;">
<strong>Why did the process/system allow this to happen?</strong>
<br/>
<span style="color: #666; font-size: 12px;">
Examine controls, procedures, and resources.
</span>
</li>
<li style="margin-bottom: 8px;">
<strong>Why was the root condition not identified or addressed earlier?</strong>
<br/>
<span style="color: #666; font-size: 12px;">
Determine the true root cause and improvement opportunity.
</span>
</li>
</ol>
</div>
</j:jelly>
Step 5: Click Submit.
What you just did: You created a reusable HTML snippet wrapped in Jelly (ServiceNow's server-side template language). The <j:jelly> wrapper is required — without it, ServiceNow won't render the macro. The actual content inside is plain HTML with inline styles.
Part 2 — Register a UI Formatter
A UI Formatter is what makes your UI Macro available as a draggable element in the Form Layout designer.
Step 1: Navigate to System UI → Formatters (or type sys_ui_formatter.list in the navigator filter).
Step 2: Click New.
Step 3: Fill in the fields:
| Field |
Value |
| Name |
rca_five_why_guidance |
| Table |
Problem Task [problem_task] |
| Formatter |
rca_five_why_guidance |
| Type |
Formatter |
| Active |
Checked |
Important: The Formatter field value must exactly match the Name of the UI Macro you created in Part 1 (case-sensitive). This is how ServiceNow links the two.
Step 4: Click Submit.
What you just did: You registered the UI Macro as a form element specifically for the problem_task table. ServiceNow now knows this formatter exists and will show it in the form layout designer.
Part 3 — Add the Formatter to the Form Layout
Now you place the guidance block onto the actual PTASK form, inside the Root Cause section.
Step 1: Open any existing Problem Task record (navigate to Problem → Problem Tasks, open any PTASK).
Step 2: At the top-left of the form, click the hamburger menu (three horizontal lines or the context menu icon) and select Configure → Form Layout.
Alternatively, right-click the form header bar and choose Configure → Form Layout.
Step 3: The Form Layout designer opens. You'll see two panels — Available (left) and Selected (right). At the top, make sure you're editing the correct View (typically Default view unless your team uses a custom view).
Step 4: In the Available list, scroll down or search. You should see your formatter listed as:
rca_five_why_guidance (Formatter)
It will appear with a (Formatter) suffix to distinguish it from regular fields.
Step 5: In the Selected list (right side), locate the Root Cause section. You need to place the formatter above the Root Cause Summary field. To do this:
- Click on
rca_five_why_guidance (Formatter) in the Available list.
- Click the right arrow (→) button to move it to the Selected list.
- It gets added at the bottom. Now use the up arrow (↑) button repeatedly to move it up until it sits just above the Root Cause Summary field within the Root Cause section.
The layout should look something like this in the Selected panel:
--- Root Cause --- ← section header
rca_five_why_guidance (Formatter) ← your guidance block
Root Cause Summary ← mandatory free-text field
Step 6: Click Save.
Step 7: The form reloads. You should now see the blue guidance callout box with the 5 WHY questions rendered permanently inside the Root Cause tab, directly above the Root Cause Summary field.
Part 4 (You Already Have This) — Make Root Cause Summary Mandatory
Since you mentioned you've already done this with a UI Policy, just confirm it's in place:
Step 1: Navigate to System UI → UI Policies (or sys_ui_policy.list).
Step 2: Verify you have a policy on problem_task where:
| Setting |
Value |
| Table |
problem_task |
| Condition |
As per your business logic (e.g., always, or when state = Analysis) |
| UI Policy Action |
Field = Root Cause Summary, Mandatory = true |
