NAME

Bric::Util::AlertType - Interface for Managing Types of Alerts

VERSION

$Revision: 1.8 $

DATE

$Date: 2002/08/17 23:49:46 $

SYNOPSIS

use Bric::Util::AlertType;

# Constructors.
my $at = Bric::Util::AlertType->new($init);
my $at = Bric::Util::AlertType->lookup({ id => $id });
my @ats = Bric::Util::AlertType->list($atarams);

# Class Methods.
my @pids = Bric::Util::AlertType->list_ids($atarams);
# Check to see if a name is already used by a user.
my $bool = Bric::Util::AlertType->name_used($name, $user);
my $meths = Bric::Util::AlertType->my_meths;
my @meths = Bric::Util::AlertType->my_meths(1);

# Instance Methods.
my $id = $at->get_id;

# Event type accessors.
my $et = $at->get_event_type;
my $et_id = $at->get_event_type_id;
$at = $at->set_event_type_id($et_id);

# Owner (user) accessors.
my $owner = $at->get_owner;
my $owner_id = $at->get_owner_id;
$at = $at->set_owner_id($owner_id);

my $name = $at->get_name;
$at = $at->set_name($name);
my $subject = $at->get_subject;
$at = $at->set_subject($subject);
my $message = $at->get_message;
$at = $at->set_message($message);

$at = $at->activate;
$at = $at->deactivate;
$at = $at->remove;
$at = $at->is_active;

my @rules = $at->get_rules;
my $rule = $at->new_rule;
$at = $at->del_rules(@rule_ids);

my @users = $at->get_users;
my @uids = $at->get_user_ids;
$at = $at->add_users(@users);
$at = $at->del_users(@uids);

my @grps = $at->get_grps;
my @gids = $at->get_grp_ids;
$at = $at->add_grps(@grps);
$at = $at->del_grps(@gids);

$at = $at->save;

DESCRIPTION

Bric::Util::AlertType provides an interface for creating, editing, and deleting types of alerts. All alerts are based on types of events. These are defined as Bric::Util::EvenType objects. Alerts have several important features.

First, users can create rules for their alerts. These rules will be examined whenever an event the alert is based on is triggered, and the alert will only be sent if all the rules are true for that particular event. Rules can be such as "Send the alert only if the user who triggered the event has a certain email login," or "Send the alert only if the Story's slug is "pooter". Rules can be combined to refine when the alert is sent to a great degree, and there is no limit on the number of rules an Bric::Util::AlertType object can have. The interface for rules is Bric::Util::AlertType::Parts::Rule.

Second, users can use the same variables by which rules are created to customize the alert message. By simply adding a reference to one of these variables, the message will be filled in with data from the event or the object on which the event is based before sending out the alert. See set_message() below for more details on message customization.

Third, users can select multiple methods of dispatching alerts (email, pager, instant message, etc.), and associate users or groups of users with a method.

INTERFACE

Constructors

my $c = Bric::Util::AlertType->new
my $c = Bric::Util::AlertType->new($init)

Instantiates a Bric::Util::AlertType object. An anonymous hash of initial values may be passed. The supported initial value keys are:

The active property will be set to true by default. Call $at->save() to save the new object.

Throws:

Side Effects: NONE.

Notes: NONE.

my $c = Bric::Util::AlertType->lookup({ id => $id })

Looks up and instantiates a new Bric::Util::AlertType object based on the Bric::Util::AlertType object ID passed. If $id is not found in the database, lookup() returns undef.

Throws:

Side Effects: If $id is found, populates the new Bric::Util::AlertType object with data from the database before returning it.

Notes: NONE.

my (@ats || $ats_aref) = Bric::Util::AlertType->list($params)

Returns a list or anonymous array of Bric::Util::AlertType objects based on the search parameters passed via an anonymous hash. The supported lookup keys are:

Throws:

Side Effects: Populates each Bric::Util::AlertType object with data from the database before returning them all.

Notes: NONE.

Destructors

$at->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Class Methods

my (@at_ids || $at_ids_aref) = Bric::Util::AlertType->list_ids($params)

Returns a list or anonymous array of Bric::Util::AlertType object IDs based on the search parameters passed via an anonymous hash. The supported lookup keys are the same as those for list().

Throws:

Side Effects: NONE.

Notes: NONE.

Bric::Util::AlertType->name_used($name, $user);

All Bric::Util::AlertType objects owned by a single user must have a unique name. Different users can have alert types with the same name, but one user cannot have two or more alerts with the same name.

