Bric::Util::AlertType(3)

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

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2004-11-05 16:10:32 -0800 (Fri, 05 Nov 2004) $

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:

    *   event_type_id

    *   owner_id

    *   name

    *   subject

    *   message

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

    Throws:

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Too many Bric::Util::AlertType objects found.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    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:

    *   event_type_id

    *   owner_id

    *   name

    *   subject

    *   message

    *   active

    Throws:

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    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:

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    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:

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    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)
my (@meths || $meths_aref) = Bric::Util::AlertType->my_meths(0, TRUE)
    Returns an anonymous hash of introspection data for this object. If called with a true argument, it will return an ordered list or anonymous array of introspection data. If a second true argument is passed instead of a first, then a list or anonymous array of introspection data will be returned for properties that uniquely identify an object (excluding "id", which is assumed).

    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:

    name
        The name of the property or attribute. Is the same as the hash key when an anonymous hash is returned.

    disp
        The display name of the property or attribute.

    get_meth
        A reference to the method that will retrieve the value of the property or attribute.

    get_args
        An anonymous array of arguments to pass to a call to get_meth in order to retrieve the value of the property or attribute.

    set_meth
        A reference to the method that will set the value of the property or attribute.

    set_args
        An anonymous array of arguments to pass to a call to set_meth in order to set the value of the property or attribute.

    type
        The type of value the property or attribute contains. There are only three types:

        short
        date
        blob
    len If the value is a 'short' value, this hash key contains the length of the field.

    search
        The property is searchable via the list() and list_ids() methods.

    req The property or attribute is required.

    props
        An anonymous hash of properties used to display the property or attribute. Possible keys include:

        type
            The display field type. Possible values are

            text
            textarea
            password
            hidden
            radio
            checkbox
            select
        length
            The Length, in letters, to display a text or password field.

        maxlength
            The maximum length of the property or value - usually defined by the SQL DDL.

    rows
        The number of rows to format in a textarea field.

    cols
        The number of columns to format in a textarea field.

    vals
        An anonymous hash of key/value pairs reprsenting the values and display names to use in a select list.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'id' required.

    *   No AUTOLOAD method.

    Side Effects: NONE.

    Notes: If the Bric::Util::AlertType object has been instantiated via the new() constructor and has not yet been "save"d, 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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'name' required.

    *   No AUTOLOAD method.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'name' required.

    *   No AUTOLOAD method.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'subject' required.

    *   No AUTOLOAD method.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'subject' required.

    *   No AUTOLOAD method.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'message' required.

    *   No AUTOLOAD method.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'message' required.

    *   No AUTOLOAD method.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Too many Bric::Biz::Person::User objects found.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'owner_id' required.

    *   No AUTOLOAD method.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'owner_id' required.

    *   No AUTOLOAD method.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Too many Bric::Util::EventType objects found.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'event_type_id' required.

    *   No AUTOLOAD method.

    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:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: WRITE access for field 'event_type_id' required.

    *   No AUTOLOAD method.

    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:

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Too many Bric::Biz::Person::User objects found.

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Too many Bric::Biz::Grp::User objects found.

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to execute SQL statement.

    *   Unable to select row.

    *   Incorrect number of args to _set.

    *   Bric::_set() - Problems setting fields.

    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:

    *   event - The Bric::Util::Event object for which the alerts are to be sent.

    *   attr - The attributes of the Bric::Util::Event object.

    *   obj - The Bricolage object for which the event was created.

    *   user - The Bric::Biz::Person::User object representing the person who triggered the alert.

    Throws:

    *   Bad AUTOLOAD method format.

    *   Cannot AUTOLOAD private methods.

    *   Access denied: READ access for field 'event_type_id' required.

    *   No AUTOLOAD method.

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to prepare SQL statement.

    *   Unable to connect to database.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    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:

    *   Bric::_get() - Problems retrieving fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to execute SQL statement.

    *   Incorrect number of args to _set.

    *   Bric::_set() - Problems setting fields.

    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