> 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/command/features/hierarchy-map.md).

# Hierarchy Map

Build a Hierarchy Map that nests your records by parent and by relationship, color it by Indicator, and change that structure by dragging.

A Hierarchy Map shows how your records fit together: capabilities and the applications under them, services and what runs them, or any other parent-and-child structure. You choose what loads around the records, and the map stays current with ServiceNow.

<figure><img src="https://414746897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx4mE784snR9Eb8oVrk4e%2Fuploads%2Fgit-blob-e1b7acd0066668b97a50ea9b9597e48818fcb4a5%2Fcommand-hierarchy-map-overview.png?alt=media" alt="A Hierarchy Map with capabilities drawn as colored nested boxes holding their applications, the Upstream row of records above the map, and the View row with Layout, Configuration, Color, Show and search across the top."><figcaption><p>A Hierarchy Map of capabilities and applications</p></figcaption></figure>

## What it is

A map starts from the records you drop on it. Command then loads what sits around them, nests each record inside its parent, and draws the result as boxes inside boxes.

| Part              | What it is                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| **Cards**         | One per record, with its table's image, its class and its name. Click the name to open the record.   |
| **Children**      | Records under a card, found through their parent field (**Load children**) or through relationships. |
| **Upstream** row  | The records your map's records depend on or belong to, shown once each in a row above the map.       |
| **Configuration** | Per table, what loads around the records and which records are kept.                                 |
| **Color**         | How cards are colored: not at all, by top-level branch, or by an Indicator.                          |
| **Show**          | What every card displays.                                                                            |

The map saves the records you dropped and your choices, never a copy of the data. Each time you open it, and each time you click **Refresh**, it reads ServiceNow again.

## When to use it

* To draw a capability map, an application landscape or a service structure from live data.
* To see at a glance which records are in which lifecycle stage or rating, using the Indicators your organization already defined.
* To see what a set of records depends on, and what depends on them.
* To fix the structure itself: put an application under the right capability, or relate two records, and review the changes before they are saved.

## How to

### Build a map

