App::Wubot::Guide::Notifications - guide to using notifications
This document describes how to enable notifications. You probably should not start at this document, as there will be no notifications unless you have figured out how to use the monitor and reactor. A good place to start is probably App::Wubot::Guide::GettingStarted.
There are currently three notification reactors:
- Console - Growl - IRC
The 'Growl' reactor currently only works on OS X. These plugins could easily be adapated to use pop-up notifications on other operating systems, but that has not yet been done.
All three reactors look for a 'subject' field on a message, and use that for the notification. Messages that do not have a 'subject' field are ignored. Many monitors will set the 'subject' field to something useful. For example, the RSS plugin will set the 'subject' field of RSS feed items to be the RSS title. You can easily use the reactor to remove the subject from messages when you want to suppress notifications.
In addition to the 'subject' field, the message key will be prefixed with the 'key' of the original monitor that generated the message, and a timestamp of when the message was originally generated. If the message contains a 'username' that is also included in the notification.
To enable the notifications, start with a rule tree that selects messages that contain subjects. For the complete config, skip to the bottom.
- name: notifications condition: subject is true rules:
The User reactor will parse the username field and extract any information such as the domain name or full name from an email address, or IRC-style username comments. See the User reactor documentation for more information. This will leave you with a short username which works better in notifications and makes it easier to locate an icon for the user.
Begin by enabing the 'Console' plugin. This will send all subjects to stdout in the terminal that is running wubot-reactor. If the message contains a 'color' field, the Console plugin will attempt to display the message in the closest ANSI color.
- name: console plugin: Console
If you have 'Growl' installed on OS X, and you have the 'growlnotify' command line tool installed, and the Growl::Tiny perl library installed, then wubot can send a growl notification. Enabling the growl notifications is easy, just add a 'Growl' rule.
- name: growl notify plugin: Growl
Note that network notifications must be enabled in the growl configuration (System Preferences => Growl => Network => Listen for incoming notifications). Otherwise some growl notifications may not be delivered. For more information, please see the BUGS_AND_LIMITATIONS section in the Growl::Tiny documentation.
It is very nice to have icons, e.g. for the growl notifications or the web ui. The Icon plugin can be used to locate one. This plugin looks at a series of fields on the message (e.g. the username, the key, the plugin, the instance name) and tries to find a custom .png file in your icons directory that is appropriate.
- name: growl icon plugin: Icon config: image_dir: /Users/your_id/.icons
It is also nice to have colorized growl messages. Unfortunately you can't just pass a color into growl. One trick I've found here is to use the 'smoke' theme and then configure a different color for each priority. For very low, I use blue, moderate is green, normal is black, high is orange, and emergency is red. Then I have a rule in the reactor which maps the name of a color to the growl priority:
- name: growl color plugin: HashLookup config: source_field: color target_field: growl_priority lookup: red: 2 yellow: 1 orange: 1 grey: 0 bold black: 0 green: -1 magenta: -2 purple: -2 blue: -2 cyan: -2
Now if I have a rule that runs before this rule that sets the 'color' field to blue, this rule will set a field called 'growl_priority' in the message which will have the priority that corresponds to the color i set for that priority in the growl preferences.
Growl has a feature called 'coalescing'. This allows multiple notifications to re-use a sigle bubble for notifications, with the latest notification taking precedence.
By default, wubot will set the growl identifier for each growl notification to be the message key. This helps prevent message floods, especially when starting up wubot if there are a lot of notifications waiting in the queue. Without a growl identifier, dozens (or even hundreds) of notification bubbles could queue up and prevent you from being able to work.
In some cases this may work against you. For example, if you use the Twitter plugin, then all notifications for a given twitter account use the same key. So, if multiple tweets come through quickly from different users, they will re-use the same notification bubble--and you may only get a chance to read the last one. So in these situations, you can override the default behavior by setting 'growl_id'. For example:
- name: twitter growl id condition: key matches ^Twitter AND username is true plugin: Template config: template: 'Twitter-{$username}' target_field: growl_id
This would give each person you follow on twitter a separate notification bubble.
When overiding the default growl id, one thing to note is that if you send a sticky notification, and then you send a non-sticky notification with the same growl id, the non-sticky notification will replace the sticky notification (since it will use the same bubble), and will time out and go away like a normal non-sticky notification. This means that your sticky window will get cleared. Wubot tries to prevent this sort of thing by using separate id for sticky notifications and non-sticky notifications. That way a sticky window can nevery be cleared by a non-sticky window.
The IRC notification lets you send a public IRC message to a channel or a private message to a user. For more information, see App::Wubot::Guide::IRC.
If your message has a field 'subject_text', then that field will be used for the notifications instead of the 'subject' field. This makes it easy to do things like strip HTML without alterting the original subject field. You most likely will not want html to be displayed in the console notification or be read aloud. You can strip HTML from any field using the HTMLStrip plugin, e.g.:
- name: strip HTML from subject condition: contains subject plugin: HTMLStrip config: field: subject target_field: subject_text
Keep this field in mind if you delete the subject field. If you have created a subject_text field, then even if you delete the subject field, you could still receive a notification. This can be confusing if you have set 'subject_text' and then you change 'subject'--since the changed subject won't be reflected in the notification. The easiest way to avoid this is simply to avoid using the subject_text field.
For more information, see App::Wubot::Web::Notify.
You will need to start up the wubot-webui process if you haven't already done so. For more information, see App::Wubot::Guide::WebUI.
So now let's put it all together. The reactor config lives here:
~/wubot/config/reactor.yaml
Here are the final contents of the reactor config.
Warning: if you are not familiar with YAML, it is extremely sensitive to whitespace!
--- rules: - name: notifications condition: subject is true rules: - name: strip HTML from subject condition: contains subject plugin: HTMLStrip config: field: subject target_field: subject_text - name: user field parser plugin: User - name: console plugin: Console - name: growl color plugin: HashLookup config: source_field: color target_field: growl_priority lookup: red: 2 yellow: 1 orange: 1 grey: 0 bold black: 0 green: -1 magenta: -2 purple: -2 blue: -2 cyan: -2 - name: growl icon plugin: Icon config: image_dir: /Users/your_id/.icons - name: growl notify plugin: Growl - name: notify sql table plugin: SQLite config: file: /Users/wu/wubot/sqlite/notify.sql tablename: notifications
To start the reactor, simply run: wubot-reactor
To install App::Wubot, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Wubot
CPAN shell
perl -MCPAN -e shell install App::Wubot
For more information on module installation, please visit the detailed CPAN module installation guide.