[Bps-public-commit] rt-extension-pagerduty branch doc-updates created. 0dcbb73e7288e7a5a088fb44402aebd32e23fb72
BPS Git Server
git at git.bestpractical.com
Fri Apr 15 18:12:10 UTC 2022
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "rt-extension-pagerduty".
The branch, doc-updates has been created
at 0dcbb73e7288e7a5a088fb44402aebd32e23fb72 (commit)
- Log -----------------------------------------------------------------
commit 0dcbb73e7288e7a5a088fb44402aebd32e23fb72
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Fri Apr 15 14:11:59 2022 -0400
Documentation updates
diff --git a/README b/README
index e16f046..eefefde 100644
--- a/README
+++ b/README
@@ -2,16 +2,15 @@ NAME
RT-Extension-PagerDuty - Two way integration with PagerDuty
DESCRIPTION
- This RT extension allows for two way integration with the PagerDuty
- incident response platform.
+ This RT extension allows for two-way integration with PagerDuty.
- On ticket creation in RT trigger an incident in PagerDuty. When a ticket
- is acknowledged or resolved in RT update the incident in 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 push noticications to RT from
- PagerDuty. When a new incident is triggered in PagerDuty have it create
- a ticket in RT. If an incident is acknowledged or resolved in PagerDuty
- update the corresponding ticket in RT.
+ 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.
@@ -36,126 +35,167 @@ INSTALLATION
Plugin('RT::Extension::PagerDuty');
- To allow PagerDuty to send data to RT without a referrer:
-
- Set( %ReferrerComponents,
- '/PagerDuty/WebHook.html' => 1,
- );
-
- 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 name 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. 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.
+ See below for additional configuration details.
Clear your mason cache
rm -rf /opt/rt5/var/mason_data/obj
Restart your webserver
-Scrips
- This extension will install three new Scrips that do not apply to any
- queues: On Acknowledge PagerDuty Acknowledge, On Create PagerDuty
- Trigger and On Resolve PagerDuty Resolve.
+CONFIGURATION
+ This section describes how to configure RT to integrate with your
+ PagerDuty account and services. See the PagerDuty services documentation
+ <https://support.pagerduty.com/docs/services-and-integrations> 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:
- You need to apply them to all the queues that integrate with PagerDuty.
+ Set( %ReferrerComponents,
+ '/PagerDuty/WebHook.html' => 1,
+ );
+
+ See "PagerDuty Webhook" for details on setting up the webhook in
+ PagerDuty.
-Custom fields
+ 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 Acknowledge PagerDuty Acknowledge
+ On Create PagerDuty Trigger
+ On Resolve PagerDuty Resolve
+
+ 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 all the queues that integrate with PagerDuty.
+ You need to apply them to the queues that integrate with PagerDuty.
- When an RT ticket creates an incident on PagerDuty or an incident on
- PagerDuty creates an RT ticket the custom fields are automatically
- filled in. The PagerDuty URL links directly to the incident on
- 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 config option:
+ group you can use the CustomFieldGroupings configuration in RT:
Set(
%CustomFieldGroupings,
'RT::Ticket' => [
- 'PagerDuty' => [ 'PagerDuty ID', 'PagerDuty URL' ],
+ 'Alerts' => [ 'PagerDuty ID', 'PagerDuty URL' ],
],
);
-Set up a webhook in PagerDuty
+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.
- Note that the user needs to be able to create and update tickets,
- usually you can grant SeeQueue, CreateTicket and ModifyTicket rights
- to all the queues that integrate with PagerDuty.
+ 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,
+ CreateTicket, ModifyTicket, and 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, note that you need to replace https://your.rt.example
- with your real RT instance.
-
- 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. Currently the only event subscriptions
- supported are incident.acknowledged, incident.resolved and
- incident.triggered.
-
- Note that the Send Test Event button sends a ping event, no tickets
- will be created.
+ 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 at bestpractical.com>
diff --git a/lib/RT/Extension/PagerDuty.pm b/lib/RT/Extension/PagerDuty.pm
index 0f766cb..94984be 100644
--- a/lib/RT/Extension/PagerDuty.pm
+++ b/lib/RT/Extension/PagerDuty.pm
@@ -11,16 +11,15 @@ RT-Extension-PagerDuty - Two way integration with PagerDuty
=head1 DESCRIPTION
-This RT extension allows for two way integration with the PagerDuty incident
-response platform.
+This RT extension allows for two-way integration with PagerDuty.
-On ticket creation in RT trigger an incident in PagerDuty. When a ticket is
-acknowledged or resolved in RT update the incident in 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 push noticications to RT from PagerDuty. When
-a new incident is triggered in PagerDuty have it create a ticket in RT. If an
-incident is acknowledged or resolved in PagerDuty update the corresponding
-ticket in RT.
+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.
=head1 RT VERSION
@@ -54,12 +53,38 @@ Add this line:
Plugin('RT::Extension::PagerDuty');
-To allow PagerDuty to send data to RT without a referrer:
+See below for additional configuration details.
+
+=item Clear your mason cache
+
+ rm -rf /opt/rt5/var/mason_data/obj
+
+=item Restart your webserver
+
+=back
+
+=head1 CONFIGURATION
+
+This section describes how to configure RT to integrate
+with your PagerDuty account and services. See the
+L<PagerDuty services documentation|https://support.pagerduty.com/docs/services-and-integrations>
+for details on configuring services on the PagerDuty side.
+
+=head2 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 L</PagerDuty Webhook> for details on setting up the webhook in
+PagerDuty.
+
+=head2 PagerDuty Services and RT Queues
+
To define the interactions between RT and PagerDuty:
Set(
@@ -82,9 +107,10 @@ To define the interactions between RT and PagerDuty:
}
);
+
The C<services> section maps a PagerDuty service id to the token and user to
use for API access. The C<api_token> and C<api_user> values are required. The
-optional C<create_queue> value is the RT queue name where new RT tickets
+optional C<create_queue> value is the RT queue where new RT tickets
should be created if a PagerDuty incident creates a new RT ticket.
C<create_queue> defaults to the General queue if not specified. Use '*' as
the C<PagerDuty Service ID> to apply to multiple PagerDuty services.
@@ -93,65 +119,80 @@ The C<queues> section maps an RT queue name to the PagerDuty service where it
should trigger new incidents when an RT ticket is created. The C<service>
value is required and must be a PagerDuty service id. The C<acknowledged> and
C<resolved> optional values indicate what RT ticket status to use when an
-incident is acknowledged or resolved on PagerDuty. If not specified they
+incident is acknowledged or resolved on PagerDuty. If not specified, they
default to acknowledged => 'open' and resolved => 'resolved'. Use '*' as the
C<RT Queue Name> to apply to multiple RT queues.
-To get the C<PagerDuty Service ID> login to your PagerDuty account and go to
-Services -> Service Directory. Click on the Service you want the ID for and
+To get the C<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 C<api_token> login to your PagerDuty account and go to
-Integrations -> API Access Keys. Click the C<Create New API Key> button. Add
+To create an C<api_token>, login to your PagerDuty account and go to
+Integrations > API Access Keys. Click the C<Create New API Key> button. Add
a description and click C<Create Key>. Copy the key and paste it into the
C<$PagerDuty> config as the C<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 C<api_user> is the email address for a valid PagerDuty user that has
-access to the PagerDuty Service you are integrating with.
+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.
-=item Clear your mason cache
+=head1 RT Scrips and Custom Fields
- rm -rf /opt/rt5/var/mason_data/obj
+=head2 Scrips
-=item Restart your webserver
+This extension will install three new Scrips:
-=back
+=over
-=head1 Scrips
+=item On Acknowledge PagerDuty Acknowledge
-This extension will install three new Scrips that do not apply to any queues:
-C<On Acknowledge PagerDuty Acknowledge>, C<On Create PagerDuty Trigger> and
-C<On Resolve PagerDuty Resolve>.
+=item On Create PagerDuty Trigger
-You need to apply them to all the queues that integrate with PagerDuty.
+=item On Resolve PagerDuty Resolve
+
+=back
-=head1 Custom fields
+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.
-This extension adds two ticket custom fields: C<PagerDuty ID> and C<PagerDuty
-URL>.
+=head2 Custom Fields
-You need to apply them to all the queues that integrate with PagerDuty.
+This extension adds two ticket custom fields: C<PagerDuty ID> and
+C<PagerDuty URL>.
-When an RT ticket creates an incident on PagerDuty or an incident on PagerDuty
-creates an RT ticket the custom fields are automatically filled in. The
-PagerDuty URL links directly to the incident on PagerDuty.
+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 config option:
+you can use the CustomFieldGroupings configuration in RT:
Set(
%CustomFieldGroupings,
'RT::Ticket' => [
- 'PagerDuty' => [ 'PagerDuty ID', 'PagerDuty URL' ],
+ 'Alerts' => [ 'PagerDuty ID', 'PagerDuty URL' ],
],
);
-=head1 Set up a webhook in PagerDuty
+=head1 PagerDuty Webhook
+
+To set up the PagerDuty webhook, do the following.
=over 4
@@ -160,24 +201,43 @@ you can use the CustomFieldGroupings config option:
Select or create an RT user that will be used for the webhook, then create an
auth token from the user admin page.
-Note that the user needs to be able to create and update tickets, usually you
-can grant C<SeeQueue>, C<CreateTicket> and C<ModifyTicket> rights to all the
-queues that integrate with PagerDuty.
+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 C<SeeQueue>, C<CreateTicket>,
+C<ModifyTicket>, and C<ModifyCustomField>.
=item 2. Create the WebHook
-Go to the PagerDuty Service Integrations Webhooks, add a new webhook, use
-C<https://your.rt.example/PagerDuty/WebHook.html> as the webhook URL, note
-that you need to replace C<https://your.rt.example> with your real RT
-instance.
+Go to the PagerDuty Service Integrations Webhooks, add a new webhook. Use
+C<https://your.rt.example/PagerDuty/WebHook.html> as the webhook URL,
+replacing C<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:
+
+=over
+
+=item incident.acknowledged
+
+=item incident.resolved
+
+=item incident.triggered
+
+=back
-Add a custom header with the name C<Authorization> and value
-C<token #-#-abc123> where C<#-#-abc123> is the value of the auth token you
-created in step one. Currently the only event subscriptions supported are
-C<incident.acknowledged>, C<incident.resolved> and C<incident.triggered>.
+At the bottom of the page, click Add custom header. Add a custom header
+with the name C<Authorization> and value C<token #-#-abc123> where
+C<#-#-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.
-Note that the C<Send Test Event> button sends a C<ping> event, no tickets will
-be created.
+The C<Send Test Event> button sends a C<ping> event and no tickets will
+be created in RT.
=back
commit 1b05dd3972e8dd23df00ea3187f3c31434412b38
Author: Jim Brandt <jbrandt at bestpractical.com>
Date: Fri Apr 15 14:10:34 2022 -0400
Add manifest
diff --git a/MANIFEST b/MANIFEST
new file mode 100644
index 0000000..6431ae1
--- /dev/null
+++ b/MANIFEST
@@ -0,0 +1,23 @@
+Changes
+etc/initialdata
+html/PagerDuty/WebHook.html
+inc/Module/Install.pm
+inc/Module/Install/Base.pm
+inc/Module/Install/Can.pm
+inc/Module/Install/Fetch.pm
+inc/Module/Install/Include.pm
+inc/Module/Install/Makefile.pm
+inc/Module/Install/Metadata.pm
+inc/Module/Install/ReadmeFromPod.pm
+inc/Module/Install/RTx.pm
+inc/Module/Install/RTx/Runtime.pm
+inc/Module/Install/Win32.pm
+inc/Module/Install/WriteAll.pm
+inc/YAML/Tiny.pm
+lib/RT/Action/UpdatePagerDuty.pm
+lib/RT/Condition/OnAcknowledge.pm
+lib/RT/Extension/PagerDuty.pm
+Makefile.PL
+MANIFEST This list of files
+META.yml
+README
-----------------------------------------------------------------------
hooks/post-receive
--
rt-extension-pagerduty
More information about the Bps-public-commit
mailing list