This class method will check for the existence of a name/owner combination in the database. If it returns true, then the owner will have to change or the name will have to change before a new Bric::Util::AlertType object can be created with those values. If it returns false (undef), then the name/owner combination is available to be created.

Throws:

Side Effects: NONE.

Notes: Also may be used as an instance method. See below.

$meths = Bric::Util::AlertType->my_meths
(@meths || $meths_aref) = Bric::Util::AlertType->my_meths(TRUE)

Returns an anonymous hash of instrospection data for this object. If called with a true argument, it will return an ordered list or anonymous array of intrspection data. The format for each introspection item introspection is as follows:

Each hash key is the name of a property or attribute of the object. The value for a hash key is another anonymous hash containing the following keys:

Throws: NONE.

Side Effects: NONE.

Notes: NONE.

Public Instance Methods

my $id = $at->get_id

Returns the ID of the Bric::Util::AlertType object.

Throws:

Side Effects: NONE.

Notes: If the Bric::Util::AlertType object has been instantiated via the new() constructor and has not yet been saved, the object will not yet have an ID, so this method call will return undef.

my $name = $at->get_name

Returns the name of the Bric::Util::AlertType object.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->name_used

Use this class method once you have set both the name and the owner of this Bric::Util::AlertType object. It will return $self if the user already owns an Bric::Util::AlertType object by that name, and undef if not.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->set_name($name)

Sets the name of the Bric::Util::AlertType object. Be sure to call $at->save if you want the new name to stick. The maximum length of the name is 64 characters.

Throws:

Side Effects: NONE.

Notes: NONE.

my $subect = $at->get_subject

Returns the Bric::Util::AlertType object's subject. This is the subject data that will be parsed for variables, sent as individual alerts, and saved with the alert in the database. See set_subject() for details on customizing the subject for variable interpolation.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->set_subject($subject)

Sets the subject that will be sent in the subject field of alerts of this type. The subject can up to 128 characters long, and can contain special variables which will be evaluated when the alert is sent. The variables that are allowed for a given type of alert are specified by the type of object on which the alert is based, and can be retrieved from the Bric::Util::EventType object in question via its get_alert_props() method.

The list of hashrefs returned from that method contain a "name" key and a "description" key. Append a dollar sign ($) to the beginning of a name to indicate a variable to be evaluated in a subject. For example, one common use for this functionality is to see who triggered the event that in turn triggered the alert. Thus, a subject might be something like:

$trig_full_name Saved a Story

When the alert is sent and saved as a Bric::Util::Alert object in the database, these variables will be evaluated and filled in with their underlying values:

David Wheeler Saved a Story

I recommend that, at most, one or two variables be included, since the subject of the alert should be short. Be sure to call $at->save if you have set a new value via set_subject().

Throws:

Side Effects: NONE.

Notes: NONE.

my $message = $at->get_message

Returns the Bric::Util::AlertType object's message. This is the message that will be parsed for variables, sent as individual alerts, and saved with the alert in the database. See set_message() for details on customizing the message for variable interpolation.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->set_message($message)

Sets the message that will be sent out in alerts of this type. The message can up to 512 characters long, and can contain special variables which will be evaluated when the alert is sent. The variables that are allowed for a given type of alert are specified by the type of object on which the alert is based, and can be retrieved from the Bric::Util::EventType object in question via its get_alert_props() method.

The list of hashrefs returned from that method contain a "name" key and a "description" key. Append a dollar sign ($) to the beginning of a name to indicate a variable to be evaluated in a message. For example, one common use for this functionality is to see who triggered the event that in turn triggered the alert. Thus, a message might be something like:

A story was saved and moved to the $desk by $trig_full_name <$trig_email>.

When the alert is sent and saved as a Bric::Util::Alert object in the database, these variables will be evaluated and filled in with their underlying values:

A story was saved and moved to the Publish Desk by David Wheeler
<david@wheeler.net>.

Feel free to use as many variables as necessary (and as are available from Bric::Util::EventType::get_alert_props()). Be sure to call $at->save if you have set a new value via set_message().

Throws:

Side Effects: NONE.

Notes: NONE.

my $user = $at->get_owner

Returns the Bric::Biz::Person::User object representing the user who owns the Bric::Util::AlertType object.

Throws:

Side Effects: NONE.

Notes: Uses Bric::Biz::Person::User->lookup internally.

my $owner_id = $at->get_owner_id

Returns the owner_id of the Bric::Biz::Person::User object representing the user who owns this Bric::Util::AlertType object.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->set_owner_id($owner_id)

