> 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/using-the-integration-for-incident.io.md).

# Using the integration for 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 use the integration for incident.io. For configuration instructions, see [Configuring the integration for incident.io](/ingesting-data-into-cortex/integrations/incidentio.md).

## Connecting an entity to incident.io

By default, Cortex tries to automatically match entities to their corresponding custom field values in incident.io.

Cortex first looks up the custom field value using the entity's name, then falls back to its identifier. For example, if your entity is named "Payment Service," Cortex looks for a matching custom field value in incident.io of either `Payment Service` or `payment-service`.

### Editing the entity descriptor

```yaml
x-cortex-incident-io:
  customFields:
  - name: Service
    value: Payment Service
    alias: prod-account
```

<table><thead><tr><th width="89.046875">Field</th><th width="397.5546875">Description</th><th align="center">Required</th></tr></thead><tbody><tr><td><code>name</code></td><td>Name for the entity (from <code>customFieldName</code>)</td><td align="center"><strong>✓</strong></td></tr><tr><td><code>value</code></td><td>Display name for the entity in Cortex</td><td align="center"><strong>✓</strong></td></tr><tr><td><code>alias</code></td><td>Alias for the configuration in Cortex (only needed if you have opted into multi-account support)</td><td align="center"></td></tr></tbody></table>

```yaml
x-cortex-incident-io:
  customFields:
  - id: SVC_12345
    value: payment-service
    alias: prod-account
```

<table><thead><tr><th width="88.69140625">Field</th><th width="397.55078125">Description</th><th align="center">Required</th></tr></thead><tbody><tr><td><code>id</code></td><td>ID for the entity (from <code>customFieldID</code>)</td><td align="center"><strong>✓</strong></td></tr><tr><td><code>value</code></td><td>Tag for the entity in Cortex</td><td align="center"><strong>✓</strong></td></tr><tr><td><code>alias</code></td><td>Alias for the configuration in Cortex (only needed if you have opted into multi-account support)</td><td align="center"></td></tr></tbody></table>

### Viewing incident.io information on entity pages

Once the integration is configured, incident data appears in two places on an [entity's details page](/ingesting-data-into-cortex/entities-overview/entities/details.md):

* When there are active (unresolved) incidents associated with an entity, an active incident card appears at the top of the **Overview** tab.
* Full incident history is available under **On-call & incidents** in the entity's sidebar.

## Creating Scorecard rules and writing CQL queries with the incident.io integration

See examples below. More examples are available in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer).

<details>

<summary>Check if incident.io service is set</summary>

Check if entity has a registered incident.io custom field value in its entity descriptor.

If no registration exists, Cortex will try to automatically detect which corresponding incident.io custom field value is associated with the entity.

**Definition:** `incidentio (==/!=) null`

**Example**

For a Scorecard focused on operational maturity, you can use this expression to make sure each entity has an incident.io project set:

```
incidentio != null
```

</details>

<details>

<summary>Incidents</summary>

List incidents, filterable by severity and status.

* Created at
* Mode
* Name
* Severity
* Status
* Summary
* Type
* URL

**Definition:** `incidentio.incidents()`

**Examples**

To assess entities' health in a Scorecard, you can write a rule to make sure a given entity has fewer than three incidents with a severity of SEV1:

```
incidentio.incidents(severity = ["SEV1"]).length < 3
```

You can also use this expression to query for entities that have two or fewer critical incidents in the last three months:

```
  incidentio.incidents(severity = ["Critical"]).filter((incident) => incident.createdAt.fromNow() > duration("-P90D")).length <= 2
```

</details>

## Viewing incident.io integration logs <a href="#still-need-help" id="still-need-help"></a>

{% hint style="info" %}
This feature is available in Cortex cloud.
{% endhint %}

While viewing an integration's settings page, select the **Logs** tab to view error logs from the last 7 days. You can filter the logs list by configuration and by operation (for example, you could filter to view errors surfaced only via Scorecards).

<div align="left" data-with-frame="true"><figure><img src="/files/x8JmoPqXZTJ7YHeFJpOA" alt="The &#x27;Logs&#x27; tab on an integration&#x27;s settings page shows error information over the past 7 days." width="563"><figcaption></figcaption></figure></div>

Click into a row to get more information, including time stamp, status code, full error, and request path.