module PagerDuty::Client::Incidents
Module encompassing interactions with the incidents API endpoint @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents
Public Instance Methods
Create a new note for the specified incident. /incidents/{id}/notes @param incident_id [String] Incident ID @param from_email_address [String] The email address of the user making the request. @param options [Sawyer::Resource] A customizable set of options
@return [Sawyer::Resource] A hash representing a note for the incident @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/post_incidents_id_notes
# 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
Show detailed information about an incident. Accepts either an incident id, or an incident number. /incidents/{id}
@param id [String] An incident id, or an incident number @param options [Sawyer::Resource] A customizable set of options. @return [Sawyer::Resource] A hash representing incident @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents_id
# File lib/pager_duty/client/incidents.rb, line 58 def incident(id, options = {}) response = get "/incidents/#{id}", options response[:incident] end
Show detailed information about an alert. Accepts an alert id. /incidents/{id}/alerts/{alert_id}/ @param incident_id [String] Incident ID @param alert_id [String] Alert ID @param options [Sawyer::Resource] A customizable set of options.
@return [Sawyer::Resource] A hash representing alerts @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents_id_alerts_alert_id
# 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
List alerts for the specified incident. /incidents/{id}/alerts @param incident_id [String] Incident ID @param options [Sawyer::Resource] A customizable set of options. @option options [Array<String>] :statuses Return only incidents with the given statuses (one or more of triggered
or resolved
. (More status codes may be introduced in the future.) @option options [String] :alert_key Alert de-duplication key. @option options [String] :sort_by 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`
@option options [Array<String>] :include Array of additional details to include. (One or more of services
, first_trigger_log_entries
, incidents
)
@return [Array<Sawyer::Resource>] An array of hashes representing alerts @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents_id_alerts
# 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
List log entries for the specified incident. /incidents/{incident_id}/log_entries @param options [Sawyer::Resource] A customizable set of options @option options [String] :time_zone Time zone to display log entries @option options [Boolean] :is_overview If true, will return a subset of log entries that show only the most important changes to the incident. @option options [Array<String>] :include Array of additional details to include. (One or more of incidents
, services
, channels
, teams
@return [Array<Sawyer::Resource>] An array of hashes representing log entries @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents_id_log_entries
# 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
List existing notes for the specified incident. /incidents/{id}/notes @param incident_id [String] Incident id @param options [Sawyer::Resource] A customizable set of options
@return [Sawyer::Resource] A hash representing notes @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents_id_notes
# 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
List incidents @param options [Sawyer::Resource] A customizable set of options. @option options [String] :since The start of the date range over which you want to search ISO8601 format @option options [String] :until The end of the date range over which you want to search ISO8601 format @option options [String] :date_range When set to :all
, the since and until parameters and defaults are ignored. @option options [Array<String>] :statuses Return only incidents with the given statuses (one or more of triggered
, acknowledged
or resolved
. (More status codes may be introduced in the future.) @option options [String] :incident_key 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. @option options [Array<String>] :service_ids Returns only the incidents associated with the passed service(s). This expects one or more service IDs. @option options [Array<String>] :team_ids An array of team IDs. Only results related to these teams will be returned. Account must have the `teams`
ability to use this parameter. @option options [Array<String>] :user_ids 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. @option options [Array<String>] :urgencies 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
) @option options [String] :time_zone Time zone in which dates in the result will be rendered. @option options [String] :sort_by 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. @option options [Array<String>] :include Array of additional details to include. (One or more of users
, services
, first_trigger_log_entries
, escalation_policies
, teams
, assignees
, acknowledgers
) @return [Array<Sawyer::Resource>] An array of hashes representing incidents @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents
# 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 a list of source incidents into this incident. /incidents/{id}/merge @param incident_id [String] Destination incident @param from_email_address [String] The email address of the user making the request. @param source_incidents [Array<String>] List of incident ids to merge into destination @param options [Sawyer::Resource] A customizable set of options
@return [Sawyer::Resource] A hash representing the incident @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/put_incidents_id_merge
# 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 an incident. /incidents/{id}/snooze @param incident_id [String] Incident ID @param from_email_address [String] The email address of the user making the request. @param 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. @param options [Sawyer::Resource] A customizable set of options
@return [Sawyer::Resource] A hash representing the incident
# 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
Acknowledge, resolve, escalate or reassign one or more incidents. /incidents @param from_email_address [String] The email address of the user making the request. @param incidents [Array<String>] List of incidents to update @param options [Sawyer::Resource] A customizable set of options
@return [Array<Sawyer::Resource>] An array of hashes representing incidents @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/put_incidents
# 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