Sets the Bric::Biz::Person::User ID representing the user who owns the Bric::Util::AlertType object.

Throws:

Side Effects: NONE.

Notes: NONE.

my $event = $at->get_event_type

Returns the Bric::Util::EventType object for which the Bric::Util::AlertType object defines alerts.

Throws:

Side Effects: NONE.

Notes: Uses Bric::Util::EventType->lookup internally.

my $event_type_id = $at->get_event_type_id

Returns the ID of the Bric::Util::EventType object for which this Bric::Util::AlertType is defined.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->set_event_type_id($event_type_id)

Sets the Bric::Util::EventType ID representing the event type for which this Bric::Util::AlertType object is defined.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->activate

Activate the alert type. When an alert type is active, it will be triggered whenever its associated event has been triggered and all its rules met. A new Bric::Util::AlertType object is active by default, so you don't need to call this method unless you need to reactivate an existing Bric::Util::AlertType object that has previously been deactivated (see below). Be sure to call $at->save to save the change to the object.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->deactivate

Deactivates the Bric::Util::AlertType object. Deactivated Bric::Util::AlertTypes will not send alerts. Call $at->save to make the change persistent.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->remove

Deletes the Bric::Util::AlertType object. Deleted alert types are still in the database, however; their del status is simply marked 1 while their active status is marked 0. So they can be manually recalled via SQL, and their individual alerts and alerted records still exist. Call $at->save to make the change persistent.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->is_active

Returns $self if the Bric::Util::AlertType object is active, and undef if it is not.

Throws:

Side Effects: NONE.

Notes: NONE.

my (@rules || $rules_aref) = $at->get_rules(@rule_ids)
foreach my $rule ($at->get_rules) {
    print "Name:  ", $rule->get_attr, "\n";
    $rule->set_attr($new_attr_name);
    print "Value: ", $rule->get_value, "\n\n";
    $rule->set_value($new_value);
}
$at->save;

If called with no arguemnts, returns a list of all the Bric::Util::AlertType::Parts::Rule objects associated with this Bric::Util::AlertType object. If called with Bric::Util::AlertType::Parts::Rule object IDs, it will return only those rules.

Rules are Bric::Util::AlertType::Parts::Rule objects, and are strictly associated with a Bric::Util::AlertType object. They cannot be created or destroyed in any other way. Indeed, if you make changes to the rule via its accessors, those changes will only stick if you call $at->save on the Bric::Util::AlertType object with which the rule is associated.

See Bric::Util::AlertType::Parts::Rule for its interface.

Throws:

Side Effects: NONE.

Notes: Uses Bric::Util::AlertType::Parts::Rule and Bric::Util::Coll::Rule internally.

my $rule = $at->new_rule
my $rule = $at->new_rule($attr, $op, $value)
$at->new_rule($attr, $op, $value);
$at->save;

Creates a new rule associated with this Bric::Util::AlertType object. You can pass in a list of values for the rule in this order--attribute, operator, value--and the rule will be complete. Or you can call new_rule() with no arguments, and then use the Bric::Util::AlertType::Parts::Rule accessor methods to set these values. Be sure to call $at->save whenever you want changes to the rule to stick.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->del_rules(@rule_ids)

$at->del_rules();
$at->save;

Deletes a rules from the object, and will delete them from the database once $at->save has been called. The arguments may consist of a simple list of all the IDs of Bric::Util::AlertType::Parts::Rule objects to be deleted. If called with no arguments, all of the rules asscociated with $at will be deleted. Be sure to call $at->save to save your changes.

Throws:

Side Effects: NONE.

Notes: NONE.

my (@uids || $uids_aref) = $at->get_user_ids($cont_type_id)

Returns a list or an anonymous array of Bric::Biz::Person::User object IDs that represent the users who will receive alerts of this type. This list does not include users in a group associated with an alert (see below). If any Bric::Biz::Contact type names are passed as arguments, only those users who will be notified of this type of alert by that method will be returned. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: NONE.

my (@users || $users_aref) = $at->get_users(@cids)

Returns a list or an anonymous array of Bric::Biz::Person::User objects that represent the users who will receive this alert. This list does not include users in a group associated with an alert (see below). If Bric::Biz::Contact type names are passed as an arguments, only those users who will be notified of this type of alert by that method will be returned. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: Uses get_user_ids() and Bric::Biz::Person::User->lookup() internally.

$at->add_users($contact_type, @users)
$at->add_users($contact_type, $user1, $user2);
$at->save;

