ApTest Manager documentation: API: Notify

NAME
AUTHOR
COPYRIGHT
SYNOPSIS
TRIGGER DEFINITION
METHODS

triggers - get trigger information
triggersInCategories - get the triggers, divided into categories
validTrigger - is a named trigger valid?
notify - send a notification email
session - send notifications about a session

NAME

Notify - notify users of system changes

AUTHOR

Ian Malpass <ian@aptest.com>

COPYRIGHT

SYNOPSIS

use Notify;

# get a hash of testChange trigger information
$testCreate = Notify->triggers( trigger => "testChange" );

# get a hash of only Edit triggers
%triggers = Notify->triggers( category => "Edit" );

# get a hash of all triggers
%triggers = Notify->triggers();

# check a trigger;
my $valid = Notify->validTrigger( "testCreate" );

# send notifcation mail
Notify->notify(
    suite   => $suite,
    trigger => "testChange",
    message => "$user created $test",
);

TRIGGER DEFINITION

$notificationTriggers{ 'aTrigger' } = {
    title    => 'Bing',
    note     => 'The machine goes &quot;bing&quot;',
    subject  => 'The machine went "bing"',
    category => 'System administration',
    perSuite => 0,
};

Each trigger is a hash of five keys:

title: The text that gets displayed in the column headers of the administrative interfaces.
note: The tooltip that accompanies the title. Typically a fuller explanation of what trips the trigger. The note is inserted as an HTML tag attribute, so it needs double quotes escaped as in the example above.
subject: The default subject line for the email. In a per-suite email, this will have the suite name appended in parentheses.
category: A category for the trigger. Categories are only used to group triggers in the administrative interfaces. The category is an arbitrary string - if you use a string that hasn't been used before, a new category will appear in the display.
perSuite: A boolean argument. If set to 1, a user can have different settings for this trigger in different suites. If set to 0, the trigger is "global" - i.e. not suite-specific, such as administrative changes.

METHODS

triggers - get trigger information

%widetTrigger = Notify->triggers( trigger => 'testChange' );
%editTriggers = Notify->triggers( category => 'Edit' );
%triggers     = Notify->triggers();

If you specify a trigger, triggers() will return a hash of information about that trigger.

If you specify a category, triggers() will return a hash of hashes of information about triggers in that category.

If you give no argument, triggers() will return a hash of hashes of information about all triggers.

triggersInCategories - get the triggers, divided into categories

%triggerCats = Notify->triggersInCategories( perSuite => $perSuite );

If the optional perSuite argument is sent, then only triggers (and categories) that match the argument's value (0 for global notifications, 1 for suite notifications) will be returned.

validTrigger - is a named trigger valid?

if ( Notify->validTrigger( $trigger ) {
    ...
}

notify - send a notification email

# send to any user subscribed to testChange
Notify->notify(
    suite   => $suite,
    trigger => "testChange",
    message => "$user created $test",
);

# send to only Alice and Bob, if they're subscribed to testChange
Notify->notify(
    suite   => $suite,
    trigger => "testChange",
    message => "$user created $test",
    userList => [ "Alice", "Bob" ],
);

# send mail to any user subscribed to testChange except Eve
Notify->notify(
    suite   => $suite,
    trigger => "testChange",
    message => "$user created $test",
    noMail   => [ "Eve" ],
);

The trigger and message arguments are required.

If suite is omitted, it is assumed that the trigger is a global one.

The userList and noMail arguments are optional (and typically mututally exclusive) and must be array refs.

If you specify a subject argument, it gets used instead of the default subject.

session - send notifications about a session

# send to any user subscribed to testChange
Notify->session(
    sessHandle  => $sessH,
    resultsHash => $resH,
    endWhen     => $stamp,
    startWhen   => $stamp
);

sessHandle is the handle to a test session that may need notifications sent.

resultsHash is an optional reference to a hash of results and tests that have those results. If provided, then testResultNotify notices will be sent.

endWhen is an optional timestamp. If provided, it indicates a time to put on session end should the session actually be complete.

startWhen is an optional timestamp. If provided, it indicates a time to put on session start should this really be the first test that was run.