View source for RequestEprint

== The Story ==

A new feature built into EPrints software could dramatically increase the rate of growth of open access (OA) content deposited in institutional repositories while, perversely it seems, allowing authors to opt out of providing OA. It's extremely simple, and if implemented carefully by the repository can produce immediate results without additional cost or resource implications.

http://www.eprints.org/news/features/request_button.php

== Overview ==

This feature displays a "Request eprint" button on the abstract page of records with:

a) one or more restricted documents
b) no documents

By clicking the button, users can submit their email address to EPrints. This generates an email to the author (or other recipient determined by EPrints - see below) requesting the restricted/missing items.

In the case of restricted documents, the email will contain 2 links:

* Accept request (and optionally make the record Open Access from now on) - EPrints will email the documents to the requester
* Reject request - EPrints will email the requester a rejection notice (the content of which can be edited)

At no point is the email address of the author (or other recipient) exposed without their consent.

== Adding Request Eprint to your repository (2.3.13) ==

This feature is part of EPrints 3. If you have an older repository, add the feature to existing releases by following these steps:

=== "Contact Email" field (optional) ===

To enable depositors to enter a contact email address directly.

Add an extra field to the eprint dataset in <tt>/opt/eprints2/archives/ARCHIVEID/cfg/ArchiveMetadataFieldsConfig.pm</tt>:

 { name => "contact_email", type => "email" },

Add a corresponding field to the database - see http://wiki.eprints.org/w/EPrints2/AddingLiveFields

Add the <tt>contact_email</tt> field to eprint types in <tt>/opt/eprints2/archives/ARCHIVEID/cfg/metadata-types.xml</tt>.

Add the following to the <tt>/opt/eprints2/archives/ARCHIVEID/cfg/phrases-en.xml</tt> or similar for whatever languages you support:

    <ep:phrase ref="eprint_fieldname_contact_email">Contact EMail</ep:phrase>
    <ep:phrase ref="eprint_fieldhelp_contact_email">Please enter your email address
      &lt;br /&gt;Example: &lt;span class="example"&gt;e.prints@soton.ac.uk&lt;/span&gt;
    </ep:phrase>

=== Determine recipient of requests ===

Add an extra method to <tt>/opt/eprints2/archives/ARCHIVEID/cfg/ArchiveConfig.pm</tt>:

 sub email_for_doc_request {
        my ( $session, $eprint ) = @_;
        # To turn off this feature, uncomment the line below
        #return undef;
        if( $eprint->is_set("contact_email") )
        {
                return $eprint->get_value("contact_email");
        }
        my $user = $eprint->get_user;
        if( $user->is_set("email") )
        {
                return $user->get_value("email");
        }
        return $session->get_repository->get_conf("adminemail");
 }

This is how EPrints will determine who to send the request to. The method first checks the contact email field. If this is not set then it looks for the email address of the depositing user. Finally, it falls back to the archive administrator's email.

If you are using the "id" part of the the creators field for email addresses then you could also check there:

 if( $eprint->is_set( "creators" ) )
 {
        for( @{ $eprint->get_value( "creators" ) } )
        {
                return $_->{id} if $_->{id} ne "";
        }
 }

'''Think carefully about how you configure this method'''

During trials on the [http://eprints.soton.ac.uk/ University of Southampton Research Repository], this feature generated up to 50 requests '''per day'''. You probably don't want all of these requests to end up in the archive administrators inbox!

=== Install MIME::Lite ===

The MIME::Lite module is used by the request document scripts for sending email with attachments.

 root> perl -MCPAN -e 'install MIME::Lite'

=== Install scripts and phrases ===

http://files.eprints.org/10/

 cp request_doc /opt/eprints2/cgi/
 cp respond_doc /opt/eprints2/cgi/users/

Insert the phrases into <tt>/opt/eprints2/archives/ARCHIVEID/cfg/phrases-en.xml</tt>

=== Add button rendering ===

Add the Request eprint button rendering to the <tt>eprint_render</tt> method in <tt>/opt/eprints2/archives/ARCHIVEID/ArchiveRenderConfig.pm</tt>:

        # Request eprint
        if( $eprint->is_set( "full_text_status" ) )
        {
                my $status = $eprint->get_value( "full_text_status" );
                if( $status ne "public" )
                {
                        if( $session->get_archive->can_call( "email_for_doc_request" ) )
                        {
                                if( defined( $session->get_archive->call( "email_for_doc_request", $session, $eprint ) ) )
                                {
                                        # only render if there is a contact email address
                                        my $form = $session->render_form( "post", $session->get_archive->get_conf( "perl_url" ) . "/request_doc" );
                                        $form->appendChild( $session->render_hidden_field( "eprintid", $eprint->get_id ) );
                                        $form->appendChild( $session->render_action_buttons(
                                                "submit" => $session->phrase( "request:button" )
                                        ) );
                                        $page->appendChild( $form );
                                }
                        }
                }
        }

Note: the can_call function in <tt>/opt/eprints2/perl_lib/EPrints/Archive.pm</tt> was only introduced in ePrints 2.3.13 those using older versions of ePrints can simply download the newer ePrints, find the function can_call in the <tt>Archive.pm</tt> and copy it into their own Archive.pm or you could of course upgrade.
 
Restart apache and run <tt>generate_abstracts</tt> to make the button appear on existing abstract pages.

'''The button will only be rendered if the item is not Open Acess AND a contact email can be determined'''

== Enhancements to RequestEprint in 3.3.? ==

Requester doen't have an Eprints account? Can access restricted document by URL with PIN.

== Enhancements to RequestEprint in 3.3.15 ==

Contact emails belong to non eprint user? Non users can accept or reject requests with URLs+PIN

Details: https://github.com/eprints/eprints/pull/262



[[Category:Howto]]
[[Category:Rubbish]]