Skip to main content
Connecting entities to Rootly is in Private Beta. To request access, contact the Cortex Customer Engineering team.
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.
This article explains how to connect Cortex entities to Rootly. For configuration instructions, see Configuring the integration for Rootly. For what you can do once entities are connected, see Using the integration for Rootly. There are two kinds of data you can connect:
  • Incidents (through Rootly services) bring incident data into Cortex, so incidents appear on an entity’s page and you can query them in CQL.
  • On-call (through Rootly services, teams, or schedules) brings on-call data into Cortex, so you can see who’s on call for an entity.
When an entity matches a Rootly service, Cortex uses that match for both incidents and on-call. On-call registrations for teams and schedules only affect on-call data.

​
Connecting an entity to Rootly incidents

Each Rootly incident lists the services it affects. Cortex matches each of those services to an entity, checking in this order:
  1. A registration in the entity descriptor - If an entity registers the Rootly service in its x-cortex-rootly block, Cortex uses that registration.
  2. The Cortex ID on the Rootly service - If you’ve set up Rootly’s Cortex integration, each Rootly service stores the ID of its Cortex entity, and Cortex matches on it.
  3. The Rootly service name - Cortex matches the service name against the entity’s Cortex tag. The match isn’t case-sensitive.
Cortex doesn’t automatically match on Rootly service slugs. If neither the Cortex ID nor the service name lines up with an entity, register the service in the entity descriptor. Incidents also appear on the pages of the Cortex teams responsible for them.

​
Connecting incidents in the entity descriptor

You can register Rootly services by ID or slug.
The YAML examples on this page show only the x-cortex-* block. When you add one to an entity descriptor, nest it inside the info section. Blocks at the root level of the file are ignored without an error. For a full example, see Defining entities with YAML.
Service ID
Service slug

​
Connecting an entity to Rootly on-call schedules

Cortex links Rootly on-call to entities automatically in two ways:
  • Through services - A Rootly service may have no escalation policy, which determines who’s paged for that service. When a Rootly service matches an entity, Cortex shows who’s on call for that service’s escalation policy on the entity. Cortex matches services the same way it does for incidents: by an x-cortex-rootly registration, by the Cortex ID on the Rootly service, or by the service name. See Connecting an entity to Rootly incidents.
  • Through teams - Each Rootly schedule has an owning team. Cortex matches that team to a Cortex team, either by the Cortex ID that Rootly’s Cortex integration stores on the team, or by matching the Rootly team name against the Cortex team’s tag. The schedule links only to the entity that matched. In this case, it is only linked to the matched cortex team, not to the services the team owns.
To link schedules explicitly, register them in one of two ways:
  • By schedule - Select one or more specific Rootly schedules to link directly to the entity.
  • By team - Select a team from Rootly. 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.
  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 Rootly.
  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

To register on-call in the YAML, add an x-cortex-oncall block to the entity’s descriptor.
The YAML examples on this page show only the x-cortex-* block. When you add one to an entity descriptor, nest it inside the info section. Blocks at the root level of the file are ignored without an error. For a full example, see Defining entities with YAML.
Registrations are made by ID, not by name. On-call registrations have the following field definitions:

​
Schedules

To map a schedule to an entity, use the schedule’s ID. You can find it in Rootly in the schedule’s URL.

​
Teams

A TEAM registration maps every Rootly schedule owned by that team. To map a team, use the team’s ID.

​
Schedules and teams

You can register both on the same entity, and map more than one of each. Use this when a team owns the entity but you also want a specific shared rotation on it:
Last modified on October 26, 2026