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).