Module: PagerDuty::Client::Incidents

Included in:
PagerDuty::Client
Defined in:
lib/pager_duty/client/incidents.rb

Overview

Module encompassing interactions with the incidents API endpoint

See Also:

Instance Method Summary collapse

Instance Method Details

#create_incident_note(incident_id, from_email_address, options = {}) ⇒ Sawyer::Resource

Create a new note for the specified incident. /incidents/id/notes

Parameters:

  • incident_id (String) —

    Incident ID

  • from_email_address (String) —

    The email address of the user making the request.

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options

Returns:

  • (Sawyer::Resource) —

    A hash representing a note for the incident

See Also:



213
214
215
216
217
218
219
220
221
 
# File 'lib/pager_duty/client/incidents.rb', line 213

def create_incident_note(incident_id, from_email_address, options = {})
  if from_email_address
    options[:headers] ||= {}
    options[:headers][:from] = from_email_address
  end 

  response = post "/incidents/#{incident_id}/notes", options
  response[:note]
end

#incident(id, options = {}) ⇒ Sawyer::Resource Also known as: get_incident

Show detailed information about an incident. Accepts either an incident id, or an incident number. /incidents/id

Parameters:

  • id (String) —

    An incident id, or an incident number

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options.

Returns:

  • (Sawyer::Resource) —

    A hash representing incident

See Also:



58
59
60
61
 
# File 'lib/pager_duty/client/incidents.rb', line 58

def incident(id, options = {})
  response = get "/incidents/#{id}", options
  response[:incident]
end

#incident_alert(incident_id, alert_id, options = {}) ⇒ Sawyer::Resource Also known as: get_incident_alert

Show detailed information about an alert. Accepts an alert id. /incidents/id/alerts/alert_id/

Parameters:

  • incident_id (String) —

    Incident ID

  • alert_id (String) —

    Alert ID

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options.

Returns:

  • (Sawyer::Resource) —

    A hash representing alerts

See Also:



93
94
95
96
 
# File 'lib/pager_duty/client/incidents.rb', line 93

def incident_alert(incident_id, alert_id, options = {})
  response = get "/incidents/{incident_id}/alerts/{alert_id}", options
  response[:alert]         
end

#incident_alerts(incident_id, options = {}) ⇒ Array<Sawyer::Resource> Also known as: get_alerts_for_incident

List alerts for the specified incident. /incidents/id/alerts