This method tells the Bric::Util::AlertMethod object which users to alert via a given contact type when an alert it sent. The first argument must be a Bric::Biz::Contact type, and the remaining arguments may be Bric::Biz::Person::User objects or IDs. All users must be associated with a contact type. Be sure to call $at->save to save your changes. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->del_users($contact_type, @users)

This method dissociates individual users from the Bric::Util::AlertType object. These contacts will no longer receive alerts sent via $contact_type, although they may continue to receive alerts if they are associated with different contact types for this alert alerting. Be sure to call $at->save to save your changes. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: NONE.

my (@gids || $gids_aref) = $at->get_group_ids(@contact_types)

Returns a list or an anonymous array of Bric::Util::Grp::User object IDs representing groups of users to whom alerts of this type will be sent via the contact types passed as arguments. If @contact_types are not passed, all the Bric::Util::Grp::User object IDs associated with this Bric::Util::AlertType object will be returned. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: NONE.

my (@groups || $groups_aref) = $at->get_groups(@cids)

Returns a list or an anonymous array of Bric::Util::Grp::User objects that represent the groups who will receive this alert. If any Bric::Biz::Contact type names are passed as an arguments, only those groups who will be notified of this type of alert by that contct type will be returned. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: Uses get_user_ids() and Bric::Biz::Person::User->lookup() internally.

$self = $at->add_groups($contact_type, @groups)
$at->add_grps($contact_type, $gid1, $gid2);
$at->save;

This method tells the Bric::Util::AlertMethod object which groups of users to alert via $contact_type when an alert it sent. The first argument must be a Bric::Biz::Contact type, and the remaining arguments must be Bric::Util::Grp::User objects or IDs. All groups must be associated with a contact type. Be sure to call $at->save to save your changes. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->del_groups($contact_type, @grps)

This method dissociates Bric::Util::Grp::User objects from the Bric::Util::AlertType object. The users in these groups will no longer receive alerts sent via $contact_type, although they may continue to receive alerts if they are associated with different contact types. Be sure to call $at->save to save your changes. To get a list of available contact types, call Bric::Biz::Contact->list_alertable_types().

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->save

Saves all the changes to the Bric::Util::AlertType object to the database. This includes all simple properties, all rules, and all contacts and groups. This is the method to call if you've changed anything about your alert type and want it to stay changed. Returns $self on success and undef on failure.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $at->send_alerts($args)

This method will evaluate whether this type of alert's rules are true when compared to the properties of the event and its associated Bricolage object. If so, it will send all necessary alerts. You will not normally need to call this method - it is called internally when a new event is logged via Bric::Util::EventType->log_event() or Bric::Util::Event->new(). The anonymous hash argument rquires the following keys:

Throws:

Side Effects: NONE.

Notes: NONE.

PRIVATE

Private Class Methods

NONE.

Private Instance Methods

NONE.

Private Functions

my $ats_aref = &$get_em( $pkg, $params )
my $ats_ids_aref = &$get_em( $pkg, $params, 1 )

Function used by lookup() and list() to return a list of Bric::Util::AlertType objects or, if called with an optional third argument, returns a listof Bric::Util::AlertType object IDs (used by list_ids()).

Throws:

Side Effects: NONE.

Notes: NONE.

my $rules = &$get_rules($self)

Returns the collection of rules for this alert type. The collection is a Bric::Util::Coll::Rule object. See that class and its parent, Bric::Util::Coll, for interface details.

Throws:

Side Effects: NONE.

Notes: NONE.

my $cont = &$get_cont($self)

Loads user and group contacts. It is called first thing when any user or group contact method is called.

Throws:

Side Effects: NONE.

Notes: NONE.

$bool = &$upd_cont($self)

Saves any changes to the user and group contacts for this alert type. Called by save().

Throws:

Side Effects: NONE.

Notes: NONE.

NOTES

NONE.

AUTHOR

David Wheeler <david@wheeler.net>

SEE ALSO

Bric, Bric::Util::Alert, Bric::Util::EventType, Bric::Util::Event

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 380:

=back doesn't take any parameters, but you said =back 4

Around line 600:

Expected '=item *'

Around line 602:

Expected '=item *'

Around line 604:

Expected '=item *'

Around line 606:

Expected '=item *'

Around line 608:

Expected '=item *'

Around line 610:

Expected '=item *'

Around line 612:

Expected '=item *'

Around line 1572:

You forgot a '=back' before '=head2'

Around line 1639:

'=item' outside of any '=over'

Around line 2448:

=back doesn't take any parameters, but you said =back 4

Around line 2797:

You forgot a '=back' before '=head1'