> ## Documentation Index
> Fetch the complete documentation index at: https://docs.incident.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Relationship mapping and automation

> Build one workflow that reaches the right team, channel, and on-call person for every incident, instead of one per team.

Catalog entries link to each other through their attributes: a service has an owning team, and that team has a Slack channel, a Slack user group, and an escalation path. Workflows, alert routes, and custom fields can all follow those links. That means one workflow can find the right people for whichever service is affected, rather than you needing a separate one for every team.

## Model the relationships

A relationship is just an attribute whose type is another catalog type. When you [add an attribute](https://docs.incident.io/catalog/catalog-setup.md), the **Reference** types on offer include your own catalog types plus the ones we provide, such as:

* **Slack Channel** and **Microsoft Teams Channel**, for where a team talks
* **Slack User Group**, for who to invite
* **Escalation Path** and **Schedule**, for who to page
* **User**, for a specific person

A common model is a **Service** type with an **Owning team** attribute, and a **Team** type with **Slack channel**, **Slack user group**, and **Escalation path** attributes. See [What data should I bring into Catalog?](https://docs.incident.io/catalog/what-data.md) for more examples, and [How do I get data into Catalog?](https://docs.incident.io/catalog/importing-data.md) to populate them.

Then add a Catalog-backed [custom field](https://docs.incident.io/incidents/custom-fields.md), like **Affected services**, so each incident records which entries it affects.

## Follow relationships in workflows

When a workflow step or condition asks for a value, the variable picker lets you step through an entry's attributes. For example, to invite the teams that own the affected services, pick **Incident → Affected services → Owning team → Slack user group** in the **Invite user or group to the incident's channel** step. Use the arrow keys, or click an item, to move in and out.

The picker only shows you variables that fit the field you're filling, which can make it look like a path is missing when it isn't. A few things to know:

* **Anything you reach through a multi-value field is a list.** An incident can have several affected services, so **Affected services → Owning team → Slack channel** is a list of channels. It'll show up in steps that take several values, but not in one that takes a single channel, like **Send message to a channel**. For those you need to decide what you want to happen: a [loop](https://docs.incident.io/workflows/loops.md) runs the step **For each value of** the list, so you could post in every affected team's channel, or a Query ending in **First** picks one value for you.
* **The picker only goes a few levels deep.** For anything longer, use a Query expression, which can follow as many links as you like.
* **What's available depends on the trigger.** An incident trigger can't see an alert's attributes. If you need those, start the workflow from **an alert is attached to an incident** instead.

### Query expressions

When you need to do more than follow a link, add a **Query** expression (see [How to use Workflow Expressions](https://docs.incident.io/workflows/expressions.md)). A Query starts from a value and applies a series of steps to it:

* **Navigate** follows an attribute to a related entry, like from a service to its team. From a list, it returns a list.
* **Filter** keeps the entries that match your conditions.
* **First**, **Maximum**, **Minimum**, and **Random** pick one entry from a list.
* **Count** and **Sum** turn a list into a number.
* **Merge** combines the result with another variable of the same type.

To fill a single-value field from a list, end the Query with **Filter** and then **First**. Be wary of **First** on its own when the list has no meaningful order, like the teams a person belongs to, because you'll get an arbitrary one.

If a required field could end up empty, give the expression a default. Otherwise the step won't be able to run for incidents where the path leads nowhere. If you'd rather those incidents were skipped altogether, add a condition to the workflow instead.

### Templates

Several workflow templates are built this way, including **Notify responders about new incidents**, **Invite the affected team to an incident**, and **Escalate via incident.io**. When you create one, we find a path through your Catalog from the incident to the channel, user group, or escalation path it needs.

## Follow relationships in alert routes

When your alert attributes are Catalog-backed, an alert route can use them the same way. Under **How should alerts be escalated?**, choose to escalate **using the alert's attributes**, and the route suggests paths from the alert to an escalation path, like **Alert → Team → Escalation path**. See [Alerts and teams](https://docs.incident.io/alerts/team-routing.md) for a walkthrough.

The route's incident template can set custom fields from the alert's attributes too, so incidents created from alerts arrive with their affected services and teams already filled in.

All of this relies on the alert's attribute value matching a catalog entry, and there are two things to know about how that works:

* **The value has to match exactly.** We compare it, case-sensitively, with each entry's ID, external ID, and aliases, and with its name if the catalog type has **Reference entries by name** turned on. If more than one entry matches, the external ID wins, then an alias, then the name.
* **If nothing matches, the attribute is left empty**, and you won't see an error. Anything the route derives from it will be empty too, so nobody gets paged from that path.

So set a fallback escalation path on the route, and an alert that doesn't match will still reach someone.

## Derive one field from another

A custom field can fill itself in from another one. Set **Affected teams** to **Set automatically**, and use an expression that navigates from **Affected services** to each service's owning team. Responders pick the service, and the team follows. See [Set a custom field automatically](https://docs.incident.io/incidents/custom-fields.md#set-a-custom-field-automatically).

## Connect people across tools

People have accounts in lots of tools, and the Catalog ties them together. Each external user type, like **Github User**, **PagerDuty User**, or **Sentry User**, has an **incident.io User** attribute that points at the person's incident.io account. Many integrations link accounts automatically when you connect them. GitHub and Jira accounts are never linked automatically: each person connects their own from their [connected accounts](https://docs.incident.io/catalog/connected-users.md) settings, or an admin links them from the **User** catalog type.

A step that needs a person, like **Invite user or group to the incident's channel** or **Assign incident roles**, takes an incident.io user. To use someone from another tool, navigate to their **incident.io User**. For example, if your **Service** type has a **Code owner** attribute of type **Github User**, pick **Incident → Affected services → Code owner → incident.io User** in the invite step to invite the code owners of the affected services.

If someone hasn't been linked, their **incident.io User** is empty. The step just leaves them out and carries on for everyone else.

Slack users are the exception: a **Slack User** can fill a user parameter directly.
