View source for Sending email when item is made live or deposited

A common question is 'how do you send an email to a user when their item is made live'.

This guide should help you get things working. If you need more assistance, please ask on the [[Contact#eprints-tech_Mailing_List|EPrints tech list]].

Recent versions of EPrints support a [[Dataset_Manipulation,_Triggers_and_Events#Triggers|trigger]] that activates when an EPrint moves between states (inbox/buffer/archive/deletion - and any additional ones defined).
Older version of EPrints support a configuration function - an example of this is included at the end of this page.
To see if your version of EPrints supports the trigger, look in <code>~/perl_lib/EPrints/Const.pm</code> for a line like this: <code>EP_TRIGGER_STATUS_CHANGE => 103</code>

If you are unsure, use the older version - as it will be called by more recent versions anyway.

==Configuration file==
This should be added to a file in the archive-specific configuration e.g. <code>~/archives/ARCHIVEID/cfg/cfg.d/z_status_change.pl</code>
You can test for different status, and send different emails to different people based on what's going on.
You can also render additional data and pass it to the relevant phrase e.g. if you wanted to include a list of documents or a full citation.

<source lang="perl">
# 
# REMEMBER TO ADD THE XML PHRASE FILES TOO!
#

$c->add_dataset_trigger( "eprint", EP_TRIGGER_STATUS_CHANGE, sub{
    my( %o ) = @_;

    my $eprint = $o{dataobj};
    my $old_status = $o{old_status};
    my $new_status = $o{new_status};

    my $session = $eprint->get_session;

    my $user = $eprint->get_user();

    my $user_email = $user->get_value( "email" ); #when you are testing, set this to your email - so you don't spam people!

#   EXAMPLE of a deposit receipt
#   if( $old_status eq "inbox" && $new_status eq "buffer" ){
#       # send a deposit receipt?
#       # Do something similar to the stuff below - but with different phrases!
#   }

    if( $old_status eq "buffer" && $new_status eq "archive" ){
        # you might want to check what the datestamp is - and not send an email if this item has
        # been moved from archive -> buffer -> archive for some reason.

        my $title = $eprint->render_value( "title" );
        my $users_name = $user->render_value( "name" );
        my $url = $session->render_link( $eprint->get_url );
        $url->appendChild( $session->make_text( $eprint->get_url ) );

        my $mail = $session->make_element( "mail" );
        $mail->appendChild( $session->html_phrase( "status_change_buffer_to_archive_user_body",
            users_name => $users_name,
                 title => $title,
            eprint_url => $url
        ) );

        my $userMailOK = EPrints::Email::send_mail(
            session => $session,
            langid => $session->get_langid,
            to_email => $user_email,
            subject => $session->phrase( "status_change_buffer_to_archive_user_subject" ),
            message => $mail,
            sig => $session->html_phrase( "mail_sig" )
        );

        # you could check the value of $userMailOK - in case the email wasn't sent
    } # END of buffer-to-archive

});

</source>

==Phrase file==
This should be saved to e.g. <code>~/archives/ARCHIVEID/cfg/lang/en/phrases/z_status_change.xml</code>.
<source lang="xml">
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE phrases SYSTEM "entities.dtd">
<epp:phrases xmlns="http://www.w3.org/1999/xhtml" xmlns:epp="http://eprints.org/ep3/phrase" xmlns:epc="http://eprints.org/ep3/control">

  <epp:phrase id="status_change_buffer_to_archive_user_subject">Your item is now live</epp:phrase>
  <epp:phrase id="status_change_buffer_to_archive_user_body">
    <p>Dear <epc:pin name="users_name"/>,<br />
      Your item <em><epc:pin name="title"/></em> has been checked and is now available at the following URL:<br />
      <epc:pin name="eprint_url"/>.
    </p>
    <p>If you have any questions or issues with your thesis please contact <epc:print expr="$config{adminemail}" />.</p>
  </epp:phrase>

</epp:phrases>
</source>

==For versions that don't support the status change trigger==

<source lang="perl">
# 
# REMEMBER TO ADD THE XML PHRASE FILES TOO!
#
$c->{eprint_status_change} = sub
{
    my( $eprint, $old_status, $new_status ) = @_;

    my $session = $eprint->get_session;
    my $user = $eprint->get_user();

    my $user_email = $user->get_value( "email" ); #when you are testing, set this to your email - so you don't spam people!

#   EXAMPLE of a deposit receipt
#   if( $old_status eq "inbox" && $new_status eq "buffer" ){
#       # send a deposit receipt?
#       # Do something similar to the stuff below - but with different phrases!
#   }

    if( $old_status eq "buffer" && $new_status eq "archive" ){
        # you might want to check what the datestamp is - and not send an email if this item has
        # been moved from archive -> buffer -> archive for some reason.

        my $title = $eprint->render_value( "title" );
        my $users_name = $user->render_value( "name" );
        my $url = $session->render_link( $eprint->get_url );
        $url->appendChild( $session->make_text( $eprint->get_url ) );

        my $mail = $session->make_element( "mail" );
        $mail->appendChild( $session->html_phrase( "status_change_buffer_to_archive_user_body",
            users_name => $users_name,
                 title => $title,
            eprint_url => $url
        ) );

        my $userMailOK = EPrints::Email::send_mail(
            session => $session,
            langid => $session->get_langid,
            to_email => $user_email,
            subject => $session->phrase( "status_change_buffer_to_archive_user_subject" ),
            message => $mail,
            sig => $session->html_phrase( "mail_sig" )
        );

        # you could check the value of $userMailOK - in case the email wasn't sent
    }

};
</source>