> 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/resources/beta/incident.io-on-call.md).

# Incident.io On-call

On-call support brings your incident.io on-call schedules into Cortex, so you can see who is on call directly on entity pages and use that data in CQL and Scorecards. This builds on our incident.io incident integration to give you a single, reliable source of truth for both incidents and on-call.

### What's new

* **YAML and UI configuration**: Manage on-call links through the entity editor UI or the `x-cortex-oncall` block in entity YAML.
* **On-call on entity pages**: See the current on-call responders and upcoming shifts for a service directly in the catalog, so anyone can find who to reach without leaving Cortex.
* **CQL support**: Write rules and queries against on-call data using the `oncall` CQL expression.
* **Scorecards**: Enforce operational standards, such as requiring every production service to have an on-call schedule configured.

{% hint style="info" %}
Note: In order to ingest on-call data from incident.io, Cortex keys will need `schedules.view`  and `catalog_entries.view` permissions. Please confirm these permissions have been added to your existing incident.io API keys before getting started. 
{% endhint %}

### Connecting entities to Incident.io On-call schedules

Connect on-call schedules from incident.io to see the latest on-call information for an entity in the catalog. You can link on-call in 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. Any schedule associated with that team is automatically linked to the entity, so new schedules for that team appear without additional configuration.

You can configure this from the on-call editor on the entity page, or by setting the `x-cortex-oncall` block in the entity's YAML. 

#### Connecting via the UI 

1. Navigate to an [entity's details page](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/details) in Cortex,
2. In the upper right corner, click **Configure entity**.
3. Click the **On-call** tab on the left side bar. 

<figure><img src="/files/L4s12R4iOd27ssXFI5kV" alt=""><figcaption></figcaption></figure>

4. Select schedule and/or team names manually from the dropdown.&#x20;
5. Once selected, click **Save changes** for the mappings to apply.&#x20;

#### Connecting via YAML&#x20;

In Incident.io, use the schedule ID to map a given schedule directly to an entity in Cortex. You can find the ID from the schedule URL within incident.io or by going to view catalog > External ID. You can map multiple schedules to a single entity.&#x20;

```json
x-cortex-oncall:
  incidentio:
    - type: SCHEDULE
      id: 01JXZXCV1NAT4B6NAVM5GMNM20
```

In incident.io, use the team ID to map a given team's schedules to an entity in Cortex. You can map multiple teams to a single entity.

```json
x-cortex-oncall:
  incidentio:
    - type: TEAM
      id: 01JXZXCV1NAT4B6NAVM5GMNM13
```

### Viewing on-call information&#x20;

#### On-call shift data

View all on-call shifts ingested via the incident.io integration in a single place from integrations > data > [on-call shifts](https://app.getcortexapp.com/admin/integrations/data). This allows you to see exactly what data Cortex has brought in from the integration and what entities it's been linked to within Cortex.&#x20;

<figure><img src="/files/U17wcKkVXDK4SGT0Acft" alt=""><figcaption></figcaption></figure>

Clicking into an on-call shift row opens a side sheet to provide additional details about who is on-call now, who is on-call next and what teams this schedule is associated with.&#x20;

#### Entity pages

View current on-call information in the **On-call** block on an entity's metadata sidebar, and on the entity's details page under **Connections > On-call**.

<figure><img src="/files/ggL2ju9ej6GGh58yQBUG" alt=""><figcaption></figcaption></figure>

On-call information also appears on the entity's **On-call** tab, showing the current responder(s) and schedule details pulled from incident.io.&#x20;

<figure><img src="/files/vywp5pPvNL2bQNAoI39J" alt=""><figcaption></figcaption></figure>

Clicking into an schedule row from the entity page or on-call shifts page, opens a side sheet to provide additional details about who is on-call now, who is on-call next, what team this schedule is associated with, and the full list of participants on rotation for the schedule.&#x20;

<figure><img src="/files/DKIM40euZWkqlGDA6Rsp" alt=""><figcaption></figcaption></figure>

#### Engineering homepage&#x20;

View upcoming on-call rotations on your engineering homepage in the **My on-calls** block. We look forward 6 months for showing on-call schedules on the homepage.&#x20;

<figure><img src="/files/xfiSTENZMNgGDmdaKiQc" alt=""><figcaption></figcaption></figure>

### Using on-call information in Scorecards and CQL  <a href="#scorecards-and-cql" id="scorecards-and-cql"></a>

#### **CQL expressions**

The `oncall` CQL expression lets you write queries and Scorecard rules based on on-call data. See the [CQL documentation](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Integrations\&path=incident.io\&path=On-call) for the complete list of available expressions.

#### **Scorecards**

Create Scorecard rules using on-call based CQL expressions to track operational readiness, for example:&#x20;

* Verify that all production services have an on-call schedule configured
* Ensure critical services have on-call coverage before go-live

## Syncing data from incident.io&#x20;

Cortex syncs schedule data from incident.io every hour.&#x20;