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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

Human Readable Output

image

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

image

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

image