1. Click **Create** (**+**) in the activity rail and choose **Hierarchy Map**. The empty map says **Build a hierarchy map**.
2. Drag records from the [Data Hub](https://docs.ins-pi.com/command/the-portal/data-hub.md) onto it. You can drag single records or a whole section; a section keeps its search and filter. You can also drop a saved Scenario.
3. Command nests the records and draws the map. On the first drop of records, the **Configuration** dialog opens by itself, so you can choose what loads around them right away.

A single drop reads at most 2,500 records. If a drop matches more, nothing is added and Command asks you to narrow the filter.

### Choose what loads around your records

1. In the **View** row, click **Configuration**. The **Configuration** dialog lists one card for each table on the map.
2. On a table you dropped, switch on **Load children** to bring in every record below it through its parent field.
3. Switch on **Relationships** to follow the table's relationships.
4. Open **Relationship types** to pick which types to follow. For each type, choose the direction with its arrows (**Both**, **Downstream** or **Upstream**), and uncheck any class of record it reaches that you do not want.
5. To keep only some of a table's records, click its funnel button (**Open filters**) and build a filter.
6. Click **Apply**. The dialog closes and the map rebuilds.

<figure><img src="https://414746897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx4mE784snR9Eb8oVrk4e%2Fuploads%2Fgit-blob-7d2df9b251aed240fe5f5ecd8bef93b945999a27%2Fcommand-hierarchy-map-configuration.png?alt=media" alt="The Configuration dialog with a card per table, one with Load children and Relationships switched on and its list of relationship types with counts, direction arrows and the classes each type reaches."><figcaption><p>Choose what loads around each table</p></figcaption></figure>

Nothing changes until you click **Apply**; **Discard changes** throws away your edits. A table filter is saved with the map, so everyone who opens it sees the same records. Records that do not match are hidden, with everything below them.

By default, **Relationships** follows every type both ways. **Follow every type both ways** brings back that default after you have narrowed it.

To change which records you dropped, click a table's **N dropped** pill. Its list lets you remove one record or a selection (**Undo** brings one back), and search the table to **Add** more. A record you take off stays off, even when a relationship would reach it. These changes are saved with **Apply** too.

### Change what the map shows

| Control            | What it does                                                                                                                                                                                                                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **State**          | Shows **Current** records, **Future** (planned) records, or **Both**.                                                                                                                                                                                                                                       |
| **Layout**         | Sets the **Direction** (**Vertical** or **Horizontal**), how many **Level**s deep the map goes, and, in **Vertical**, how many **Columns** it uses. At **Auto**, the map uses as many columns as fit and lets small branches share a row; with a number, the top-level branches stack in that many columns. |
| **Color**          | Colors cards **Off** (plain), **By top level** (each top-level branch its own color) or **By Indicator**. See [Color cards by an Indicator](#color-cards-by-an-indicator).                                                                                                                                  |
| **Show**           | Switches card details on and off: **Table**, **Icon**, **Upstream** (the row above the map), **Relationship type**, **Relationship count**, **Children count** and **Repeat count**. **Relationship type** and **Repeat count** start off. **Indicator Legend** brings back the legend.                     |
| **Search the map** | Highlights the cards that match and opens the branches that hold them. Press **Enter** to jump to the next match and **Shift+Enter** to go back; the box counts where you are, for example *2 of 7*.                                                                                                        |

Click a branch's band to fold or unfold it. Folds are saved with the map. The band shows how many direct children the branch has.

### Color cards by an Indicator

Indicators are the color codes your organization set up in ServiceNow, such as a lifecycle stage or a rating, each with its values and colors. Command reads them; it does not change them.

1. In the **View** row, click **Color**.
2. Choose **By Indicator**. Under **Indicator per table**, each table on the map has its own menu.
3. For each table, pick an Indicator, or leave it at **None**. An Indicator marked **(inherited)** comes from a broader table that this one extends.
4. Click outside the popover. The cards take the colors of their values, and the **Indicator** legend appears over the map.

<figure><img src="https://414746897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx4mE784snR9Eb8oVrk4e%2Fuploads%2Fgit-blob-2bf893e6428714b2e370a61c5d4e8f5990cae7ae%2Fcommand-hierarchy-map-indicators.png?alt=media" alt="A Hierarchy Map whose application cards are filled with lifecycle colors, the Color popover with By Indicator chosen and an Indicator menu per table, and the floating Indicator legend listing each value with its color and count."><figcaption><p>Cards colored by a lifecycle Indicator</p></figcaption></figure>

* **In the legend**, click a value to dim every card that does not hold it; pick several to compare. The reset icon (**Show all**) beside **×** shows every card again. Drag the legend by its header to move it.
* **Close the legend** with **×** (**Close legend**); **Show > Indicator Legend** brings it back.
* **All to None**, beside **Indicator per table**, sets every table back to **None** at once.
* **No value** cards, whose field is empty, are outlined. **Other value** cards hold a value the Indicator gives no color, and are gray. Point at a card to read its value.
* A table set to **None** keeps its cards plain.

### Explore what is upstream

When the map follows relationships upstream, the **Upstream** row above the map lists every record your map's records depend on or belong to. Each one appears once, joined to the cards it reaches by faint lines.

* **Point at an upstream card, or at a card on the map,** to light its lines. The rest of the map dims. If a lit upstream card has scrolled out of view, a one-line strip at the top of the view shows it.
* **Read the counts.** An upstream card shows how many map records it reaches (**↓N**) and how many records sit upstream of it in turn (**↑N**). On a map card, the **↑N** chip says how many upstream records it has; click it to list them. **Show > Relationship count** hides all of these.

To focus the map on one upstream record:

1. Click the filter button on an upstream card (**Filter by this record**). The map keeps only the cards it reaches, and the row reads **Filtered by …**.
2. Click **Show all**, press **Esc**, or click the filter button again (**Show the whole map**) to see the whole map again.

<figure><img src="https://414746897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx4mE784snR9Eb8oVrk4e%2Fuploads%2Fgit-blob-140f34e44f3a693e58e691d3b431758c892b4ccc%2Fcommand-hierarchy-map-upstream.png?alt=media" alt="The Upstream row above a Hierarchy Map, filtered by one upstream record, with Show all beside the Filtered by heading and only the cards that record reaches drawn below."><figcaption><p>The map filtered by an upstream record</p></figcaption></figure>

A record that sits under two parents appears under each. Switch on **Show > Repeat count** to mark each copy with **×N**; click the marker to **Go to** another place or **Highlight all** of them.

### Relate records or change a parent

1. Click **Edit** in the content header. It reads **Editing** while on.
2. Drag a card onto the card it belongs under. Only cards that can take it are outlined.
3. In the popover, under **How**, choose **Move** to take the card out of where it sits now, or **Add** to keep it there as well. Each choice says what it does.
4. If a **Relationship type** list appears, pick the type. **parent of** sets the record's parent field instead of a relationship. The line underneath reads the relationship you are making.
5. Click **Move** or **Add**. The card now says **Moved** or **Added**. Repeat for other changes.
6. Click **Commit** in the content header; its badge counts your changes. **Review and confirm** lists them as **Additions**, **Removals** and **Changes**. Click **Undo** on any change you do not want.
7. Click **Commit**. Command saves the changes and reads the map again.

<figure><img src="https://414746897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx4mE784snR9Eb8oVrk4e%2Fuploads%2Fgit-blob-d244affebefc82866fdff9b30e2318420db9aa0a%2Fcommand-hierarchy-map-relate.gif?alt=media" alt="An application card is dragged onto another capability in edit mode, Move is chosen in the popover, and the card appears under its new capability marked Moved while Commit shows one change."><figcaption><p>Move a record by dragging it</p></figcaption></figure>

* **Without dragging**, open a card's **Actions** menu and choose **Move to…**. The list puts the records the card can go under first; the others say why not. Picking one asks the same **Move** or **Add** question.
* **Top level**, at the top of the **Move to…** list, takes the card out from under its parent. Dropping a card on the map's background does the same.
* **Drag a single record from the Data Hub onto a card** while **Editing** to relate it there; it joins the map marked **Added**. Dropped on the background, it is simply added to the map.
* The **Actions** menu also has **Open record**, **Edit relationships** and **Remove**.

### Refresh, clear or download

* Click the round arrow (**Refresh**) to read the map again now. Maps never refresh on a timer.
* **⋮ > Clear** empties the map: its records, what loads around them, and its folds. Command asks first, and it cannot be undone. The view settings stay.
* The arrow next to **Share** offers **Copy image**, and **Download PNG**, **JPG** or **PDF**.

## Good to know

{% hint style="info" %}
Relating records needs the Command editor role and write access to the records. Changing a parent field needs write access to that field. Without them, **Edit** or the drop explains what is missing.
{% endhint %}

* **With the keyboard**, the map's cards are one Tab stop. **Up** and **Down** arrows move between cards, **Left** and **Right** between a card's buttons, and **Home** and **End** go to the first and last card. The **Upstream** row works the same way.
* **Removing a card** keeps it off the map, even after a refresh.
* **Planned records** (from the [Future State Repository](https://docs.ins-pi.com/command/features/future-state-repository.md)) can be shown but not related or moved by field.
* **On a map built from a Scenario**, there is no **Configuration**, no filter and no relating: dragging, or **Actions > Move on this map…**, only changes where cards sit on that map.
* **Big maps** follow at most 5,000 relationships; the map says so when it stops there.
* **Records whose parent is not on the map** are left out, and the map says how many.

## Related

* [Data Hub](https://docs.ins-pi.com/command/the-portal/data-hub.md)
* [Relationship Editor](https://docs.ins-pi.com/command/features/relationship-editor.md)
* [Content types](https://docs.ins-pi.com/command/the-portal/content-types.md)
* [Future State Repository](https://docs.ins-pi.com/command/features/future-state-repository.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/command/features/hierarchy-map.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.
