Skip to content
This repository has been archived by the owner on Nov 29, 2017. It is now read-only.

Alert syntax

Jump to bottom
troy edited this page Mar 29, 2013 · 1 revision

Intro

A process definition says how an alert should reach a human.

A process definition defines participants, such as SMSing Bob at 2065558123.

Participants are inside a process definition. For example:

process_definition do
  participant 'call bob', :recipient => '4155554242', :timeout => '5m'
  participant 'IM Alex', :recipient => 'alex42@gmail.com', :using => 'jabber'
end

A participant has a method of notification (like IM or SMS), a recipient (like a phone number), and optional arguments (like a timeout to wait before moving on to the next step, or a constraint to decide whether to notify the participant).

The format for a participant looks like this:

participant '<method> <arbitrary freeform name>', :recipient => '<recipient>', :timeout => '<length><m|s>'

Alert Participants

Notification Methods

  • Call
  • Email
  • IM (not currently functioning)
  • SIP
  • SMS

Alert methods are case insensitive. All of call bob, CaLl Bob, and CALL BOB will make Bob's phone ring and can be used interchangeably in the same process definition.

Arguments

Required

For all participants:

  • recipient. 10-digit phone number (2065551234), IM account (alex42 or alex42@gmail.com depending on recipient network), email address (alex42@gmail.com), or SIP URI (alex42@onsip.com).

For IM participants

  • using. IM network. One of: AIM, Jabber, MSN, Yahoo. Case insensitive.

Optional

  • timeout. How long to wait before continuing on the alert sequence
  • if. A conditional to decide whether to invoke this participant (like for time-of-day constraints)
  • many other conditionals and constraints described in Workflow

Argument Details

timeout

Specify a timeout before the next step in a sequence is invoked.

Syntax

<X><m|s>

Examples:

  • 3 minutes: :timeout => '3m'
  • 30 seconds: :timeout => '30s'

Participants with no timeout will use 2 minutes except for call and SIP, which use 30 seconds because the prompt is interactive.

Individual participants and entire alert invocations can last up to 30 minutes.

if (time and date constraints)

Alerts can use the time and date to decide whether a participant should be notified.

When an alert is invoked, the start time is recorded. That time is provided to each participant in the form of named variables for each time component (like hour of the day).

The time is localized to the timezone chosen when the process definition was created. Basically this means as long as your process definition is consistent, it can ignore timezones.

Convenience Names

4 convenience names are provided:

  • weekend: true between midnight Saturday morning and midnight Sunday night; false otherwise.

  • weekday: inverse of weekend

  • daytime: true between 7:00 AM and 6:59 PM; false otherwise.

  • nighttime: inverse of daytime

Absolute Time

The following variables are provided with absolute time values: hour, minute, day, month, day_of_week, day_of_year.

All value formats are consistent with the corresponding Ruby Time class methods.

Examples

At night:|:if => '${nighttime}'

Business day only: :if => '${weekday} && ${daytime}'

Off-hours: ':if => ${weekend} || ${nighttime}'

Between 9 AM and 6 PM: :if => '${hour} > 9 && ${hour} < 18'

Only on odd days, like to share duties among 2 people: :if => '${day_of_year}%2 == 0'

Only on every 5th day, like to share duties among 5 people: :if => '${day_of_year}%5 == 0'

Most and probably all ruote operators should work.

Alert Workflow

The most powerful alerts minimize the number of false positives: alerts that the recipient can't act on or doesn't care about. Use workflow commands to do that.

2 of the most powerful workflow objects are concurrence and subprocesses.

Most ruote expressions should function.

Concurrence

Concurrence runs multiple steps at the same time.

Subprocesses

A subprocess is a flow defined separately and given a name. It can then be referred to elsewhere in the process definition.

Example

process_definition do
  define 'notify Eric' do
    participant 'IM Eric', :recipient => 'eric@example.com', :using => 'jabber', :timeout => '2m'
    participant 'SMS Eric', :recipient => '8145557438'
  end

  define 'Gripe to Phong' do
    participant 'call phong', :recipient => '7165554288'
    participant 'sms Phong', :recipient => '7165554288'
  end

  concurrence do
    subprocess 'notify Eric'
    subprocess 'Gripe to Phong'
    participant 'Call Sally', :recipient => '2065558484', :if => '${nighttime}'
  end
end

A concurrence can also have a global timeout, like: `concurrence :timeout => '5m do .. end'. When a concurrence's timeout is reached, all participants within the concurrence are stopped (regardless of their timeout).

As shown above, participants, subprocesses, and concurrence can be mixed together. Participant and subprocess names aren't case sensitive for Transmit Logic, but what you create must be the same as what you refer to.

Clone this wiki locally