# pagerduty – Create PagerDuty maintenance windows

- Synopsis
- Requirements
- Parameters
- Examples
- Status

## Synopsis

- This module will let you create PagerDuty maintenance windows

## Requirements

The below requirements are needed on the host that executes this module.

- PagerDuty API access

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
desc - | Default: "Created by Ansible" | Short description of maintenance window.
hours - | Default: 1 | Length of maintenance window in hours.
minutes - | Default: 0 | Maintenance window in minutes (this is added to the hours).
name - |  | PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API.
requester_id - |  | ID of user making the request. Only needed when creating a maintenance_window.
service - |  | A comma separated list of PagerDuty service IDs. aliases: services

state
- / required

Choices:
- running
- started
- ongoing
- absent

Create a maintenance window or get a list of ongoing windows.

token - / required |  | A pagerduty token, generated on the pagerduty site. It is used for authorization.
user - |  | PagerDuty user ID. Obsolete. Please, use token for authorization.

validate_certs
boolean

Choices:
- no
- yes ←

If `no`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.

window_id - added in 2.7 |  | ID of maintenance window. Only needed when absent a maintenance_window.

## Examples

    # List ongoing maintenance windows using a token
    - pagerduty:
        name: companyabc
        token: xxxxxxxxxxxxxx
        state: ongoing

    # Create a 1 hour maintenance window for service FOO123
    - pagerduty:
        name: companyabc
        user: example@example.com
        token: yourtoken
        state: running
        service: FOO123

    # Create a 5 minute maintenance window for service FOO123
    - pagerduty:
        name: companyabc
        token: xxxxxxxxxxxxxx
        hours: 0
        minutes: 5
        state: running
        service: FOO123

    # Create a 4 hour maintenance window for service FOO123 with the description "deployment".
    - pagerduty:
        name: companyabc
        user: example@example.com
        state: running
        service: FOO123
        hours: 4
        desc: deployment
      register: pd_window

    # Delete the previous maintenance window
    - pagerduty:
        name: companyabc
        user: example@example.com
        state: absent
        window_id: '{{ pd_window.result.maintenance_window.id }}'

    # Delete a maintenance window from a separate playbook than its creation, and if it is the only existing maintenance window.
    - pagerduty:
        requester_id: XXXXXXX
        token: yourtoken
        state: ongoing
      register: pd_window

    - pagerduty:
        requester_id: XXXXXXX
        token: yourtoken
        state: absent
        window_id: "{{ pd_window.result.maintenance_windows[0].id }}"

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

- Andrew Newdigate (@suprememoocow)
- Dylan Silva (@thaumos)
- Justin Johns (!UNKNOWN)
- Bruce Pennypacker (@bpennypacker)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.