NAME

RT::Action::PushoverNotify - Send RT activity to a Pushover user or group

DESCRIPTION

Send RT activity information to Pushover for distribution to mobile clients. The message is defined with an RT template.

The message receipients are controlled by setting the contents of the array-ref-ref Recipients, which is a predefined variable in the template. If an entry is an RT::User then its PushoverUserKey custom field is looked up to obtain the Pushover key to notify. Otherwise the result is assumed to be a pushover key and notified as-is. Eg:

  push(@$$Recipients, @{$Ticket->QueueObj->AdminCc->UserMembersObj->ItemsArrayRef})

Headers in the template are parsed out to control additional request parameters:

- Priority: message priority as defined by Pushover API. -1 is low / do not disturb; 0 is normal, 1 is emergency (override silent hours), 2 is emergency that requires acknowledgement.

- Subject: message title

- Retry: Seconds between retry attempts (within 'expires' interval). Only applies for priority=2. Default 60. The API sets limits on these values and will fail requests - currently for retry values less than 30.

- Expire: Number of seconds after message delvery that message acknowledgement request expires. Only applies for priority=2. Default 300.

- URL: A link to include in the message

- URL-Title: Title to add to the message

- Device: The user's device name, if you want to send a message only to one particular device.

- Sound: The name of the Pushover notification sound to use; see https://pushover.net/api#sounds

The message time and the application API key are added to the request automatically.

Limitations are documented in https://pushover.net/api#limits

USAGE

In RT_SiteConfig.pm add your application API token, which you can request at http://pushover.com/ .

    Set($PushoverNotifyConfig, {
        api_token => 'lkhasdf87234lkhsfd123sdfASAFD1'
    });

Create a custom user field named PushoverUserKey. Apply it to all users, and populate the field for the users who you want to receive notificatoins. You can get your pushover key from http://pushover.com/.

Create the following table in your RT database:

    CREATE TABLE PushoverNotifications (id serial primary key, RequestId text, UserId text, TicketId integer, AcknowledgedAt timestamptz, ReceiptId text, UserToken text not null, Priority integer, SentAt timestamptz);

Create an entry in the scripactions table in the RT database for RT::Action::PushoverNotify, or (only once) "make initdb" on this extension to create the entry. Do not repeat this step as you will get duplicate entries.

Create a suitable Template as documented below and then create a scrip that uses the template and action with a suitable condition to send notifications.

Exposed pages

  /NoAuth/Pushover/callback.html - Accepts acknowledgement callbacks from pushover.com

Database tables

  pushovernotifications - Keeps records of notifications sent and acknowledged

Example template

    Subject: New ticket #{$Ticket->Id}
    Priority: 2
    Retry: 30
    Expire: 120
    URL: http://mysite.zz/rt/Ticket/Display.html?id=1111
    URL-Title: Ticket 1111

    {
      # Recipients is a ref to an array ref
      push(@$$Recipients, 'u1321321123123123');
    }
    A new ticket has been filed in the queue {$Ticket->Queue->Name}.

The template argument is set to the scrip argument if any. @$$Recipients may be set hard coded, based on the template argument, based on some other calls, etc.

Future work

* Set all options via a hash parameter, instead of using header-style parsing * Provide an easier way to filter recipients based on a function for checking "on shift" status, etc.

cpanm RT::Extension::PushoverNotify

perl -MCPAN -e shell
install RT::Extension::PushoverNotify