> 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/pagerduty/connecting-entities-to-pagerduty.md).
# Connecting entities to PagerDuty
Connect entities to PagerDuty automatically or manually via the entity's descriptor YAML
{% 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 entities to PagerDuty. For configuration instructions, see [Configuring the integration for PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty.md#configuring-pagerduty). For instructions on using the integration, see [Using the integration for PagerDuty](/ingesting-data-into-cortex/integrations/pagerduty/using-the-integration-for-pagerduty.md).
{% hint style="info" %}
Cortex runs the following background jobs for PagerDuty:
* On-call information on the Engineering homepage is refreshed every 60 minutes.
* Services used for automapping and active incidents are fetched approximately every 5 minutes, or however long the refresh takes.
* User data for identity mapping is synced daily at 10 a.m. UTC.
{% endhint %}
## Connecting an entity to PagerDuty
Cortex entities are connected to PagerDuty in one of two ways: automatically through discovery, or explicitly by defining a PagerDuty service, schedule, or escalation policy in the entity's descriptor YAML.
### Discovering entities automatically
By default, Cortex uses the [Cortex tag](/ingesting-data-into-cortex/entities-overview/entities.md#cortex-tag) (e.g. `checkout-api`) or the entity's name as the "best guess" for PagerDuty services. For example, if the Cortex tag is `checkout-api`, the corresponding service in PagerDuty should also be `checkout-api`.
If your PagerDuty services don't cleanly match the Cortex tag or name, define the connection in the [entity descriptor](#connecting-via-an-entity-descriptor) instead.
#### Considerations for registering PagerDuty entities
Cortex recommends setting up PagerDuty at the **service level** by registering service entities with PagerDuty services, rather than configuring team entities with a PagerDuty schedule.
If PagerDuty is set up on a service level, you can see current on-call information listed within a given service's page. If PagerDuty is set up on the team level, you can only view on-call rotation information from a team page.
Other benefits of setting up PagerDuty on a service level include:
* Structuring PagerDuty 1-1 with services enables better alert routing and analytics, something organizations struggle with more when PagerDuty is set up on a team level.
* With a service-level setup, it's easier to enforce a compliant on-call policy for all services in PagerDuty, especially when making use of Scorecards.
* The service-level setup is less reliant on team members tagging incidents with service information because services and incidents are already linked.
* You gain the ability to get data from your Cortex catalog into PagerDuty, such as tier and criticality. By tying the service entities in the catalog to those in PagerDuty, you can automate processes and streamline severity protocols.
#### Viewing on-call data only
If you only want to view on-call data for entities, and do not want incidents displayed in Cortex, you can register the escalation policy ID for an entity. See [Defining an escalation policy](#defining-an-escalation-policy) below.
### Connecting via entity descriptor
To explicitly connect an entity to PagerDuty, add the `x-cortex-oncall` block to the entity's YAML, specifying a PagerDuty service, schedule, or escalation policy.
Field
Description
Required?
id
PagerDuty ID for the service, schedule, or escalation policy
:check:
type
SERVICE, SCHEDULE, or ESCALATION_POLICY
:check:
{% hint style="warning" %}
You can only set up one of the three options below per entity.
{% endhint %}
#### Defining a PagerDuty service
In PagerDuty, find the [service ID value](https://support.pagerduty.com/main/docs/service-directory#configure-service-standards-settings). The URL for the service contains the ID, e.g. `PDEF456` in `https://yourdomain.pagerduty.com/services/PDEF456`.
You can only configure one service ID per entity.
```yaml
x-cortex-oncall:
pagerduty:
id: PDEF456
type: SERVICE
```
#### Defining a schedule
In PagerDuty, find the [schedule ID](https://developer.pagerduty.com/api-reference/3f03afb2c84a4-get-a-schedule). The URL for the schedule contains the ID, e.g. `PABC123` in `https://yourdomain.pagerduty.com/schedules/PABC123`.
You can only configure one schedule per entity.
```yaml
x-cortex-oncall:
pagerduty:
id: PABC123
type: SCHEDULE
```
#### Defining an escalation policy
In PagerDuty, find the [escalation policy ID](https://developer.pagerduty.com/api-reference/51b21014a4f5a-list-escalation-policies). The URL for the escalation policy contains the ID, e.g. `P7LVMYP` in `https://yourdomain.pagerduty.com/escalation_policies/P7LVMYP`. You can only configure one escalation policy per entity.
Linking a Cortex entity to a PagerDuty escalation policy surfaces only on-call information in Cortex, not incidents. This is useful for teams that want to show on-call schedules without incident visibility.
```yaml
x-cortex-oncall:
pagerduty:
id: P7LVMYP
type: ESCALATION_POLICY
```
### Identity mappings
Cortex maps email addresses in your PagerDuty instance to email addresses that belong to team members in Cortex. When [identity mapping](/configure/settings/managing-users/identity-mapping.md) is set up, users can see their personal on-call status from the [Engineering homepage](/streamline/homepage.md).
## Enabling the On-call Assistant
{% hint style="info" %}
The On-call Assistant only works for service-level PagerDuty registrations, since these notifications are related to affected services.
{% endhint %}
After configuring the integration, you can turn on the On-call Assistant, which notifies users via Slack when an incident is triggered in PagerDuty. Notifications include runbooks, links, dependencies, and key information about the affected entity. For instructions, see [On-call Assistant](/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant.md).