# PagerDuty

> Service ownership, open incident state and on-call coverage beside the component they belong to.

Link a PagerDuty technical service to the stratum for the component it covers.
The saved tab shows who owns the service, what is open against it, and whether
the primary escalation level had cover when it was fetched. Responding to
incidents stays in PagerDuty.

A PagerDuty technical service is the only object that can be linked. Business
services appear inside a service's panel as related rows, and cannot be linked
on their own.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In PagerDuty, create a dedicated read-only REST API key under
   **Integrations → Developer Tools → API Access Keys**. An Events API
   integration key will not work here. If you paste one, Blueprintr sends it and
   PagerDuty rejects it with "PagerDuty services read failed (HTTP 401). Check or
   replace the REST API key."
3. In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, choose **New integration**, and select
   PagerDuty as the **Type**.
4. Give the connection a **Name**, set the two options below, paste the key into
   **API token**, and choose **Connect & verify**. Without a name the form
   refuses with "Give this integration a name."

### Connection options

Both dropdowns open on **Use default**, which stores nothing and behaves as the
first real option.

| Field | Options | Effect |
| --- | --- | --- |
| **PagerDuty region** | Use default, United States (US), Europe (EU) | Chooses the API host. Use EU for accounts whose address ends in `eu.pagerduty.com`. Default is US |
| **Imported content** | Use default, Summary (recommended), Detailed: include titles and description | Detailed adds incident titles and the service description. Default is Summary |

Verification makes two list calls, one for services and one for incidents. Both
may return nothing and still verify, so a successful check proves the key reads
those collections, not that the account has content. On-call coverage and
service dependencies are not exercised at verification time, so they may still
fail when a service is linked.

## Link a service

Open the stratum and choose **Continuum Link**, then search by any of these.
PagerDuty has no prefix syntax.

| What you type | What happens |
| --- | --- |
| A service name | Searches service names, up to about 300 services |
| A service ID (6 to 32 uppercase letters and digits) | Looked up directly. If PagerDuty returns 404, the same text is searched as a name |
| A PagerDuty service URL | The ID is read out of `/service-directory/<ID>` or `/services/<ID>`. The URL itself is never called |

A URL from the other region is refused rather than looked up: "This PagerDuty
service URL belongs to a different region. Choose the matching connection."

## What the panel shows

| Section | Contents |
| --- | --- |
| Service | Service, Service ID, Region, Incident posture, Meaning, Owning team, Escalation policy, and the description in Detailed mode |
| Open incidents | Counts of reported open, high-urgency, low-urgency, unknown urgency and unknown status |
| Incident coverage | Retrieval, time range, content mode, how many incidents are shown, and a consistency row when the two reads disagree |
| Open incident details | Up to 20 incidents, newest first |
| Ownership in PagerDuty | Links to the escalation policy and the owning team |
| On-call coverage | Whether the primary level had cover, when to recheck, and a privacy note |
| Service relationships | Retrieval state, then a table of related services |

The headline restates PagerDuty's service status: "No open incidents reported",
"Acknowledged incidents", "Triggered incidents", "Maintenance · new incidents
suppressed" or "Disabled · new incidents suppressed". The Meaning row spells out
the limit of that reading: "PagerDuty incident and notification state; not a
measurement of component availability."

If the service read and the incident read disagree, the headline is replaced with
"Service and incident state disagree · refresh to recheck" rather than showing a
healthy state.

### Counting and its limits

Open incidents are those PagerDuty reports as triggered or acknowledged, with no
creation-date cutoff. Retrieval stops after five pages of up to 100, so roughly
500 incidents. When that cap is reached, the section title gains "partial
retrieval", every count gains a trailing plus sign, and the Retrieval row reads
"Partial: stopped after 5 pages; counts are lower bounds."

On-call coverage is computed over one hour starting at the fetch, filtered to the
service's escalation policy. If those pages could not all be read, coverage reads
Unknown rather than claiming a gap: "Coverage retrieval is partial; absence does
not establish a coverage gap." A service with no escalation policy makes no
on-call call at all.

Related services are limited to six detail lookups. Business services never carry
a state, showing "Business impact not retrieved", because the connector does not
infer business impact.

## What is never imported

Responder names, user IDs, email addresses and schedule names are excluded in
both content modes. So are incident bodies, assignees, acknowledgers,
conference-bridge numbers, service integration keys and business-service points
of contact. Detailed mode adds exactly two fields: the incident title, truncated
to 250 characters, and the service description, truncated to 1000 characters.

Only `pagerduty.com` HTTPS links reach the panel, with query strings and
fragments stripped.

## Audience

PagerDuty declares no audience setting, so its saved panel is visible to everyone
who can read the stratum. On a public blueprint that includes anonymous readers,
embeds and exports. Service names, team names and relationships are visible even
in Summary mode.

Choose **Detailed** only when incident titles and the service description are
appropriate for that audience. Reducing detail later applies to subsequent
refreshes and does not recall copies already shared.

## Changing the region later

Changing the region is refused while any binding predates the region setting:
"Remove the existing legacy bindings before changing PagerDuty region, then link
services from the new region."

If every binding does carry a region, the change is allowed, and each of those
services then fails on refresh with "This service was linked in a different
PagerDuty region. Unlink it and choose the service again." The new region is
verified with the existing credential before it saves, so a US-only key fails the
switch to EU and the previous setting is kept.

## Refreshing and recovery

Snapshots become due for refresh after five minutes, which is a reminder rather
than automatic polling. A failed service or incident read keeps the previous
snapshot and adds a warning; it never becomes a healthy zero. A failed on-call or
dependency read marks only that section unavailable and still saves the panel.