PagerDuty v2

Use the PagerDuty integration to manage schedules and on-call users. This integration was integrated and tested with PagerDuty API v2.

Configure PagerDuty on Demisto

1. Navigate to Settings > Integrations > Servers & Services .
2. Search for PagerDuty.
3. Click Add instance to create and configure a new integration instance.
   
   • Name : a textual name for the integration instance.
   • API Key
   • Service Key (for triggering events only)
4. Click Test to validate the URLs, token, and connection.

Fetched Incidents Data

By default, the integration will import PagerDuty incidents data as Demisto incidents. All incidents created in the minute prior to the configuration of Fetch Incidents and up to current time will be imported.

Commands

You can execute these commands from the Demisto CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

1. Get all schedules: PagerDuty-get-all-schedules
2. Get information for on-call users by time or schedule: PagerDuty-get-users-on-call
3. Get information for current on-call users: PagerDuty-get-users-on-call-now
4. Get incidents: PagerDuty-incidents
5. Create a new event/incident: PagerDuty-submit-event
6. Get the contact methods of a user: PagerDuty-get-contact-methods
7. Get a user's notification rules: PagerDuty-get-users-notification
8. Resolve an event: PagerDuty-resolve-event
9. Acknowledge an event: PagerDuty-acknowledge-event
10. Get incident information: PagerDuty-get-incident-data
11. Get service keys for each configured service: PagerDuty-get-service-keys

1. Get all schedules

---

Retrieves all schedules from PagerDuty.

Base Command

PagerDuty-get-all-schedules

Input

Argument Name	Description	Required
query	Returns schedules that match the query.	Optional
limit	The maximum number of schedules to retrieve. Default = 25, Maximum = 100.	Optional

Context Output

Path	Type	Description
PagerDuty.Schedules.id	string	The Schedule ID.
PagerDuty.Schedules.name	string	The name of the schedule.

Command Example

!PagerDuty-get-all-schedules

Context Example

Human Readable Output

2. Get information for on-call users by time or schedule

---

Returns the names and details of on-call users at a certain time or according to a specific schedule.

Base Command

PagerDuty-get-users-on-call

Input

Argument Name	Description	Required
scheduleID	The unique identifier of the schedule (default).	Required
since	Start date and time in ISO 8601 format (2011-05-06T17:00Z).	Optional
until	End date and time in ISO 8601 format (2011-07-06T17:00Z).	Optional

Context Output

Path	Type	Description
PagerDutyUser.id	string	The ID of the user.
PagerDutyUser.Emails	string	The email address of the user.
PagerDutyUser.Username	string	The user's username.
PagerDutyUser.DisplayName	string	The display name of the user.
PagerDutyUser.Role	string	The display role of the user.
PagerDutyUser.TimeZone	string	The time zone of the user.

Command Example

!PagerDuty-get-users-on-call scheduleID=PFE1I5O

Context Example

Human Readable Output

3. Get information for current on-call users

---

Returns the names and details of all personnel currently on-call.

Base Command

PagerDuty-get-users-on-call-now

Input

Argument Name	Description	Required
limit	The maximum number of users to retrieve. Default = 25, Maximum = 100.	Optional
escalation_policy_ids	Filters results by the specified escalation policy. If the value is null, permanent on-call users are included due to direct user escalation policy targets.	Optional
schedule_ids	Filters the results by on-call users for the specified schedule IDs. If the value is null, permanent on-call users are included due to direct user escalation policy targets.

Context Output

Path	Type	Description
PagerDutyUser.ID	string	The ID of the user.
PagerDutyUser.Email	string	The email address of the user.
PagerDutyUser.Username	string	The user's username.
PagerDutyUser.DisplayName	string	The display name of the user.
PagerDutyUser.Role	string	The display role of the user.
PagerDutyUser.TimeZone	string	The time zone of the user.

Command Example

!PagerDuty-get-users-on-call-now

Context Example

Human Readable Output

4. Get incidents

---

Shows incidents in PagerDuty.

Base Command

PagerDuty-incidents

Input

Argument Name	Description	Required
status	Returns only the incidents currently in the passed status(es). Valid status options are triggered , acknowledged , and resolved .	Optional
since	Start date and time in ISO 8601 format (2011-05-06T17:00Z)	Optional
sortBy	Used to specify both the field you want to sort the results by, and the direction of the results (ascending/descending). See the PagerDuty documentation .	Optional
until	End date and time in ISO 8601 format (2011-05-06T17:00Z).	Optional

Context Output

