NAME

    pkg('Alert') -  interface to specify events to alert upon, 
                    schedule alerts, and mail out alerts.

SYNOPSIS

    use Krang::ClassLoader 'Alert';

    # add new alert scenario - user 1 will be notified with a custom message when story 14 is published
    my $alert = pkg('Alert')->new(  user_id => '1',
                                    action => 'publish',
                                    object_type => 'story',
                                    object_id => '13',
                                    custom_msg_subject => 'THIRTEEN HAS GONE LIVE!',
                                    custom_msg_body => 'Story 13 has gone live -- numerologically this does not bode well' );

    # add new alert scenario - user 1 will be notified when any new story is 
    # created in category 3 (or its descendants)
    my $alert = pkg('Alert')->new(  user_id => '1',
                                    action => 'new',
                                    category_id => '3' );

    # save the alert
    $alert->save;

    # add new alert scenario - user 1 will be notified when any story is
    # moved to desk 4
    my $alert2 = pkg('Alert')->new( user_id => '1',
                                    action => 'move',
                                    desk_id => '4' );

    # save the alert
    $alert2->save;

    # Let's pretend that category 5 is a decendant of category 3.
    # This find should return the $alert object from the above example. 
    my @found = pkg('Alert')->find( user_id => '1',
                                    action => 'new',
                                    category_id => '5' );

    # check to see if history event should trigger an alert
    # for specified object.  If a match is found, an alert 
    # will be scheduled to be mailed with Krang::Schedule
    # This is a convenience method that uses Krang::Alert->find() 
    # and Krang::Schedule->new()
    pkg('Alert')->check_alert(  history_object => $history_object,  
                                story_object => $story_object );
    
    # delete alert scenario
    $alert->delete();

DESCRIPTION

This class handles the storage of events to alert upon. It also checks Krang::History objects to see if an alert is matched. If so, an alert mailing ( Krang::Alert->send() ) will be scheduled in Krang::Schedule.

INTERFACE

METHODS

• new()
  
This adds a new scenario to alert upon.

Supports the following name-value pairs:

user_id
action - one of ( new save checkin checkout publish move )
object_type
object_id
category_id
desk_id
custom_msg_subject - text scalar: overrides the default email message subject (replacing any instance of $USER with the user who triggered the action)
custom_msg_body - text scalar: overrides the default email message template (populating the same TMPL_VARs used by Krang's default template)

• save()
  
Saves (inserts) alert scenario to the database, or updates scenario if already exists.
• find()
  
Find and return alert objects with parameters specified.

Supported keys:

alert_id
user_id
action
desk_id
category_id - An arrayref of category ids can be passed in. 'NULL' can also be used here.
parent_categories - if set true will return results in parent categories as well.
order_by - field to order search by, defaults to alert_id
order_desc - results will be in ascending order unless this is set to 1 (making them descending).
limit - limits result to number passed in here, else no limit.
offset - offset results by this number, else no offset.
count - return only a count if this is set to true.
ids_only - return only alert_ids, not objects if this is set true.

• check_alert()
  
Check to see if given criteria matches a set user alert.

This method takes two arguments, a Krang::History object and a Krang::Story or Krang::Media object.

• Krang::Alert->send( alert_id => $alert_id, user_id => $user_id, object_type => $object_type, object_id => $object_id )
  
Sends an alert to email address. Message sent is formatted by template at KrangRoot/templates/Alert/message.tmpl
• delete()
  
• Krang::Alert->delete( alert_id => $alert_id)
  
Deletes alert or alert with specified id.
• $alert->serialize_xml(writer => $writer, set => $set)
  
Serialize as XML. See Krang::DataSet for details.
• $alert = Krang::Alert->deserialize_xml(xml => $xml, set => $set, no_update => 0)
  
Deserialize XML. See Krang::DataSet for details.

If an incoming alert has the same fields as an existing alert then it is ignored (not duplicated).