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 v2 on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for PagerDuty v2.

  3. Click Add instance to create and configure a new integration instance.

    ParameterRequired
    API KeyTrue
    Service Key (for triggering events only)False
    Trust any certificate (not secure)False
    Use system proxy settingsFalse
    Fetch incidentsFalse
    Incident typeFalse
    Initial Fetch Interval (In minutes, used only for the first fetch or after Reset last run)False
  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 Cortex XSOAR 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

PagerDuty-get-all-schedules#


Receive all schedules from PagerDuty

Base Command#

PagerDuty-get-all-schedules

Input#

Argument NameDescriptionRequired
queryShow only the schedules whose name matches the query.Optional
limitThe limit for the amount of schedules to receive(Default is 25, max value is 100).Optional

Context Output#

PathTypeDescription
PagerDuty.Schedules.idstringThe ID of the schedule
PagerDuty.Schedules.namestringThe name of the schedule

Command Example#

!PagerDuty-get-all-schedules

Context Example#

{
"PagerDuty": {
"Schedules": [
{
"escalation_policies": [
{
"id": "someid",
"name": "Default"
}
],
"id": "scheduleid",
"name": "New Schedule #1",
"time_zone": "America/Los_Angeles",
"today": "2021-03-10"
},
{
"escalation_policies": [
{
"id": "anotherid",
"name": "test policy"
}
],
"id": "anotherscheduleid",
"name": "New Schedule #2",
"time_zone": "Europe/Athens",
"today": "2021-03-10"
}
]
}
}

Human Readable Output#

All Schedules#

IDNameTodayTime ZoneEscalation PolicyEscalation Policy ID
scheduleidNew Schedule #12021-03-10America/Los_AngelesDefaultsomeid
anotherscheduleidNew Schedule #22021-03-10Europe/Athenstest policyanotherid

PagerDuty-get-users-on-call#


Returns the names and details of on call users at a certain time or by specific schedule

Base Command#

PagerDuty-get-users-on-call

Input#

Argument NameDescriptionRequired
scheduleID(default and mandatory) The unique identifier of the schedule.Required
sinceThe start of the date range Using ISO 8601 Representation. E.g. !PagerDutyGetUsersOnCall since=2011-05-06T17:00Z.Optional
untilThe end of the date range.Optional

Context Output#

PathTypeDescription
PagerDutyUser.idstringUser's ID
PagerDutyUser.EmailsstringEmail of user
PagerDutyUser.UsernamestringUsername of person
PagerDutyUser.DisplayNamestringDisplay name of person
PagerDutyUser.RolestringDisplay role of person
PagerDutyUser.TimeZonestringThe time zone of the user

Command Example#

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

Context Example#

{
"PagerDutyUser": [
{
"DisplayName": "Demisto User",
"Email": "demisto@demisto.com",
"ID": "someid",
"Role": "owner",
"TimeZone": "Europe/Athens",
"Username": "Demisto User"
},
{
"DisplayName": "Another User",
"Email": "demisto@gmail.com",
"ID": "anotherid",
"Role": "user",
"TimeZone": "Europe/Athens",
"Username": "Another User"
}
]
}

Human Readable Output#

Users On Call#

IDEmailNameRoleUser UrlTime Zone
someiddemisto@demisto.comDemisto Userownerhttps://demisto.pagerduty.com/users/someidEurope/Athens
anotheriddemisto@mail.comAnother Useruserhttps://demisto.pagerduty.com/users/anotheridEurope/Athens

PagerDuty-get-users-on-call-now#


Returns the names and details of current on call personnel

Base Command#

PagerDuty-get-users-on-call-now

Input#

Argument NameDescriptionRequired
limitThe limit for the amount of users to receive(Default is 25, max value is 100).Optional
escalation_policy_idsFilters the results, showing only on-call users for the specified escalation policy IDs.Optional
schedule_idsFilters the results, showing only on-call users for the specified schedule IDs. If the value is null, permanent on-call user are included due to direct user escalation policy targets.Optional

Context Output#

