module PagerDuty::Client::OnCalls

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 support.pagerduty.com/hc/en-us/articles/202828840-What-is-an-Alert-Notification- @see v2.developer.pagerduty.com/v2/page/api-reference#!/On-Calls

Public Instance Methods

list_on_calls(options = {})
Alias for: on_calls
on_calls(options = {}) click to toggle source

@option options [String] :time_zone Time zone in which dates in the result will be rendered. @option options [Array<String>] :include Array of additional details to include. (One of escalation_policies, schedules or users) @option options [Array<String>] :user_ids Filters the results, showing only on-calls for the specified user IDs. @option options [Array<String>] :escalation_policy_ids Filters the results, showing only on-calls for the specified escalation policy IDs. @option options [Array<String>] :schedule_ids 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. @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 [Boolean] :earliest 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.

@return [Array<Sawyer::Resource>] An array of hashes representing notifications @see v2.developer.pagerduty.com/v2/page/api-reference#!/Incidents/get_incidents

# 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
Also aliased as: list_on_calls