/ 
App-Wubot-0.5.0
/ App::Wubot::Guide::Notifications

NAME

App::Wubot::Guide::Notifications - guide to using notifications

DESCRIPTION

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.

Notification reactors

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:

User

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.

Console

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

Growl

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.

Icons

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

Growl Colors

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 identifier

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.

IRC

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.

subject_text field

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.

Notifications Web UI

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.

Reactor Config

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/your_id/wubot/sqlite/notify.sql
          tablename: notifications

Starting the Reactor

To start the reactor, simply run: wubot-reactor