Bric::Util::AlertType(User Contributed Perl DocumentaBric::Util::AlertType(3p)



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

VERSION
       $LastChangedRevision$

DATE
       $LastChangedDate: 2007-06-19 17:17:44 +0200 (Tue, 19 Jun 2007) $

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:

           o   event_type_id

           o   owner_id

           o   name

           o   subject

           o   message

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

           Throws:

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

           id  Alert type ID. May use "ANY" for a list of possible values.

           event_type_id
               Event type ID. May use "ANY" for a list of possible values.

           owner_id
               User id for user who owns alert types. May use "ANY" for a list
               of possible values.

           name
               Alert type name. May use "ANY" for a list of possible values.

           subject
               Alert type subject. May use "ANY" for a list of possible
               values.

           message
               Alert type message. May use "ANY" for a list of possible
               values.

           active
               Boolean value indicating whether or not an alert type is
               active.

           grp_id
               ID of a Bric::Util::Grp with which alert types may be
               associated. May use "ANY" for a list of possible values.

           Throws:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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@justatheory.com>.

           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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

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

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

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

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   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:

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

           o   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:

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

           o   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:

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

           o   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:

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

           o   Unable to select row.

           o   Incorrect number of args to _set.

           o   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:

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

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

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

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

           Throws:

           o   Bad AUTOLOAD method format.

           o   Cannot AUTOLOAD private methods.

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

           o   No AUTOLOAD method.

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to prepare SQL statement.

           o   Unable to connect to database.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   Unable to fetch row from statement handle.

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

           o   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:

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to execute SQL statement.

           o   Incorrect number of args to _set.

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

           Side Effects: NONE.

           Notes: NONE.

NOTES
       NONE.

AUTHOR
       David Wheeler <david@justatheory.com>

SEE ALSO
       Bric, Bric::Util::Alert, Bric::Util::EventType, Bric::Util::Event



perl v5.12.2                      2007-06-19         Bric::Util::AlertType(3p)
