# PagerDuty
{% hint style="info" %}
The following documentation is for **PagerDuty v1.0.3** *(BDK)*.
{% endhint %}
## Overview
PagerDuty is an incident management platform that helps teams respond to and resolve critical issues quickly. This integration enables automated incident creation, escalation management, and on-call scheduling workflows. Improve incident response times and maintain system reliability through automated monitoring.
## Prerequisites
### 1. Required Books
The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:
* **PagerDuty**
#### How to Add the Book(s)
1. Go to **Books** → **All Books**.
2. Search for the name of the book and click on it.
3. Click on **Install** or **Add Connection** to add the book to your agent.
4. If adding a connection, you'll be prompted for [**connectivity**](#connectivity) details.
## Connectivity
This section outlines the available methods for connecting to the Book, along with the required configuration details for each.
### Connect using API Key
Connect to PagerDuty API using API key.
| Label | Description | Type |
| ------- | ------------------------------- | ----------- |
| API Key | The API key for authentication. | `sensitive` |
## Procedures
### to create an (incident) in *pagerduty*
Create an incident in PagerDuty.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ------------------------------------------------- | ------------------------------------ | ------------------------------------- | -------- | ------------- |
| [`payload`](#pagerduty-incident-creation-payload) | The data for the incident to create. | `pagerduty incident creation payload` | Yes | (no default) |
**Output Concepts**
| Concept | Description | Type |
| --------------------------------- | --------------------- | -------------------- |
| [`incident`](#pagerduty-incident) | The created incident. | `pagerduty incident` |
**Examples**
Create an incident in PagerDuty
```generic
create a json
use the above as the body
the body's title is "Application Failure"
the body's type is "incident"
get '{"id": "P0ED7MS", "type": "service_reference"}' as a json
use the above as the service
the body's service is the service
create an incident in pagerduty
the payload is the body
```
### to get some (incidents) from *pagerduty*
Get incidents from PagerDuty using a Filter Expression.
**Output Concepts**
| Concept | Description | Type |
| ---------------------------------- | -------------------- | -------------------- |
| [`incidents`](#pagerduty-incident) | A list of incidents. | `pagerduty incident` |
**Examples**
Get all incidents from PagerDuty
```generic
get some incidents from pagerduty
```
### to manage an (incident) in *pagerduty*
Manage an incident in PagerDuty.
Manage (update) an incident in PagerDuty. The 'From' header with a valid user email may be required by PagerDuty for this operation, depending on what was the authentication method used.
**Input Concepts**
| Concept | Description | Type | Required | Default Value |
| ----------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------- | -------- | ------------- |
| [`incident`](#pagerduty-incident) | The ID of the incident to update. | `pagerduty incident` | Yes | (no default) |
| [`payload`](#pagerduty-incident-update-payload) | The data to update for the incident. | `pagerduty incident update payload` | Yes | (no default) |
| `user email` | The email of the PagerDuty user for 'From' header in write operations. | `text` | No | (no default) |
**Output Concepts**
| Concept | Description | Type |
| --------------------------------- | --------------------- | -------------------- |
| [`incident`](#pagerduty-incident) | The updated incident. | `pagerduty incident` |
**Examples**
Manage an incident in PagerDuty
```generic
get some incidents from pagerduty
get the first incident as the incident
create a json
use the above as the body
the body's status is "acknowledged"
manage the incident in pagerduty
the payload is the incident
the user email is "integrations@kognitos.com"
```
## Concepts
### Pagerduty incident creation payload
Payload for creating a PagerDuty incident.Payload for creating an incident
| Field Name | Description | Type |
| ----------------------------------------------------------------------------- | -------------------------------------------- | ------------------------ |
| `title` | The title of the incident. | `text` |
| `service` | The service the incident is associated with. | `json` |
| `type` | The type of the incident. | `optional[text]` |
| [`priority`](#priority-pagerduty-incident-creation-payload) | The priority of the incident. | `optional[json]` |
| `urgency` | The urgency of the incident. | `optional[text]` |
| [`body`](#body-pagerduty-incident-creation-payload) | The body of the incident. | `optional[json]` |
| `incident_key` | The incident key. | `optional[text]` |
| [`assignments`](#assignments-pagerduty-incident-creation-payload) | The assignments of the incident. | `optional[list of json]` |
| [`escalation_policy`](#escalation_policy-pagerduty-incident-creation-payload) | The escalation policy of the incident. | `optional[json]` |
| [`conference_bridge`](#conference_bridge-pagerduty-incident-creation-payload) | The conference bridge of the incident. | `optional[json]` |
| `incident_type_name` | The incident type name. | `optional[text]` |
### Pagerduty incident
PagerDuty incident data model.A PagerDuty incident.
| Field Name | Description | Type |
| ------------------------------------------------------------------------ | -------------------------------------------- | ------------------------ |
| `id` | The ID of the incident. | `text` |
| `type` | The type of the incident. | `text` |
| `summary` | The summary of the incident. | `optional[text]` |
| `self_url` | The self URL of the incident. | `optional[text]` |
| `html_url` | The HTML URL of the incident. | `optional[text]` |
| `incident_number` | The incident number. | `optional[number]` |
| `title` | The title of the incident. | `optional[text]` |
| `created_at` | The creation time of the incident. | `optional[text]` |
| `updated_at` | The last update time of the incident. | `optional[text]` |
| `status` | The status of the incident. | `optional[text]` |
| `incident_key` | The incident key. | `optional[text]` |
| [`service`](#service-pagerduty-incident) | The service the incident is associated with. | `optional[json]` |
| [`assignments`](#assignments-pagerduty-incident) | The assignments of the incident. | `optional[list of json]` |
| `assigned_via` | The assigned via of the incident. | `optional[text]` |
| `last_status_change_at` | The last status change time of the incident. | `optional[text]` |
| `resolved_at` | The resolution time of the incident. | `optional[text]` |
| [`first_trigger_log_entry`](#first_trigger_log_entry-pagerduty-incident) | The first trigger log entry of the incident. | `optional[json]` |
| [`alert_counts`](#alert_counts-pagerduty-incident) | The alert counts of the incident. | `optional[json]` |
| `is_mergeable` | Whether the incident is mergeable. | `optional[boolean]` |
| [`incident_type`](#incident_type-pagerduty-incident) | The type of the incident. | `optional[json]` |
| [`escalation_policy`](#escalation_policy-pagerduty-incident) | The escalation policy of the incident. | `optional[json]` |
| [`teams`](#teams-pagerduty-incident) | The teams of the incident. | `optional[list of json]` |
| [`pending_actions`](#pending_actions-pagerduty-incident) | The pending actions of the incident. | `optional[list of json]` |
| [`acknowledgements`](#acknowledgements-pagerduty-incident) | The acknowledgements of the incident. | `optional[list of json]` |
| [`last_status_change_by`](#last_status_change_by-pagerduty-incident) | The last status change by of the incident. | `optional[json]` |
| [`priority`](#priority-pagerduty-incident) | The priority of the incident. | `optional[json]` |
| [`conference_bridge`](#conference_bridge-pagerduty-incident) | The conference bridge of the incident. | `optional[json]` |
| `urgency` | The urgency of the incident. | `optional[text]` |
| [`body`](#body-pagerduty-incident) | The body of the incident. | `optional[json]` |
### Pagerduty incident update payload
Payload for updating a PagerDuty incident.Payload for updating an incident (subset of fields)
| Field Name | Description | Type |
| --------------------------------------------------------------------------- | -------------------------------------- | ------------------------ |
| `status` | The status of the incident. | `optional[text]` |
| `resolution` | The resolution of the incident. | `optional[text]` |
| `title` | The title of the incident. | `optional[text]` |
| [`priority`](#priority-pagerduty-incident-update-payload) | The priority of the incident. | `optional[json]` |
| `escalation_level` | The escalation level of the incident. | `optional[number]` |
| [`assignments`](#assignments-pagerduty-incident-update-payload) | The assignments of the incident. | `optional[list of json]` |
| `incident_type_name` | The incident type name. | `optional[text]` |
| [`escalation_policy`](#escalation_policy-pagerduty-incident-update-payload) | The escalation policy of the incident. | `optional[json]` |
| `urgency` | The urgency of the incident. | `optional[text]` |
| [`conference_bridge`](#conference_bridge-pagerduty-incident-update-payload) | The conference bridge of the incident. | `optional[json]` |
**Concept attribute specifications**
**priority (pagerduty incident creation payload)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**body (pagerduty incident creation payload)**
| Name | Type |
| --------- | ---------------- |
| `type` | `optional[text]` |
| `details` | `optional[any?]` |
**assignments (pagerduty incident creation payload)**
| Name | Type |
| ---------- | ---------------- |
| `at` | `optional[text]` |
| `assignee` | `optional[json]` |
**escalation\_policy (pagerduty incident creation payload)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**conference\_bridge (pagerduty incident creation payload)**
| Name | Type |
| ------------------- | ---------------- |
| `conference_number` | `optional[text]` |
| `conference_url` | `optional[text]` |
**service (pagerduty incident)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**assignments (pagerduty incident)**
| Name | Type |
| ---------- | ---------------- |
| `at` | `optional[text]` |
| `assignee` | `optional[json]` |
**first\_trigger\_log\_entry (pagerduty incident)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**alert\_counts (pagerduty incident)**
| Name | Type |
| ----------- | ------------------ |
| `triggered` | `optional[number]` |
| `resolved` | `optional[number]` |
| `all` | `optional[number]` |
**incident\_type (pagerduty incident)**
| Name | Type |
| ------ | ---------------- |
| `name` | `optional[text]` |
**escalation\_policy (pagerduty incident)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**teams (pagerduty incident)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**pending\_actions (pagerduty incident)**
| Name | Type |
| ------ | ---------------- |
| `type` | `text` |
| `at` | `text` |
| `to` | `optional[text]` |
**acknowledgements (pagerduty incident)**
| Name | Type |
| -------------- | ---------------- |
| `at` | `optional[text]` |
| `acknowledger` | `optional[json]` |
**last\_status\_change\_by (pagerduty incident)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `text` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**priority (pagerduty incident)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**conference\_bridge (pagerduty incident)**
| Name | Type |
| ------------------- | ---------------- |
| `conference_number` | `optional[text]` |
| `conference_url` | `optional[text]` |
**body (pagerduty incident)**
| Name | Type |
| --------- | ---------------- |
| `type` | `optional[text]` |
| `details` | `optional[any?]` |
**priority (pagerduty incident update payload)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**assignments (pagerduty incident update payload)**
| Name | Type |
| ---------- | ---------------- |
| `at` | `optional[text]` |
| `assignee` | `optional[json]` |
**escalation\_policy (pagerduty incident update payload)**
| Name | Type |
| ---------- | ---------------- |
| `id` | `text` |
| `type` | `optional[text]` |
| `summary` | `optional[text]` |
| `self_url` | `optional[text]` |
| `html_url` | `optional[text]` |
**conference\_bridge (pagerduty incident update payload)**
| Name | Type |
| ------------------- | ---------------- |
| `conference_number` | `optional[text]` |
| `conference_url` | `optional[text]` |