> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/integrations/incidentio/connecting-entities-to-incident.io.md). # Connecting entities to incident.io {% hint style="info" %} Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance. {% endhint %} This article explains how to connect Cortex entities to incident.io. For configuration instructions, see [Configuring the integration for incident.io](/ingesting-data-into-cortex/integrations/incidentio.md). For what you can do once entities are connected, see [Using the integration for incident.io](/ingesting-data-into-cortex/integrations/incidentio/using-the-integration-for-incident.io.md). There are two connections you can make, and they're independent of each other: * **Incidents (through custom fields)** bring incident data into Cortex, so incidents appear on an entity's page and you can query them in CQL. * **On-call schedules** bring on-call data into Cortex, so you can see who's on call for an entity. Configuring one doesn't configure the other. If you want both incident and on-call data for an entity, set up both. **How Cortex matches values** For both connections, Cortex matches on name first, then falls back to the identifier. For example, if your entity is named "Payment Service," Cortex looks for a value in incident.io of either `Payment Service` or `payment-service`. If your Cortex team is named "Data Team," Cortex looks for either `Data Team` or `data-team`. ## Connecting an entity to incident.io incidents Cortex automatically matches incidents to Cortex entities using custom field values in incident.io. As long as the custom field value matches the entity's name or identifier, you don't need to register anything. To point an entity at a specific custom field instead, add an `x-cortex-incident-io` block to the YAML. ### Connecting incidents in the entity descriptor Reference the custom field by its name: ```yaml x-cortex-incident-io: customFields: - name: Affected Service value: Payment Service alias: prod-account ``` If the custom field's name might change, reference it by ID instead. You can find the ID in the custom field's URL in incident.io. ```yaml x-cortex-incident-io: customFields: - id: 01HQ3W8ZK5MJTPV2N6RXBD4Y7C value: Payment Service alias: prod-account ``` Custom fields have the following field definitions:

Field	Description	Required
`name`	The name of the custom field in incident.io. Use either `name` or `id`.
`id`	The ID of the custom field in incident.io. Use either `name` or `id`.
`value`	The value stored in that custom field for this entity.
`alias`	Alias for the configuration in Cortex (only needed if you have opted into multi-account support).

## Connecting an entity to incident.io on-call schedules {% hint style="info" %} On-call support for incident.io is in Public Beta. {% endhint %} Connect on-call schedules from incident.io to see current on-call information for an entity in the catalog. Unlike custom fields, on-call schedules aren't matched automatically. You link them in one of two ways: * **By schedule** - Select one or more specific incident.io schedules to link directly to the entity. * **By team** - Select a team from incident.io. Every schedule associated with that team is linked to the entity automatically, so new schedules for that team appear without additional configuration. Link by team when the team owns the entity and you don't want to revisit the mapping each time its rotations change. Link by schedule when you need a specific rotation on the entity and not everything the team runs. You can configure on-call from an entity page in Cortex, or in the YAML. ### Connecting from an entity's details page 1. Navigate to an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md). 2. In the upper-right corner, click **Configure entity**. 3. From the left sidebar, locate the **Connections** section, then select the **On-call** tab. 4. From the **Integration** dropdown, select incident.io. 5. Do one of the following: 1. From the **Schedule name** dropdown, select a schedule to link to the entity. 2. From the **Team name** dropdown, select a team to link to the entity. 6. Click **Save changes**. ### Connecting in the YAML Registrations are made by ID, not by name, and don't take an alias. On-call registrations have the following field definitions:

Field	Type	Required?
`type`	Either `SCHEDULE` or `TEAM`
`id`	ID of the incident.io schedule or team.

#### Schedules To map a single schedule to an entity, use the schedule's ID. You can find it in incident.io in the schedule's URL. ```yaml x-cortex-oncall: incidentio: - type: SCHEDULE id: 01JXZXCV1NAT4B6NAVM5GMNM20 ``` Multiple schedules can be mapped to an entity: ```yaml x-cortex-oncall: incidentio: - type: SCHEDULE id: 01JXZXCV1NAT4B6NAVM5GMNM20 - type: SCHEDULE id: 01JXZXCV1NAT4B6NAVM5GMNM47 ``` #### Teams A `TEAM` registration maps every incident.io schedule whose team field matches that Cortex team. To map a team, use the team's ID. You can find it in incident.io in the team's URL. ```yaml x-cortex-oncall: incidentio: - type: TEAM id: 01JXZXCV1NAT4B6NAVM5GMNM13 ``` Multiple teams can be mapped to an entity: ```yaml x-cortex-oncall: incidentio: - type: TEAM id: 01JXZXCV1NAT4B6NAVM5GMNM13 - type: TEAM id: 01JXZXCV1NAT4B6NAVM5GMNM14 ``` #### Schedules and Teams You can register both on the same entity. Use this when a team owns the entity but you also want a specific shared rotation on it: ```yaml x-cortex-oncall: incidentio: - type: TEAM id: 01JZ7K2WN4CQD9BX5VHTF6RGA3 - type: SCHEDULE id: 01JXZXCV1NAT4B6NAVM5GMNM20 ```