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_incident_note(incident_id, from_email_address, options = {}) click to toggle source

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
get_alerts_for_incident(incident_id, options = {})
Alias for: incident_alerts
get_incident(id, options = {})
Alias for: incident
get_incident_alert(incident_id, alert_id, options = {})
Alias for: incident_alert
incident(id, options = {}) click to toggle source

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
Also aliased as: get_incident
incident_alert(incident_id, alert_id, options = {}) click to toggle source

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
Also aliased as: get_incident_alert
incident_alerts(incident_id, options = {}) click to toggle source

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
Also aliased as: get_alerts_for_incident
incident_log_entries(incident_id, options = {}) click to toggle source

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
incident_notes(incident_id, options = {}) click to toggle source

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
incidents(options = {}) click to toggle source

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
Also aliased as: list_incidents
list_incidents(options = {})
Alias for: incidents
merge_incidents(incident_id, from_email_address, source_incidents, options = {}) click to toggle source

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_incident(incident_id, from_email_address, duration, options = {}) click to toggle source

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
update_incidents(from_email_address, incidents, options = {}) click to toggle source

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