Path	Type	Description
PagerDuty.Incidents.ID	string	The ID of the Incident.
PagerDuty.Incidents.Title	string	The title of the incident.
PagerDuty.Incidents.Status	string	The status of the incident.
PagerDuty.Incidents.created_at	date	The time the incident was created.
PagerDuty.Incidents.urgency	string	The incident urgency.
PagerDuty.Incidents.assignee	string	The user assigned to the incident.
PagerDuty.Incidents.service_id	string	The ID of the impacted service.
PagerDuty.Incidents.service_name	string	The name of the impacted service.
PagerDuty.Incidents.escalation_policy	string	The escalation policy.
PagerDuty.Incidents.last_status_change_at	date	The time of the last status change.
PagerDuty.Incidents.last_status_change_by	string	The Name of the user who performed the last status change
PagerDuty.Incidents.number_of_escalations	number	Number of escalations that took place
PagerDuty.Incidents.resolved_by	string	Name of the user who resolved the incident
PagerDuty.Incidents.resolve_reason	string	The reason the issue was resolved.
PagerDuty.Incidents.Description	string	The description of the incident.
PagerDuty.Incidents.teams.ID	string	The ID of the team assigned to the incident.
PagerDuty.Incidents.teams.ID	string	Name of the team assigned to the incident.
PagerDuty.Incidents.assignment.time	date	Time of the assignment to the incident.
PagerDuty.Incidents.assignment.assignee	string	Name of the user assigned to the incident.
PagerDuty.Incidents.acknowledgement.time	date	The time the incident was  acknowledged.
PagerDuty.Incidents.acknowledgement.acknowledger	string	The name of the user that acknowledged the incident.

Command Example

!PagerDuty-incidents

Context Example

Human Readable Output

5. Create an event/incident

---

Creates a new event or incident in PagerDuty.

Base Command

PagerDuty-submit-event

Input

Argument Name	Description	Required
source	Specific human-readable unique identifier, such as a hostname, for the system with the problem.	Required
summary	A high-level, text summary message of the event. Will be used to construct an alert's description.	Required
severity	The severity of the event	Required
action	The action to be executed	Required
description	A short description of the problem	Optional
group	A cluster or grouping of sources. For example, sources “prod-datapipe-02” and “prod-datapipe-03” might both be part of “prod-datapipe”. Example: "prod-datapipe" "www"	Optional
event_class	The class/type of the event. Example: "High CPU" "Latency"	Optional
component	The part or component of the affected system that is broken. Example: "keepalive" "webping"	Optional
incident_key	Incident key, used to acknowledge/resolve specific event	Optional

Context Output

Path	Type	Description
PagerDuty.Event.Status	string	Status of the action on the event
PagerDuty.Event.incident_key	string	Incident key

Command Example

!PagerDuty-submit-event action=resolve severity=info source=rony summary=testing incident_key=1de3b86c5fd8484ca011839c4cf33923

Context Example

Human Readable Output

6. Get the contact methods of a user

---

Gets the contact methods of the specified user.

Base Command

PagerDuty-get-contact-methods

Input

Argument Name	Description	Required
UserID	ID of the user	Required

Context Output

Path	Type	Description
PagerDuty.Contact_methods.address	string	The address of the user
PagerDuty.Contact_methods.id	string	ID of the contact method
PagerDuty.Contact_methods.type	string	Current contact method type
PagerDuty.Contact_methods.email	string	User email

Command Example

!PagerDuty-get-contact-methods UserID=PKVY389

Context Example

Human Readable Output

7. Get a user's notification rules

---

Get the users notification rules

Base Command

PagerDuty-get-users-notification

Input

Argument Name	Description	Required
UserID	ID of the user	Required

Context Output

Path	Type	Description
PagerDuty.Notification_rules.start_delay_in_minutes	string	The delay time for notifying the user
PagerDuty.Notification_rules.urgency	string	The urgency of the notification
PagerDuty.Notification_rules.id	string	Notification rule ID

Command Example

!PagerDuty-get-users-notification UserID="PKVY389"

Context Example

Human Readable Output

8. Resolve an event

---

Resolves an existing event in PagerDuty.

Base Command

PagerDuty-resolve-event

Input

Argument Name	Description	Required
incident_key	Incident key	Required
serviceKey	Service key for the integration	Required

Context Output

Path	Type	Description
PagerDuty.Event.Status	string	Status of the action on the event
PagerDuty.Event.incident_key	string	Incident key

Command Example

!PagerDuty-resolve-event incident_key=84d6f9baaca346658f5d85d12b4156e6 serviceKey=XXXXXXXXXXXXXX

