NAME

App::Wubot::Plugin::Pulse - send a message once per minute

VERSION

version 0.5.0

SYNOPSIS

# The plugin configuration lives here:
~/wubot/config/plugins/Pulse/myhostname.yaml

# There is no actual configuration for this plugin.  All that is
# needed is that a minimal configuration file exist:
---
enable: 1

# an example message:

age: 0
checksum: ae947857531889e0fb55a517c4e0fc94
date: 2011-07-31
day: sunday
hostname: myhostname
key: Pulse-myhostname
lastupdate: 1312158327
plugin: App::Wubot::Plugin::Pulse
time: 17:25

DESCRIPTION

The 'pulse' plugin sends a message once per minute. The message contains the following fields:

date: yyyy-mm-dd
time: hh:mm
day: xday

The 'day' field will contain the full weekday name in lower case.

The message can be used within the reactor to trigger jobs to start at certain times or dates.

Each time the Pulse plugin runs, it will reschedule itself to run again at the minute change.

There is no guarantee that the pulse will occur on time, but there is a guarantee that no minutes will be skipped. When the Pulse plugin runs, it checks the cache to find the last time it was run. If any pulses were missed (e.g. because wubot was not running or was unable to run the Pulse for a minute), then the Pulse check will immediately send messages for all the missed minutes. If the pulse was triggered late, then the 'age' field on the message will indicate the number of minutes old that the message was at the time it was generated. If the 'age' field is false, that indicates that the message was sent during the minute that was indicated on the message.

There is also a 'max_pulses' config param that can be used to limit the maximum number of missed pulses that will be sent. This is designed to prevent a massive flood of pulses (e.g. in the event that wubot had not been running for months and then is started back up). max_pulses defaults to 10080, which is 1 week's worth of pulses:

1 pulse/minute * 60 minutes/hour * 24 hours/day * 7 days = 10080 pulses

SCHEDULED TASKS

You can trigger a reaction to take place at a specific time by creating a rule that triggers from the pulse. The reaction might be as simple as setting a 'subject' on the pulse message itself so that a notification occurs (assuming you have reactions set up to perform notifications for messages with subjects).

- name: hourly announcements
  condition: key matches ^Pulse AND time matches :00 AND age < 60
  plugin: Template
  config:
    template: the time is {$time}
    target_field: subject

Notice that the condition contains an 'age' field--this is because a pulse is guaranteed to be delivered for every minute, even if wubot has not been running for a few days. Without this condition, if you start up wubot after it has not been running for a while (or enable the pulse plugin after it has been disabled for a while) it will spam you with a notification for every hour since the plugin last ran. With the condition

SUBROUTINES/METHODS

check( $inputs )

The standard monitor check() method.