/ 
RT-Extension-PagerDuty-0.01
River stage zero No dependents
/ RT::Extension::PagerDuty

NAME

RT-Extension-PagerDuty - Two way integration with PagerDuty

DESCRIPTION

This RT extension allows for two-way integration with PagerDuty.

On ticket creation in RT, trigger an alert in PagerDuty. When a ticket is acknowledged or resolved in RT, update the incident in PagerDuty.

Configure a PagerDuty webhook to send updates to RT from PagerDuty. When a new incident is triggered in PagerDuty, create a ticket in RT. If an incident is acknowledged or resolved in PagerDuty, update the corresponding ticket in RT.

RT VERSION

Works with RT 5.

INSTALLATION

perl Makefile.PL
make
make install

May need root permissions

make initdb

Only run this the first time you install this module.

If you run this twice, you may end up with duplicate data in your database.

If you are upgrading this module, check for upgrading instructions in case changes need to be made to your database.

Edit your /opt/rt5/etc/RT_SiteConfig.pm

Add this line:

Plugin('RT::Extension::PagerDuty');

See below for additional configuration details.

Clear your mason cache
rm -rf /opt/rt5/var/mason_data/obj
Restart your webserver

CONFIGURATION

This section describes how to configure RT to integrate with your PagerDuty account and services. See the PagerDuty services documentation for details on configuring services on the PagerDuty side.

PagerDuty Webhook

PagerDuty will call a webhook provided by this extension to send information to your RT. To allow PagerDuty to send data to RT without a referrer, set this option in your RT configuration:

Set( %ReferrerComponents,
    '/PagerDuty/WebHook.html' => 1,
);

See "PagerDuty Webhook" for details on setting up the webhook in PagerDuty.

PagerDuty Services and RT Queues

To define the interactions between RT and PagerDuty:

Set(
    $PagerDuty,
    {
        services => {
            'PagerDuty Service ID' => {
                api_token => 'PagerDuty API Token',
                api_user => 'PagerDuty User',
                create_queue => 'General',
            }
        },
        queues => {
            'RT Queue Name' => {
                service => 'PagerDuty Service ID',
                acknowledged => 'open',
                resolved => 'resolved',
            }
        }
    }
);

The services section maps a PagerDuty service id to the token and user to use for API access. The api_token and api_user values are required. The optional create_queue value is the RT queue where new RT tickets should be created if a PagerDuty incident creates a new RT ticket. create_queue defaults to the General queue if not specified. Use '*' as the PagerDuty Service ID to apply to multiple PagerDuty services.

The queues section maps an RT queue name to the PagerDuty service where it should trigger new incidents when an RT ticket is created. The service value is required and must be a PagerDuty service id. The acknowledged and resolved optional values indicate what RT ticket status to use when an incident is acknowledged or resolved on PagerDuty. If not specified, they default to acknowledged => 'open' and resolved => 'resolved'. Use '*' as the RT Queue Name to apply to multiple RT queues.

To get the PagerDuty Service ID, login to your PagerDuty account and go to Services > Service Directory. If you are creating a new service for this integration, when you come to the "Integrations" section of the create new service process, click "Create service without an integration". The RT integration uses the Incidents API, as recommented by PagerDuty, and that doesn't require a specific Integrations configuration in PagerDuty.

Click on the Service you want the ID for and the the ID will be at the end of the URL. For example:

pagerduty.com/service-directory/P3AFFQR

the Service ID is P3AFFQR.

To create an api_token, login to your PagerDuty account and go to Integrations > API Access Keys. Click the Create New API Key button. Add a description and click Create Key. Copy the key and paste it into the $PagerDuty config as the api_token. You will not be able to view the key again but you can generate a new one if you lose the key.

The api_user is the email address for a valid PagerDuty user that has access to the PagerDuty Service you are integrating with. This is set as the "From" for any incidents created. You can create a utility user account in PagerDuty just for RT alerts.

RT Scrips and Custom Fields

Scrips

This extension will install three new Scrips:

On Create PagerDuty Trigger

When a ticket is created, also create an incident in PagerDuty.

On Acknowledge PagerDuty Acknowledge

On any transition from initial status (often 'new') to an active status (often 'open'), send a message to PagerDuty to set the incident as 'Acknowledged'.

On Resolve PagerDuty Resolve

When a ticket is resolved, resolve the incident in PagerDuty.

They are not applied to any queues when they are initially installed. Edit the scrips and click "Applies To" to select the queues that should integrate with PagerDuty.

Custom Fields

This extension adds two ticket custom fields: PagerDuty ID and PagerDuty URL.

You need to apply them to the queues that integrate with PagerDuty.

When an RT ticket creates an incident in PagerDuty, or an incident on PagerDuty creates an RT ticket, the custom fields are automatically set to the corresponding PagerDuty incident ID and URL. The PagerDuty URL links directly to the incident on PagerDuty.

If you would like to group the new custom fields in their own PagerDuty group you can use the CustomFieldGroupings configuration in RT:

Set(
    %CustomFieldGroupings,
    'RT::Ticket' => [
        'Alerts' => [ 'PagerDuty ID', 'PagerDuty URL' ],
    ],
);

PagerDuty Webhook

To set up the PagerDuty webhook, do the following.

1. Create an auth token in RT

Select or create an RT user that will be used for the webhook, then create an auth token from the user admin page.

The API user must be a Privileged user. If you use a user account that is Unprivileged, the calls to the webhook will redirect to Self Service and not work.

The RT user will also need some rights in RT to update tickets. A typical set of rights to grant for the API user are SeeQueue, ShowTicket, CreateTicket, ModifyTicket, SeeCustomField and SetInitialCustomField(or ModifyCustomField).

2. Create the WebHook

Go to the PagerDuty Service Integrations Webhooks, add a new webhook. Use https://your.rt.example/PagerDuty/WebHook.html as the webhook URL, replacing https://your.rt.example with your real RT domain.

For Scope Type and Scope, pick Service and the service you want to integrate with RT.

In the Event Subscriptions section, deselect all, then select the following supported events:

incident.acknowledged
incident.resolved
incident.triggered

At the bottom of the page, click Add custom header. Add a custom header with the name Authorization and value token #-#-abc123 where #-#-abc123 is the value of the auth token you created in step one. Note the word "token" followed by a space before the actual token value.

The Send Test Event button sends a ping event and no tickets will be created in RT.

AUTHOR

Best Practical Solutions, LLC <modules@bestpractical.com>

All bugs should be reported via email to bug-RT-Extension-PagerDuty@rt.cpan.org or via the web at rt.cpan.org.

LICENSE AND COPYRIGHT

This software is Copyright (c) 2022 by BPS

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991