PathTypeDescription
PagerDutyUser.IDstringUser's ID
PagerDutyUser.EmailstringEmail of user
PagerDutyUser.UsernamestringUsername of person
PagerDutyUser.DisplayNamestringDisplay name of person
PagerDutyUser.RolestringRole of person
PagerDutyUser.TimeZonestringThe time zone of the user

Command Example#

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

Context Example#

{
"PagerDutyUser": [
{
"DisplayName": "Demisto User",
"Email": "demisto@demisto.com",
"ID": "someid",
"Role": "owner",
"TimeZone": "Europe/Athens",
"Username": "Demisto User"
}
]
}

Human Readable Output#

Users On Call Now#

IDEmailNameRoleUser UrlTime Zone
someiddemisto@demisto.comDemisto Userownerhttps://demisto.pagerduty.com/users/someidEurope/Athens

PagerDuty-incidents#


Shows incidents in PagerDuty. Default status parameters are triggered,acknowledged

Base Command#

PagerDuty-incidents

Input#

Argument NameDescriptionRequired
statusReturns only the incidents currently in the passed status(es). Valid status options are triggered,acknowledged, and resolved. (Default values are triggered,acknowledged). Possible values are: triggered, acknowledged, resolved.Optional
sinceBeginning date and time. Using ISO 8601 Representation. E.g. PagerDutyIncidents since=2011-05-06T17:00Z (must be used with until argument).Optional
sortByUsed to specify both the field you wish to sort the results on, as well as the direction (ascending/descending) of the results.See more https://v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents.Optional
untilLast date and time. Using ISO 8601 Representation. E.g. PagerDutyIncidents until=2016-05-06T13:00Z.Optional
incident_keyIncident de-duplication key,.Optional

Context Output#

PathTypeDescription
PagerDuty.Incidents.IDstringIncident ID
PagerDuty.Incidents.TitlestringThe title of the incident
PagerDuty.Incidents.StatusstringIncident Status
PagerDuty.Incidents.created_atdateTime in which the incident was created
PagerDuty.Incidents.urgencystringIncident Urgency
PagerDuty.Incidents.assigneestringThe assignee of the incident
PagerDuty.Incidents.service_idstringThe id of the impacted service
PagerDuty.Incidents.service_namestringThe name of the impacted service
PagerDuty.Incidents.escalation_policystringThe escalation policy
PagerDuty.Incidents.last_status_change_atdateTime in which the last status change occurred
PagerDuty.Incidents.last_status_change_bystringName of the user who done the last status change
PagerDuty.Incidents.number_of_escalationsnumberNumber of escalations that took place
PagerDuty.Incidents.resolved_bystringName of the User who resolved the incident
PagerDuty.Incidents.resolve_reasonstringThe reason for resolving the issue
PagerDuty.Incidents.DescriptionstringThe Description of the incident
PagerDuty.Incidents.teams.IDstringThe ID of the team assigned for the incident.
PagerDuty.Incidents.teams.IDstringThe name of the team assigned for the incident.
PagerDuty.Incidents.assignment.timedateThe time of the assignment to the incident
PagerDuty.Incidents.assignment.assigneestringThe name of the assignee to the incident
PagerDuty.Incidents.acknowledgement.timedateThe time of the acknowledgement to the incident
PagerDuty.Incidents.acknowledgement.acknowledgerstringThe name of the acknowledger to the incident
PagerDuty.Incidents.incident_keyStringThe incident's de-duplication key

Command Example#

!PagerDuty-incidents

Context Example#

