Module: PagerDuty::Client::OnCalls

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

Overview

An on-call represents a contiguous unit of time for which a [user](#resource_Users) will be on call for a given escalation policy and escalation rule.

This may be the result of that user always being on call for the escalation rule, or a block of time during which the computed result of a schedule on that escalation rule puts the user on call.

During an on-call, the user is expected to bear responsibility for responding to any notifications she receives and working to resolve the associated incident(s).

On-calls cannot be created directly through the API; they are the computed result of how escalation policies and schedules are configured.

The API provides read-only access to the on-calls generated by PagerDuty.

See Also:

Instance Method Summary collapse

Instance Method Details

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

Returns An array of hashes representing notifications.

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :time_zone (String) —

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

  • :include (Array<String>) —

    Array of additional details to include. (One of escalation_policies, schedules or users)

  • :user_ids (Array<String>) —

    Filters the results, showing only on-calls for the specified user IDs.

  • :escalation_policy_ids (Array<String>) —

    Filters the results, showing only on-calls for the specified escalation policy IDs.

  • :schedule_ids (Array<String>) —

    Filters the results, showing only on-calls for the specified schedule IDs. If ‘null` is provided in the array, it includes permanent on-calls due to direct user escalation targets.

  • :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

  • :earliest (Boolean) —

    This will filter on-calls such that only the earliest on-call for each combination of escalation policy, escalation level, and user is returned. This is useful for determining when the “next” on-calls are for a given set of filters.

Returns:

  • (Array<Sawyer::Resource>) —

    An array of hashes representing notifications

See Also:



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/pager_duty/client/on_calls.rb', line 36

def on_calls(options = {})
  user_ids              = options.fetch(:user_ids, [])
  escalation_policy_ids = options.fetch(:escalation_policy_ids, [])
  schedule_ids          = options.fetch(:schedule_ids, [])

  query_params = Hash.new

  query_params[:time_zone]  = options[:time_zone] if options[:time_zone]
  query_params[:since]      = options[:since].utc.iso8601 if options[:since]
  query_params[:until]      = options[:until].utc.iso8601 if options[:until]
  query_params[:earliest]   = options.fetch(:earliest, false) if options[:earliest]
  
  query_params[:include]               = options[:include] if options[:include]
  query_params["user_ids[]"]              = user_ids.join(",") if user_ids.length > 0
  query_params["escalation_policy_ids[]"] = escalation_policy_ids.join(",") if escalation_policy_ids.length > 0
  query_params["schedule_ids[]"]          = schedule_ids.join(",") if schedule_ids.length > 0

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