PagerDuty
Import PagerDuty incidents as Aegis incidents.
PagerDuty is where many operations teams are alerted and paged when a service fails. This connector reads those incidents into the Aegis incident register, so an outage that started as a page can be assessed, documented and, where needed, reported like any other incident. It reads only: Aegis does not create, acknowledge or resolve anything in PagerDuty.
At a glance
| Direction | Into Aegis. |
|---|---|
| What it brings in | PagerDuty incidents, up to 100 per sync. Through the API you can limit a sync to incidents since a date or to chosen services; the button on the page has no such filter. |
| Where it lands | Incidents, as system-outage incidents with PagerDuty as their source and the PagerDuty service as the affected system. |
| Credentials and permissions | A PagerDuty REST API key (v2). Your PagerDuty subdomain is optional and is stored for reference only. |
| Owner of imported records | The person who ran the sync. |
| When it runs |
On demand, from Sync Incidents on the connector page or
through the API (POST /api/connectors/pagerduty/sync).
There is no schedule.
|
| Set it up |
/connectors/pagerduty, by people allowed to configure
connectors, on a plan that includes the connector.
|
Who uses it
Admin Manager Managers and Admins can open the page, save the API key, test the connection and run a sync.
Contributor
Viewer Contributors and Viewers are
redirected away from /connectors/pagerduty. They work with the
imported records in Incidents like any other
incident.
What's on this screen
No screenshot of this page was captured for this edition. Reading from the top, the page shows:
-
A breadcrumb back to
Connectors, the titlePagerDuty Connectorand a one-line description. -
The
Connection Statuspanel. A coloured dot and label show the state:Not Tested,Testing...,Connected,Syncing...orConnection Failed. Before an API key is saved the panel readsConfigure API key below to connect.Once a key is saved it offersTest Connection, and after a successful test alsoSync Incidents. -
Sync Results, which appears after a sync with three counts —Imported,UpdatedandSkipped— and a line with the number of errors when any occurred. -
The
Configurationform:API Key(required, masked),Subdomain (Optional)andSave Configuration. -
Setup Instructions, six numbered steps for creating the key in PagerDuty, and aSync Featuresbox.
Connect PagerDuty
-
In PagerDuty, open
Integrations›Developer Tools›API Access Keysand create a REST API key (v2). PagerDuty shows the key only once, so copy it straight away. -
In Aegis, open
/connectors/pagerduty. Paste the key intoAPI Keyand, if you like, enter your subdomain (for examplecompanyfromcompany.pagerduty.com). -
Select
Save Configuration. AConfiguration savedmessage appears and the status returns toNot Tested: saving never proves the connection. -
Select
Test Connection. While it runs the label readsTesting.... On success the panel showsConnected to PagerDutywith whether any services and incidents were found and up to three of your account's abilities. On failure it showsConnection Failedwith the reason.
To keep the saved key when you change only the subdomain, leave
API Key blank; the hint under the field says so.
Import incidents
-
After a successful test, select
Sync Incidents. The status readsSyncing...while Aegis reads incidents from PagerDuty. -
When it finishes,
Sync Resultsshows how many incidents were imported as new, updated, or skipped because nothing had changed. If the sync imported and updated nothing and reported errors,Sync Resultsdoes not appear; the status readsConnection Failedwith the reason instead. - Open Incidents to review the imported records. You are the owner of each new one.
Once the connector has synced, the page shows
Last successful sync: with the date and time of the last completed
sync, and it still does after a reload. The counts of a sync are shown only for
the visit in which you ran it; the audit log records every sync.
How PagerDuty values are mapped
| PagerDuty | Aegis |
|---|---|
Status triggered |
Status Open |
Status acknowledged |
Status Investigating |
Status resolved |
Status Resolved |
| Priority 1 / 2 / 3 / lower | Severity Critical / High / Medium / Low |
No priority: urgency high / low |
Severity High / Low |
What a repeat sync does
- Each PagerDuty incident is matched by its PagerDuty ID, so a second sync does not create duplicates.
- If the PagerDuty status has changed, the Aegis status follows it, and the severity is refreshed at the same time. If only the severity changed in PagerDuty, the incident is skipped.
-
A sync never reopens an incident that has been closed in Aegis, and it does
not make a status change the incident's workflow does not allow. Such
changes are refused, counted in the audit log entry for the sync, and not
shown in
Sync Results.
Tips and limits
-
If PagerDuty rejects the key, the connector switches to
Errorand keeps the reason. Before the first sync you can enter a new key, save and test again. - The first sync copies the key into a separate encrypted credential store, and later tests and syncs use that stored key. A key saved in the form after that is not picked up, so replacing a key after the first sync needs help from your administrator or Euraika support.
- Each sync reads at most 100 incidents and does not page further. Incidents beyond that are not imported in that run.
- Every sync, with its counts, and every successful test is recorded in the audit log. A failed test is not; its reason is kept on the connector instead.
- An imported incident still needs a person to assess whether it is a reportable breach.
Where this connects
Incidents are handled in Incidents; regulatory reporting is covered in Incident reporting. For the other connectors, see Connectors.