{
"PagerDuty": {
"Incidents": [
{
"Description": {
"description": "No description"
},
"ID": "someid",
"Status": "acknowledged",
"Title": "[#264] Ticket 01439490",
"acknowledgement": {
"acknowledger": "",
"time": "2021-03-04T08:53:04Z"
},
"assignee": "someone",
"assignment": {
"assignee": "someone",
"time": "2021-03-04T08:53:04Z"
},
"created_at": "2021-03-04T08:52:56Z",
"escalation_policy": "Default",
"incident_key": null,
"last_status_change_at": "2021-03-04T08:53:04Z",
"last_status_change_by": "someone",
"number_of_escalations": null,
"resolve_reason": "",
"resolved_by": "someone",
"service_id": "P5CX6RZ",
"service_name": "PD SF",
"teams": [],
"urgency": "high"
},
{
"Description": {
"description": "No description"
},
"ID": "anotherid",
"Status": "triggered",
"Title": "[#278] my event",
"acknowledgement": {},
"assignee": "someone-else",
"assignment": {
"assignee": "someone-else",
"time": "2021-03-10T08:37:17Z"
},
"created_at": "2021-03-10T07:57:16Z",
"escalation_policy": "Default",
"incident_key": "somekey",
"last_status_change_at": "2021-03-10T08:37:17Z",
"last_status_change_by": "API Service",
"number_of_escalations": null,
"resolve_reason": "",
"resolved_by": "someone-else",
"service_id": "someid",
"service_name": "API Service",
"teams": [],
"urgency": "high"
}
]
}
}

Human Readable Output#

PagerDuty Incidents#