Parameters:

  • incident_id (String) —

    Incident ID

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :statuses (Array<String>) —

    Return only incidents with the given statuses (one or more of triggered or resolved. (More status codes may be introduced in the future.)

  • :alert_key (String) —

    Alert de-duplication key.

  • :sort_by (String) —

    Used to specify both the field you wish to sort the results on (created_at/resolved_at), as well as the direction (asc/desc) of the results. The sort_by field and direction should be separated by a colon. A maximum of two fields can be included, separated by a comma. Sort direction defaults to ascending. (One of `created_at` or `resolved_at` with `asc` or `desc`

  • :include (Array<String>) —

    Array of additional details to include. (One or more of services, first_trigger_log_entries, incidents)

Returns:

  • (Array<Sawyer::Resource>) —

    An array of hashes representing alerts

See Also:



75
76
77
78
79
80
81
82
 
# File 'lib/pager_duty/client/incidents.rb', line 75

def incident_alerts(incident_id, options = {})
  query_params = Hash.new
  query_params[:statuses] = options.fetch(:statuses, [])
  query_params[:alert_key] = options[:alert_key] if options[:alert_key]
  query_params[:sort_by]   = options[:sort_by] if options[:sort_by]
  response = get "/incidents/#{incident_id}/alerts", options.merge({query: query_params})
  response[:alerts]        
end

#incident_log_entries(incident_id, options = {}) ⇒ Array<Sawyer::Resource>

List log entries for the specified incident. /incidents/incident_id/log_entries

Parameters:

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options

Options Hash (options):

  • :time_zone (String) —

    Time zone to display log entries

  • :is_overview (Boolean) —

    If true, will return a subset of log entries that show only the most important changes to the incident.

  • :include (Array<String>) —

    Array of additional details to include. (One or more of incidents, services, channels, teams

Returns:

  • (Array<Sawyer::Resource>) —

    An array of hashes representing log entries

See Also:



107
108
109
110
111
112
113
114
115
 
# File 'lib/pager_duty/client/incidents.rb', line 107

def incident_log_entries(incident_id, options = {})
  query_params = Hash.new
  query_params[:time_zone]    = options[:time_zone] if options[:time_zone]
  query_params[:is_overview]  = options[:is_overview] if options[:is_overview]
  query_params[:include]      = options[:include] if options[:include]

  response = get "/incidents/#{incident_id}/log_entries", options.merge({query: query_params})
  response[:log_entries]                
end

#incident_notes(incident_id, options = {}) ⇒ Sawyer::Resource

List existing notes for the specified incident. /incidents/id/notes

Parameters:

  • incident_id (String) —

    Incident id

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options

Returns:

  • (Sawyer::Resource) —

    A hash representing notes

See Also:



124
125
126
127
 
# File 'lib/pager_duty/client/incidents.rb', line 124

def incident_notes(incident_id, options = {})
  response = get "/incidents/#{incident_id}/notes", options
  response[:notes]          
end

#incidents(options = {}) ⇒ Array<Sawyer::Resource> Also known as: list_incidents

List incidents

Parameters:

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :since (String) —

    The start of the date range over which you want to search ISO8601 format

  • :until (String) —

    The end of the date range over which you want to search ISO8601 format

  • :date_range (String) —

    When set to :all, the since and until parameters and defaults are ignored.

  • :statuses (Array<String>) —

    Return only incidents with the given statuses (one or more of triggered, acknowledged or resolved. (More status codes may be introduced in the future.)

  • :incident_key (String) —

    Incident de-duplication key. Incidents with child alerts do not have an incident key; querying by incident key will return incidents whose alerts have alert_key matching the given incident key.

  • :service_ids (Array<String>) —

    Returns only the incidents associated with the passed service(s). This expects one or more service IDs.

  • :team_ids (Array<String>) —

    An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter.

  • :user_ids (Array<String>) —

    Returns only the incidents currently assigned to the passed user(s). This expects one or more user IDs. Note: When using the assigned_to_user filter, you will only receive incidents with statuses of triggered or acknowledged. This is because resolved incidents are not assigned to any user.

  • :urgencies (Array<String>) —

    Array of the urgencies of the incidents to be returned. Defaults to all urgencies. Account must have the urgencies ability to do this. (:high or :low)

  • :time_zone (String) —

    Time zone in which dates in the result will be rendered.

  • :sort_by (String) —

    Used to specify both the field you wish to sort the results on (incident_number/created_at/resolved_at/urgency), as well as the direction (asc/desc) of the results. The sort_by field and direction should be separated by a colon. A maximum of two fields can be included, separated by a comma. Sort direction defaults to ascending. NOTE: The account must have the `urgencies` ability to sort by the urgency.

  • :include (Array<String>) —

    Array of additional details to include. (One or more of users, services, first_trigger_log_entries, escalation_policies, teams, assignees, acknowledgers)

Returns:

  • (Array<Sawyer::Resource>) —

    An array of hashes representing incidents

See Also:



23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/pager_duty/client/incidents.rb', line 23

def incidents(options = {})
  query_params = Hash.new
  if options[:date_range]
    # they passed in a value and we'll assume it's all
    query_params[:date_range] = "all"
  else
    query_params[:since] = options[:since].utc.iso8601 if options[:since]
    query_params[:until] = options[:until].utc.iso8601 if options[:until]
  end
  query_params[:incident_key]   = options[:incident_key] if options[:incident_key]
  query_params[:time_zone]      = options[:time_zone] if options[:time_zone]
  query_params[:sort_by]        = options[:sort_by] if options[:sort_by]

  user_ids = options.fetch(:user_ids, [])
  team_ids = options.fetch(:team_ids, [])

  query_params["statuses"]      = options.fetch(:statuses, [])
  query_params["service_ids[]"] = options[:service_ids].join(", ") if options[:service_ids]
  query_params["team_ids[]"]    = team_ids.join(",") if team_ids.length > 0
  query_params["user_ids[]"]    = user_ids.join(",") if user_ids.length > 0
  query_params["urgencies"]     = options[:urgencies] if options[:urgencies]
  query_params["include"]       = options[:include] if options[:include]

  response = get "/incidents", options.merge({query: query_params})
  response[:incidents]
end

#merge_incidents(incident_id, from_email_address, source_incidents, options = {}) ⇒ Sawyer::Resource

Merge a list of source incidents into this incident. /incidents/id/merge

Parameters:

  • incident_id (String) —

    Destination incident

  • from_email_address (String) —

    The email address of the user making the request.

  • source_incidents (Array<String>) —

    List of incident ids to merge into destination

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options

Returns:

  • (Sawyer::Resource) —

    A hash representing the incident

See Also:



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/pager_duty/client/incidents.rb', line 159

def merge_incidents(incident_id, from_email_address, source_incidents, options = {})
  options[:source_incidents] = source_incidents.map { |incident_id| 
    { 
      id: incident_id, 
      type: "incident_reference" 
    } 
  }

  if from_email_address
    options[:headers] ||= {}
    options[:headers][:from] = from_email_address
  end

  response = put "/incidents/#{incident_id}/merge", options
  response[:incident]
end

#snooze_incident(incident_id, from_email_address, duration, options = {}) ⇒ Sawyer::Resource

Snooze an incident. /incidents/id/snooze

Parameters:

  • incident_id (String) —

    Incident ID

  • from_email_address (String) —

    The email address of the user making the request.

  • duration (Integer) —

    The number of seconds to snooze the incident for. After this number of seconds has elapsed, the incident will return to the “triggered” state.

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options

Returns:

  • (Sawyer::Resource) —

    A hash representing the incident



137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/pager_duty/client/incidents.rb', line 137

def snooze_incident(incident_id, from_email_address, duration, options = {})
  query_params = Hash.new
  query_params[:duration] = duration

  if from_email_address
    options[:headers] ||= {}
    options[:headers][:from] = from_email_address
  end

  response = post "/incidents/#{incident_id}/snooze", options.merge({query: query_params})
  response[:incident]
end

#update_incidents(from_email_address, incidents, options = {}) ⇒ Array<Sawyer::Resource>

Acknowledge, resolve, escalate or reassign one or more incidents. /incidents

Parameters:

  • from_email_address (String) —

    The email address of the user making the request.

  • incidents (Array<String>) —

    List of incidents to update

  • options (Sawyer::Resource) (defaults to: {}) —

    A customizable set of options

Returns:

  • (Array<Sawyer::Resource>) —

    An array of hashes representing incidents

See Also:



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/pager_duty/client/incidents.rb', line 184

def update_incidents(from_email_address, incidents, options = {})
  options[:incidents] = incidents.map { |incident|
    item = { id: incident[:id], type: "incident_reference" }
    item[:status] = incident[:status] if incident[:status]
    item[:resolution] = incident[:resolution] if incident[:resolution]
    item[:title] = incident[:title] if incident[:title]
    item[:escalation_level] = incident[:escalation_level] if incident[:escalation_level]
    item[:assignments] = incident[:assignments] if incident[:assignments]
    item[:escalation_policy] = incident[:escalation_policy] if incident[:escalation_policy]
    item
  }

  if from_email_address
    options[:headers] ||= {}
    options[:headers][:from] = from_email_address
  end 

  response = put "/incidents", options
  response[:incidents]               
end