Module: PagerDuty::Client::MaintenanceWindows

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

Overview

Methods for the MaintenanceWindows API

A maintenance window is used to temporarily disable one or more services for a set period of time.

No incidents will be triggered and no notifications will be received while a service is disabled by a maintenance window.

Maintenance windows are specified to start at a certain time and end after they have begun.

Once started, a maintenance window cannot be deleted; it can only be ended immediately to re-enable the service.

Read more about maintenance windows in the PagerDuty Knowledge Base

See Also:

Instance Method Summary collapse

Instance Method Details

#create_maintenance_window(from_email_address, start_time, end_time, description, service_id, options = {}) ⇒ Sawyer::Resource

# Create a new maintenance window for the specified services. No new incidents will be created for a service that is in maintenance.

Parameters:

  • from_email_address (String) —

    User creating maintenance window

  • start_time (String) —

    Start time of maintenance window in ISO8601 format

  • end_time (String) —

    End time of maintenance window in ISO8601 format

  • description (String) —

    Description of maintenace window

  • service_id (String) —

    Service referenced in maintenance window

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

    A customizable set of options.

Returns:

  • (Sawyer::Resource) —

    An hash representing maintenance window

See Also:



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/pager_duty/client/maintenance_windows.rb', line 70

def create_maintenance_window(from_email_address, start_time, end_time, description, service_id, options = {})
  if from_email_address
    options[:headers] ||= {}
    options[:headers][:from] = from_email_address
  end 

  params = { 
    maintenance_window: {
      type: "maintenance_window",
      start_time: start_time,
      end_time:  end_time,
      description: description,
      services: [
        {
          id: service_id,
          type: "service_reference"
        }
      ]
    }
  }
  response = post "/maintenance_windows", options.merge(params)
  response[:maintenance_window]        
end

#delete_maintenance_window(id, options = {}) ⇒ Boolean

# Delete an existing maintenance window if it’s in the future, or end it if it’s currently on-going. If the maintenance window has already ended it cannot be deleted.

Parameters:

  • id (String) —

    PagerDuty identifier for maintenance window

Returns:

  • (Boolean)

See Also:



99
100
101
 
# File 'lib/pager_duty/client/maintenance_windows.rb', line 99

def delete_maintenance_window(id, options = {})
  boolean_from_response :delete, "/maintenance_windows/#{id}", options
end

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

Get an existing maintenance window.

Parameters:

  • id (String) —

    ID for maintenance window

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

    A customizable set of options.

Options Hash (options):

  • :include (Array<string>) —

    Array of additional details to include (One or more of :services, :teams, :users)

Returns:

  • (Sawyer::Resource) —

    An hash representing maintenance window

See Also:



51
52
53
54
55
56
57
 
# File 'lib/pager_duty/client/maintenance_windows.rb', line 51

def maintenance_window(id, options = {})
  query_params = Hash.new
  query_params["include[]"]     = options[:include] if options[:include]

  response = get "/maintenance_windows/#{id}", options.merge({query: query_params})
  response[:maintenance_window]
end

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

List existing maintenance windows, optionally filtered by service and/or team, or whether they are from the past, present or future.

Parameters:

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

    A customizable set of options.

Options Hash (options):

  • :query (String) —

    Filters the results, showing only the maintenance windows whose descriptions contain the query.

  • :service_ids (Array<string>) —

    An array of service IDs. Only results related to these services will be returned.

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

  • :include (Array<string>) —

    Array of additional details to include (One or more of :services, :teams, :users)

  • :filter (String) —

    Only return maintenance windows in a given state. (One of :past, :future, :ongoing, :open or :all).

Returns:

  • (Array<Sawyer::Resource>) —

    An array of hashes representing maintenance windows

See Also:



28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/pager_duty/client/maintenance_windows.rb', line 28

def maintenance_windows(options = {})
  service_ids = options.fetch(:service_ids, [])
  team_ids    = options.fetch(:team_ids, [])
  
  query_params = Hash.new
  query_params["query"]         = options[:query] if options[:query]
  query_params["team_ids[]"]    = team_ids.join(",") if team_ids.length > 0
  query_params["service_ids[]"] = service_ids.join(",") if service_ids.length > 0
  query_params["include[]"]     = options[:include] if options[:include]
  query_params["filter"]        = options[:filter] if options[:filter]

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

#update_maintenance_window(id, start_time, end_time, description, service_id, options = {}) ⇒ Sawyer::Resource

# Update an existing maintenance window.

Parameters:

  • id (String) —

    PagerDuty id for maintenance window

  • start_time (String) —

    Start time of maintenance window in ISO8601 format

  • end_time (String) —

    End time of maintenance window in ISO8601 format

  • description (String) —

    Description of maintenace window

  • service_id (String) —

    Service referenced in maintenance window

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

    A customizable set of options.

Returns:

  • (Sawyer::Resource) —

    An hash representing maintenance window

See Also:



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/pager_duty/client/maintenance_windows.rb', line 118

def update_maintenance_window(id, start_time, end_time, description, service_id, options = {})
  params = { 
    maintenance_window: {
      type: "maintenance_window",
      start_time: start_time,
      end_time:  end_time,
      description: description,
      services: [
        {
          id: service_id,
          type: "service_reference"
        }
      ]
    }
  }
  response = put "/maintenance_windows/#{id}", options.merge(params)
  response[:maintenance_window]        
end