# pagerduty_alert – Trigger, acknowledge or resolve PagerDuty incidents

- Synopsis
- Requirements
- Parameters
- Examples
- Status

## Synopsis

- This module will let you trigger, acknowledge or resolve a PagerDuty incident by sending events

## Requirements

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

- PagerDuty API access

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_key - / required |  | The pagerduty API key (readonly access), generated on the pagerduty site.
client - |  | The name of the monitoring client that is triggering this event.
client_url - |  | The URL of the monitoring client that is triggering this event.

desc
-

Default:
"Created via Ansible"

For `triggered` state - Required. Short description of the problem that led to this trigger. This field (or a truncated version) will be used when generating phone calls, SMS messages and alert emails. It will also appear on the incidents tables in the PagerDuty UI. The maximum length is 1024 characters.
For `acknowledged` or `resolved` state - Text that will appear in the incident's log associated with this event.

incident_key
-
added in 2.7

Identifies the incident to which this state should be applied.
For `triggered` state - If there's no open (i.e. unresolved) incident with this key, a new one will be created. If there's already an open incident with a matching key, this event will be appended to that incident's log. The event key provides an easy way to "de-dup" problem reports.
For `acknowledged` or `resolved` state - This should be the incident_key you received back when the incident was first opened by a trigger event. Acknowledge events referencing resolved or nonexistent incidents will be discarded.

integration_key - / required added in 2.7 |  | The GUID of one of your "Generic API" services. This is the "integration key" listed on a "Integrations" tab of PagerDuty service.
name - |  | PagerDuty unique subdomain. Obsolete. It is not used with PagerDuty REST v2 API.
service_id - / required added in 2.7 |  | ID of PagerDuty service when incidents will be triggered, acknowledged or resolved.
service_key - |  | The GUID of one of your "Generic API" services. Obsolete. Please use integration_key.

state
- / required

Choices:
- triggered
- acknowledged
- resolved

Type of event to be sent.

## Examples

    # Trigger an incident with just the basic options
    - pagerduty_alert:
        name: companyabc
        integration_key: xxx
        api_key: yourapikey
        service_id: PDservice
        state: triggered
        desc: problem that led to this trigger

    # Trigger an incident with more options
    - pagerduty_alert:
        integration_key: xxx
        api_key: yourapikey
        service_id: PDservice
        state: triggered
        desc: problem that led to this trigger
        incident_key: somekey
        client: Sample Monitoring Service
        client_url: http://service.example.com

    # Acknowledge an incident based on incident_key
    - pagerduty_alert:
        integration_key: xxx
        api_key: yourapikey
        service_id: PDservice
        state: acknowledged
        incident_key: somekey
        desc: "some text for incident's log"

    # Resolve an incident based on incident_key
    - pagerduty_alert:
        integration_key: xxx
        api_key: yourapikey
        service_id: PDservice
        state: resolved
        incident_key: somekey
        desc: "some text for incident's log"

## Status

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

### Authors

- Amanpreet Singh (@ApsOps)

Hint

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