Context Example

Human Readable Output

9. Acknowledge an event

---

Acknowledges an existing event in PagerDuty.

Base Command

PagerDuty-acknowledge-event

Input

Argument Name	Description	Required
incident_key	The incident key.	Required
serviceKey	The service key for the integration.	Required

Context Output

Path	Type	Description
PagerDuty.Event.Status	string	Status of the action on the event
PagerDuty.Event.incident_key	string	Incident key

Command Example

!PagerDuty-acknowledge-event incident_key=84d6f9baaca346658f5d85d12b4156e6 serviceKey=XXXXXXXXXXXXXX

Context Example

Human Readable Output

10. Get incident data

---

Gets data from PagerDuty about an incident.

Base Command

PagerDuty-get-incident-data

Input

Argument Name	Description	Required
incident_id	ID of the incident for which to get information.	Required

Context Output

Path	Type	Description
PagerDuty.Incidents.ID	string	Incident ID
PagerDuty.Incidents.Title	string	The incident title.
PagerDuty.Incidents.Status	string	The incident status.
PagerDuty.Incidents.created_at	date	Time that the incident was created.
PagerDuty.Incidents.urgency	string	The incident urgency.
PagerDuty.Incidents.assignee	string	The incident assignee.
PagerDuty.Incidents.service_id	string	The ID of the impacted service.
PagerDuty.Incidents.service_name	string	The name of the impacted service.
PagerDuty.Incidents.escalation_policy	string	The escalation policy.
PagerDuty.Incidents.last_status_change_at	date	Time when the last status change occurred.
PagerDuty.Incidents.last_status_change_by	string	Name of the user who preformed the last status change.
PagerDuty.Incidents.number_of_escalations	number	Number of escalations that occurred.
PagerDuty.Incidents.resolved_by	string	Name of the user who resolved the incident.
PagerDuty.Incidents.resolve_reason	string	The reason for resolving the issue.
PagerDuty.Incidents.Description	string	The description of the incident.
PagerDuty.Incidents.teams.ID	string	The ID of the team assigned to the incident.
PagerDuty.Incidents.teams.ID	string	The name of the team assigned to the incident.
PagerDuty.Incidents.assignment.time	date	The time that the incident was assigned.
PagerDuty.Incidents.assignment.assignee	string	The name of the incident assignee.
PagerDuty.Incidents.acknowledgement.time	date	The time the incident was acknowledged.
PagerDuty.Incidents.acknowledgement.acknowledger	string	The name of the incident acknowledger.

Command Example

!PagerDuty-get-incident-data incident_id=PW159UV

Context Example

{
  "PagerDuty.Incidents": [
    {
      "Description": "",
      "ID": "PW159UV",
      "Status": "resolved",
      "Title": "[#98] test",
      "acknowledgement": {},
      "assignee": "-",
      "assignment": {},
      "created_at": "2019-03-30T00:07:37Z",
      "escalation_policy": "Default",
      "last_status_change_at": "2019-03-30T04:07:37Z",
      "last_status_change_by": "API Service",
      "number_of_escalations": null,
      "resolve_reason": null,
      "resolved_by": "-",
      "service_id": "P6UX4CI",
      "service_name": "API Service",
      "teams": [],
      "urgency": "high"
    }
  ]
}

Human Readable Output

11. Get service keys for each configured service

---

Gets service keys for each of the services configured in the PagerDuty instance.

Base Command

PagerDuty-get-service-keys

Input

There are no input arguments for this command.

Context Output

Path	Type	Description
PagerDuty.Service.ID	string	The ID of the service connected to PagerDuty.
PagerDuty.Service.Name	string	The name of the service connected to PagerDuty.
PagerDuty.Service.Status	string	The status of the service connected to PagerDuty.
PagerDuty.Service.CreatedAt	date	The date when the service connected to PagerDuty was created.
PagerDuty.Service.Integration.Name	string	The name of the integration used with the service.
PagerDuty.Service.Integration.Key	string	The key used to control events with the integration.

Command Example

!PagerDuty-get-service-keys

Context Example

{
  "PagerDuty.Service": [
    {
      "CreatedAt": "2016-03-20T14:00:55+02:00",
      "ID": "P6UX4CI",
      "Integration": [
        {
          "Key": "e18b825980164e03a85964679dcb4b2c",
          "Name": "API Service",
          "Vendor": "Missing Vendor information"
        }
      ],
      "Name": "API Service",
      "Status": "active"
    }
  ]
}

Human Readable Output