> For the complete documentation index, see [llms.txt](https://docs.ins-pi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ins-pi.com/models/admin/realtime-indicators.md).

# Realtime Indicators

> This task requires the **YouDesign Admin** (`x_inpi_yd.admin`) role.

Realtime Indicators (RTI) are visual elements — background colors, borders, symbols, or text — embedded in shapes that reflect the current state of a ServiceNow record field. They turn a static diagram into a live dashboard: an architecture map instantly shows which applications are "End of Life," a capability map highlights immaturity, a dependency map surfaces compliance risk.

Technically, an RTI is a **field-value-to-visual mapping**. This page covers the admin side: how to create, configure, and maintain RTIs.

For the end-user view of applying RTIs to a board, see [Realtime Indicators (end-user)](/models/work-in-the-app/editor/realtime-indicators.md).

## What Admins Configure

Three tables together drive RTI behavior:

| Table                                | Holds                                                                     |
| ------------------------------------ | ------------------------------------------------------------------------- |
| `x_inpi_yd_realtime_indicator`       | The RTI definitions (name + source table + source field)                  |
| `x_inpi_yd_realtime_indicator_value` | The value-to-color/symbol mapping per RTI                                 |
| `x_inpi_yd_realtime_indicator_shape` | Per-shape RTI configuration (which RTIs apply to which shapes on a board) |

Admins work mainly with the first two. The third is populated automatically as users apply RTIs in the editor.

## RTI Styles

When an end user applies an RTI to a shape, they pick a **Style** that determines how the indicator renders. Five styles are available:

| Style          | What It Does                                                                                       |
| -------------- | -------------------------------------------------------------------------------------------------- |
| **Background** | Colors the entire shape background in the configured color                                         |
| **Border**     | Colors the shape's border in the configured color                                                  |
| **Shape**      | Adds a small shape (square / circle / rounded rectangle — see below) as a symbol on the main shape |
| **Symbol**     | Adds a UTF-8 symbol or emoji, in the configured color                                              |
| **Text**       | Adds a text string in the form *"Field name: Value"*                                               |

### Shape sub-type

When the user picks the **Shape** style, a second choice narrows the rendered symbol:

| Shape sub-type        | What It Does                |
| --------------------- | --------------------------- |
| **Square**            | A colored square            |
| **Circle**            | A colored circle            |
| **Rounded Rectangle** | A colored rounded rectangle |

### Subject of the RTI

The backend also classifies RTIs by what they're **attached to**:

* **Element** — attached to an individual Data Hub shape (the common case)
* **Relationship** — attached to a relationship line between two elements
* **RelatedList** — attached to a related-list relationship

Admins don't pick the subject directly when creating an RTI; it's inferred from the **Source Table** and context. Most RTI definitions are Element-scoped.

### Positioning

For the **Shape**, **Symbol**, and **Text** styles, users place the indicator on the shape via a **Positioning Tool** (Directions: ↑ ↓ ← → **ADD**). The position is saved per-shape on the board.

**Background** and **Border** don't use the positioning tool — they always apply to the whole shape.

> <img src="https://2110136944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOS5XKTz5WlrX4s5rESlH%2Fuploads%2FoYGXSm6wBD2XIPSduZin%2FScreenshot%202026-04-24%20at%2017.49.20.png?alt=media&amp;token=1ee59111-c5b0-4dd4-a07c-82a4c76fa3e2" alt="" data-size="original">

1. In the ServiceNow navigator, open the **YouDesign Models** application menu
2. Expand **Configuration**
3. Select **Realtime Indicators**

The list shows all configured RTIs with columns for Name, Source Table, Source Field, Active status, and Updated timestamp.

## Anatomy of an RTI Record

Each RTI has a header (defining where the data comes from) and a related list of values (defining the visual output).

### Header Fields

| Field            | Description                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| **Name**         | Display name of the indicator — visible to end users in the RTI panel                                      |
| **Active**       | Uncheck to disable the RTI without deleting it                                                             |
| **Source Table** | The ServiceNow table the indicator reads from                                                              |
| **Source Field** | The field on that table whose value triggers the visual. Can be a field on a referenced record, see below. |

### RTI Value Fields (related list)

Each row under an RTI record defines what happens for a specific value (or range of values) on the source field:

| Field           | Description                                                                                                |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| **Label**       | Display label for the value/range — visible to end users                                                   |
| **Value**       | The exact field value to match (as stored in the ServiceNow dictionary). Leave empty for range indicators. |
| **Order**       | Display order of the values in the RTI panel                                                               |
| **Symbol**      | Optional — a UTF-8 character or emoji to display when this value matches                                   |
| **Color**       | The color applied (HTML name or hex — hex is most flexible)                                                |
| **Range Start** | For range indicators only — the start of the numeric range                                                 |
| **Range End**   | For range indicators only — the end of the numeric range                                                   |

For range indicators, leave **Value** empty and fill in **Range Start** and **Range End**. Range matching is numeric only.

> **🖼 Screenshot needed:** \[RTI record form with header fields filled and the Values related list showing 3–4 entries with labels, values, colors, and symbols] *Show: an RTI named "Architecture Type" with Source Table = Business Application, Source Field = architecture\_type, and a grid of value rows (Client Server, N-Tier, Platform Application, etc.) with color swatches and symbols.*

### Dot-Walked Source Fields

The source field does not have to be on the source table itself. In the **Source Field** picker (*Select the element from the tree*), reference fields appear as folders with a **+**. Expand one and pick a field of the referenced record, and the indicator reflects a value stored one or more tables away. The record then shows the combined label, for example **Business Unit Company** for `business_unit.company`. Examples:

| Source table         | Source field             | What the indicator shows                       |
| -------------------- | ------------------------ | ---------------------------------------------- |
| Business Application | `business_unit.company`  | The company of the application's business unit |
| Business Capability  | `parent.lifecycle_stage` | The lifecycle stage of the parent capability   |
| Server               | `location.country`       | The country of the server's location           |

How it behaves:

* The **Values** related list works on the final field in the path, so define value rows for the referenced table's field, for example the choices of `department`.
* The indicator label shown to users in the panel, on the canvas and in the export legend is the label of the **final** field.
* Every step in the path except the last must be a reference field. A path that walks through a non-reference field is rejected and the indicator shows no data for that record.
* Fields inherited from parent tables are resolved, so `cmdb_ci` fields are available on every CI class.
* Each dot-walked indicator costs an extra lookup per record when data is refreshed. Keep paths short on boards with many records.

<figure><img src="https://2110136944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOS5XKTz5WlrX4s5rESlH%2Fuploads%2Fgit-blob-76f3e46a7e795a7635974421be064c3bf1982d81%2Fv26.1-rti-source-field-tree.png?alt=media" alt=""><figcaption><p>The Source Field tree: plain fields as documents, reference fields as expandable folders</p></figcaption></figure>

## Creating a New RTI — Step by Step

1. From the Realtime Indicators list, click **New**.
2. Enter a descriptive **Name** (end users will see this).
3. Confirm **Active** is checked (the default).
4. Select the **Source Table** from the drop-down.
5. Click **Source Field** and pick the field from the tree. To use a field of a referenced record, expand the reference field first and pick the field beneath it.
6. Click **Submit** to save the header. The related list for values becomes editable.
7. Click **New** on the Values related list to create the first value.
8. Fill in the value configuration:
   * **Value** (exact dictionary value) OR **Range Start** + **Range End**
   * **Label** (user-facing)
   * **Color** (hex recommended)
   * **Symbol** (optional)
   * **Order**
9. Click **Submit**.
10. Repeat for each value you want to map.

> **Save the RTI header before adding values.** The Values related list isn't editable until the parent record exists.

## Applying RTIs to Shapes

Once RTIs exist, end users apply them per-board through the **Realtime Indicators** panel in the editor:

1. Open the RTI panel (right sidebar in editor mode).
2. Pick the **Table** the RTI targets.
3. Pick the **Field** (which scopes to the RTIs defined for that field).
4. Pick the **Style** (Background, Border, Square, Circle, Rounded Rectangle, Symbol, Text).
5. Click **Add**.

The RTI is now active on every matching shape on the board. Per-shape configuration is stored in `x_inpi_yd_realtime_indicator_shape`.

See [Realtime Indicators (end-user)](/models/work-in-the-app/editor/realtime-indicators.md) for the user experience in detail.

## Common RTI Patterns

* **Lifecycle status** — Source: `install_status` or similar. Values: Installed (green), Retired (red), Pipeline (amber). Style: Background.
* **Criticality** — Source: `criticality` / `business_criticality`. Values: High/Medium/Low mapped to red/amber/green. Style: Border.
* **Compliance flag** — Source: custom compliance field. Values: Compliant (check symbol) / Non-compliant (cross symbol). Style: Symbol.
* **Maturity range** — Source: numeric maturity score. Range: 0–2 red, 3 amber, 4–5 green. Style: Background.

## Limits & Gotchas

* **Value must match dictionary exactly.** If the dictionary stores `client_server` but your RTI value says `Client Server`, the mapping won't match. Confirm the dictionary value (not the display label).
* **Range indicators are numeric only.** Don't try to express string ranges.
* **Inactive RTIs still show up** in the per-shape configuration until they're removed from the board. Deactivate thoughtfully.
* **Do not update `x_inpi_yd.gl.rti_last_updated` or `x_inpi_yd.gl.rti_shape_last_updated` manually.** These are maintained by the application — manual edits can cause sync issues. See [Global Settings](/models/admin/global-settings.md).
* **RTI changes migrate via XML**, not Update Sets. When promoting, include `x_inpi_yd_realtime_indicator`, `x_inpi_yd_realtime_indicator_value`, and `x_inpi_yd_realtime_indicator_shape`. See [Migrating Configuration](/models/get-the-app/migrating-configuration.md).
* **Test in nonprod before shipping.** Wrong colors or labels are very visible to end users.

## Best Practices

* Pick source tables with data that actually changes — stale fields produce misleading indicators.
* Use **meaningful labels** users can interpret without context.
* Use **color conventions** consistent across your org (green = healthy, red = risk, etc.).
* For range indicators, design ranges that align to business thresholds, not arbitrary buckets.
* Keep a short list of canonical RTIs rather than letting every team invent their own.
* **Document each RTI** in your organization's architecture standards so users know when to apply which.
* Regularly audit RTI accuracy — values drift as ServiceNow data models evolve.

## Related

* [Realtime Indicators (end-user)](/models/work-in-the-app/editor/realtime-indicators.md)
* [Shape Administration](/models/admin/shapes.md)
* [Metamodel Prerequisites](/models/admin/metamodel.md)
* [Global Settings](/models/admin/global-settings.md) — the `rti_last_updated` warning
* [Migrating Configuration](/models/get-the-app/migrating-configuration.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ins-pi.com/models/admin/realtime-indicators.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.