IDTitleDescriptionStatusCreated OnUrgencyHtml UrlIncident keyAssigned To UserService IDService NameEscalation PolicyLast Status Change OnLast Status Change ByResolved By User
someid[#264] Ticket 01439490description: No descriptionacknowledged2021-03-04T08:52:56Zhighhttps://demisto.pagerduty.com/incidents/someidsomeoneP5CX6RZPD SFDefault2021-03-04T08:53:04Zsomeone-
anotherid[#278] my eventdescription: No descriptiontriggered2021-03-10T07:57:16Zhighhttps://demisto.pagerduty.com/incidents/anotheridsomekeysomeone-elsesomeidAPI ServiceDefault2021-03-10T08:37:17ZAPI Service-

PagerDuty-submit-event#


Creates a new event/incident in PagerDuty(In order to use this command you have to enter the Service Key in the integration settings)

Base Command#

PagerDuty-submit-event

Input#

Argument NameDescriptionRequired
sourceSpecific human-readable unique identifier, such as a hostname, for the system having the problem.Required
summaryA high-level, text summary message of the event. Will be used to construct an alert's description.Required
severityThe severity of the event. Possible values are: critical, error, warning, info.Required
actionThe action to be executed. Possible values are: trigger, acknowledge, resolve.Required
descriptionA short description of the problem.Optional
groupA 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_classThe class/type of the event. Example: "High CPU" "Latency".Optional
componentThe part or component of the affected system that is broken. Example: "keepalive" "webping".Optional
incident_keyIncident key, used to acknowledge/resolve specific event.Optional
serviceKeyService key for the integration.Optional

Context Output#

PathTypeDescription
PagerDuty.Event.StatusstringStatus of the action on the event
PagerDuty.Event.incident_keystringIncident key

Command Example#

!PagerDuty-submit-event action=trigger severity=info source=demisto summary="my new event"

Human Readable Output#

Incident keyMessageStatus
somekeyEvent processedsuccess

PagerDuty-get-contact-methods#


Get the contact methods of a given user

Base Command#

PagerDuty-get-contact-methods

Input#

Argument NameDescriptionRequired
UserIDID of the wanted user .Required

Context Output#

PathTypeDescription
PagerDuty.Contact_methods.phonestringThe phone number of the user
PagerDuty.Contact_methods.idstringID of the contact method
PagerDuty.Contact_methods.typestringThe type of the current contact method
PagerDuty.Contact_methods.emailstringThe email of the user

Command Example#

!PagerDuty-get-contact-methods UserID=someid

Context Example#

{
"PagerDuty": {
"Contact_methods": [
{
"email": "demisto@demisto.com",
"html_url": null,
"id": "someotherid",
"label": "Default",
"self": "https://api.pagerduty.com/users/someid/contact_methods/someotherid",
"send_html_email": false,
"send_short_email": false,
"summary": "Default",
"type": "email_contact_method"
},
{
"blacklisted": false,
"html_url": null,
"id": "someid",
"label": "Mobile",
"phone": "000000",
"self": "https://api.pagerduty.com/users/someid/contact_methods/someid",
"summary": "Mobile",
"type": "phone_contact_method"
},
{
"blacklisted": false,
"enabled": true,
"html_url": null,
"id": "onemoreid",
"label": "Mobile",
"phone": "0000000",
"self": "https://api.pagerduty.com/users/someid/contact_methods/onemoreid",
"summary": "Mobile",
"type": "sms_contact_method"
}
]
}
}

Human Readable Output#

Contact Methods#

IDTypeDetails
someotheridEmaildemisto@demisto.com
someidPhone0000000
onemoreidSMS000000

PagerDuty-get-users-notification#


Get the users notification rules

Base Command#

PagerDuty-get-users-notification

Input#

Argument NameDescriptionRequired
UserIDID of the wanted user.Required

Context Output#

PathTypeDescription
PagerDuty.Notification_rules.start_delay_in_minutesstringThe delay time for notifying the user
PagerDuty.Notification_rules.urgencystringThe urgency of the notification
PagerDuty.Notification_rules.idstringThe id of the notification rule

Command Example#

!PagerDuty-get-users-notification UserID=someid

Context Example#

{
"PagerDuty": {
"Notification_rules": {
"contact_method": {
"address": "demisto@demisto.com",
"html_url": null,
"id": "someotherid",
"label": "Default",
"self": "https://api.pagerduty.com/users/someid/contact_methods/someotherid",
"send_html_email": false,
"send_short_email": false,
"summary": "Default",
"type": "email_contact_method"
},
"html_url": null,
"id": "someid",
"self": "https://api.pagerduty.com/users/someid/notification_rules/someid",
"start_delay_in_minutes": 0,
"summary": "0 minutes: channel someotherid",
"type": "assignment_notification_rule",
"urgency": "high"
}
}
}

Human Readable Output#

User notification rules#

IDTypeUrgencyNotification timeout(minutes)
someidassignment_notification_rulehigh0

PagerDuty-resolve-event#


Resolves an existing event in PagerDuty

Base Command#

PagerDuty-resolve-event

Input#

Argument NameDescriptionRequired
incident_keyIncident key.Required
serviceKeyService key for the integration.Required

Context Output#

PathTypeDescription
PagerDuty.Event.StatusstringStatus of the action on the event
PagerDuty.Event.incident_keystringIncident key

Command Example#

!PagerDuty-resolve-event incident_key=somekey serviceKey=servicekey

Context Example#

{
"Event": {
"ID": "somekey"
},
"PagerDuty": {
"Event": {
"Message": "Event processed",
"Status": "success",
"incident_key": "somekey"
}
}
}

Human Readable Output#

Resolve Event#

Incident keyMessageStatus
somekeyEvent processedsuccess

PagerDuty-acknowledge-event#


Acknowledges an existing event in PagerDuty

Base Command#

PagerDuty-acknowledge-event

Input#

Argument NameDescriptionRequired
incident_keyIncident key.Required
serviceKeyService key for the integration.Required

Context Output#

PathTypeDescription
PagerDuty.Event.StatusstringStatus of the action on the event
PagerDuty.Event.incident_keystringIncident key

Command Example#

!PagerDuty-acknowledge-event incident_key=somekey serviceKey=servicekey

Context Example#

{
"Event": {
"ID": "8e42eeb6391a4a2abeda5d12e09bddec"
},
"PagerDuty": {
"Event": {
"Message": "Event processed",
"Status": "success",
"incident_key": "somekey"
}
}
}

Human Readable Output#

Acknowledge Event#

Incident keyMessageStatus
somekeyEvent processedsuccess

PagerDuty-get-incident-data#


Get data about a incident from PagerDuty

Base Command#

PagerDuty-get-incident-data

Input#

Argument NameDescriptionRequired
incident_idID of the incident to get information for.Required

Context Output#

PathTypeDescription
PagerDuty.Incidents.IDstringIncident ID
PagerDuty.Incidents.TitlestringThe title of the incident
PagerDuty.Incidents.StatusstringIncident Status
PagerDuty.Incidents.created_atdateTime in which the incident was created
PagerDuty.Incidents.urgencystringIncident Urgency
PagerDuty.Incidents.assigneestringThe assignee of the incident
PagerDuty.Incidents.service_idstringThe id of the impacted service
PagerDuty.Incidents.service_namestringThe name of the impacted service
PagerDuty.Incidents.escalation_policystringThe escalation policy
PagerDuty.Incidents.last_status_change_atdateTime in which the last status change occurred
PagerDuty.Incidents.last_status_change_bystringName of the user who done the last status change
PagerDuty.Incidents.number_of_escalationsnumberNumber of escalations that took place
PagerDuty.Incidents.resolved_bystringName of the User who resolved the incident
PagerDuty.Incidents.resolve_reasonstringThe reason for resolving the issue
PagerDuty.Incidents.DescriptionstringThe Description of the incident
PagerDuty.Incidents.teams.IDstringThe ID of the team assigned for the incident.
PagerDuty.Incidents.teams.IDstringThe name of the team assigned for the incident.
PagerDuty.Incidents.assignment.timedateThe time of the assignment to the incident
PagerDuty.Incidents.assignment.assigneestringThe name of the assignee to the incident
PagerDuty.Incidents.acknowledgement.timedateThe time of the acknowledgement to the incident
PagerDuty.Incidents.acknowledgement.acknowledgerstringThe name of the acknowledger to the incident
PagerDuty.Incidents.incident_keyStringThe incident's de-duplication key

Command Example#

!PagerDuty-get-incident-data incident_id=someid

Context Example#

{
"PagerDuty": {
"Incidents": {
"Description": "",
"ID": "someid",
"Status": "acknowledged",
"Title": "[#281] my new event",
"acknowledgement": {
"acknowledger": "",
"time": "2021-03-10T09:31:48Z"
},
"assignee": null,
"assignment": {
"assignee": "someone",
"time": "2021-03-10T09:31:48Z"
},
"created_at": "2021-03-10T09:31:48Z",
"escalation_policy": "Default",
"incident_key": "somekey",
"last_status_change_at": "2021-03-10T10:00:50Z",
"last_status_change_by": "API Service",
"number_of_escalations": null,
"resolve_reason": "",
"resolved_by": null,
"service_id": "someid",
"service_name": "API Service",
"teams": [],
"urgency": "high"
}
}
}

Human Readable Output#

PagerDuty Incident#

IDTitleStatusCreated OnUrgencyHtml UrlIncident keyService IDService NameEscalation PolicyLast Status Change OnLast Status Change ByResolved By User
someid[#281] my new eventacknowledged2021-03-10T09:31:48Zhighhttps://demisto.pagerduty.com/incidents/someid8e42eeb6391a4a2abeda5d12e09bddecsomeidAPI ServiceDefault2021-03-10T10:00:50ZAPI Service-

PagerDuty-get-service-keys#


Get 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#

PathTypeDescription
PagerDuty.Service.IDstringThe ID of the service connected to PagerDuty
PagerDuty.Service.NamestringThe name of the service connected to PagerDuty
PagerDuty.Service.StatusstringThe status of the service connected to PagerDuty
PagerDuty.Service.CreatedAtdateThe date in which the service connected to PagerDuty was created
PagerDuty.Service.Integration.NamestringThe name of the integration used with the service
PagerDuty.Service.Integration.VendorstringThe name of the vendor for the integration used with the service.(A value of 'Missing Vendor information' will appear once no information could be found)
PagerDuty.Service.Integration.KeystringThe 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": "someid",
"Integration": [
{
"Key": "somekey",
"Name": "API Service",
"Vendor": "Missing Vendor information"
}
],
"Name": "API Service",
"Status": "critical"
}
]
}
}

Human Readable Output#

Service List#

IDNameStatusCreated AtIntegration
someidAPI Servicecritical2016-03-20T14:00:55+02:00Name: API Service, Vendor: Missing Vendor information, Key: somekey