> 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/relationship-editor/add-relationships.md).

# Add relationships

Relate records to the element in the Relationship Editor by dragging them in from the Data Hub or with the Add button.

There are two ways to relate a record to the element: drag it in from the Data Hub, or pick it with **+ Add**. Either way, the new relationship is marked **New** and waits for you to commit it.

{% hint style="info" %}
You need the **Command Relationship Editor** role. To relate a planned record, you also need permission to change future state.
{% endhint %}

## How to

### Drag records in from the Data Hub

1. Open the [Data Hub](https://docs.ins-pi.com/command/the-portal/data-hub.md). In the editor it lists only the tables related to the element; click **Show all** to see every table.
2. Find the record you want and start dragging it. You can drag several at once.
3. The sides you are allowed to drop on light up. Drop the record on **↑ Upstream** or **↓ Downstream**. In the **List** view, drop it anywhere on the list: Command picks the side, or asks.
4. If more than one relationship type fits, choose one in **Relate … as…**. With only one type, the relationship is added right away.

<figure><img src="https://414746897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx4mE784snR9Eb8oVrk4e%2Fuploads%2Fgit-blob-ed3ab71fa6e7296e8ece37aacb26415a10fae2a4%2Fcommand-relationship-editor-drag-add.gif?alt=media" alt="A business capability is dragged from the Data Hub onto the upstream side and appears with a New marker, ready to commit."><figcaption><p>Drag a record in to relate it</p></figcaption></figure>

On a Form, click **Edit** first: a record dropped on a Form that is not in edit mode is not added, and a message says why.

In the **Graph** view, each side is split into one area per relationship type, so where you drop also picks the type.

### Add a record with + Add

Use this on a phone, with a keyboard, or when the Data Hub is closed.

1. Click **+ Add** at the top of **↑ Upstream** or **↓ Downstream**.
2. Choose a **Class**, such as *Business Capability*.
3. Type part of the name in **Record** and pick the record.
4. Choose the relationship type if asked.

<figure><img src="https://414746897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx4mE784snR9Eb8oVrk4e%2Fuploads%2Fgit-blob-be3d81ca4195fc29e4649221380083f8a3ea87b4%2Fcommand-relationship-editor-add-picker.png?alt=media" alt="The Relate a record upstream popover, with a class chosen and matching records listed under the search box."><figcaption><p>Pick a record with + Add</p></figcaption></figure>

**+ Add** searches live records only. To relate a planned record, drag it in from the Data Hub.

## Good to know

When a record cannot be added, a notice explains why. The common reasons:

| Notice                                                                | What to do                                                                                                    |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| *No suggested relationship exists between this record and …*          | ServiceNow does not suggest a relationship between these two classes. Ask your administrator if you need one. |
| *This relationship only goes upstream* (or *downstream*)              | Drop it on the other side.                                                                                    |
| *Relating a planned element needs permission to change future state.* | Ask your administrator for that permission.                                                                   |

You cannot drop a whole hierarchy at once; drag the records you need.

## Related

* [Relationship Editor](https://docs.ins-pi.com/command/features/relationship-editor.md)
* [Change, remove and commit relationships](https://docs.ins-pi.com/command/features/relationship-editor/change-and-commit.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/relationship-editor/add-relationships.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.
