EPrints Documentation - User contributions [en-gb]

Transitioning from IRUS to OpenAIRE Usage Counts

2026-04-10T14:16:48Z

Libjlrs:

# Register your repository in the [https://provide.openaire.eu/home OpenAIRE Provide service]
# Install EPrintsOpenAIRE https://github.com/eprintsug/EprintsOpenAIRE<br>- A new version (v1.1.0) is being tested as both an [https://github.com/eprintsug/EPrintsOpenAIRE/tree/support_config_option ingredient] and a [https://github.com/eprintsug/EPrintsOpenAIRE/tree/support_config_option-epm Bazaar/EPM package].
# Make sure repository is getting harvested in OpenAIRE Provide
# Install tracker NB we need to consolidate these (which are in approx. chronological order):
## https://github.com/Rudjer-Boskovic-Institute/EPrints-OAPiwik
## https://github.com/openaire/EPrints-OAPiwik (forked from the above)
## https://github.com/alex-ball/EPrints-OAPing
## https://github.com/eprints/EPrints-OAPiwik ''I think this is where the official release will live?''
# Check data is being received - OpenAIRE is only updated monthly
# remove/disable IRUS tracker

== Instructions for sending historic data ==
See notes in Eprints-OAPiwik?

== Useful links ==
# [https://www.openaire.eu/?view=article&id=2343&catid=255 UsageCounts – How to track the usage activity of your repository]
# [https://usagecounts.openaire.eu/resources#apis OpenAIRE - Provide - APIs and reports (COUNTER v4 compliant!?)]

Transitioning from IRUS to OpenAIRE Usage Counts

2026-04-10T14:15:54Z

Libjlrs:

# Register your repository in the [https://provide.openaire.eu/home OpenAIRE Provide service]
# Install EPrintsOpenAIRE https://github.com/eprintsug/EprintsOpenAIRE
<br>
A new version (v1.1.0) is being tested as both an [https://github.com/eprintsug/EPrintsOpenAIRE/tree/support_config_option ingredient] and a [https://github.com/eprintsug/EPrintsOpenAIRE/tree/support_config_option-epm Bazaar/EPM package].
# Make sure repository is getting harvested in OpenAIRE Provide
# Install tracker NB we need to consolidate these (which are in approx. chronological order):
## https://github.com/Rudjer-Boskovic-Institute/EPrints-OAPiwik
## https://github.com/openaire/EPrints-OAPiwik (forked from the above)
## https://github.com/alex-ball/EPrints-OAPing
## https://github.com/eprints/EPrints-OAPiwik ''I think this is where the official release will live?''
# Check data is being received - OpenAIRE is only updated monthly
# remove/disable IRUS tracker

== Instructions for sending historic data ==
See notes in Eprints-OAPiwik?

== Useful links ==
# [https://www.openaire.eu/?view=article&id=2343&catid=255 UsageCounts – How to track the usage activity of your repository]
# [https://usagecounts.openaire.eu/resources#apis OpenAIRE - Provide - APIs and reports (COUNTER v4 compliant!?)]

Transitioning from IRUS to OpenAIRE Usage Counts

2026-04-10T14:14:41Z

Libjlrs:

# Register your repository in the [https://provide.openaire.eu/home OpenAIRE Provide service]
# Install EPrintsOpenAIRE https://github.com/eprintsug/EprintsOpenAIRE
## A new version (v1.1.0) is being tested as both an [https://github.com/eprintsug/EPrintsOpenAIRE/tree/support_config_option ingredient] and a [https://github.com/eprintsug/EPrintsOpenAIRE/tree/support_config_option-epm Bazaar/EPM package].
# Make sure repository is getting harvested in OpenAIRE Provide
# Install tracker NB we need to consolidate these (which are in approx. chronological order):
## https://github.com/Rudjer-Boskovic-Institute/EPrints-OAPiwik
## https://github.com/openaire/EPrints-OAPiwik (forked from the above)
## https://github.com/alex-ball/EPrints-OAPing
## https://github.com/eprints/EPrints-OAPiwik ''I think this is where the official release will live?''
# Check data is being received - OpenAIRE is only updated monthly
# remove/disable IRUS tracker

== Instructions for sending historic data ==
See notes in Eprints-OAPiwik?

== Useful links ==
# [https://www.openaire.eu/?view=article&id=2343&catid=255 UsageCounts – How to track the usage activity of your repository]
# [https://usagecounts.openaire.eu/resources#apis OpenAIRE - Provide - APIs and reports (COUNTER v4 compliant!?)]

Transitioning from IRUS to OpenAIRE Usage Counts

2026-03-19T08:34:37Z

Libjlrs:

# Register in OpenAIRE [link]
# Install EPrintsOpenAIRE https://github.com/eprintsug/EprintsOpenAIRE
# Make sure repository is getting harvested https://provide.openaire.eu/
# Install tracker NB we need to consolidate these (which are in approx. chronological order):
## https://github.com/Rudjer-Boskovic-Institute/EPrints-OAPiwik
## https://github.com/openaire/EPrints-OAPiwik (forked from the above)
## https://github.com/alex-ball/EPrints-OAPing
## https://github.com/eprints/EPrints-OAPiwik
# Check data is being received
# remove/disable IRUS tracker

== Useful links ==
# [https://www.openaire.eu/?view=article&id=2343&catid=255 UsageCounts – How to track the usage activity of your repository]
# [https://usagecounts.openaire.eu/resources#apis OpenAIRE - Provide - APIs and reports (COUNTER v4 compliant!?)]

Transitioning from IRUS to OpenAIRE Usage Counts

2026-03-05T16:23:43Z

Libjlrs:

Transitioning from IRUS to OpenAIRE Usage Counts

2026-03-04T12:26:43Z

Libjlrs: Created page with " # Register in OpenAIRE [link] # Install EPrintsOpenAIRE https://github.com/eprintsug/EprintsOpenAIRE # Make sure repository is getting harvested https://provide.openaire.eu/..."

Altmetric badges

2025-11-06T15:03:08Z

Libjlrs:

The Altmetric plugin for EPrints is available from the [https://bazaar.eprints.org/1300/ Bazaar] or [https://github.com/eprintsug/altmetric/ GitHub] (see the '3_4' branch for the 'ingredient' version).

== Changes (November 2025) - API key now mandatory ==
Before v2.0.0 the Altmetric plugin used the Altmetric API to get data. In v2.0.0+ this has been updated to use the API if an API key is defined, and fall back to
the Altmetric 'embed' script to display the badges.

Please see the README at https://github.com/eprintsug/altmetric/ for full details.

You can also embed the badges without this plugin - see instructions here: [https://badge-docs.altmetric.com/index.html], although the plugin assists in finding relevant identifiers within a record to display.

Altmetric badges

2025-10-21T14:56:56Z

Libjlrs: Created page with "The Altmetric plugin for EPrints is available from the [https://bazaar.eprints.org/555/ Bazaar] or [https://github.com/eprintsug/altmetric/ GitHub]. The Altmetric badges can..."

The Altmetric plugin for EPrints is available from the [https://bazaar.eprints.org/555/ Bazaar] or [https://github.com/eprintsug/altmetric/ GitHub].

The Altmetric badges can also be added to pages by following the instructions here: [https://badge-docs.altmetric.com/index.html]

== Changes (November 2025) - API key now mandatory ==
The Altmetric plugin uses the Altmetric API to get data. If you are using this to display Altmetric badges, please check to see if you have an API key defined.
This should be in <code>EPRINTS_ROOT/archives/ARCHIVEID/cfg/cfg.d/z_altmetric.pl</code>, although may have been defined in another config file.

From: https://github.com/eprintsug/altmetric/blob/main/cfg/cfg.d/z_altmetric.pl#L20-L21

<source lang=perl>
# Optional API key - see http://api.altmetric.com/index.html#keys
# $c->{altmetric}->{api_key} = "";
</source>

An upcoming update to the plugin will start requiring this to be set before rendering a badge on a page.

The future of this integration may be a deprecation of the 'API' route, and support a configurable embedded badge instead.

Shibboleth

2025-08-07T15:33:53Z

Libjlrs: /* Using Remote IdP Metatdata */

{{Manual}}
'''This page details how to install and integrate Shibboleth with EPrints 3.3.x or 3.4.x on a CentOS 7 operating system.''' The process should be fairly similar for other comparable Red Hat based Linux distributions such as RHEL 7 and Fedora 21/22. These instructions should also be generally applicable to later versions of RHEL-based Linux (e.g. Rocky Linux 8, Red Hat Enterprise Linux 9, etc.). However, they may be somewhat different for Debian-based Linux, such as Ubuntu and Debian itself and other Linux distributions. Typically, this will just be different package names and different commands to manage applications.

Generally, it is a good idea to run EPrints with '''HTTPS''' when using Shibboleth authentication for increased security on the attributes being sent back by the Shibboleth Identity Provider (IdP). Therefore, it is assumed that EPrints has already been set up to use HTTPS and there already exists an '''ssl/securevhost.conf''' under the archive directory structure.

== Installing Shibboleth ==
* First, add the Shibboleth repository to your list of YUM repositories (if you need this for a different RHEL-based Linux distribution fill in the form at https://shibboleth.net/downloads/service-provider/latest/RPMS/):
root> wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7

* Now you can use Yum to install all package dependencies:
root> yum install log4shib opensaml shibboleth unixODBC xerces-c xml-security-c xmltooling

* You may be prompted to accept the importing of the key for the Shibboleth repository, for which you should type '''y''' and press enter.

* Once you have done that, test that '''shibd''' has no issues:
root> LD_LIBRARY_PATH=/opt/shibboleth/lib64 shibd -t

* ''shibd -t'' should return a couple of warning, like those listed below. These are due to it not yet being configured.
2015-05-11 10:39:01 WARN Shibboleth.Application : insecure cookieProps setting, set to "https" for SSL/TLS-only usage
2015-05-11 10:39:01 WARN Shibboleth.Application : handlerSSL should be enabled for SSL/TLS-enabled web sites
2015-05-11 10:39:01 WARN Shibboleth.Application : no MetadataProvider available, configure at least one for standard SSO usage
overall configuration is loadable, check console for non-fatal problems

* If there are no other warning or error messages from ''shibd -t'', you can start it properly and check to make sure it is running. You may also want ensure Shibboleth starts at boot using '''systemctl enable'''
root> systemctl start shibd.service
root> ps aux | grep shib
shibd 29338 0.4 0.7 419784 15024 ? Ssl 11:16 0:00 /usr/sbin/shibd -p /var/run/shibboleth/shibd.pid -f -w 30
root 29345 0.0 0.0 112640 940 pts/2 S+ 11:17 0:00 grep --color=auto -i shib
root> systemctl enable shibd.service

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following. Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml''). '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if you have installed a recent version of Shibboleth from a package repository. [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

<SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
clockSkew="180">

<ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
REMOTE_USER="eppn subject-id pairwise-id persistent-id"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">

<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
<Logout>SAML2 Local</Logout>
<LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
<Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
<Handler type="Session" Location="/Session" showAttributeValues="false"/>
<Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
</Sessions>

<Errors supportContact="root@localhost" helpLocation="/about.html" styleSheet="/shibboleth/main.css"/>
<MetadataProvider type="XML" path="foo/idp-metadata.xml"/>
<AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
<AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
<CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
<CredentialResolver type="File" use="encryption" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>

</ApplicationDefaults>

<SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
<ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>

</SPConfig>

* Create the directory '''/etc/shibboleth/foo''', substituting ''foo'' for your repository name.
root> mkdir /etc/shibboleth/foo

* Copy '''attribute-map.xml''' into this new directory.
cp /etc/shibboleth/attribute-map.xml /etc/shibboleth/foo/

* Temporarily rename '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/''' to '''sp-cert.pem.old''' and '''sp-key.pem.old'''.
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-cert.pem.old
root> mv sp-key.pem sp-key.pem.old

* Run '''keygen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname.
root> cd /etc/shibboleth
root> ./keygen.sh -f -h foo.eprints.org -e https://foo.eprints.org/shibboleth

* Move the new '''sp-cert.pem''' and '''sp-key.pem''' to '''/etc/shibboleth/foo/''' and move the ''.old'' files back in place:
root> cd /etc/shibboleth
root> mv sp-cert.pem sp-key.pem foo/
root> mv sp-cert.pem.old sp-cert.pem
root> mv sp-key.pem.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''shibd'''.
root> ls -l /etc/shibboleth/foo/sp-*
-rw-r--r-- 1 shibd shibd 1192 May 6 19:04 /etc/shibboleth/foo/sp-cert.pem
-rw------- 1 shibd shibd 1708 May 6 19:04 /etc/shibboleth/foo/sp-key.pem

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname. You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
root> cd /etc/shibboleth
root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp_metadata.xml

* Modify ''' foo/sp_metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
<md:EntityDescriptor entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo>
to:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://foo.eprints.org/shibboleth">
...
...
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* Use ''wget'' to download the metadata from your Shibboleth IdP (e.g. shib.foo.example.org) to the '''/etc/shibboleth/foo/''' directory.
root> wget -O /etc/shibboleth/foo/idp-metadata.xml https://shib.foo.example.org/idp/shibboleth

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy. This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following. The reloadInterval is best set to 7200 but this can be set less frequently:

<MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading. If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default. However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

chown shibd:shibd /etc/shibboleth/foo/
chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''.

LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t
This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily. However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider. Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

systemctl restart shibd

== Configuring Apache and EPrints ==
'''N.B. All these actions should be carried out by the ''eprints'' user, except when prepended with ''root>'' which means the command should be run as the ''root'' user.'''
* Add the following configuration to your archive's '''ssl/securevhost.conf''', after the '''Include /opt/eprints3/cfg/apache_ssl/foo.conf''', substituting '''foo''' for your archive's name where appropriate. (This assumes you are running Apache 2.4 or greater). See [[#Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration |Troubleshooting]] for instructions on the configuration to use for Apache 2.2. or lower.

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Location "/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequestSetting requireSession 1
require shib-session
</Location>

* Copy the following code into your archive (e.g. /opt/eprints3/archives/foo/) as '''cgi/shibboleth'''.
use EPrints;
use strict;
my $session = new EPrints::Session;
exit( 0 ) unless( defined $session );

$session->send_http_header( "content_type" => "text/html" );

print "<html><head/><body><code>\n";

foreach my $key (sort keys(%ENV)) {
print "<p>$key = $ENV{$key}</p>";
}

print "</code></body></html>";
$session->terminate;
exit;

* Now restart Shibboleth and Apache:
root> systemctl restart shibd.service
root> apachectl restart

* In a web browser go the '''/cgi/shibboleth''' page for your repository, (e.g. ''https://foo.eprints.org/cgi/shibboleth''). You should be redirected to an error page for your your Shibboleth IdP (e.g. ''https://shib.foo.example.org/idp/profile/SAML2/Redirect/SSO?...'').

* If instead you are displayed with a list of key values or are forbidden to access the page, you have not configured Apache properly, if so, see [[#Apache_Configuration_Issues|Apache_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]]. If you see an error message like the one below, you have not set up Shibboleth properly, if so, see [[#Shibboleth_Configuration_Issues|Shibboleth_Configuration_Issues]] under [[#Troubleshooting|Troubleshooting]].
opensaml::saml2md::MetadataException
The system encountered an error at Wed May 6 15:19:27 2015
To report this problem, please contact the site administrator at root@localhost.
Please include the following message in any email:
opensaml::saml2md::MetadataException at (http://foo.eprints.org/cgi/shibboleth)
Unable to locate metadata for identity provider (https://shib.foo.example.org/idp/shibboleth)

* Next, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''cfg/cfg.d/zz_shibboleth.pl'''. This is needed to redirect login and logout to use Shibboleth rather than local login.
$c->{get_login_url} = sub {
my( $session, $target ) = @_;

# preserve CGI params
$session->read_params;
$target = $session->get_url(
host => 1,
path => "auto",
query => 1,
);

my $url = URI->new( $session->config( "https_url" ) . "/shibboleth/login" );
$url->query_form( target => "$target" );
return "$url";
};

$c->{on_logout} = sub {
my( $session ) = @_;
my $query = $session->query;
return unless defined $query;

# remove _shibsession_ cookie
my( $shibname, $shibvalue );
for( $query->cookie() ) {
if( $_ =~ /^_shibsession/ ) {
$shibname = $_;
$shibvalue = $query->cookie( $shibname );
}
}

my $cookie = $query->cookie(
-name => $shibname,
-path => "/",
-value => "",
-host => $session->config("cookie_domain"),
-expires => "-1d",
);
EPrints::Apache::AnApache::header_out(
$session->{request},
"Set-Cookie" => $cookie
);
};

push @{$c->{rewrite_exceptions}}, "/shibboleth/";

* Create a folder at the top level of your archive (e.g. ''/opt/eprints3/archives/foo/'') called '''shibboleth''' and copy the main CSS file for Shibboleth into this folder:
eprints> mkdir /opt/eprints3/archives/foo/shibboleth/
eprints> cp /usr/share/shibboleth/main.css /opt/eprints3/archives/foo/shibboleth/

* Now, copy the following code into your archive (e.g. ''/opt/eprints3/archives/foo/'') as '''shibboleth/login'''. This is the most basic login script that should work with the minimal attributes any Shibboleth IdP returns and '''only logging in users with existing accounts'''. Look under the [[#Customisation|Customisation]] section for advice on how to modify this script to meet your requirements, such as creation user accounts on-the-fly.
use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ( $username, $email ) = ( undef, "" );
if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
$email = $ENV{eppn};
}
return unless EPrints::Utils::is_set( $username );
my $user = $session->user_by_username( $username );
if( defined $user && defined $email )
{
$user->set_value( "email", $email );
$user->commit;
}
return $user;
}

* Next, add the following markup to '''cfg/lang/en/static/account_required.xpage''' under your archive (e.g. ''/opt/eprints3/archives/foo/''). Substituting ''staff and students of the University of Foo'' to describe to which particular group of people logged in access is restricted.

<?xml version="1.0" standalone="no" ?>
<!DOCTYPE page SYSTEM "entities.dtd" >
<xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
<xpage:title>Login Failed</xpage:title>
<xpage:body>
<p style='text-align: center;'>Please note that only staff and students of the University of Foo may log in to <epc:phrase ref="archive_name" /></p>
</xpage:body>
</xpage:page>

* Now, reload Apache.
root> apachectl reload

* In a web browser go to the '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login''). Like before with ''/cgi/shibboleth'' you should be taken to your Shibboleth IdP's site albeit displaying an error message.

* The Shibboleth IdP shows an error message because EPrints as a Shibboleth Service Provider is not yet registered with it. To do this you need to send the administrator of the Shibboleth IdP the metadata for your Service Provider. You will have generated this earlier when you ran <code>metagen.sh</code>. Copy off your EPrints server the file that this wrote (e.g. to <tt>/etc/shibboleth/foo/sp_metadata.xml</tt>) and send it to the Shibboleth IdP administrator. They should be able to upload this to register EPrints as a Service Provider application.

* Once registered, use a web browser to go to '''/shibboleth/login''' page for your repository, (e.g. ''https://foo.eprints.org/shibboleth/login'') again. This time you should be prompted for a username and password on the Shibboleth IdP site. Once you have typed this in and clicked to login, you should be returned to EPrints on the '''/cgi/users/home''' page for your repository. If not, see [[#Login_Issues|Login Issues]] under [[#Troubleshooting|Troubleshooting]] below.

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
<Directory "/opt/eprints3/archives/foo/shibboleth">
SetHandler perl-script
PerlHandler ModPerl::Registry
PerlSendHeader Off
Options ExecCGI FollowSymLinks

AuthType shibboleth
ShibRequireSession On
require valid-user
</Directory>

<Location /cgi/shibboleth>
AuthType shibboleth
ShibRequireSession On
require valid-user
</Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml. In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account. However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''. In some cases you may still see an line like this in the log even if you think you have defined the attribute. The line below demonstrate two known issues:

2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name: givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just ''''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped. As well as define the name of the attribute without a namespace:

<Attribute name="givenName" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string. Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case.

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn'''). Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP. For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''. Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

<md:Extensions>
<shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
</md:Extensions>

=== Login Issues ===
To be added.

== Customisation ==

=== Shibboleth /etc/shibboleth/foo/attribute-map.xml config ===
This is adapted from the default '''attribute-map.xml''' provided when the Shibboleth SP package is installed to only include the attribute subsequently used by EPrints Shibboleth Perl script that can be found below. Namely:

{| border="1" cellpadding="10" cellspacing="0"
!Field name
!Field description
!SAML v1.1 attribute URN
!SAMLv2 attribute URN
|-
|eppn
|Edu Person Principal Name
|urn:mace:dir:attribute-def:eduPersonPrincipalName
|urn:oid:1.3.6.1.4.1.5923.1.1.1.6
|-
|sn
|Surname
|urn:mace:dir:attribute-def:sn
|urn:oid:2.5.4.4
|-
|givenName
|Given (first) name(s)
|urn:mace:dir:attribute-def:givenName
|urn:oid:2.5.4.42
|-
|mail
|Email address
|urn:mace:dir:attribute-def:mail
|urn:oid:0.9.2342.19200300.100.1.3
|-
|}

You may wish to refer to the default '''attribute-map.xml''' is you want to use other attributes.

<Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<Attribute name="urn:mace:dir:attribute-def:eduPersonPrincipalName" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>
<Attribute name="urn:oid:1.3.6.1.4.1.5923.1.1.1.6" id="eppn">
<AttributeDecoder xsi:type="ScopedAttributeDecoder"/>
</Attribute>

<Attribute name="urn:mace:dir:attribute-def:sn" id="sn"/>
<Attribute name="urn:mace:dir:attribute-def:givenName" id="givenName"/>
<Attribute name="urn:mace:dir:attribute-def:mail" id="mail"/>

<Attribute name="urn:oid:2.5.4.4" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="sn"/>
<Attribute name="urn:oid:2.5.4.42" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="givenName"/>
<Attribute name="urn:oid:0.9.2342.19200300.100.1.3" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" id="mail"/>

</Attributes>

=== EPrints /shibboleth/login script with user account creation ===
This is the standard EPrints Shibboleth login script. It makes a number of assumptions:
# That accounts should be created if they do not already exist for a particular user.
# That you wish to create a standard user account (not an editor administrator) account.
# That the Shibboleth IdP provides all the attributes (eduPersonPrinicpalName (seen as eppn), sn, givenName and mail) required.

use EPrints;
use strict;

my $session = EPrints::Session->new();
my $url = $session->param( "target" );
if ( defined $url )
{
my $target_uri = URI->new( $url );
my $repository_uri = URI->new( $session->get_repository->get_conf( 'base_url' ) );
if ( !$target_uri->can( 'host' ) || $target_uri->host ne $repository_uri->host )
{
$url = undef;
}
}
$url = $session->get_repository->get_conf( "userhome" ) unless EPrints::Utils::is_set( $url );

my $user = &get_user;

if( defined $user )
{
$user->set_value( "last_login", EPrints::Time::get_iso_timestamp() );
$user->commit;

EPrints::DataObj::LoginTicket->expire_all( $session );
$session->dataset( "loginticket" )->create_dataobj({
userid => $user->id,
})->set_cookies();
}
else
{
$url = $session->get_repository->get_conf( "base_url" ) . "/account_required.html";
}

$session->send_http_header( "content-type" => "text/html" );
print '<html><head><meta http-equiv="refresh" content="0;url='.$url.'"/></head><body></body></html>';
$session->terminate;

sub get_user
{
my ($username, $given, $family, $email) = (undef, "", "", "");

if( $ENV{eppn} )
{
( $username ) = split( /@/, $ENV{eppn}, 2);
$username = lc( $username );
}
$email = $ENV{mail} if $ENV{mail};
if( $ENV{givenName} )
{
$given = lc( $ENV{givenName} );
$given =~ s/^(.)/uc($1)/e;
$given =~ s/([- ].)/uc($1)/e;
}
if( $ENV{sn} )
{
$family = lc( $ENV{sn} );
$family =~ s/^(.)/uc($1)/e;
$family =~ s/([- ].)/uc($1)/e;
}

return unless EPrints::Utils::is_set( $username );

my $user = $session->user_by_username( $username ); # relying on this to be case insensitive

if( !defined $user )
{
my $usertype = 'user';
$user = EPrints::DataObj::User::create( $session, $usertype );
$user->set_value( "username", $username );
}
my $name = {
given => $given,
family => $family,
};
$user->set_value( "name", $name );
$user->set_value( "email", $email );
$user->commit;
return $user;
}

== Further Information ==
* Older instructions of how to set up EPrints for Shibboleth using UK Access management Federation discovery service is available [[Shibboleth authentication|here]].

* For general information about installing and configuring Shibboleth [http://shibboleth.internet2.edu/ click here].

* [https://docs.openathens.net/display/public/TPA/Sign+in+to+a+generic+application+using+OpenAthens#SignintoagenericapplicationusingOpenAthens-SetupthecustomSAMLresourceinOpenAthens Instructions of connection a Shibboleth Service Provider with OpenAthens]

[[Category:Authentication]]

EPrints Control Format

2025-08-05T09:23:25Z

Libjlrs: /* epc:list (3.3.17+ and 3.4.2+) */

{{formats}}

= EPrints Control =

== Output Tags ==

=== epc:print ===

<epc:print expr='expression' opt='key=value;key2=value2'/>
<source lang="xml">
<cite:citation xmlns="http://www.w3.org/1999/xhtml"
xmlns:cite="http://eprints.org/ep3/citation"
xmlns:epc="http://eprints.org/ep3/control">
<epc:print expr="$item.citation('default')" />
</cite:citation>
</source>
Outputs the result of the expression in the 'expr' attribute.

Rendering options may be passed in the opt attribute using a key=value form, with semicolons separating multiple options.

Any [[EPScript]] expression can be used. The most simple is just 'eprintid','title','creators' etc. You can also use values from the configuration files by using '$config{base_url}'.

=== Print in attributes using {} ===

Sometimes you may wish to insert a value into an XML attribute. eg. the "href" part of an anchor. Rather than a complicated system, but correct XML, we decide to go for something a bit more readable. Any {} pair in an XML attribute will be treated as a epc:print.

So you can do something like
<source lang="xml">
<a href="http://eprints.badger.edu/cgi/myscript.pl?eprintid={eprintid}">run myscript on this eprint</a>
</source>

=== epc:phrase ===

simple:
<source lang="xml">
<epc:phrase ref='phraseid' />
</source>
with pins:
<source lang="xml">
<epc:phrase ref='phraseid'>
<epc:param name='somepin'>Content</epc:param>
</epc:phrase>
</source>
Outputs the content of the phrase refered to by 'ref'. Any necessary parameters may be set using the <epc:param> tag, with the contents inserted into the pin with the name corresponding to the name attribute.

== Conditional Tags ==

=== epc:if ===
<source lang="xml">
<epc:if test='expr'>
...
</epc:if>
</source>
Outputs any XHTML content and evaluates any EPrints Control structures within the epc:if block if the expression in the test attribute is true.

=== epc:choose, epc:when, epc:otherwise ===
<source lang="xml">
<epc:choose>
<epc:when test='expr'>
...
</epc:when>
<epc:when test='expr2'>
...
</epc:when>
<epc:otherwise>
...
</epc:otherwise>
</epc:choose>
</source>
epc:choose allows for the construction of a complex conditional. Each epc:when block's 'test' attribute is evaluated, and the content of the block is returned if the result is true. If no expressions return true, the optional epc:otherwise block is returned. Note that no subsequent epc:when blocks are evaluated once the first block to return true is reached.

=== epc:comment ===
XML comments are not removed from the output when they are encountered in a citation or other EPScript.
<source lang="xml">
<epc:if test="blah">

<epc:print expr="blah" />
</epc:if>
</source>
will result in the comment appearing in the html source:
<source lang="xml">

This is Blah
</source>
Using an epc:comment block allows you to include comments that aren't rendered in the output:
<source lang="xml">
<epc:if test="blah">
<epc:comment> only print blah if it exists </epc:comment>
<epc:print expr="blah" />
</epc:if>
</source>

== Loops ==

Multiple values can be iterated over. For example.
<source lang="xml">
<epc:foreach expr="creators_name" iterator="name">
( <epc:print expr="$name" /> )
</epc:foreach>
</source>
=== $index (3.2.0+) ===

Within a foreach block you can use $index to find what iteration of the loop is on. The first value is zero.

This can be used with the modulus "%" to add a strip effect, if wanted, eg.

<source lang="xml">
<table>
<epc:foreach expr="creators_name" iterator="name">
<epc:if test="$index % 2">
<tr class='odd'><td><epc:print expr="$name" /></td></tr>
</epc:if>
<epc:if test="!($index % 2)">
<tr class='even'><td><epc:print expr="$name" /></td></tr>
</epc:if>
</epc:foreach>
</table>
</source>

=== limit (3.2.0+) ===

You can set a limit of how many iterations to process using a "limit" attribute on the epc:foreach element. For example,
<source lang="xml">
<epc:foreach expr="creators_name" iterator="name" limit="3">
</source>
== epc:debug (3.2.0+) ==

The epc:debug element has identical syntax to epc:print, but the result is sent to the error log -- either the command line, or to the apache error log.
<source lang="xml">
<epc:debug expr='expression' opt='key=value;key2=value2'/>
</source>

== epc:set (3.2.0+) ==

This allows a variable to be set for any print or if elements within the epc:set. This is useful if creating the value has a notable cost which you wish to minimise.

$item.documents() requires some database access, and the results are not cached, so using this speeds things up.
<source lang="xml">
<epc:set name='docs' expr='$item.documents()'>
</source>

== epc:list (3.3.17+ and 3.4.2+) ==
Allows multiple variables to be printed out with a common separator, where separator is not added if any variables are not set. Also allows a prefix and suffix to the list. E.g.

<epc:list prefix='[ ' suffix=' ]' join=" | ">
<epc:item>First</epc:item>
<epc:item> </epc:item>
<epc:item>Third</epc:item>
<epc:item><epc:print expr="title"/></epc:item>
<epc:item><epc:print expr="patent_applicant"/></epc:item>
<epc:item>Sixth</epc:item>
</epc:list>

Produces:
[ First | Third | Test Title | UNSPECIFIED | Sixth ]

If the value inside the <epc:item> is empty or only contains whitespace (spaces, tabs, newlines and carriage returns) it will be ignored. If a variable is used that is not specified, such as patent_applicant, then this will still be displayed if the default value for an unspecified value is set (e.g. like UNSPECIFIED in the example above). To avoid this put an if test for the variable and the whole item will be ignored.

Bots

2025-07-23T17:34:16Z

Libjlrs: /* Analysing traffic */

<big>'''NOTE: 2025-07-23 THIS PAGE IS CURRENTLY UNDER CONSTRUCTION'''</big>

The GLAM (Galleries, Libraries, Archives and Museums) sector have seen increased activity that appears to be automated, but doesn't identify itself as a 'robot' and doesn't follow robots.txt rules. The traffic makes repeated requests to systems (including EPrints repositories) for the same search terms, but with requests coming from a wide spread of IP addresses. Often an IP address will only make a single request, so traditional approaches to block traffic based in the IP address may not be enough.

Other attributes of these requests e.g. the User-Agent are variable and don't help to distinguish when requests are part of the same 'swarm' of requests.

The problematic traffic are requests to the search interface. These are , and this can cause performance issues with the platform. This isn't just an EPrints issue, other platforms experience the same issues.

Below are some approaches that may help to limit the impact of these 'swarms' of bots.

== Analysing traffic ==
* if system logs are in an analysis platform e.g. splunk
* TODO (+ Thanks to members of the EP-Tech mailing list for some of the suggestions below.

=== Apache logs ===
TODO (detail from tech-list)

=== Cachemap ===
When the internal EPrints search is used, a cache table is created in the database, and the details of the search are stored in the core <code>cachemap</code> table.

The pattern of 'swarm' activity can result in many identical searches being run. We can see these using the following query:
<source lang="sql">
SET @threshold = 30;
SELECT COUNT(*) c, searchexp FROM cachemap GROUP BY searchexp HAVING c > @threshold ORDER BY c;
</source>

Analysis of the web logs using search expressions returned from above may identify some attributes of the 'swarm'.

NB If EPrints is using Xapian to process searches, the majority of searches will ''not'' create a cache table.

== Blocking abusive search traffic ==

=== Firewall ===
???

=== fail2ban ===
??? - scanning logs for repeated cache=[x]

=== Apache configuration - mod_security (WAF) ===
<source lang="shell">
# details from DRN 2025-07-23
</source>

=== Approach: EPrints configuration to block specific searches ===
The example below creates an EPrints trigger that is active when a request is being processed by EPrints. Any incoming requests that contain the terms in the <code>$bad_search</code> configuration will not run a search, but will be presented with a '429 - too many requests' page.

NB the core Apache::Const module does not include a constant for a 429 response, so a numeric value is used instead of e.g. <code>OK</code> or <code>FORBIDDEN</code>

<source lang="perl">
# save in a cfg.d dir somewhere e.g. [EPRINTS_ROOT]/archives/[ARCHIVE_ID]/cfg/cfg.d/a_BOT_BLOCK.pl
use EPrints::Const;

### UPDATE THESE WITH SEARCHES YOU WANT TO BLOCK!
my $bad_search = join "|", map quotemeta, qw{
IN:Habits|
%3AHabits%7C
ZEPLIN+COSINE+DRIFT+ADMX+LIGO+Kamiokande+SBND
};
$c->{blocked_search_terms_re} = qr/$bad_search/;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %args ) = @_;

# args passed are: request, lang, args, urlpath, cgipath, uri, secure, return_code
my( $repository, $request, $return_code, $uri, $urlpath ) = @args{ qw( repository request return_code uri urlpath ) };

# Just interested in searches
if( $uri =~ /^$urlpath\/cgi\/search/ )
{
my $r_args = $request->args();

if( defined $r_args )
{
if( $r_args =~ /$c->{blocked_search_terms_re}/ )
{
#NB Apache2::COnst doesn't define 429.
$request->custom_response( 429, $c->{bot_429_page_html} );
${$return_code} = 429;
return EP_TRIGGER_DONE;
}
}
}
});

$c->{bot_429_page_html} = '<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style>
body {
font-family: sans-serif;
margin: 3em;
}
footer {
font-size: 80%;
margin-top:2em;
}
</style>
<title>Rate Limited</title>
</head>
<body>
<header>
<h1>429 Too Many Requests</h1>
</header>
<section>
<p>This search has been blocked due to abuse by automated activity.</p>
</section>
<footer>
<p>White Rose Libraries</p>
</footer>
</body>
</html>';
</source>

=== Using 3rd party tools ===
* Cloudflare
* Anubis

== Related resources ==

* [https://wiki.code4lib.org/Blocking_Bots Code4Lib Blocking Bots] - there is also a useful channel on the Code4Lib slack
* [https://www.glamelab.org/products/are-ai-bots-knocking-cultural-heritage-offline/ Are AI Bots Knocking Cultural Heritage Offline? GLAM-E Lab report]

Bots

2025-07-23T17:33:05Z

Libjlrs: Created page with "<big>'''NOTE: 2025-07-23 THIS PAGE IS CURRENTLY UNDER CONSTRUCTION'''</big> The GLAM (Galleries, Libraries, Archives and Museums) sector have seen increased activity that app..."

<big>'''NOTE: 2025-07-23 THIS PAGE IS CURRENTLY UNDER CONSTRUCTION'''</big>

The GLAM (Galleries, Libraries, Archives and Museums) sector have seen increased activity that appears to be automated, but doesn't identify itself as a 'robot' and doesn't follow robots.txt rules. The traffic makes repeated requests to systems (including EPrints repositories) for the same search terms, but with requests coming from a wide spread of IP addresses. Often an IP address will only make a single request, so traditional approaches to block traffic based in the IP address may not be enough.

Other attributes of these requests e.g. the User-Agent are variable and don't help to distinguish when requests are part of the same 'swarm' of requests.

The problematic traffic are requests to the search interface. These are , and this can cause performance issues with the platform. This isn't just an EPrints issue, other platforms experience the same issues.

Below are some approaches that may help to limit the impact of these 'swarms' of bots.

== Analysing traffic ==
You may be lucky enough to have your system logs available for analysis in a system like Splunk o
TODO (+ Thanks to members of the EP-Tech mailing list for some of the suggestions below.

=== Apache logs ===
TODO (detail from tech-list)

=== Cachemap ===
When the internal EPrints search is used, a cache table is created in the database, and the details of the search are stored in the core <code>cachemap</code> table.

The pattern of 'swarm' activity can result in many identical searches being run. We can see these using the following query:
<source lang="sql">
SET @threshold = 30;
SELECT COUNT(*) c, searchexp FROM cachemap GROUP BY searchexp HAVING c > @threshold ORDER BY c;
</source>

Analysis of the web logs using search expressions returned from above may identify some attributes of the 'swarm'.

NB If EPrints is using Xapian to process searches, the majority of searches will ''not'' create a cache table.

== Blocking abusive search traffic ==

=== Firewall ===
???

=== fail2ban ===
??? - scanning logs for repeated cache=[x]

=== Apache configuration - mod_security (WAF) ===
<source lang="shell">
# details from DRN 2025-07-23
</source>

=== Approach: EPrints configuration to block specific searches ===
The example below creates an EPrints trigger that is active when a request is being processed by EPrints. Any incoming requests that contain the terms in the <code>$bad_search</code> configuration will not run a search, but will be presented with a '429 - too many requests' page.

NB the core Apache::Const module does not include a constant for a 429 response, so a numeric value is used instead of e.g. <code>OK</code> or <code>FORBIDDEN</code>

<source lang="perl">
# save in a cfg.d dir somewhere e.g. [EPRINTS_ROOT]/archives/[ARCHIVE_ID]/cfg/cfg.d/a_BOT_BLOCK.pl
use EPrints::Const;

### UPDATE THESE WITH SEARCHES YOU WANT TO BLOCK!
my $bad_search = join "|", map quotemeta, qw{
IN:Habits|
%3AHabits%7C
ZEPLIN+COSINE+DRIFT+ADMX+LIGO+Kamiokande+SBND
};
$c->{blocked_search_terms_re} = qr/$bad_search/;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %args ) = @_;

# args passed are: request, lang, args, urlpath, cgipath, uri, secure, return_code
my( $repository, $request, $return_code, $uri, $urlpath ) = @args{ qw( repository request return_code uri urlpath ) };

# Just interested in searches
if( $uri =~ /^$urlpath\/cgi\/search/ )
{
my $r_args = $request->args();

if( defined $r_args )
{
if( $r_args =~ /$c->{blocked_search_terms_re}/ )
{
#NB Apache2::COnst doesn't define 429.
$request->custom_response( 429, $c->{bot_429_page_html} );
${$return_code} = 429;
return EP_TRIGGER_DONE;
}
}
}
});

$c->{bot_429_page_html} = '<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style>
body {
font-family: sans-serif;
margin: 3em;
}
footer {
font-size: 80%;
margin-top:2em;
}
</style>
<title>Rate Limited</title>
</head>
<body>
<header>
<h1>429 Too Many Requests</h1>
</header>
<section>
<p>This search has been blocked due to abuse by automated activity.</p>
</section>
<footer>
<p>White Rose Libraries</p>
</footer>
</body>
</html>';
</source>

=== Using 3rd party tools ===
* Cloudflare
* Anubis

== Related resources ==

* [https://wiki.code4lib.org/Blocking_Bots Code4Lib Blocking Bots] - there is also a useful channel on the Code4Lib slack
* [https://www.glamelab.org/products/are-ai-bots-knocking-cultural-heritage-offline/ Are AI Bots Knocking Cultural Heritage Offline? GLAM-E Lab report]

Miscellaneous Config Options

2025-06-25T08:55:43Z

Libjlrs: /* E */

__NOTOC__
[[Category:Manual]]
<div style="border: solid black 1px; text-align: center; background-color: #eee; font-size: 1.5em; font-weight: bold;">
[[#A|A]] | [[#B|B]] | [[#C|C]] | [[#D|D]] | [[#E|E]] | [[#F|F]] | [[#G|G]] | [[#H|H]] | [[#I|I]] | [[#J|J]] | [[#K|K]] | [[#L|L]] | [[#M|M]] | [[#N|N]] | [[#O|O]] | [[#P|P]] | [[#Q|Q]] | [[#R|R]] | [[#S|S]] | [[#T|T]] | [[#U|U]] | [[#V|V]] | [[#W|W]] | [[#X|X]] | [[#Y|Y]] | [[#Z|Z]]
</div>

This page describes configuration options that do not appear in any [[Config Options by File|specific configuration files present]] in the main codebase (inc. pub_lib flavour). <font style="color: red;">The reason a configuration option does not appear in a default configuration file may be because it is a legacy option that may become deprecated and removed.</font> Some descriptions below state that a configuration option is legacy but some descriptions may still need updating to explain they are legacy options.

== A ==
* '''access_logger_func''' - Defines a function that is called every time a documents is downloaded or abstract/summary page is viewed (i.e. an access record is created). This is used by recent versions of IRStats2, so it can process stats from a file-based access records rather than the database, which is more efficient if the <code>access</code> database table is large (10 million+ records).
* '''access_table_logger_disabled''' - Whether access records should still be saved to the database. (Without a setting database will continue to store access records).
* '''allow_duplicate_usernames''' - Whether the validation of <code>user</code> metadata should check for duplicate usernames. (Without a setting user metadata validation will fail if there are duplicate usernames. This should only ever be set to <code>1</code> temporarily, if username changes are required that may briefly lead to duplicates).
* '''allow_uploaded_doc_js''' - A malevolent user could deliberately upload malicious JavaScript to perform a clickjacking or similar attack against logged in users. Should uploaded JavaScript only be returned with a Content Security Policy (CSP) to prevent it from being run on the client web browser. (Without a setting CSP to prevent JavaScript running on the client is enabled).
* '''<font style="color: red;">auth_basic</font>''' - <font style="color: red;">Legacy configuration for specifying basic rather than cookie-based user authentication.</font>

== B ==
* '''browse_views_max_items''' - Global setting for the maximum number of results that can be displayed on a browse view listing page. Superseded if a particular view has a <code>max_items</code> attribute set. (Without a setting this defaults to <code>2000</code> items).

== C ==
* '''check_user_password''' - Allows a function to be defined to perform a bespoke check of whether the users password is correct. Is passed the username and password and should return <code>0</code> if the password validation failed and <code>1</code> if it was successful. (Without a setting, standard local authentication of the user's password is used).
* '''custom_handlers''' - If you have a third-party application that needs to integrate with its own connector (e.g. Pure), then this allow you to [[Custom_handlers|define configuration for this]].

== D ==
* '''dbdriver''' - Which database driver (type of database, i.e. <code>mysql</code>, <code>Pg</code> or <code>Oracle</code>) to use. (Without a setting this defaults to <code>mysql</code>).
* '''dbschema''' - Which database schema to use. This is only applicable for <code>Pg</code> (PostGreSQL) databases.
* '''default_export_plugin''' - Which export plugin to pre-select on browse view and search results pages. (Without a setting, whichever export plugin appears first is pre-selected).
* '''deps''' - Defines dependencies of [[EPrints_Ingredients|ingredients]] on other ingredients. By default this is not defined as no ingredients packaged in an EPrints standard release have any dependencies.
* '''disable_basic_auth''' - Ensure authentication cannot accidentally fallback to basic (rather than cookie-based) authentication. (Without a setting it could fallback but it is very unlikely to do this unless your EPrints repository has been significantly modified).
* '''disable_make_open_access''' - Remove the option on the Request Copy approval form to immediately make the document open access. (Without a setting the checkbox for this is present).
* '''does_user_own_eprint''' - Allows a function to augment what eprint records a user appears to own. This may be useful if a particular user is acting as a surrogate for another user. Should be defined in conjunction with <code>get_users_owned_eprints</code>.

== E ==
* '''email_blacklist''' - Array reference containing a list of email addresses that are not allowed to make requests for copies. Can be useful if some individual is making excessive requests, although ReCaptcha is probably more useful (Without being defined there is no restriction on email addresses that can requests copies).
* '''enable_file_imports''' - Whether local files (for the importer) can be uploaded to the repository an part of an XML (e.g. EP3XML, Atom, etc.) import. (Without a setting they cannot be uploaded).
* '''enable_import_fields''' - Specify fields for a data object that can be imported even through their field definition says they can not.
* '''enable_web_imports''' - Whether web-based files can be uploaded to the repository an part of an XML (e.g. EP3XML, Atom, etc.) import. (Without a setting they cannot be uploaded).
* '''eprints_access_restrictions_callback''' - Allows a function to be defined to test if the current user has access to read/write (access View/Edit page for) the specified eprint record. Useful if you want to give access to certain eprint records without changing a user's type.
* '''eprint_rss_media_doc''' - Allows a function to be defined to build a bespoke XML document fragment to encapsulate RSSv2 export (Without a setting an empty XML document fragment is used).
* '''<font style="color: red;">eprint_status_change</font>''' - Allows a function to be defined that is called when the status (i.e. <code>eprint_status</code> metadata field) has changed. <font style="color: red;">This is a legacy function. <code>EP_TRIGGER_STATUS_CHANGE</code> [[Triggers#Dataset Triggers|dataset trigger function]] should be used instead.</font>
* '''expiry_for_doc_request''' - How many days an approved request copy link will last before access will be revoked. (Without a setting this is <code>7</code> days).
* '''expiry_for_unresponded_doc_request''' - How many days an unapproved request can exists before the request can no longer be approved. Saves really old requests being approved without proper consideration or confusing / annoying the requester months/years after their request. (Without a setting this is <code>90</code> days, approx. 3 months).
* '''export_fieldlists''' - What fields can exported for a data object. Further restricts field definition settings for <code>export_as_xml</code>. This may be useful to block fields with data privacy concerns but it will mean that not even repository admins will not be able to export these fields. Consider using [[y_export_privacy.pl|export_privacy]] instead. (Without a setting, what fields can be exported are only defined by their field definitions).

== F ==
* '''file_local_path_function''' - Allows function to be defined to modify the location where the file represented by the file data object can be found on the local filesystem. Could be used if a bespoke new type of data object that has associated files need to be added.

== G ==
* '''generic_filenames''' - New (non-history) files will be added to the documents directory as <code><fileid>.bin</code> rather than there actual filename. This can be useful if users are uploading files with names that use special characters that are not compatible with the filesystem or database encoding. EPrints will already allow existing files to be manually changed to the <code><fileid>.bin</code> to provide a simple fix for existing issues using special characters, which subsequently cannot be downloaded.
* '''get_current_user''' - Allows a bespoke function to defined to determine who the current user is. (Without a setting current user is determine from cookie or basic authentication attributes in the request).
* '''get_custom_view_header''' - Allows a function to be defined that adds custom HTML markup (XML DOM object) to a browse view page. By default this is after the navigation but before any listings / menus.
* '''get_custom_view_header_location''' - Allows content for <code>get_custom_view_header</code> (if defined) to be added either before the navigation (<code>before_nav</code>) or after the navigation (<code>after_nav</code>). (Without a setting it is added after the navigation. Only added since EPrints 3.4.6).
* '''get_login_url''' - Allows bespoke function to defined to generate the login URL for the repository archive. Useful for [[Shibboleth]] or other SAML-based login. (Without a setting <code>/cgi/users/login</code> is used).
* '''get_request_eprint_descriptor''' - Allows a bespoke function to be defined to generate the descriptor for an eprint. This may be useful if multiple eprints have the same title. (Without a setting the <code>title</code> of the eprint is used as the descriptor).
* '''[[Miscellaneous Config Options/get_users_owned_eprints|get_users_owned_eprints]]''' - Allows function to be defined that lists the set of eprints a user owns, instead of just those where their <code>userid</code> is set on the eprint record. Should be defined in conjunction with <code>does_user_own_eprint</code>.

== H ==
* '''history_enable''' - Allows revision history to be recorded for [[API:EPrints/DataObj/RichDataObj|rich data objects]] beyond just eprint data objects. Is an hash reference of <code>datasetid</code> to whether history is enabled. Any defined value means enabled.

== I ==
* '''ignore_login_ip''' - Whether IP address should be ignored in <code>loginticket</code> so user can change IP address without being logged out. (Without a setting up to 3.4.6 the login IP address has not been ignored, from 3.4.6. it will be ignored by default).
* '''items_filters''' - What filters can be used on the <code>EPrints::Plugin::Screen::Items</code> (i.e. Manage Deposits) page. Useful if an additional <code>eprint_status</code> option has been added. (Without a setting this uses the four <code>eprint_status</code> options (<code>inbox, buffer, archive, deletion</code>).
* '''items_filters_order''' - What order should filters be displayed on the <code>EPrints::Plugin::Screen::Items</code> (i.e. Manage Deposits) page. (Without a setting this uses the four <code>eprint_status</code> options in the following order (<code>inbox, buffer, archive, deletion</code>).
* '''import_xml_permitted_tags''' - When importing HTML encoded text through an XML import what HTML tags are allowed. Useful if there is a particular HTML tag that is commonly used is not included in the hardcoded default list, which is quite restrictive to avoid use of certain HTML tags for malicious purposes. (By default allowed HTML tags are: <code>b big blockquote br code dd div dl dt em h1 h2 h3 h4 h5 h6 hr i li ol p pre s small span strike strong sub sup table tbody td th tr tt u ul</code>).

== J ==

== K ==

== L ==
* '''login_required_for_cgi'''
** '''enable''' - Whether users need to be logged in to access <code>/cgi/...</code> pages (<code>/cgi/users/...</code> pages always required being logged in). (Without a setting login is not required, set to <code>1</code> to enable).
** '''exceptions''' - Array reference of paths that are excluded from needing login. (Without a setting all CGI scripts require login, if <code>enabled</code> is set to <code>1</code>. This would cause a problem if your <code>login_required_url</code> is <code>/cgi/users/login</code> and therefore at least <code>users/login</code> should be added).
* '''login_required_for_eprints'''
** '''enable''' - Whether users need to be logged in to access eprint abstract/summary pages. (Without a setting login is not required, set to <code>1</code> to enable).
* '''login_required_for_static''' (EPrints 3.4.7+)
** '''enable''' - Whether users need to be logged in to access static pages (e.g. the homepage, information and help pages. etc.). (Without a setting login is not required, set to <code>1</code> to enable).
** '''exceptions''' - Array reference of paths that are excluded from needing login. (Without a setting all static require login, if <code>enabled</code> is set to <code>1</code>. All paths requires leading <code>/</code>. So information page would be <code>/information.html</code> and hompage would be just <code>/</code>. If some static pages are excepted, some of their resources will also need to be, e.g. <code>/favicon.ico</code>, <code>/images/.*</code> and <code>/style/images/.*</code>).
* '''login_required_for_views'''
** '''enable''' - Whether users need to be logged in to access browse view pages. (Without a setting login is not required, set to <code>1</code> to enable).
* '''login_required_url''' - URL for page to be redirected to if login is required. This is different to <code>get_login_url</code> as it is only applicable to pages that are affected by <code>login_required_for_cgi</code>, <code>login_required_for_eprints</code> and <code>login_required_for_views</code>. (Typically, this should be set to ths default login URL <code>/cgi/users/login</code>. If this is not set the pages will try redirecting to themselves and get stuck in a loop).

== M ==
* '''max_history_width''' - The number of characters per line for XML displayed in the history tab before wrapping to a new line. (Without a setting a maximum of <code>120</code> characters are displayed before wrapping).

== N ==
* '''notify_embargo_expiry''' - Allows a bespoke function to be defined to perform actions when an embargo is lifted on a document. As the name suggests, such actions may be sending out a notification to the eprint owner or a repository administrator. (Without a setting no additional actions are performed when an embargo is lifted).

== O ==
* '''oai'''
** '''v2'''
*** '''output_plugins''' - Hash reference of additional export plugins that can be used with OAI-PMH. (Without a setting just those that have an <code>xmlns</code> set, provide export for the appropriate dataset (typically <code>eprint</code>) and are at least visible to <code>staff</code>).
*** '''sample_identifier''' - An example of an identifier used by OAI-PMH for individual records. (Without a setting no sample identifier is shown on OAI-PMH pages).
* '''<font style="color: red;">on_files_modified</font>''' - Allows a function to be defined that is called when a <code>FilesModified</code> indexer task runs. <font style="color: red;">This is a legacy function. <code>EP_TRIGGER_FILES_MODIFIED</code> [[Triggers|trigger function]] should be used instead.</font>
* '''<font style="color: red;">on_generate_thumbnails</font>''' - Allows a function to be defined that is called when a <code>FilesModified</code> indexer task runs which includes generating thumbnails. This may be useful if a special type of thumbnail file is required but cannot be defined with existing configuration for thumbnail types. <font style="color: red;">This is a legacy function. <code>EP_TRIGGER_THUMBNAIL_TYPES</code> [[Triggers|trigger function]] instead</font>.
* '''on_logout''' - Allows a bespoke function to be defined to carry out certain actions before a user is logged out. (Without a setting no additional actions are performed).
* '''order_auto_submit''' - Whether changing the ordering for search results will automatically reload the page. (Without a setting search results pages will not automatically be reloaded on ordering change).

== P ==

== Q ==

== R ==

* '''recaptcha''' - Configuration for [[Recaptcha field]]s.
** '''ignore_countries''' - Array reference of ISO-639-1 two character codes for countries who should be automatically rejected. (Without a setting no countries are automatically rejected).
** '''private_key''' - The secret key generated by registering the hostname of the EPrints repository as a reCATPCHAv2 site.
** '''public_key''' - The site key generated by registering the hostname of the EPrints repository as a reCATPCHAv2 site.
** '''timeout''' - The maximum time to wait for a response from ReCAPTCHA. (Without a setting LWP's default of 180 seconds is used. ReCAPTCHA is usually fairly quick to respond, so there is not really any need to set this).
* '''recaptcha3''' - Configuration for [[Recaptcha3 field]]s.
** '''ignore_countries''' - Array reference of ISO-639-1 two character codes for countries who should be automatically rejected. (Without a setting no countries are automatically rejected).
** '''min_score''' - The minimum score reCAPTCHAv3 needs gives for the request for it to be valid. (Without a setting Google's default of <code>0.5</code> is used).
** '''private_key''' - The secret key generated by registering the hostname of the EPrints repository as a reCATPCHAv3 site.
** '''public_key''' - The site key generated by registering the hostname of the EPrints repository as a reCATPCHAv3 site.
** '''timeout''' - The maximum time to wait for a response from ReCAPTCHA. (Without a setting LWP's default of 180 seconds is used. ReCAPTCHA is usually fairly quick to respond, so there is not really any need to set this).
* '''request_copy_cc''' - Array reference of email addresses that should be cc-ed in on all requests submissions that lead to an email being sent.
* '''<font style="color: red;">required_formats</font>''' - Allows the definition of either an array reference or a function that will generate an array reference of required formats for documents. <font style="color: red;">This is a legacy option. <code>EP_TRIGGER_VALIDATE_FIELD</code> [[Triggers|trigger function]] should now be used instead.</font>
* '''retain_embargo_dates''' - Whether embargo dates for documents should be retained when the embargo date has been reached. This may be useful if EPrints integrates with a third-party application that needs to retain embargo dates. (Without this setting <code>bin/lift_embargos</code> will remove dates once the embargoes expire. Otherwise, validation warnings for both the dates being in the past and documents still having embargo dates when they are public will be generated).
* '''rewrite_exceptions''' - Array reference of paths that should not be served by EPrints's Perl handler and should be served directly by Apache or some other handler.
* '''robotstxt'''
** '''crawl_delay''' - Adds crawl delay configuration to robots.txt.
*** '''default_seconds''' - The default number of seconds all other user agents (bots) should wait between crawl requests. (without a setting no default crawl delay will be set).
*** '''seconds''' - The number of seconds for specified (i.e. more aggressive) user agents (bots) should wait between crawl requests. (Without a setting <code>10</code> seconds will be used).
*** '''user_agents''' - Array reference of specific (more aggressive) user agents that require a (greater) crawl delay. (Without a setting no user agents will have a crawl delay, unless <code>default_seconds</code> is set).

== S ==
* '''saved_search_additional_recipients''' - Comma separated list of emails addresses that should additionally be included in saved search emails. (Without a setting no additional recipients will be added to saved search emails).
* '''saved_search_citation''' - <code>eprint</code> citation format to use for items listed in saved search emails. (Without a set the default eprint citation format will be used).
* '''signup_style''' - The introductory message to show on the sign up page. (Without a setting the default introductory message is used. If set to <code>minimal</code> then the minimal introductory message is used. Typically using this setting is only useful if <code>default_user_type</code> is also set to <code>minuser</code>).
* '''skip_validation''' - Allows a bespoke function to be defined to determine if an eprint is allowed to skip validation. This may be useful for imported records that had different validation rules (Without a setting, no eprints are allowed to skip validation).
* '''STAFF_ONLY_LOCAL_callback''' - Allows a function to be defined to test of current user is a local staff (editor/admin) user to set <code>STAFF_ONLY_LOCAL</code> for use in workflows. (Without setting <code>STAFF_ONLY_LOCAL</code> will be set to <code>0</code>, i.e. current user is not local staff).

== T ==
* '''theme''' - Rather than having to define templates, CSS and JavaScript branding just for the archive, use the files under the defined theme subdirectory (e.g. <code>lib/theme/</code>, <code>archives/ARCHIVE_ID/cfg/theme/</code> or a theme sub-directory for paths listed in flavour's inc file). (Without a setting no theme will be used).
* '''<font style="color: red;">thumbnail_types</font>''' - Allows a function to be define to add extra thumbnail types that should be generated for a document. <font style="color: red;">This is a legacy option. <code>EP_TRIGGER_THUMBNAIL_TYPES</code> [[Triggers|trigger function]] should be used instead.</font>

== U ==
* '''ultimate_doc_pos''' - Allows a bespoke function to be defined for determining the <code>pos</code> value (i.e. the sub-directory where files associated with this document are stored on disk) for the newly created document under an eprint. (Without a setting this value for the document's <code>pos</code> field is one greater than the current maximum <code>pos</code> value of all documents under that eprint).
* '''<font style="color: red;">update_submitted_eprint</font>''' - Allows a bespoke function to be defined to perform actions once an eprint has been moved to the review buffer. <font style="color: red;">This is a legacy option. The more generic <code>EP_TRIGGER_STATUS_CHANGE</code> [[Triggers#Dataset Triggers|dataset trigger function]] should be used instead.</font>
* '''user_access_restrictions_callback''' - Allows a function to be defined to test if the current user has access to read/write (access View/Edit page) the specified user record.
* '''<font style="color: red;">user_area_template</font>''' - Page template to use when accessing user area pages. Superseded in EPrints 3.4.x by automatically using <code>default_internal</code> template all screen plugins. (Without a setting either <code>default</code> (EPrints 3.3.x) or <code>default_internal</code> (EPrints 3.4.x) template is used.
* '''user_cookie_timeout''' - The amount time (using: h, d, w, m, and y) before the user session cookie should expire (e.g. <code>+1h</code>, <code>+7d</code>). (Without a setting no cookie timeout is set).
* '''user_inactivity_timeout''' - How long to wait in seconds before logging the user out after their last activity. (Without a setting <code>86400 * 7</code> seconds, i.e. 7 days is used).
* '''user_session_timeout''' - How long in seconds the user can stay logged in before they must re-log in. (Without a setting user session never times out. With a setting <code>user_inactivity_timeout</code> probably will to be reduced to a considerably shorter period of time to this).

== V ==
* '''version_extra''' - Extra information to add about the EPrints repository software version, as appears under <code>/cgi/counter</code> Useful if the version of the codebase has been augmented. (Without a setting no extra version is included).
* '''view_sort_function''' - Redefines the sort function used by <code>EPrints::MetaField->sort_values</code> (Without setting the <code>Unicode::Collate</code> is used as the collator to compare values when sorting).
* '''virtualhost''' - When running <code>bin/generate_apacheconf</code> what to set in the <code><virtualhost HOSTNAME:PORT></code> lines. (Without a setting, <code>*</code>, i.e. a wildcard is used).

== W ==
* '''workflow_datepicker''' - Defines function for rendering a date-picker for date fields in a workflow. Useful if you want to include some JavaScript to help a user pick a date. (Without a setting, a simple year, month and day set of fields is rendered.)

== X ==
== Y ==
== Z ==

XPAGE Format

2025-06-24T14:17:21Z

Libjlrs: Add 'template' to list of tags.

{{formats}}

'''See [[API:EPrints/Apache/Template#Static_HTML_Pages]] for a list of the pins you can use in an xpage'''

Stored in the [[EPrints_Directory_Structure/eprints3/archives/ARCHIVEID/cfg/lang/en/static|static]] folder, xpage files are portions of HTML that are rendered into static files when generate_static is run. Four tags are in the xpage namespace: <code>xpage:page</code>, <code>xpage:title</code>, <code>xpage:body</code> and <code>xpage:template</code>.

The beginning of index.xpage (which generates the site's index page) is as follows - the three tags are analogous to the html, title, and body tags of an HTML document, except the body is included within the site's template. It is recommended to use xhtml as the default namespace to ease writing. As with templates, [[EPrints Control Format]] tags may be used.

<source lang="xml">
<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
<!DOCTYPE page SYSTEM "entities.dtd" >
<xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
<xpage:title>Welcome to <epc:phrase ref="archive_name" /></xpage:title>
<xpage:body>Some example body text.</xpage:body>
</xpage:page>
</source>
When generate_statics is run, four static files are created for each xpage file. For index.xpage, these would be index.html (the HTML page), index.page (the contents of the xpage:body tag), index.title (the contents of the xpage:title tag), and index.title.textonly (the contents of the xpage:title with HTML tags stripped out). Note that these files are generated by generate_static, and shouldn't be edited by hand.

2013-10-21 NOTE: Some versions of EPrints (3.3.10 and lower?) don't process phrases with pins in them properly from xpages. Whitespace in the phrase tag breaks the processor, resulting in a '[error in script]' message in the page, and something like ' EPScript error: Can't locate object method "tagName" via package "XML::LibXML::Text" at /usr/share/eprints/perl_lib/EPrints/XML/EPC.pm line 204' in the apache error logs.
This can be fixed by removing the whitespace:
<source lang="xml">

<epc:phrase ref="lib/searchexpression:results_for">
<epc:param name='title'>Test</epc:param>
</epc:phrase>

<epc:phrase ref="lib/searchexpression:results_for"><epc:param name='title'>Test</epc:param></epc:phrase>
</source>
or possibly patching ~/perl_lib/EPrints/XML/EPC.pm with https://github.com/eprints/eprints/commit/10fc4e67fac54dc87c6968ac3be79c4cb121efcf

Views.pl

2025-04-28T13:15:50Z

Libjlrs: /* View list options */

[[Category:Browse Views]]
{{dirs}}
{{cfgd}}

'''views.pl''' contains configuration for rendering ''views''. Conceptually a ''view'' is a browsable list of eprints split into ''menus'' and a ''list''.

<div align="center">
{| cellpadding="0" cellspacing="0" border="0"
|-
| style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px" |Menu1
|  
|  
|  
|  
|-
| style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item1_1 ------
| style="font-size:10px"|--->
| style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px"|Menu2
|  
|  
|-
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; font-size:10px"|   Item1_2
|  
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item2_1 -----
|style="font-size:10px"|--->
|style="border-color:black; border-style:solid; border-width:1px 1px 0 1px; margin:0; padding:0; text-align:center; font-size:10px"|     LIST    
|-
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|  
|style="border-color:black; border-style:solid; border-width:0 1px; text-align: left; margin:0; padding:0; font-size:10px"|   Item2_2
| 
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|-
|  
|  
|style="border-color:black; border-style:solid; border-width:0 1px 1px 1px; margin:0; padding:0; text-align:left; font-size:10px"|   ....
|  
| 
|}
</div>
In a ''menu'' values of one (or more) fields are listed, and a link points to the collection of all items with that particular value in that field.

The ''list'' contains the final list of eprints with field values as determined by the menus above it.

== Options available for the views config ==
This link is an [http://wiki.eprints.org/w/Adding_new_views 'How to' about views] with examples.

The general form of views definition is

$c->{browse_views} = [
{ <first view definition> },
{ <second view definition> },
...
{ <last view definition> },
];

(be careful about commas and semicolons). The order of the view definitions determines the order in which these will appear in the <nowiki>http://repoid/view/</nowiki> page.

Each view definition is a collection of attributes, given as

attribute1 => value1,
attribute2 => value2,
...

(again, the ''value'' should end by a comma). The ''value'' can be
*''integer''
*''string'' enclosed by quotation marks (") or by apostrophes (')
*''array'' which starts by a square bracket [ followed by the elements of the array (separated by commas) and closed by ] or
*''hash'' which is a list of "attribute => value" pairs enclosed by curly brackets { and }.
Thus the browse_views definition is an array of hashes.

Attributes marked by <sup style="font-weight:bold; font-size:10px">(V)</sup> are ''view'' attributes and are in the view definition; attributes marked by <sup style="font-weight:bold; font-size:10px">(M)</sup> are ''menu'' attributes and should be used only in [[#Menu options|menu definitions]].

==Basic options==

Options in the first category are ''view'' options.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
| id <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| (mandatory) String, this is the ID by which you will refer to this view, and also the name of the top directory in <nowiki>http://repoid/view/</nowiki>. This is the value of the ''browse_link'' attribute in [[eprint_fields.pl]]. Example:

id => 'divisions',
|- valign="top"
|fields <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|(deprecated) This attribute describes the field(s) by which the view is built. It has been replaced by the more general [[#Menu options|menus]] attribute.
|- valign="top"
|hideempty <sup style="font-weight:bold; font-size:10px;">(V)</sup>
allow_null <sup style="font-weight:bold; font-size:10px;">(V)</sup>
new_column_at <sup style="font-weight:bold; font-size:10px;">(V)</sup>
render_menu <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|These define the default values of the same attributes in all [[#Menu options|menus]]. I.e, if not defined otherwise there, they take this as the default value in this view. "Hideempty" is also used when rendering the [[#View list options|view]] list.
|- valign="top"
|menus <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|An array of ''[[#Menu options|menu descriptions]]''. Each ''menu'' is a refinement of the previous ones, and last menu points to the [[#View list options|view list(s)]]. In each menu, as minimum, you should give the field(s) which are used to define entries at that level. The menus definition looks like
menus => [
{ <first menu definition> },
{ <second level menu> },
{ <last level> },
],
You must have at least one menu level.
|- valign="top"
|template <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Define an alternate template for all pages in this view. The template page should be a proper xml file in the <tt>repoid/cfg/lang/<langid>/templates/</tt> directory. The best way is to copy the default.xml file and edit it according to taste.
template => 'view_template',
|- valign="top"
|nolink <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|When this is set to 1 by adding
nolink => 1,
then this view won't appear in the outmost <nowiki>http://repoid/view/</nowiki> browse page.
|- valign="top"
| max_menu_age <sup style="font-weight:bold; font-size:10px;">(V)</sup>
| Defaults to 86400 (one day in seconds). If the menus in this view has been generated more than that many seconds ago, it is regenerated.
|- valign="top"
| max_items <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Defaults to 2000. If the items list is larger increase the number enough to accomodate the number of items needed to be displayed.
max_items => 3000,
|}

===View list options===
These are the options which determine how the last list page in the menu chain should look like. They must be entered at the outmost ''view'' level.
{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|order <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|This defines how the items in the view list (at the lowest level) are ordered. The format is 'foo/-bar'. This means that the list will be sorted by 'foo' and then any equal 'foo' values will be reverse sorted by 'bar'. More than 2 fields can be specified. Example:
order => "-date/title",
|- valign="top"
|hideup <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Don't show the "up one level" link in the list page. You ''must'' set this attribute for each menu separately, it is not inherited.
|- valign="top"
|hideempty <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Do not list the empty (undefined) entry in the list. This property inherits to the menus.
|- valign="top"
|nocount <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "Number of items" line at the top of the page is omitted.
|- valign="top"
|notimestamp <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|If set, the "This list was generated on" line at the bottom of the list is omitted.
|- valign="top"
|variations <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|An array of strings describing different rendering of the items at the ''list''. For datails see [[#Variations|variations]]. Example:
variations => [ "creators_name;first_letter",
"type", "DEFAULT", ],
|- valign="top"
|layout <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Possible values are
*paragraph (default)
*orderedlist
*unorderedlist
Determines how items in the list (or sublist) is rendered. In the first case each item is a paragraph by itself. In the other cases items are rendered as an ordered (unordered) list.
|- valign="top"
|citation <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|The citation style defined in archives/<REPOID>/cfg/citations/eprint/ which is used to render each item. Example:
citation => 'screen',
|- valign="top"
|max_list_age <sup style="font-weight:bold; font-size:10px;">(V)</sup>
|Defaults to 86400 (one day in seconds). If the lists in this view were generated more than than many seconds ago, it is regenerated.
|}

===Variations===

Variations, if defined, determine how the final list is rendered. ''Variations'' is an array of strings, for example,

[ "creators_name;first_letter",
"type",
"DEFAULT",
]

For each string in the list, a different rendering is produced, and you can switch from one to the other. The variation "DEFAULT" is the default one, it is always a good practice to include it in the list. If no variation is given, "DEFAULT" is used.

A ''variation definition'' consists of a field name, followed by zero, one or more ''options'' after a semicolon. Options are separated by commas. An ''option'' is either a single attribute, or an attribute, an equal sign, and the value of the attribute. For example,
"creators_name;truncate=4,hideup"
sets the attribute value "truncate" to 4, and "hideup" to 1 (or true).

The following options are available. These options are ''part of the string'' defining the variation, and ''should not be entered'' as attributes.

{| border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|reverse
|Reverses the order in which the groupings are shown. Default is the ordervalue for that field (usually alphanumeric). Useful for dates as you may want the highest values first.
|- valign="top"
|filename
|Changes the filename of the view variation. The default is the name of the metadata field used, so if two variations use the same metadata field with different options, this is needed.
filename=different_filename
|- valign="top"
|first_value
|If a field is multiple, only use the first value. Otherwise each item will appear once for each value.
|- valign="top"
|first_initial
|If using a name, truncate the given name to the first initial. This will make items like "Les Carr" and "Leslie Carr" appear together. Note it will also make "John Smith" and "Jake Smith" appear together too, showing that you really never can win.
|- valign="top"
|first_letter
|The same as 'truncate=1'
|- valign="top"
|truncate
|Use the first X characters of a value to group by. truncate=4 may be useful for dates as it will group by the first four digits (the year) only.
truncate=4
|- valign="top"
|tags
|Useful for fields like keywords where values may be separated by commas or semi-colons. The value is split on these two characters ( , and ; ) and a heading is created for each.
|- valign="top"
|cloud
|Creates a tag cloud. Sets jump to 'plain', cloudmax to 200, cloudmin to 80 and no_separator, then resizes the jump-to links according to frequency of use.
|- valign="top"
|cloudmax
|The % size of the largest tag in a tag cloud.
|- valign="top"
|cloudmin
|The % size of the smallest tag in a tag cloud.
|- valign="top"
|jump
|Possible values are 'plain', 'default', and 'none'. Example:
jump=plain
When set to 'plain' turns off the 'jump to' text before the list of subheading navigation links. When 'none', then the 'jump' part is not rendered.
|- valign="top"
|no_seperator (sic)
|Turns of the separator between each subheading navigation link (by default a vertical bar symbol).
|- valign="top"
|string
|Uses values 'as is'. No ordervalues, no phrases.
|- valign="top"
|hideup (since 3.1.1)
|Defaults to "0". If set to "1" this hides the "up to parent" link (often you want to hide this on .include files)
|- valign="top"
|render_fn
|Name of a function to render this groupings list of items. For an example, see views_render_items_example.pl
|}

===Menu options===

These options can only be used in the '''menu definitions'''.

{|border="1" cellpadding="4" cellspacing="0"
|- valign="top"
|fields <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|Obligatory, an array of field identifiers. Items in all fields are merged together. For example, to define a list of those those who are either authors or editors or both, use the definition

fields => [ "creators_id", "editors_id" ],

Even if there is a single field, you must use square brackets, such as

fields => [ "subjects" ],

<div style="color: #662211; background-color:#ddffdc; border:1px solid black; padding:3px;">'''Important!''' All fields must have the same type - i.e. you cannot mix titles and authors, say.</div>

You can also add extra rendering info to the field name, without the "render_" prefix. For example, to make a date have resolution year, you would write

fields => [ "date;res=year" ],

or, ordering authors by their ''given'' names rather than by their family names:

fields => [ "creators_name;order=gf" ],

You can add ";quiet" to the field name to force non-existing values to appear as empty space rather than the ugly "UNDEFINED" (see the allow_null property below). You can find the available rendering properties of different fields in the [[Metadata]] section.
|- valign="top"
|allow_null <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|The ''undefined'' value among the possible values of the fields does not show up in the generated view. To allow the undefined value to appear as well, set

allow_null => 1,

Beware: the title of the undefined entries will be the ugly UNDEFINED. You might consider to use the ";quiet" rendering option for field names.
|- valign="top"
|hideempty <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If a category is empty, don't show it as an entry. Default value: show all entries, even if they contain no entries. Used only in menus, not at the lower level (list).
Example:

hideempty => 1,
|- valign="top"
|reverse_order <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|If set, then the ordering of items in this menu is reversed. Example:

reverse_order => 1,
|- valign="top"
|mode <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|Possible values: ''[[#Sections|sections]]'' and ''default'' (default). When defined as ''sections'' then grouping can be defined by the following data:
* ''grouping_function'' (group by first character if not defined)
* ''group_sorting_function'' (how to sort members of a group)
* ''group_range_function''
* ''open_first_section'' the front page should show the first section
See [[#Sections|below]].
|- valign="top"
|hideup <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|When set to 1, don't show the "move one level up" link at the top of the page.
|- valign="top"
|render_menu <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|The configuration parameter which renders this menu. This should be a string, and also you should define a routine with the same name. For example if you write
render_menu => 'render_view_menu_3col_boxes',
then this menu will be rendered by the routine which is defined in [[views_render_menu_example.pl]] as
$c->{render_view_menu_3col_boxes} = sub
{
...
}
See there for hints how to tweak your own routine.
|- valign="top"
|new_column_at <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|Used in menus (not lists) and in default mode. This is an array of integers representing the number of items in a view list before another column is added. For example:

[ 11 ]

The menu is rendered as a single column data if there are less than 11 entries, then there would be 2 columns.

[ 11, 21 ]

This would have one column if there were ten or less values, two columns if there are twenty or less, and three columns for all other cases.

[ 0, 0 ]

This would always have three columns.

[ 2, 3 ]

This would have one column for a single data, two columns for two, and three columns for three or more data.

Add one to the number of integers in the array and you get the maximum number of columns. The entries are evenly distributed in the columns.
|}

===Sections===

When a menu is using "sections", then items on the menu are grouped together. The exact method is defined by defining values for several options. These options go to the ''menus section'' as well.

{|border="1" cellpadding="4" cellspacing="0"
|-valign="top"
|grouping_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|This function determines how grouping is done. The following predefined functions can be used:
*"EPrints::Update::Views::group_by_a_to_z"
*"EPrints::Update::Views::group_by_first_character" (default)
*"EPrints::Update::Views::group_by_2_characters"
*"EPrints::Update::Views::group_by_3_characters"
*"EPrints::Update::Views::group_by_4_characters"
*"EPrints::Update::Views::group_by_5_characters"
with the usual meaning. If you use 'group_by_a_to_z', all entries not starting with a letter will be discarded.
|-valign="top"
|group_sorting_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|A custom function which sorts the group identifiers. The only available function
*"EPrints::Update::Views::default_sort"
sorts alphabetically.
|-valign="top"
|group_range_function <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|Splits the groups (as determined by the grouping function) into sections so that a group never splits. Groups are rendered separately, but a section is kept on a single page. Available grouping functions are
*"Eprints::Update::Views::no_ranges" (default)
*"EPrints::Update::Views::cluster_ranges_<range>"
where <range> is one of 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, and 200.
|-valign="top"
|open_first_section <sup style="font-weight:bold; font-size:10px;">(M)</sup>
|if set, the first section is included in the front page.
|}

==Phrases==

Views can have their own titles and other phrases. If they do not exist, then a default one is used (usually containing the view's id). For examples, see the views.xml file.

{|border="1" cellpadding="3" cellspacing="0"
|-valign="top"
|viewname_eprint_<viewid>
|the name of the browse pages
|-valign="top"
|viewintro_<viewid>
|The phrase to replace the text "Please select a value to browse from the list below." in the top level menu
|-valign="top"
|viewintro_<viewid>/<value>
|Intro phrase on the next level
|-valign="top"
|viewtitle_eprint_<viewid>_menu_<level>
|Title of browse page at level <level>, which is 1, 2, ... In the phrase you can use the pins "value1", "value2", etc. where the number can be one less than the present level; the value of the pin is the actual value of the previous levels. See the example below.
|-valign="top"
|viewgroup_eprint_<viewid>_<filename>
|Used as a pin value for the title on the list pages, when [[#Variations|variations]] are used. <Filename> is the filename defined as the option of the variation, or, if it is not defined, then it is the fieldname at the beginning.
|-valign="top"
|viewtitle_eprint_<viewid>_list
|Title of the list pages of the view. You can use the same pins as before ("value1", "value2", etc.). If the list was generated by a [[#Variations|variation]] then the "grouping" pin is also available.
|}

The following example shows how to define these values.
<epp:phrase id="viewname_eprint_divisions">Divisions</epp:phrase>
<epp:phrase id="viewtitle_eprint_divisions_menu_1">
Browse by Division and Year</epp:phrase>
<epp:phrase id="viewtitle_eprint_divisions_menu_2">
Browse by Year where Division is
<epc:pin name="value1" /> </epp:phrase>

==Other==

{|border="1" cellpadding="4" cellspacing="0"
|heading_level
| ?
|-
|include
| ?
|-
|subheadings
| ?
|-
|nohtml
| ?
|-
|noindex
| ?
|}

=Example=
==EPrints 3.2 example==
===cfg/cfg.d/views.pl===
{ id => "target", # The 'name' for this view
allow_null => 0,
hide_empty => 1,
menus => [
{ fields => ["broker_reponame"], # The field(s) to use - in this case the 'reponame' sub-element of the 'broker' field
new_column_at => [0], # force 2 columns, even if the
# second is blank
mode => "sections",
open_first_section => 1,
group_range_function => "EPrints::Update::Views::cluster_ranges_30",
group_sorting_function => "EPrints::Update::Views::default_sort",
},
],
order => "-date/title",
citation => 'router', # This defines the file in cfg/citations/eprint/
layout => 'router', # This is used in Views.pm to determine how to
# join individual citations together...
},

This creates a view, which will be 2-columns wide.
Two important definitions here are:
* '''citation''' defines the citation file used to create the block of html for each record to be displayed, and
* '''layout''' indicates how those blocks are joined together.

====Layout====
'''Layout''' can be one of:
* paragraph (the default)
puts <p> elements round each citation

* orderedlist
makes an ordered list (1,2,3,4 or whatever the CSS defines)

* unorderedlist
makes an unordered list

* ''anything else''
just puts a newline (in the page source) after each citation

====citation====
In our example, we're using a home-made citation layout

The citation file is in <code>/cfg/citations/eprint/</code>

In the above view, we have defined the citation format to be '''router''', therefore we need a file called '''router.xml''' in the citations directory.

Remember this format is used for each record, so needs to be complete in it's own right - and if you want records to line up vertically, you need to plan that in advance.

<?xml version="1.0" ?>

<cite:citation xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://eprints.org/ep3/control" xmlns:cite="http://eprints.org/ep3/citation" >
<table class='ep_rt_citation'>;
<tr><td colspan='2'>
<choose>
<when test="type = 'book' and is_set( creators )">
<span class='strong'><print expr="creators_name"/></span>
</when>
.... more code ....
</choose>
</td><td style="width:8em">
<if test="date"><span class='right strong'>(<print expr="date" opts="res=year"/>)</span></if>
</td></tr>
<tr><td style="width:50%">
<cite:linkhere><xhtml:em><print expr="title" opts="magicstop"/></xhtml:em></cite:linkhere>
</td>
<choose>
.... more code
<when test="type = 'article'">
<td>
<if test="publication"><print expr="publication"/>
<if test="volume">, <print expr="volume"/></if>
<if test="number"> (<print expr="number"/>)</if>
.</if>
<if test="pagerange"> <print expr="pagerange"/>.</if>
</td><td>
<if test="issn"><span class='right'> ISSN <print expr="issn"/></span></if>
</td>
</when>
.... more code
</choose>
</tr>
<if test=" ! type.one_of( 'patent','thesis' )">
<if test="ispublished.one_of('unpub', 'submitted', 'inpress')">
<tr><td colspan='2'>
(<print expr="ispublished"/>)
</td></tr>
</if>
</if>
</table>
</cite:citation>

This creates a table for each record, and CSS is used to manage the size & position of the various elements

===cfg/cfg.d/eprint_render.pl===
When viewing a record, the main abstract view page can also be altered

In <code>cfg/cfg.d/eprint_render.pl</code>, towards the bottom of the subroutine <code>$c->{eprint_render}</code> is the following line:

my $page = $eprint->render_citation( "router_page", %fragments, flags=>$flags );

Here, '''router_page''' is the name of the citation file for creating the abstract page..... '''router_page.xml''' in this case

Installing EPrints on Debian/Ubuntu

2025-04-09T19:21:17Z

Libjlrs: /* Configuration */

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 20.04 LTS, 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 10 (Buster), Debian 11 (Bullseye) or Debian 12 (Bookworm) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints ('''N.B.''' Some dependencies may not be able in certain versions of Debian/Ubuntu. See [[#Operating System Version Specific Requirements|Operating System Version Specific Requirements]] towards the end of this page):

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-binaries psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl python3-html2text make libexpat1-dev libxslt1-dev

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client libmysqlclient-dev

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client libmariadb-dev

Next, create the eprints user

useradd eprints

Now add the eprints user to the www-data group and vice-versa

usermod -a -G eprints www-data
usermod -a -G www-data eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt install git
mkdir /opt/eprints3
chown eprints:eprints /opt/eprints3
chmod 2775 /opt/eprints3
su eprints
git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.4.6

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz
tar -xzvf eprints-3.4.6.tar.gz

Then put in the source code in place:

mv eprints-3.4.6 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) packages will no longer be produced. Due to the complexity of the installation process there are a number of inherent problems with installing using a Deb package. As new operating systems (e.g. Debian and Ubuntu) are released the available packages have changed. This often leads to packages upon which that EPrints depends ceasing to be available. This makes it very difficult or impossible to install the Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian package is likely to lead to EPrints producing errors, as configuration changes are often required as part of the upgrade process. Automating these changes within the Debian package would be all but impossible due to EPrints' high level of customisability.

== Configuration ==
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>, if it does not already exist.

<code>EPRINTS_PATH</code> will be either <code>/opt/eprints3/</code>, <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

root> a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 restart

You should now be able to access your vanilla repository at the hostname you specified when running '''epadmin create''' from the [[Getting Started with EPrints 3]] instructions. You should then login as the admin user you created during this process and turn on the indexer. This can be done by clicking on the '''Admin''' link under the Logged in menu, then clicking on the '''System Tools''' tab and finally the '''Start Indexer''' button.

== Operating System Version Specific Requirements ==

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Ubuntu 24.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 24.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on Debian/Ubuntu

2025-04-09T10:54:08Z

Libjlrs: /* Post-configuration */

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 20.04 LTS, 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 10 (Buster), Debian 11 (Bullseye) or Debian 12 (Bookworm) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints ('''N.B.''' Some dependencies may not be able in certain versions of Debian/Ubuntu. See [[#Operating System Version Specific Requirements|Operating System Version Specific Requirements]] towards the end of this page):

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-binaries psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl python3-html2text make libexpat1-dev libxslt1-dev

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client libmysqlclient-dev

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client libmariadb-dev

Next, create the eprints user

useradd eprints

Now add the eprints user to the www-data group and vice-versa

usermod -a -G eprints www-data
usermod -a -G www-data eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt install git
mkdir /opt/eprints3
chown eprints:eprints /opt/eprints3
chmod 2775 /opt/eprints3
su eprints
git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.4.6

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz
tar -xzvf eprints-3.4.6.tar.gz

Then put in the source code in place:

mv eprints-3.4.6 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) packages will no longer be produced. Due to the complexity of the installation process there are a number of inherent problems with installing using a Deb package. As new operating systems (e.g. Debian and Ubuntu) are released the available packages have changed. This often leads to packages upon which that EPrints depends ceasing to be available. This makes it very difficult or impossible to install the Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian package is likely to lead to EPrints producing errors, as configuration changes are often required as part of the upgrade process. Automating these changes within the Debian package would be all but impossible due to EPrints' high level of customisability.

== Configuration ==
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>, if it does not already exist.

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

root> a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 restart

You should now be able to access your vanilla repository at the hostname you specified when running '''epadmin create''' from the [[Getting Started with EPrints 3]] instructions. You should then login as the admin user you created during this process and turn on the indexer. This can be done by clicking on the '''Admin''' link under the Logged in menu, then clicking on the '''System Tools''' tab and finally the '''Start Indexer''' button.

== Operating System Version Specific Requirements ==

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Ubuntu 24.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 24.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Installing EPrints on Debian/Ubuntu

2025-04-09T10:53:59Z

Libjlrs: /* Post-configuration */

[[Category:Debian and Ubuntu]]
[[Category:Installation]]

== Requirements ==
* Ubuntu 20.04 LTS, 22.04 LTS and Ubuntu 24.04 LTS (non-LTS versions not recommended)
* Debian 10 (Buster), Debian 11 (Bullseye) or Debian 12 (Bookworm) - These are not as comprehensively tested as Ubuntu LTS versions.

== Installing EPrints from Source ==

=== Dependencies and Pre-configuration ===
'''The ideal way to install from source is via git using the Core Git repositories [https://github.com/eprints/eprints3.4 EPrints 3.4] or [https://github.com/eprints/eprints EPrints 3.3], and installing from a source tarball is generally discouraged.'''

'''Installing from source via git is now the recommended way to install EPrints for production repositories, after having proved to be a useful installation method to those seeking to develop the EPrints code, develop a plugin or develop a Bazaar package too.'''

First, as the root user install all the dependencies for EPrints ('''N.B.''' Some dependencies may not be able in certain versions of Debian/Ubuntu. See [[#Operating System Version Specific Requirements|Operating System Version Specific Requirements]] towards the end of this page):

apt-get install perl libncurses5 libselinux1 apache2 libapache2-mod-perl2 libxml-libxml-perl \
libunicode-string-perl libterm-readkey-perl libmime-lite-perl libmime-types-perl libdigest-sha-perl \
libdbd-mysql-perl libxml-parser-perl libxml2-dev libxml-twig-perl libarchive-any-perl libjson-perl \
liblwp-protocol-https-perl libtext-unidecode-perl lynx wget ghostscript poppler-utils antiword elinks \
texlive-base texlive-binaries psutils imagemagick adduser tar gzip unzip libsearch-xapian-perl \
libtex-encode-perl libio-string-perl python3-html2text make libexpat1-dev libxslt1-dev

If you are installing on Ubuntu, install MySQL server and client:

apt-get install mysql-server mysql-client libmysqlclient-dev

If you are installing on Debian, install MariaDB server and client:

apt-get install mariadb-server mariadb-client libmariadb-dev

Next, create the eprints user

useradd eprints

Now add the eprints user to the www-data group and vice-versa

usermod -a -G eprints www-data
usermod -a -G www-data eprints

=== Downloading and Deploying EPrints Source ===

==== EPrints 3.4.x for GitHub ====

apt install git
mkdir /opt/eprints3
chown eprints:eprints /opt/eprints3
chmod 2775 /opt/eprints3
su eprints
git clone https://github.com/eprints/eprints3.4.git /opt/eprints3
cd /opt/eprints3/
git checkout tags/v3.4.6

==== EPrints 3.4.x from files.eprints.org ====

cd /tmp/
wget https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz
tar -xzvf eprints-3.4.6.tar.gz

Then put in the source code in place:

mv eprints-3.4.6 /usr/share/eprints
chmod 2775 /usr/share/eprints
chown -R eprints:eprints /usr/share/eprints

If you want a publications flavoured repository, then also:

wget https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz
tar -xzvf eprints-3.4.6-flavours.tar.gz
mv eprints-3.4.6/flavours/pub_lib /usr/share/eprints/flavours
chmod -R g+w /usr/share/eprints/flavours/pub_lib
chown -R eprints:eprints /usr/share/eprints/flavours/pub_lib

== Installing from Debian package ==
As of EPrints 3.4.5 Debian (.deb) packages will no longer be produced. Due to the complexity of the installation process there are a number of inherent problems with installing using a Deb package. As new operating systems (e.g. Debian and Ubuntu) are released the available packages have changed. This often leads to packages upon which that EPrints depends ceasing to be available. This makes it very difficult or impossible to install the Debian package, as well as requiring retrospective effort to install packages using other sources, (e.g. additional APT repositories or using CPAN). However, the main concern of installation the Debian package, particularly through EPrints' APT repository, is that it can lead to EPrints being upgraded automatically to a new version. Upgrading EPrints using a Debian package is likely to lead to EPrints producing errors, as configuration changes are often required as part of the upgrade process. Automating these changes within the Debian package would be all but impossible due to EPrints' high level of customisability.

== Configuration ==
Next, as the eprints user copy <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm.tmpl</code> to <code>EPRINTS_PATH/perl_lib/EPrints/SystemSettings.pm</code>, if it does not already exist.

<code>EPRINTS_PATH</code> will be either <code>/usr/share/eprints3/</code> or <code>/usr/share/eprints</code> depending on which instructions you followed above.

EPrints is now fully installed at <code>EPRINTS_PATH/</code>. However, you will not yet have a running archive. Follow the [[Getting Started with EPrints 3]] instructions to set this up.

=== Post-configuration ===
Next, add the file <code>/etc/apache2/sites-available/eprints.conf</code> with the following line:

Include EPRINTS_PATH/cfg/apache.conf

To enable this as root run the command:

root> a2ensite eprints

Also it may be necessary to disable the default site otherwise the default Apache page will still be shown:

a2dissite 000-default

Finally, restart Apache:

service apache2 restart

You should now be able to access your vanilla repository at the hostname you specified when running '''epadmin create''' from the [[Getting Started with EPrints 3]] instructions. You should then login as the admin user you created during this process and turn on the indexer. This can be done by clicking on the '''Admin''' link under the Logged in menu, then clicking on the '''System Tools''' tab and finally the '''Start Indexer''' button.

== Operating System Version Specific Requirements ==

=== Ubuntu 20.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 20.04}}

=== Ubuntu 22.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 22.04}}

=== Ubuntu 24.04 LTS ===
{{:Issues with Installing EPrints on Ubuntu 24.04}}

=== Debian Known Issues ===
See [[Debian Known Issues]]

Export bar on abstract page

2025-03-30T22:55:23Z

Libjlrs: Add a sort to the plugins to provide consistent ordering on item pages.

[[Category:Abstract Pages]]
{{Version|since=3.2.0}}

To add an export bar to the abstract page requires editing the eprint_render() method, eprint summary citation style and adding a CGI script to link the abstract page's form to the export URL.

===cgi/export_redirect===

<source lang="perl">
#!/usr/bin/perl

use strict;
use warnings;

use EPrints;

my $eprints = EPrints->new;
my $repo = $eprints->current_repository;
exit( 0 ) if !defined $repo;

my $id = $repo->param( "dataobj" );
my $format = $repo->param( "format" );

exit( 0 ) if !EPrints::Utils::is_set( $id );
exit( 0 ) if !EPrints::Utils::is_set( $format );

my $dataobj = $repo->dataset( "archive" )->dataobj( $id );
if( !defined $dataobj )
{
$repo->not_found( "eprint $id doesn't exist" );
exit( 0 );
}

my $plugin = $repo->plugin( "Export::".$format );
if( !defined $plugin )
{
$repo->not_found( "export format $format doesn't exist" );
exit( 0 );
}

$repo->redirect( $plugin->dataobj_export_url( $dataobj ) );
exit( 0 );
</source>

===archives/[repoid]/cfg/cfg.d/eprint_render.pl===

Somewhere in eprint_render.pl, below <em>my $fragments</em> add this:

<source lang='perl'>
my $export_bar = $session->make_element( "div", class => "ep_block" );
$fragments{export_bar} = $export_bar;
{
my @plugins = $session->get_plugins(
type => "Export",
can_accept => "dataobj/eprint",
is_advertised => 1,
is_visible => "all" );

# Added March 2025 - sort the plugins into a consistent order.
# You may also want to make a custom order somehow. The 'qs' parameter seems
# more focused on machine users than humans.
my %names = map { $_ => $_->get_name } @plugins;
@plugins = sort { $names{$a} cmp $names{$b} } @plugins;
# /End Added March 2025

my $uri = $session->get_url( path => "cgi" ) . "/export_redirect";
my $form = $session->render_form( "GET", $uri );
$export_bar->appendChild( $form );
$form->appendChild( $session->render_hidden_field( dataobj => $eprint->id ) );
my $select = $session->make_element( "select", name => "format" );
$form->appendChild( $select );
foreach my $plugin (@plugins)
{
my $plugin_id = $plugin->get_id;
$plugin_id =~ s/^Export:://;
my $option = $session->make_element( "option", value => $plugin_id );
$select->appendChild( $option );
$option->appendChild( $plugin->render_name );
}
my $button = $session->make_element( "input", type => "submit", value => $session->phrase( "lib/searchexpression:export_button" ), class => "ep_form_action_button" );
$form->appendChild( $button );
}
</source>

===archives/[repoid]/cfg/citations/eprint/summary_page.xml===

Where you want the export bar to appear add this:

<source lang='xml'>
<epc:print expr="$export_bar" />
</source>

Contact

2025-02-14T12:35:20Z

Libjlrs: /* eprints-tech Mailing List */

{{manual}}

==Bug Report Policy==

We use a [https://github.com/eprints/eprints/ Github] to record bugs and issues for EPrints. You can search there or the eprints-tech mailing list for existing bugs and possible solutions.

If you identify a new bug or "issue" (issues are not bugs, but are things which could be clearer or better) please post a message to the eprints-tech mailing list - include all the information you can: what version of eprints, operating system etc.

If you think the bug has security implications (i.e. it shouldn't be made public) please email [mailto:support@eprints.org support@eprints.org].

== [[eprints-tech Mailing List]] ==

[https://www.eprints.org/eptech/ eprints-tech] is the mailing list for technical queries or feedback. It can also have general queries, but most traffic is of a technical nature.

{{EPrints-tech Subscription}}

For more options to manage your subscription to the eprints-tech list [[eprints-tech Mailing List#Subscription Options|click here]].

{{EPrints-tech Archive}}

== Twitter==

The following twitter accounts and hashtags are currently used:

* [http://twitter.com/EPrints @EPrints] - EPrints twitter account
* [http://twitter.com/EPrintsServices @EPrintsServices] - EPrints Services twitter account
* [http://twitter.com/hashtag/EPrints #EPrints] - EPrints Hashtag

== EPrints User Groups ==

For general or language dependent EPrints discussion

* [[German_User_Group|DE]]
* [https://groups.google.com/forum/#!forum/eprints-uk-user-group UK]

Upgrading 3.3.12+ to 3.4

2025-02-11T12:59:58Z

Libjlrs: /* Notes */

These instructions help you upgrade EPrints 3.3.16+ (or any newer version of EPrints 3.3) to EPrints 3.4 while keeping all your eprints, documents and local configuration changes.

It assumes your EPrints 3.3.16+ was installed using a tarball (tar.gz) file and installed in <code>/opt/eprints3</code>. The commands in these instructions assume Centos 7 OS and run as the eprints user, unless it is stated to run as the root user.

=Upgrade from Tarball=

==Pre-upgrade==
* If you have local modifications to the core files (in /opt/eprints3/perl_lib), you may need to manually migrate your changes.
* If you use Twitter integration, use CPAN to install LWP::Authen::OAuth as this is no longer in perl_lib. To do so, as root run:
cpan LWP::Authen::OAuth
* Download each of the Bazaar plugins you have installed as EPM files from your existing repository.
* Make a backup of your local configurations.

==Process==
We will move your existing eprints 3.3.16+ installation from <code>/opt/eprints3/</code> to <code>/opt/eprints3.3</code>, install eprints 3.4, then migrate your configurations into EPrints 3.4; cf. [https://wiki.eprints.org/w/Category:Installation Category Installation]
<br>
'''as root'''
apachectl stop
cd /opt
eprints3/bin/epindexer stop
mv eprints3 eprints3.3

* Download EPrints 3.4 core and publication flavour tarball and install them from [http://files.eprints.org/ Files.eprints.org] with
wget https://files.eprints.org/3097/5/eprints-3.4.6.tar.gz
wget https://files.eprints.org/3097/6/eprints-3.4.6-flavours.tar.gz
'''as root'''
cd /root
tar xvzf eprints-3.4.6.tar.gz
tar xvzf eprints-3.4.6-flavours.tar.gz

* Have a look to <code>/root/eprints-3.4.6/INSTALL</code> for some local adaption options.
'''as root'''
cd eprints-3.4.6
./configure
make install

* Move your current repository from 3.3 to 3.4
'''as root'''
cd /opt
mv eprints3.3/archives/ARCHIVENAME eprints3/archives/
* After moving, make sure all files inside <code>/opt/eprints3</code> are still owned by eprints user and belongs to eprints group, thus
'''as root'''
chown -R eprints:eprints /opt/eprints3

* Create <code>/opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl</code> to set the appropriate flavour, typically 'pub', i.e.
echo "\$c->{flavour} = 'pub';" > /opt/eprints3/archives/ARCHIVENAME/cfg/cfg.d/00_flavour.pl

* create a symbolic link to <tt>default.xml</tt>
cd /opt/eprints3/archives/ARCHIVENAME/cfg/templates/ (or /opt/eprints3/archives/ARCHIVENAME/cfg/lang/en/templates/
ln -s default.xml default_internal.xml

* Audit each of their local config files against the pub_lib flavours config files:
#The first <code>diff</code> below will identify all the files that are the same. If so, delete the ones in <code>archives/ARCHIVENAME/cfg/cfg.d/</code>. You almost certainly should not find any, as the files in <code>flavours/pub_lib/cfg.d</code> will at very least have updated copyright/licensing boilerplate.
#The second <code>diff</code> will find where files exists in both directory are different. Here they should be compared to see, if the local differences are superficial (e.g. slightly different comments or spacing) and therefore can be removed. Also the pub_lib flavour version may fix an outstanding bug or perform the required functionality more succinctly. If this is the only change, then the local archive version can be deleted, otherwise the change should be incorporated in the local version.
cd /opt/eprints3/
diff -rs archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ are identical$'
diff -rq archives/ARCHIVENAME/cfg/cfg.d flavours/pub_lib/cfg.d | egrep '^Files .+ and .+ differ$'

<ul><li>Compare <code>archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl</code> with <code>flavours/pub_lib/cfg/cfg.d/eprint_fields_pub.pl</code> maybe with the help of [http://diffuse.sourceforge.net/download_de.html ''diffuse''] to overcome this business easier:<ul>
<li>If these are different and fields are present in <code>eprint_fields_pub.pl</code> and not <code>eprint_fields.pl</code> or the definitions (e.g. type, options, etc.) for the same field are different then:<ol>
<li>Copy <code>flavours/pub_lib/cfg.d/eprint_fields_pub.pl</code> to their archive's <code>cfg/cfg.d/</code>.
<li>Modify the fields in their archive's <code>cfg/cfg.d/eprint_fields_pub.pl</code> where they have different definitions (e.g. type, options, etc.) to those in <code>eprint_fields.pl</code>.
<li>Remove all fields in their archive's <code>cfg/cfg.d/eprint_fields.pl</code> where they also occur in their archive's <code>cfg/cfg.d/eprint_fields_pub.pl</code>, no matter if already transferred due to previous item or initially the same.</ol>
<li>If there are only additional fields in <code>archives/ARCHIVENAME/cfg/cfg.d/eprint_fields.pl</code> then just do the last step.
<li>If the two files are identical then you need to do nothing. However, this is extremly unlikely.
</ul>
Finally, the specification is still the same, but mostly split into two distinct files, which obey the known rule ''Local version overrides central one''.</ul>
* Synchronise <code>archives/ARCHIVENAME/cfg/cfg.d/epm.pl</code> with <code>ingredients/bazaar/cfg.d/epm.pl</code>, i.e. remove <code>archives/ARCHIVENAME/cfg/cfg.d/epm.pl</code> in case of ''no'' local modifications.

* Ensure the following bazaar files are disabled by renaming to FILENAME.pl''.disabled''. Once they have been reinstalled via the Bazaar then they can be moved back into place. Using <code>epadmin test</code> is a good way of discovering which files need this doing, but below is a list of common files that should be temporarily moved, if they exist in your archive's <code>cfg/cfg.d/</code> directory:
mv z_orcid_support.pl z_orcid_support.pl.disabled
mv zz_hefce_oa_fields.pl zz_hefce_oa_fields.pl.disabled
mv zz_rioxx2.pl zz_rioxx2.pl.disabled
mv z_meprints.pl z_meprints.pl.disabled

* As the eprints user, run <code>epadmin update</code> to add any new fields that were not previously present (typically this is embargo_reason for documents and requester_email for request)
/opt/eprints3/bin/epadmin update ARCHIVENAME

* Generate new Apache configuration and as root test (fixing any issues) and restart Apache after necessary site-specific adaption are done.
/opt/eprints3/bin/generate_apacheconf --system --replace ARCHIVENAME
'''as root'''
apachectl configtest
apachectl restart

* Once confirming that EPrints is generally working. Go to Admin->Bazaar then install the Bazaar plugins you downloaded from your 3.3 repository before starting the upgrade process. This can be done by going to the Available tab in the Bazaar and strolling to the Upload section at the bottom. Unfortunately, you cannot do a bulk upload, so will need to install each plugin in turn.

* Move back the files you renamed to FILENAME''.disabled'' earlier, the epindexer into service and reload Apache
'''as root'''
/opt/eprints3/bin/epindexer start
apachectl graceful

* Finally, run <code>generate_static</code> to make sure all pages are regenerated with any changes to configuration.
/opt/eprints3/bin/generate_static ARCHIVEID

==Notes==
* EPrints 3.4.4+ now uses LONGTEXT instead of VARCHAR(255) for the <code>requester_user_agent</code> column. Upgrading from v3.3 '''will not''' automatically update this column definition in the database. Manually altering the column is an option, but may take a long time as the access table can contain millions of rows. See: https://github.com/eprints/eprints3.4/issues/427
* 3.4 does not automatically update an archive's <code>html/en/</code> files. If there are any bugs with broken JavaScript or unexpected CSS, try deleting the archives <code>html/en/javascript/auto.js</code> or <code>html/en/style/auto.css</code>. Similarly if a static page cannot be changed try deleting it under the archive's <code>html/en/</code> or running <code>generate_static</code>.
* If some Perl modules are giving out error messages like:
Can't locate object method "new" via package "EPrints::Plugin::Event::PIRUS" at /opt/eprints3/bin/../perl_lib/EPrints/PluginFactory.pm line 276.
Can't locate object method "new" via package "EPrints::Plugin::Screen::EPrint::Box::Tools::SUPER" at /opt/eprints3/site_lib/plugins/EPrints/Plugin/Screen/EPrint/Box/Tools.pm line 12.
It is because their parent module has not been initialised. This happens when the parent module lives in perl_lib, and the problem module live in elsewhere; e.g. parent module of PIRUS(Event.pm) is in <code>./perl_lib</code>, while the <code>PIRUS.pm</code> is in <code>./pub_lib</code>.
Just need to <code>use</code> the parent module before the <code>ISA</code> line:
use EPrints::Plugin::Event;

[[Category:Upgrading]]

Cron Events and Simple email Reports

2025-01-29T09:52:14Z

Libjlrs:

[[Category:EPrints_Bazaar]]
'''NOTE''' On EPrints v3.3.14 and lower, day-of-week or day-of-month events may actually run on a daily basis. See: https://github.com/eprints/eprints/issues/313 for details and patches.

In this exercise we are going to create an Event plug-in which will run every day and produce a report of all the EPrints which have been added in the last day.

= Step 1: Create the Event Plug-In =

In the lib/plugins/EPrints/Plugin/Event directory create your main plugin with the following:

<source lang=perl>
package EPrints::Plugin::Event::EPrintsReportEx;

use EPrints::Plugin::Event;

@ISA = qw( EPrints::Plugin::Event );

sub action_send_email
{
my ( $self ) = @_;

}

sub generate_content
{
my ( $self ) = @_;

}

1;
</source>

= Step 2: Create your package =

Create your package and don't forget to enable the Event Plugin according to http://wiki.eprints.org/w/My_First_Bazaar_Package

= Step 3: Search for EPrints Added in the Last Day =

In your event fill the <code>generate_content</code> routine with the following:

<source lang=perl>
my $repository = $self->{repository};
my $xml = $repository->xml;

my $content = $xml->create_document_fragment();
my $h1 = $xml->create_element("h1");
$content->appendChild($h1);
$h1->appendChild($repository->make_text("EPrints Added in the Last Day"));

my $ds = $repository->dataset( "eprint" );

my $date = time() - 86400; # 1 day ago
$date = EPrints::Time::iso_date( $date ) . " 00:00:00";

my $eprint_section;

$ds->search(
custom_order => "-datestamp",
)->map(sub {
my( undef, undef, $item ) = @_;
return if(!defined $item);

my $ep_date = $item->get_value("datestamp");

last if($ep_date lt $date);

if( !defined $eprint_section )
{
$eprint_section = $xml->create_document_fragment();
}
$eprint_section->appendChild( $item->render_value("title") );
$eprint_section->appendChild( $item->render_citation_link() );
$eprint_section->appendChild( $repository->make_text(" (") );
$eprint_section->appendChild( $item->render_value("eprint_status") );
$eprint_section->appendChild( $repository->make_text(")") );
$eprint_section->appendChild( $xml->create_element("br") );
$eprint_section->appendChild( $xml->create_element("br") );

});

if( defined $eprint_section ) {
$content->appendChild($eprint_section);
} else {
$content->appendChild($repository->make_text("Nothing has happened!"));
}

return $content;
</source>

=Step 4: Email the report to the repository admins=

In the <code>action_send_email</code> sub routine, add the following code:

<source lang=perl>
my $repository = $self->{repository};

my $mail_body = $self->generate_content();
my $subject = "id/report_email_title";

my $ds = $repository->dataset( "user" );

$ds->search(
filters => [
{ meta_fields => [qw( usertype )], value => "admin" },
],
)->map(sub {
my( undef, undef, $user ) = @_;
$user->mail( $subject, $mail_body,undef,undef );
});

return 1;
</source>

= Step 5: Set up the crontab to email you this report =

In order to set up the cron event we need to add some code to an EPMC screen related to this package, follow the instructions @ http://wiki.eprints.org/w/XML_manipulation_of_the_EPrints_Workflow_using_a_Bazaar_Package on creating an EPMC screen with and enable and disable method.

To enable cron we need to add the following to the enable method:

<source lang=perl>
EPrints::DataObj::EventQueue->create_unique( $repository, {
pluginid => "Event",
action => "cron",
params => [
"0,15,30,45,60 * * * *",
"Event::EPrintsReportEx",
"action_send_email",
],
});
</source>

This will send you an update email every 15 minutes, note that EPrints uses the standard cron syntax so you can change this as you will.

A guide on using cron can be found @ http://en.wikipedia.org/wiki/Cron

We also need to disable this event again when the package is removed, to do this add the following to the disable method:

<source lang=perl>
my $event = EPrints::DataObj::EventQueue->new_from_hash( $repository, {
pluginid => "Event",
action => "cron",
params => [
"0,15,30,45,60 * * * *",
"Event::EPrintsReportEx",
"action_send_email",
],
});
$event->delete if (defined $event);
</source>

Note that the 2 events and cron syntax's MUST match.

= Step 6 - Package Test and Wait for Email =

Finish up, package and enable your code. Note that we have not defined any nice phrases here that will be needed to make a proper package.

API:EPrints/Plugin/Search/Xapian

2025-01-28T12:40:46Z

Libjlrs: /* DESCRIPTION */ Default qs for 'Internal' search is 0, so setting a value of 0.1 as previously suggested doesn't stop if being used. Now suggests a value of -1.

{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Plugin/Search/Xapian.pm|package_name=EPrints::Plugin::Search::Xapian}}[[Category:API|XAPIAN]][[Category:API:EPrints/Plugin/Search|XAPIAN]][[Category:API:EPrints/Plugin/Search/Xapian|XAPIAN]]<div>


==NAME==
EPrints::Plugin::Search::Xapian





==DESCRIPTION==
<pre> Xapian is a highly adaptable toolkit which allows developers to easily add
advanced indexing and search facilities to their own applications. It supports
the Probabilistic Information Retrieval model and also supports a rich set of
boolean query operators.</pre>

Xapian currently only supports simple searches.

Xapian simple searches are parsed by the Xapian query parser which supports prefixes for search terms:

<pre> title:(eagle buzzard) abstract:"london wetlands"</pre>

The field prefixes are taken from the search configuration and constrain the following term (or bracketed terms) to that field only. If no prefix is given the entire Xapian index will be used i.e. it will search any indexed term, not just those from the search configuration fields. For example, the following simple search configuration:

<pre> search_fields => [
{
id => "q",
meta_fields => [
"documents",
"title",
"abstract",
"creators_name",
"date"
]
},
],</pre>

Allows the user to specify "documents", "title", "abstract", "creators_name" or "date" as a prefix to a search term. Omitting a prefix will match any field e.g. "publisher".

Terms can be negated by prefixing the term with '-':

<pre> eagle -buzzard</pre>

Phrases can be specified by using quotes, for example "Southampton University" won't match <em>University of Southampton</em>.

Terms are stemmed by default ('bubbles' becomes 'bubble') except if you use the term in a phrase.

Partial matches are supported by using '*':

<pre> ameri* - americans, americas, amerillo etc.</pre>

Xapian search results are returned in a sub-class of [[API:EPrints/List|EPrints::List]] (a wrapper around a Xapian enquire object). Calling [[API:EPrints/List#count|EPrints::List/count]] will return an '''estimate''' of the total matches.

As Xapian has a higher 'qs' score than Internal it will (once enabled) override the default EPrints simple search. You can override this behaviour in '''cfg.d/plugins.pl''':

<pre> $c->{plugins}{'Search::Xapian'}{params}{qs} = -1;</pre>

Or disable completely (including disabling indexing):

<pre> $c->{plugins}{'Search::Xapian'}{params}{disable} = 1;</pre>






==USAGE==
Install the [http://search.cpan.org/search?query=xapian&mode=dist Search::Xapian] extension. Note: there are two Perl bindings available for Xapian. The CPAN version is older and based on Perl-XS. xapian-bindings-perl available from xapian.org is based on SWIG and has better coverage of the API. Regardless, for the best feature support/performance it is highly recommended to have the latest stable version of the Xapian library.

Xapian uses a separate (from MySQL) index that is stored in <tt>archives/''[archiveid]''/var/xapian</tt>. To build the Xapian index you will need to reindex:

<pre> ./bin/epadmin reindex [archiveid] eprint</pre>

(Repeat for any other datasets you expect to use Xapian with.)

The <tt>var/xapian/</tt> directory should contain something like:

<pre> flintlock position.baseA position.DB postlist.baseB
record.baseA record.DB termlist.baseB
iamchert position.baseB postlist.baseA postlist.DB
record.baseB termlist.baseA termlist.DB</pre>

The indexing process for Xapian is in <tt>lib/cfg.d/search_xapian.pl</tt>. This can be overridden by dropping the same-named file into your repository <tt>archives/''[archiveid]''/cfg.d/</tt>. If the Xapian search is not matching what you might expect it to, you probably need to fix the indexing process (and re-index!). Terms indexed by Xapian can also be weighted to e.g. give names a higher weighting than abstract text.

You will need to restart your Apache server to enable the Xapian search plugin and dependencies.

If the Xapian search is working correctly you will have a "by relevance" option available in the ordering of simple search results.





===Lock Files===
Xapian maintains a lock file in <tt>archives/''[archiveid]''/var/xapian</tt>. If you see indexing errors about not being able to lock the database ensure you aren't running multiple copies of the EPrints [http://wiki.eprints.org/w/API:bin/indexer indexer]. If no other processes are running you may need to manually remove the lock file from the <tt>var/xapian</tt> directory. While only one process may modify the Xapian index at a time, any number of processes may concurrently read.






==PARAMETERS==
* lang
: Override the default language used for stemming.

* stopwords
: An array reference of stop words to use (defaults to English).





==METHODS==

===stemmer===

<source lang="perl">$stemmer = $plugin->stemmer()

</source>
Returns a {{API:PodLink|file=Search/Xapian/Stem|package_name=Search::Xapian::Stem|section=|text=Search::Xapian::Stem}} for the default language.





===stopper===

<source lang="perl">$stopper = $plugin->stopper()

</source>
Returns a {{API:PodLink|file=Search/Xapian/SimpleStopper|package_name=Search::Xapian::SimpleStopper|section=|text=Search::Xapian::SimpleStopper}} for <code>stopwords</code>.





==COPYRIGHT==
Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.

Miscellaneous Config Options/get users owned eprints

2024-07-26T14:33:21Z

Libjlrs: /* Example */

This example should work with v3.4.6+.

Prior to v3.4.6 defining this method resulted in unexpected behaviour when eprint_status checkboxes were used on the ''Manage deposits'' page.

== Example ==
$c->{get_users_owned_eprints} = sub
{
my( $session, $user, %opts ) = @_;
# for non-editorial accounts, return the normal list
if( $user->get_type ne "editor" )
{
return $user->owned_eprints_list_actual( %opts );
}
# only interested in editor accounts now
# allow editors to see their items, and items from a specific userid e.g. 99999
my $extra_userid = 99999;
my $searchexp = $opts{dataset}->prepare_search( %opts );
$searchexp->add_field( $opts{dataset}->field( "userid" ), $user->id . " $extra_userid", "IN", "ANY" );
return $searchexp->perform_search;
};

Adding multilang fields

2024-02-08T14:00:54Z

Libjlrs: Add another note about return value

[[Category:Howto]]

EPrints' builtin fields are not multilingual, in the sense that there is only one version of each field -indirectly this means one language support. This page explains how to add multilingual versions of existing fields in EPrints and how they can be integrated with its subsystems.

== Multilang fields and EPrints ==
EPrints supports the '''multilang''' field type (see [[API:EPrints/MetaField/Multilang]] for more details) which allows a user to insert different content for different languages. There are a few limitations with '''multilang''' fields though:

* When its value is printed it is shown in all languages containing content.
* If a basic EPrints field's type is replaced to become '''multilang''' (like '''title''' and '''abstract'''), EPrints functionality breaks because it expects a single output.

To address these limitations. this article explains how we can replace a basic field, the '''title''' field as an example, with a multilingual one.

== Warning for already populated repositories ==
Once you follow this article's procedure, '''existing titles and abstracts''' will not be copied into their multilingual counterparts and '''access to them via the API will be lost'''! The users of this plugin are requested to use EPrints API to copy the values from the old fields to the new ones. A script that copies the '''title''' value of each eprint to '''ml_title''' field's '''en''' and '''el''' languages can be found here:[https://github.com/mamalos/eprints/blob/master/help_scripts/set_ml_title.pl]. Please, use this script at your own risk and don't forget to change its content to reflect the languages of your repository. The same script can be used for copying the '''abstract''' field's values to '''ml_abstract''' '''en''' and '''el''' by replacing title with abstract in this script.

== How to add a custom, multilingual field ==
Replacing an EPrints basic field, like the '''title''' field, involves a few steps. First, a new field needs to be created that will be able to store information for different languages; this field will be of type '''multilang'''. Next, the basic field's type needs to be replaced with one that is able to use our newly created field as its storage place. This field type will use a function wrapper for storing and retrieving information from the '''multilang''' field, hence the '''title''' field will become a calculated field.

So, in order to add multilingual support for the '''title''' field, the following actions need to take place:

* A ''new field type needs to be created'' that will help our '''title''' field to implement some of EPrints logic. Our field type is called '''virtualwithvalue'''.
* A ''new '''multilang''' field needs to be created'' that will store our multilingual information. We will call this field '''ml_title'''.
* '''''ml_title''' field and '''title''' field's functionality need to be introduced to the EPrints system'' via a configuration file located in '''~eprints/archives/<reponame>/cfg/cfg.d/'''.
* ''EPrints' database needs to be updated'' to include the new field.
* ''The appropriate phrases need to be added'' for the '''ml_title''' field on each supported language.
* ''The '''title''' field needs to be replaced'' with '''ml_title''' field in the workflow.
* '''''ml_title''' field in the workflow will needs a custom lookup script''.
* ''The '''title''' field needs to be replaced with the '''ml_title''' field in the simple and advanced search scripts''.
* The ''repository needs to be reloaded''.
* ''Static files need to be regenerated'' if our repository already contains data.
The following sections explain each step in detail, and ''title''' and '''ml_title''' are used as our example fields. The code snippets are just for demonstration purposes - and proof of concept. If you want to see the final, working implementation, you should look at the source code of the [[MultiLang_Fields_Bazaar_Package]] plugin.

== Adding a new field type (VirtualWithValue)==
In order to create a multiple-language field we have to create an appropriate field type. EPrints' '''MetaField''' (see [[API:EPrints/MetaField|MetaField]] article for details) is a perfect candidate for this, and we need to extend it and override its '''get_value''' and '''set_value''' functions for the field to work properly with the rest of EPrints API, as well as its '''get_property_defaults''' function to sort out warnings for default values. The following code could be a rough implementation of such a field:

<source lang="perl">package EPrints::MetaField::Virtualwithvalue;

use strict;
use warnings;

use EPrints::MetaField;

our @ISA = qw( EPrints::MetaField );

use strict;

sub get_property_defaults
{
my ( $self ) = @_;
my %defaults = $self->SUPER::get_property_defaults;
$defaults{get_value} = $EPrints::MetaField::UNDEF;
$defaults{set_value} = $EPrints::MetaField::UNDEF;

return %defaults;
}

sub get_value
{
my( $self, $object ) = @_;
if ( defined $self->get_property("get_value") )
{
return $self->call_property( "get_value", $object);
}
return undef; # This is important. Using just a 'return;' or no return statement may break your repository e.g. when an EPrint revision file tried to be created.
}

sub set_value
{
my( $self, $object, $value ) = @_;
if ( defined $self->get_property("set_value") )
{
return $self->call_property( "set_value", $object, $value);
}
return undef;
}

</source>

We could save this file in '''~eprints/lib/plugins/EPrints/MetaField/Virtualwithvalue.pm'''.

== Introducing ml_title field in EPrints and replacing title field's type==
To inform EPrints about our new field (that will be of type '''virtualwithvalue'''), we should create a configuration file, eg: '''~eprints/archives/<reponame>/cfg/cfg.d/zz_multilang_field.pl''' with content like the following:

<source lang='perl'>
#define local fields
my $local_fields = [
{
name => 'ml_title',
type => 'multilang',
multiple => 1,
fields => [ { sub_name => "text", type => "longtext", input_rows => 3, make_single_value_orderkey => 'EPrints::Extras::english_title_orderkey' } ],
input_add_boxes => 1,
},

{
name => 'title',
type => 'virtualwithvalue',
virtual => 1,

get_value => sub
{
my ($eprint) = @_;
if ($eprint->is_set('ml_title'))
{
my $lang = $eprint->repository->get_langid;
my $lang_set = 0;
my $vals = $eprint->get_value('ml_title');
my $title = '';
if (!$lang)
{
$lang_set = 1;
}
else
{
# set the default lang's text as title
foreach my $v1 (@{$vals})
{
if ($v1->{lang} eq $lang)
{
$title = $v1->{text};
}
}
}
# if the language is not set or I can't find an abstract in the
# user's language, get the first object's text as abstract
if ($lang_set or $title eq '')
{
$title = $vals->[0]->{text};
}
return $title;

}
return undef; # This is important. Using just a 'return;' or no return statement may break your repository e.g. when an EPrint revision file tried to be created.
},

set_value => sub
{
my ($eprint, $value) = @_;
my $lang = 'en';
#only use this on imports, NOT if the value is already set
if ($eprint->is_set('ml_title'))
{
return;
}
if ($value)
{
$eprint->set_value('ml_title', [{lang=>$lang, text=>$value}]);
}
}
},
];

#create lookup hash of local field names
my $local_fieldnames = {};

foreach my $f (@{$local_fields})
{
$local_fieldnames->{$f->{name}} = 1;
}

#merge in existing field configurations
foreach my $f (@{$c->{fields}->{eprint}})
{
if (!$local_fieldnames->{$f->{name}})
{
push @{$local_fields}, $f;
}
}

#overwrite original array of configured fields
$c->{fields}->{eprint} = $local_fields;
</source>

Where we can see that our new '''ml_title''' field is of type '''multilang''' and the '''title''' field's type has become '''virtualwithvalue'''. Moreover, the '''title''' field now implements the two aforementioned functions: '''get_value''' and '''set_value'''. Both these functions -whose names imply their functionality- are used by EPrints API, and their existence, as well as their return values, are critical for EPrints to work properly. The last statements of our example code show how a custom field can be added in the list of EPrints fields.

What has happened in effect is that the '''title''' field has become a calculated field that gets or sets its value via its corresponding '''multilang''' field ('''ml_title'''). So, each new record now has a '''multilang''' field which it can access via the interface provided by the calculated field of type '''virtualwithvalue''', which is no other than EPrints' basic '''title''' field.

The reason we didn't set the '''title''' field to be of type '''multilang''' in the first place is that many EPrints builtin functions expect only a single value from the '''title''' (and '''abstract''') field, and '''multilang''' fields don't support such functionality. Hence, doing so would cause EPrints to throw errors. By using and extending calculated fields (like '''MetaFields'''), we can calculate and produce always a single output for our '''title''' field (using the data stored in '''ml_title''' field) via its '''get_value''' function; its '''set_value''' function is used for populating our '''ml_title''' field's values. Our sample code prints output based on the user's language settings, but the programmer can do whatever they wish when overriding these functions, as long as their code return values that comply with EPrints' API.

== Updating EPrints database to include the ml_title field ==
EPrints database is updated when the user eprints executes (from his home directory):
<source lang="bash">
$ ./bin/epadmin update reponame
</source>

== Adding the appropriate phrases ==
EPrints phrases are not aware of our new field ('''ml_title'''), so we need to update them. In our example we update the phrases for the English and for the Greek languages ('''en''' and '''el''' respectively). We chose to add new files instead of changing the default ones so as to help EPrints upgrades. So, for the English language we can add the file '''~eprints/archives/reponame/cfg/lang/en/phrases/local.xml''' that contains the following information:
<source lang="html4strict">
<epp:phrase id="eprint_fieldname_ml_title">Title</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_text">Text</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_lang">Language</epp:phrase>
<epp:phrase id="eprint_fieldhelp_ml_title">The title of the item. The title should not end with a full stop, but may end with a question mark. There is no way to make italic text, please enter it normally. If you have a subtitle, it should be preceded with a colon [:]. Use capitals only for the first word and for proper nouns.
<br/>Example: <span class="ep_form_example">A brief history of time</span>
<br/>Example: <span class="ep_form_example">Life: an unauthorised biography</span>
<br/>Example: <span class="ep_form_example">Mathematics for engineers and scientists. 5th edition</span>
<br/>Example: <span class="ep_form_example">Ecosystems of the world. Vol. 26. Estuaries of the world</span>
</epp:phrase>
</source>

Greek phrases can be added in file '''~eprints/archives/reponame/cfg/lang/el/phrases/local.xml''':
<source lang="html4strict">
<epp:phrase id="eprint_fieldname_ml_title">Τίτλος</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_text">Κείμενο</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_help">Το help τεξτ</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_lang">Γλώσσα</epp:phrase>
<epp:phrase id="eprint_fieldhelp_ml_title">Ο τίτλος του τεκμηρίου. Ο τίτλος δεν πρέπει να τελειώνει με τελεία, αλλά μπορεί να τελειώνει με ερωτηματικό. Δεν υπάρχει τρόπος να γράψετε με πλάγια γράμματα, παρακαλώ χρησιμοποιήστε απλό κείμενο. Εάν έχετε έναν υπότιτλο, θα πρέπει να προηγείται η άνω και κάτω τελεία του υπότιτλου [:]. Χρησιμοποιήστε κεφαλαία γράμματα μόνο στην πρώτη λέξη και στα κύρια ονόματα.
<br/>Παράδειγμα: <span class="ep_form_example">Μια σύντομη ιστορία</span>
<br/>Παράδειγμα: <span class="ep_form_example">Καβάφης: η βιογραφία</span>
<br/>Παράδειγμα: <span class="ep_form_example">Μαθηματικά για μηχανικούς και επιστήμονες. 5η έκδοση</span>
<br/>Παράδειγμα: <span class="ep_form_example">Οικοσυστήματα του πλανήτη. Τόμ. 26. Εκβολές του πλανήτη.</span>
</epp:phrase>
</source>

== Replacing the title field with ml_title field in the workflow ==
In order to use our new '''ml_title''' field in the workflow, we need to replace the existing one ('''title'''). So, the '''title''' needs to be commented out and the new '''multilang''' should be added. This means that '''~eprints/archives/reponame/cfg/workflows/eprint/default.xml''' is edited as follows:
<source lang="html4strict">

<component><field ref="ml_title" required="yes" input_lookup_url="{$config{rel_cgipath}}/users/lookup/ml_title_duplicates" input_lookup_params="id={eprintid}&dataset=eprint&field=ml_title"/></component>
<component><field ref="ml_abstract"/></component>
</source>
As can be seen, the default lookup script is replaced by the plugin's lookup script ('''ml_title_duplicates''') which supports our new '''ml_title''' field.

== Adding a custom lookup script for ml_title autocompletion ==
We copy the default lookup script to a new one ('''~eprints/cgi/users/lookup/ml_title_duplicates in our example'''):
<source lang="bash">
$ cp ~eprints/cgi/users/lookup/title_duplicates ~eprints/cgi/users/lookup/ml_title_duplicates
</source>
and edit the SQL statement to contain '''ml_title''' instead of '''title''' (line 70 in EPrints 3.3.14):
<source lang="php">
my $sql = "SELECT ep.eprintid, ml_title_text FROM eprint AS ep JOIN eprint_ml_title_text AS ml ON ep.eprintid = ml.eprintid WHERE ";
if ($dataset_name eq "eprint") {
$sql .= " $Q_eprint_status=" . $db->quote_value( "archive" ) . " AND ";
}
$sql .= "ml.ml_title_text IS NOT NULL" .
" AND ml.ml_title_text " .
$db->sql_LIKE() .
$db->quote_value( EPrints::Database::prep_like_value( $q ) . '%' );
</source>

== Adding search support for the ml_title field ==
EPrints' search functionality is only aware of the '''title''' field, so its search mechanisms -which directly search EPrints' database- has no knowledge about '''ml_title'''. To address this, we should allow our search scripts to be able to search into '''ml_title''' instead of '''title''', since '''title''' is now a calculated field and contains no information in EPrints database. To do so, we add two configuration files that add support for each search respectively. We have chosen not to change EPrints' default search configuration files, in order not to affect future EPrints' upgrades. So, for the simple search we add the file '''~eprints/archives/reponame/cfg/cfg.d/eprint_search_simple.pl''' with the content:
<source lang="perl">$c->{search}->{simple} =
{
search_fields => [
{
id => "q",
meta_fields => [
"documents",
"ml_title",
"abstract",
"creators_name",
"date"
]
},
],
# preamble_phrase => "cgi/search:preamble",
title_phrase => "cgi/search:simple_search",
citation => "result",
page_size => 20,
order_methods => {
"byyear" => "-date/creators_name/title",
"byyearoldest" => "date/creators_name/title",
"byname" => "creators_name/-date/title",
"bytitle" => "title/creators_name/-date"
},
default_order => "byyear",
show_zero_results => 1,
};
</source>

And for the advanced search we add the file: '''~eprints/archives/reponame/cfg/cfg.d/eprint_search_advanced_local.pl''' that reads:
<source lang="perl">
$c->{search}->{advanced} =
{
search_fields => [
{ meta_fields => [ "documents" ] },
{ meta_fields => [ "ml_title" ] },
{ meta_fields => [ "creators_name" ] },
{ meta_fields => [ "abstract" ] },
{ meta_fields => [ "date" ] },
{ meta_fields => [ "keywords" ] },
{ meta_fields => [ "subjects" ] },
{ meta_fields => [ "type" ] },
{ meta_fields => [ "department" ] },
{ meta_fields => [ "editors_name" ] },
{ meta_fields => [ "ispublished" ] },
{ meta_fields => [ "refereed" ] },
{ meta_fields => [ "publication" ] },
{ meta_fields => [ "documents.format" ] },
],
preamble_phrase => "cgi/advsearch:preamble",
title_phrase => "cgi/advsearch:adv_search",
citation => "result",
page_size => 20,
order_methods => {
"byyear" => "-date/creators_name/title",
"byyearoldest" => "date/creators_name/title",
"byname" => "creators_name/-date/title",
"bytitle" => "title/creators_name/-date"
},
default_order => "byyear",
show_zero_results => 1,
};
</source>

== Reloading our repository ==
In order for our changes to take effect, we should reload our repository by running:
<source lang="bash">
$ ./bin/epadmin reload reponame</source>
within eprints user's home directory as user eprints.

== Regenerating static files and abstracts ==
If our repository already contained records, we need to recreate static content such as static pages and abstracts. Hence, as eprints user we should run:
<source lang="bash">
$ ./bin/generate_abstracts reponame
$ ./bin/generate_static reponame
</source>
within eprints user's home directory.

Adding multilang fields

2024-02-08T14:00:01Z

Libjlrs: Add note about return value for 'get_value'

[[Category:Howto]]

EPrints' builtin fields are not multilingual, in the sense that there is only one version of each field -indirectly this means one language support. This page explains how to add multilingual versions of existing fields in EPrints and how they can be integrated with its subsystems.

== Multilang fields and EPrints ==
EPrints supports the '''multilang''' field type (see [[API:EPrints/MetaField/Multilang]] for more details) which allows a user to insert different content for different languages. There are a few limitations with '''multilang''' fields though:

* When its value is printed it is shown in all languages containing content.
* If a basic EPrints field's type is replaced to become '''multilang''' (like '''title''' and '''abstract'''), EPrints functionality breaks because it expects a single output.

To address these limitations. this article explains how we can replace a basic field, the '''title''' field as an example, with a multilingual one.

== Warning for already populated repositories ==
Once you follow this article's procedure, '''existing titles and abstracts''' will not be copied into their multilingual counterparts and '''access to them via the API will be lost'''! The users of this plugin are requested to use EPrints API to copy the values from the old fields to the new ones. A script that copies the '''title''' value of each eprint to '''ml_title''' field's '''en''' and '''el''' languages can be found here:[https://github.com/mamalos/eprints/blob/master/help_scripts/set_ml_title.pl]. Please, use this script at your own risk and don't forget to change its content to reflect the languages of your repository. The same script can be used for copying the '''abstract''' field's values to '''ml_abstract''' '''en''' and '''el''' by replacing title with abstract in this script.

== How to add a custom, multilingual field ==
Replacing an EPrints basic field, like the '''title''' field, involves a few steps. First, a new field needs to be created that will be able to store information for different languages; this field will be of type '''multilang'''. Next, the basic field's type needs to be replaced with one that is able to use our newly created field as its storage place. This field type will use a function wrapper for storing and retrieving information from the '''multilang''' field, hence the '''title''' field will become a calculated field.

So, in order to add multilingual support for the '''title''' field, the following actions need to take place:

* A ''new field type needs to be created'' that will help our '''title''' field to implement some of EPrints logic. Our field type is called '''virtualwithvalue'''.
* A ''new '''multilang''' field needs to be created'' that will store our multilingual information. We will call this field '''ml_title'''.
* '''''ml_title''' field and '''title''' field's functionality need to be introduced to the EPrints system'' via a configuration file located in '''~eprints/archives/<reponame>/cfg/cfg.d/'''.
* ''EPrints' database needs to be updated'' to include the new field.
* ''The appropriate phrases need to be added'' for the '''ml_title''' field on each supported language.
* ''The '''title''' field needs to be replaced'' with '''ml_title''' field in the workflow.
* '''''ml_title''' field in the workflow will needs a custom lookup script''.
* ''The '''title''' field needs to be replaced with the '''ml_title''' field in the simple and advanced search scripts''.
* The ''repository needs to be reloaded''.
* ''Static files need to be regenerated'' if our repository already contains data.
The following sections explain each step in detail, and ''title''' and '''ml_title''' are used as our example fields. The code snippets are just for demonstration purposes - and proof of concept. If you want to see the final, working implementation, you should look at the source code of the [[MultiLang_Fields_Bazaar_Package]] plugin.

== Adding a new field type (VirtualWithValue)==
In order to create a multiple-language field we have to create an appropriate field type. EPrints' '''MetaField''' (see [[API:EPrints/MetaField|MetaField]] article for details) is a perfect candidate for this, and we need to extend it and override its '''get_value''' and '''set_value''' functions for the field to work properly with the rest of EPrints API, as well as its '''get_property_defaults''' function to sort out warnings for default values. The following code could be a rough implementation of such a field:

<source lang="perl">package EPrints::MetaField::Virtualwithvalue;

use strict;
use warnings;

use EPrints::MetaField;

our @ISA = qw( EPrints::MetaField );

use strict;

sub get_property_defaults
{
my ( $self ) = @_;
my %defaults = $self->SUPER::get_property_defaults;
$defaults{get_value} = $EPrints::MetaField::UNDEF;
$defaults{set_value} = $EPrints::MetaField::UNDEF;

return %defaults;
}

sub get_value
{
my( $self, $object ) = @_;
if ( defined $self->get_property("get_value") )
{
return $self->call_property( "get_value", $object);
}
return undef; # This is important. Using just a 'return;' or no return statement may break your repository e.g. when an EPrint revision file tried to be created.
}

sub set_value
{
my( $self, $object, $value ) = @_;
if ( defined $self->get_property("set_value") )
{
return $self->call_property( "set_value", $object, $value);
}
return undef;
}

</source>

We could save this file in '''~eprints/lib/plugins/EPrints/MetaField/Virtualwithvalue.pm'''.

== Introducing ml_title field in EPrints and replacing title field's type==
To inform EPrints about our new field (that will be of type '''virtualwithvalue'''), we should create a configuration file, eg: '''~eprints/archives/<reponame>/cfg/cfg.d/zz_multilang_field.pl''' with content like the following:

<source lang='perl'>
#define local fields
my $local_fields = [
{
name => 'ml_title',
type => 'multilang',
multiple => 1,
fields => [ { sub_name => "text", type => "longtext", input_rows => 3, make_single_value_orderkey => 'EPrints::Extras::english_title_orderkey' } ],
input_add_boxes => 1,
},

{
name => 'title',
type => 'virtualwithvalue',
virtual => 1,

get_value => sub
{
my ($eprint) = @_;
if ($eprint->is_set('ml_title'))
{
my $lang = $eprint->repository->get_langid;
my $lang_set = 0;
my $vals = $eprint->get_value('ml_title');
my $title = '';
if (!$lang)
{
$lang_set = 1;
}
else
{
# set the default lang's text as title
foreach my $v1 (@{$vals})
{
if ($v1->{lang} eq $lang)
{
$title = $v1->{text};
}
}
}
# if the language is not set or I can't find an abstract in the
# user's language, get the first object's text as abstract
if ($lang_set or $title eq '')
{
$title = $vals->[0]->{text};
}
return $title;

}
return undef;
},

set_value => sub
{
my ($eprint, $value) = @_;
my $lang = 'en';
#only use this on imports, NOT if the value is already set
if ($eprint->is_set('ml_title'))
{
return;
}
if ($value)
{
$eprint->set_value('ml_title', [{lang=>$lang, text=>$value}]);
}
}
},
];

#create lookup hash of local field names
my $local_fieldnames = {};

foreach my $f (@{$local_fields})
{
$local_fieldnames->{$f->{name}} = 1;
}

#merge in existing field configurations
foreach my $f (@{$c->{fields}->{eprint}})
{
if (!$local_fieldnames->{$f->{name}})
{
push @{$local_fields}, $f;
}
}

#overwrite original array of configured fields
$c->{fields}->{eprint} = $local_fields;
</source>

Where we can see that our new '''ml_title''' field is of type '''multilang''' and the '''title''' field's type has become '''virtualwithvalue'''. Moreover, the '''title''' field now implements the two aforementioned functions: '''get_value''' and '''set_value'''. Both these functions -whose names imply their functionality- are used by EPrints API, and their existence, as well as their return values, are critical for EPrints to work properly. The last statements of our example code show how a custom field can be added in the list of EPrints fields.

What has happened in effect is that the '''title''' field has become a calculated field that gets or sets its value via its corresponding '''multilang''' field ('''ml_title'''). So, each new record now has a '''multilang''' field which it can access via the interface provided by the calculated field of type '''virtualwithvalue''', which is no other than EPrints' basic '''title''' field.

The reason we didn't set the '''title''' field to be of type '''multilang''' in the first place is that many EPrints builtin functions expect only a single value from the '''title''' (and '''abstract''') field, and '''multilang''' fields don't support such functionality. Hence, doing so would cause EPrints to throw errors. By using and extending calculated fields (like '''MetaFields'''), we can calculate and produce always a single output for our '''title''' field (using the data stored in '''ml_title''' field) via its '''get_value''' function; its '''set_value''' function is used for populating our '''ml_title''' field's values. Our sample code prints output based on the user's language settings, but the programmer can do whatever they wish when overriding these functions, as long as their code return values that comply with EPrints' API.

== Updating EPrints database to include the ml_title field ==
EPrints database is updated when the user eprints executes (from his home directory):
<source lang="bash">
$ ./bin/epadmin update reponame
</source>

== Adding the appropriate phrases ==
EPrints phrases are not aware of our new field ('''ml_title'''), so we need to update them. In our example we update the phrases for the English and for the Greek languages ('''en''' and '''el''' respectively). We chose to add new files instead of changing the default ones so as to help EPrints upgrades. So, for the English language we can add the file '''~eprints/archives/reponame/cfg/lang/en/phrases/local.xml''' that contains the following information:
<source lang="html4strict">
<epp:phrase id="eprint_fieldname_ml_title">Title</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_text">Text</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_lang">Language</epp:phrase>
<epp:phrase id="eprint_fieldhelp_ml_title">The title of the item. The title should not end with a full stop, but may end with a question mark. There is no way to make italic text, please enter it normally. If you have a subtitle, it should be preceded with a colon [:]. Use capitals only for the first word and for proper nouns.
<br/>Example: <span class="ep_form_example">A brief history of time</span>
<br/>Example: <span class="ep_form_example">Life: an unauthorised biography</span>
<br/>Example: <span class="ep_form_example">Mathematics for engineers and scientists. 5th edition</span>
<br/>Example: <span class="ep_form_example">Ecosystems of the world. Vol. 26. Estuaries of the world</span>
</epp:phrase>
</source>

Greek phrases can be added in file '''~eprints/archives/reponame/cfg/lang/el/phrases/local.xml''':
<source lang="html4strict">
<epp:phrase id="eprint_fieldname_ml_title">Τίτλος</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_text">Κείμενο</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_help">Το help τεξτ</epp:phrase>
<epp:phrase id="eprint_fieldname_ml_title_lang">Γλώσσα</epp:phrase>
<epp:phrase id="eprint_fieldhelp_ml_title">Ο τίτλος του τεκμηρίου. Ο τίτλος δεν πρέπει να τελειώνει με τελεία, αλλά μπορεί να τελειώνει με ερωτηματικό. Δεν υπάρχει τρόπος να γράψετε με πλάγια γράμματα, παρακαλώ χρησιμοποιήστε απλό κείμενο. Εάν έχετε έναν υπότιτλο, θα πρέπει να προηγείται η άνω και κάτω τελεία του υπότιτλου [:]. Χρησιμοποιήστε κεφαλαία γράμματα μόνο στην πρώτη λέξη και στα κύρια ονόματα.
<br/>Παράδειγμα: <span class="ep_form_example">Μια σύντομη ιστορία</span>
<br/>Παράδειγμα: <span class="ep_form_example">Καβάφης: η βιογραφία</span>
<br/>Παράδειγμα: <span class="ep_form_example">Μαθηματικά για μηχανικούς και επιστήμονες. 5η έκδοση</span>
<br/>Παράδειγμα: <span class="ep_form_example">Οικοσυστήματα του πλανήτη. Τόμ. 26. Εκβολές του πλανήτη.</span>
</epp:phrase>
</source>

== Replacing the title field with ml_title field in the workflow ==
In order to use our new '''ml_title''' field in the workflow, we need to replace the existing one ('''title'''). So, the '''title''' needs to be commented out and the new '''multilang''' should be added. This means that '''~eprints/archives/reponame/cfg/workflows/eprint/default.xml''' is edited as follows:
<source lang="html4strict">

<component><field ref="ml_title" required="yes" input_lookup_url="{$config{rel_cgipath}}/users/lookup/ml_title_duplicates" input_lookup_params="id={eprintid}&dataset=eprint&field=ml_title"/></component>
<component><field ref="ml_abstract"/></component>
</source>
As can be seen, the default lookup script is replaced by the plugin's lookup script ('''ml_title_duplicates''') which supports our new '''ml_title''' field.

== Adding a custom lookup script for ml_title autocompletion ==
We copy the default lookup script to a new one ('''~eprints/cgi/users/lookup/ml_title_duplicates in our example'''):
<source lang="bash">
$ cp ~eprints/cgi/users/lookup/title_duplicates ~eprints/cgi/users/lookup/ml_title_duplicates
</source>
and edit the SQL statement to contain '''ml_title''' instead of '''title''' (line 70 in EPrints 3.3.14):
<source lang="php">
my $sql = "SELECT ep.eprintid, ml_title_text FROM eprint AS ep JOIN eprint_ml_title_text AS ml ON ep.eprintid = ml.eprintid WHERE ";
if ($dataset_name eq "eprint") {
$sql .= " $Q_eprint_status=" . $db->quote_value( "archive" ) . " AND ";
}
$sql .= "ml.ml_title_text IS NOT NULL" .
" AND ml.ml_title_text " .
$db->sql_LIKE() .
$db->quote_value( EPrints::Database::prep_like_value( $q ) . '%' );
</source>

== Adding search support for the ml_title field ==
EPrints' search functionality is only aware of the '''title''' field, so its search mechanisms -which directly search EPrints' database- has no knowledge about '''ml_title'''. To address this, we should allow our search scripts to be able to search into '''ml_title''' instead of '''title''', since '''title''' is now a calculated field and contains no information in EPrints database. To do so, we add two configuration files that add support for each search respectively. We have chosen not to change EPrints' default search configuration files, in order not to affect future EPrints' upgrades. So, for the simple search we add the file '''~eprints/archives/reponame/cfg/cfg.d/eprint_search_simple.pl''' with the content:
<source lang="perl">$c->{search}->{simple} =
{
search_fields => [
{
id => "q",
meta_fields => [
"documents",
"ml_title",
"abstract",
"creators_name",
"date"
]
},
],
# preamble_phrase => "cgi/search:preamble",
title_phrase => "cgi/search:simple_search",
citation => "result",
page_size => 20,
order_methods => {
"byyear" => "-date/creators_name/title",
"byyearoldest" => "date/creators_name/title",
"byname" => "creators_name/-date/title",
"bytitle" => "title/creators_name/-date"
},
default_order => "byyear",
show_zero_results => 1,
};
</source>

And for the advanced search we add the file: '''~eprints/archives/reponame/cfg/cfg.d/eprint_search_advanced_local.pl''' that reads:
<source lang="perl">
$c->{search}->{advanced} =
{
search_fields => [
{ meta_fields => [ "documents" ] },
{ meta_fields => [ "ml_title" ] },
{ meta_fields => [ "creators_name" ] },
{ meta_fields => [ "abstract" ] },
{ meta_fields => [ "date" ] },
{ meta_fields => [ "keywords" ] },
{ meta_fields => [ "subjects" ] },
{ meta_fields => [ "type" ] },
{ meta_fields => [ "department" ] },
{ meta_fields => [ "editors_name" ] },
{ meta_fields => [ "ispublished" ] },
{ meta_fields => [ "refereed" ] },
{ meta_fields => [ "publication" ] },
{ meta_fields => [ "documents.format" ] },
],
preamble_phrase => "cgi/advsearch:preamble",
title_phrase => "cgi/advsearch:adv_search",
citation => "result",
page_size => 20,
order_methods => {
"byyear" => "-date/creators_name/title",
"byyearoldest" => "date/creators_name/title",
"byname" => "creators_name/-date/title",
"bytitle" => "title/creators_name/-date"
},
default_order => "byyear",
show_zero_results => 1,
};
</source>

== Reloading our repository ==
In order for our changes to take effect, we should reload our repository by running:
<source lang="bash">
$ ./bin/epadmin reload reponame</source>
within eprints user's home directory as user eprints.

== Regenerating static files and abstracts ==
If our repository already contained records, we need to recreate static content such as static pages and abstracts. Hence, as eprints user we should run:
<source lang="bash">
$ ./bin/generate_abstracts reponame
$ ./bin/generate_static reponame
</source>
within eprints user's home directory.

Display a custom response during downtime

2023-09-07T09:35:00Z

Libjlrs: Update Apache method call (which doesn't exist in modern versions) with newer call to remote_ip

[[Category:Howto]]
[[Category:Management]]

See also [[Creating a Maintenance Page]].

We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hours where EPrints wouldn't be accessible.

During this downtime, I wanted to to display a useful message, with a '503 Service unavailable' HTTP response.
This is how to achieve this using EPrints triggers:
'''NOTE''' if you are doing maintenance that means EPrints will not be able to connect to the database, the method below will not work, as EPrints will complain about not being able to connect to the database before processing the trigger. If you maintenance will result in the database being offline (rather than read-only), the maintenance page should be delivered using Apache. Please see https://stackoverflow.com/questions/622466/how-to-put-apache-website-to-503-temporary-down for some examples).

# Create a file <code>~/archives/ARCHIVEID/cfg/cfg.d/a_MAINTENANCE.pl</code>. The name of the file isn't important - but it should be alphabetically '''before''' any other config file that defined a URL_REWRITE trigger.
# Add the following to the file, altering the <code>maintenance_ip</code>, <code>maintenance_retry_after</code> and <code>maintenance_page_html</code> appropriately. I'd keep the html page quite simple, but with enough info to help a human. Remember to escape any single-quotes in the HTML block with a backslash e.g. BAD: <code>we've</code>; GOOD: <code>we\'ve</code>.:
<source lang="perl">
# Set maintenance to 1 to respond with a 503 for requests, except those from the maintenance_ip.
$c->{maintenance} = 0;
$c->{maintenance_allowed_ip} = '127.0.0.1'; #set this to your IP address

# set to a date/time after your maintenance will have finished,
# or a period (in seconds) that the maintenance will last for
$c->{maintenance_retry_after} = 'Mon, 14 Mar 2016 12:00:00 GMT'; #set to a date/time after your maintenance will have finished

use EPrints::Const;
$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %args ) = @_;

# args passed to EP_TRIGGER_URL_REWRITE are:
# request, lang, args, urlpath, cgipath, uri, secure, return_code
my( $repository, $request, $return_code, $uri, $urlpath ) = @args{ qw( repository request return_code uri urlpath ) };

#check we're in maintenance mode
if( $repository->config( "maintenance" ) && $repository->config( "maintenance" ) == 1 ){
# is there an IP we should allow through?
# NB You might need to do other checks - e.g. X-Forwarded-For if you are behind a load-balancer
# or for different versions of Apache (like here: https://github.com/eprints/eprints/issues/214)
# if you're not sure, ask on the EPrints Tech list first!
if( $repository->config( "maintenance_allowed_ip" ) &&
$repository->remote_ip eq $repository->config( "maintenance_allowed_ip" ) ){
return EP_TRIGGER_OK;
}
elsif( $uri !~ /^$urlpath\/(style|images)\// ) # allow image/stylesheet requests
# through - so you can display a branded 503 page
{
$request->custom_response( Apache2::Const::HTTP_SERVICE_UNAVAILABLE, $c->{maintenance_page_html} );
if( $repository->config( "maintenance_retry_after" ) ){
$request->err_headers_out->{'Retry-After'} = $repository->config( "maintenance_retry_after" );
}
# set the 503 response
${$return_code} = EPrints::Const::HTTP_SERVICE_UNAVAILABLE;
# and don't process any more EP_TRIGGER_URL_REWRITE triggers.
return EP_TRIGGER_DONE;
}
}
} );

# A simple maintenance page - not using the template (which will probably link to various other pages that aren't
# accessible during the maintenance window
$c->{maintenance_page_html} = '<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style>
body {
font-family: sans-serif;
margin: 3em;
}
footer {
font-size: 80%;
margin-top:2em;
}
</style>
<title>###REPO NAME### - Maintenance</title>
</head>
<body>
<header>
<img src="/images/sitelogo.png" />
<h1>###REPO NAME### - Maintenance</h1>
</header>
<section>
<p><strong>Date/Time</strong> We\'re currently doing things to the system.<br />
We\'ll be back soon!</p>
<p>If you have any questions, please contact someone@somewhere.blah</p>
</section>
<footer>
<p>###REPO NAME###</p>
</footer>
</body>
</html>';

</source>

# Do a <code>~/bin/epadmin test ARCHIVEID</code> to make sure you haven't done anything silly in the config file.
# Do a <code>~/bin/epafmin reload ARCHIVEID</code> and check that nothing's changed
# When you want to turn the maintenance response on, change set: <code>$c->{maintenance} = 1;</code> and reload the archive.
# Check that you can get in from the IP specified, and that you get the 503 response from other IPs.
# Do a graceful restart of Apache - to stop the noisy 'repository had been reloaded' error messages.
# Do the maintenance, test.
# Change <code>$c->{maintenance} = 0;</code>, graceful restart Apache, test.
# Done!

If you want to include the default CSS files in the 503 page, include <code><link rel="stylesheet" type="text/css" href="/style/auto-3.3.14.css"></code> in the maintenance_html_page -> head section (update it for your version of EPrints!).

Redirect specific eprints to somewhere else

2023-02-16T21:09:59Z

Libjlrs: Create new page

This page is based on a question posed on the [http://mailman.ecs.soton.ac.uk/pipermail/eprints-tech/2023-February/thread.html#9203 EP-Tech mailing list: Adding 301 redir_permanent for some migrated items before 404 kicks in.], around approaches to redirect specific EPrints to different URLs (e.g. where certain items have been migrated to different services).

There were two solutions suggested, and an additional (untested) approach, detailed below.

* use an EPrints URL rewrite trigger
* use the `rewrite_exceptions` configuration, in combination with an Apache `RewriteMap`
* register a new PerlTransHandler to do rewrites

The best approach will depend on the size of the repository, the percentage of items that need to be redirected, whether additional aspects (e.g. mapping document-level requests or export URLs) are needed.

The `EP_TRIGGER_URL_REWRITE` will be triggered on each request - so it's important to keep the code 'quick' - and return quickly for URLs that are of no interest.

The `rewrite_exceptions` array is searched for each request too - so having a very large array to search through may also slow your repository down.

== EPrints URL rewrite trigger ==

<source lang="perl">
# Save as e.g. EPRINTS_ROOT/archives/ARCHIVE_ID/cfg/cfg.d/z_url_rewrite_map.pl
# source is available from: https://gist.github.com/jesusbagpuss/2e9172a2ee94d4dcfc5f23a08486f3fe
# Maps specific URLs to be permanently redirected

use EPrints::Const; # for trigger return values

# define specific URLs that have been moved.
# If all the new URLs are to the same base URL, you could have e.g 1234 => 5678 in the
# hash, and prepend a static 'https://new.repo.com/' in the 'Location' line below.
# the hash could also be defined by reading data in from a file (e.g. csv)

$c->{z_url_rewrite_map} = {
'1234' => 'https://abc.de/1/',
'2345' => 'https://abc.de/9/',
};

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %o ) = @_;

# Available hash keys in %o
# request, lang (en), args ("" or "?foo=bar"), urlpath ("" or "/subdir"), cgipath ("/cgi" or "/subdir/cgi")
# uri (/foo/bar), secure ( boolean ), return_code (set to trigger a return - stop stack of triggers), repository

my $redirect_map = $o{repository}->get_conf( "z_url_rewrite_map" );
return if !defined $redirect_map;

# Optimisation over the 404 handler regex...
# If you have a long-standing repository, there may be EPrint URLs out in the wild that refer to repo.com/1234 (without trailing slash).
# Currently, EPrints will redirect this to repo.com/1234/ - and then m#^/(\d+)/# (from 404 handler) would capture it.
# This could result in multiple redirects ( /1234 --> /1234/ --> other server ) which isn't best practice for SEO.
#
# The first regex below will match `/1234` , `/1234/`, `/00001234`, `/00001234/` (zero-padded IDs were from old versions of EPrints - but may still be in use.
# These are currently handled in EPrints::Apache::Rewrite with a redirect, so capturing them here stops one redirect loop.
#
# If your repo is _really_ old, you might also want to capture repo.com/archive/1234 or repo.com/archive/00001234...
# ...I guess looking in the Apache logs will indicate if this is necessary!

if( defined $o{uri} && ( $o{uri} =~ m#^/0{0,9}(\d+)(?>/|$)# || $o{uri} =~ m#^/id/eprint/0{0,9}(\d+)/# ) )
{
# We've got what looks like an EPrintID...
# Is there a redirect map for it?
if( defined $redirect_map->{$1} ){
EPrints::Apache::AnApache::send_status_line( $o{request}, 301, "Moved Permanently" );
EPrints::Apache::AnApache::header_out( $o{request}, "Location", "$redirect_map->{$1}" );
EPrints::Apache::AnApache::send_http_header( $o{request} );

${$o{return_code}} = EPrints::Const::DONE;
return EP_TRIGGER_DONE;
}
# an EPrintID, but not redirected.
}
# not an EPrintID URL - just return (could explicitly set a trigger return value, but not necessary)
} );
</source>

== Apache RewriteMap solution ==

By default, EPrints will process all requests, so including additional directives in the Apache config doesn't work.
Luckily, EPrints provides a configuration variable for URL stubs to ''not'' be processed.
<source lang="perl">
# Save as e.g. EPRINTS_ROOT/archives/ARCHIVE_ID/cfg/cfg.d/z_rewrite_exceptions.pl - ***BUT CHECK YOUR CONFIG FOR AN EXISTING DEFINITION!!!***
$c->{rewrite_exceptions} = [ '/1234/', '/2345/' ];
</source>

URLs matching those specified will not be handled by the EPrints stack, allowing Apache to handle the requests.
The `newid` part shows how to map the 'exception' IDs to one new system (with new IDs).
The `newurl` part can be used to map the exception IDs to any URL.

<source lang="apache">
# In apache vhost config file
RewriteMap newid "txt:/etc/apache2/newid.txt"
RewriteMap newurl "txt:/etc/apache2/newurl.txt"

RewriteCond ${newid:$1|Unknown} !Unknown
RewriteRule "^/([0-9]+)/?$" "new.server/${newid:$1|$1}" [R,L]

RewriteCond ${newurl:$1|Unknown} !Unknown
RewriteRule "^/([0-9]+)/?$" "${newurl:$1}" [R,L]
</source>

The newid.txt file would contain something like:
1234 1234
2345 9876

The newurl.txt file would contain something like:
1234 https://new.host/item1000
2345 https://some.other.host/42/life

The Apache RewriteMap also allows other approaches - e.g. querying a database to find matches. Just make sure it's quick and stable!

== PerlTransHandler (possible solution for proper perl geeks - completely untested!) ==
EPrints is added to the Apache configuration with the following config:

PerlTransHandler +EPrints::Apache::Rewrite

The `+` before the module name tells Apache to load the specified module before using it. It's equivalent to including a specific `PerlModule Apache::Foo` line.

[https://perl.apache.org/docs/2.0/user/handlers/http.html#PerlTransHandler `PerlTransHandler`] is a [https://perl.apache.org/docs/2.0/user/handlers/intro.html#Stacked_Handlers stacked handler].
This means you could write your own custom Perl module to handle the redirects:
<source lang="perl">
# save as e.g. EPRINTS_ROOT/lib/plugins/Custom/Rewrites.pm
# THIS APPROACH IS UNTESTED! (feel free to test it, and correct it ;)
package Custom::Rewrites;

use strict;
use warnings;

use Apache2::RequestRec ();
use Apache2::Const -compile => qw(DECLINED HTTP_MOVED_PERMANENTLY);

# default method name used by Apache Perl handlers
sub handler {
my $r = shift;

my ( $id ) = $r->uri =~ m#^/0{0,9}(\d+)(?>/|$)#; # matching id. could also capture pos, filename etc. if needed

# get a list of IDs/Locations somehow.
# do some logic to work out if $id should be redirected, and to where - $new_location
if( $needs_redirection )
{
$r->err_headers_out->add( Location => "$new_location" );
return Apache2::Const::HTTP_MOVED_PERMANENTLY;
}

# This ID does not need to be redirected. This handler returns 'DECLINED', and the next handler is passed the request to process
return Apache2::Const::DECLINED;
}
1;
</source>

The above handler can be added to the `PerlTransHandler` stack '''before''' the EPrints one in the `VirtualHost` definition:
<source lang="apache">
<VirtualHost *:443>
ServerName eprints.somehwere
...
...
# Handle redirects with custom module first
PerlTransHandler +Custom::Rewrites
# then fall back to 'normal' EPrints handling
PerlTransHandler +EPrints::Apache::Rewrite
</VirtualHost>
</source>

== See Also ==
* [[Custom handlers]]
* [http://mailman.ecs.soton.ac.uk/pipermail/eprints-tech/2022-May/008931.html EP-Tech discussion]
*

[[Category:Howto]]

Boolean field

2023-01-26T12:11:21Z

Libjlrs: /* menu style */

{{fieldtypes}}
__NOTOC__
== Inheritance ==
* [[Metadata]]
** [[Boolean field]]

== Description ==

Describes a simple yes/no value. Unless the field has the ''required'' property set, it can actually have a third setting of unset. This can be useful as it distinguishes between a "False" and a "don't know/haven't filled this in yet". For example when asking if a paper is refereed, this is a boolean field. However it's not required as often someone isn't sure, and does not want to click "no" when that's not necessarily true.

== Properties ==

{| border="1" cellpadding="3" cellspacing="0"
| name || default || description
|-
| '''input_style''' || checkbox || May be one of (menu<nowiki>|</nowiki>radio<nowiki>|</nowiki>checkbox). This controls how the field is rendered in input forms.

"checkbox" gives just a single HTML checkbox which can be ticked or not. It looks a bit rubbish, and does not provide a way to indicate an "unset" value.

"menu" gives an HTML "select" menu with two or three options. The third is "unspecified" and only available if the field is not a required field.

"radio" gives an HTML radio buttons interface. It renders an html phrase with the true and false radio buttons placed in the phrase using pins. If the field is not required then a third radio button for "unspecified" appears below this.

|}

== Required Phrases ==

=== menu style ===

If you use input_style=>"menu" then you need two phrases of the type:

''datasetid'' + "_fieldopt_" + ''fieldname'' + "_TRUE"
''datasetid'' + "_fieldopt_" + ''fieldname'' + "_FALSE"

These control the display of the items in the menu.

Example:

<epp:phrase id="eprint_fieldopt_myboolean_TRUE">Certainly!</epp:phrase>
<epp:phrase id="eprint_fieldopt_myboolean_FALSE">No way!</epp:phrase>

==== optional phrase to replace 'UNSPECIFIED' text ====
To overwrite the default 'UNSPECIFIED' option displayed when a boolean field is not required, a phrase with an underscore at the end can be used:

''datasetid'' + "_fieldopt_" + ''fieldname'' + "_"

Example:

<epp:phrase id="eprint_fieldopt_myboolean_">Don't know.</epp:phrase>

=== radio style ===

This uses a single phrase with two pins in it to indicate the locations of the radio buttons. The phrase id is:

''datasetid'' + "_radio_" + ''fieldname''

We suggest placing a <label> element around the radio button and it's title - as well as being good practice, this also means that in some browsers clicking on the text will select the button.

For example:

<epp:phrase id="eprint_radio_myboolean"><label><epc:pin name="true"/>Yes, I like cheese.</label><br/><label><epc:pin name="false"/>No, cheese is bad.</label></epp:phrase>

== Database ==

Boolean fields are stored in the database as

fieldname SET( 'TRUE', 'FALSE' )

== API ==

In the code these fields are stored as strings containing "TRUE", "FALSE" or ""/undef if they are not set.

Category:User Roles

2022-12-14T08:58:24Z

Libjlrs: Created page with "Collection of pages relating to User roles and how to use them."

Collection of pages relating to User roles and how to use them.

Listings of User Roles and Privileges

2022-12-14T08:57:19Z

Libjlrs:

[[Category:Plugins]]
[[Category:User Roles]]
This page is intended to be a near exhaustive listing of roles and privileges that can be assigned to a user to allow them to carry out certain actions.

== User Roles ==
;admin
:[[#indexer/start|indexer/start]], [[#indexer/stop|indexer/stop]], [[#indexer/force_start|indexer/force_start]], [[#create_user|create_user]], [[#subject/edit|subject/edit]], [[#staff/user_search|staff/user_search]], [[#staff/history_search|staff/history_search]], [[#staff/issue_search|staff/issue_search]], [[#config/view/FILETYPE|config/view]], [[#config/view/FILETYPE|config/view/xml]], [[#config/view/FILETYPE|config/view/workflow]], [[#config/view/FILETYPE|config/view/citation]], [[#config/view/FILETYPE|config/view/phrase]], [[#config/view/FILETYPE|config/view/namedset]], [[#config/view/FILETYPE|config/view/template]], [[#config/view/FILETYPE|config/view/static]], [[#config/view/FILETYPE|config/view/autocomplete]], [[#config/view/FILETYPE|config/view/apache]], [[#config/view/FILETYPE|config/view/perl]], [[#config/test_email|config/test_email]], [[#config/imports|config/imports]], [[#config/add_field|config/add_field]], [[#config/remove_field|config/remove_field]],[[#config/regen_abstracts|config/regen_abstracts]], [[#config/regen_citations|config/regen_citations]], [[#config/regen_views|config/regen_views]], [[#config/edit/FILETYPE|config/edit/perl]], [[#storage/manager|storage_manager]], [[#repository/epm|repository/epm]], [[#event_queue/destroy|event_queue/destroy]], [[#event_queue/details/event_queue/details]], [[#event_queue/edit|event_queue/edit]], [[#event_queue/export|event_queue/export]], [[#event_queue/view|event_queue/view]], [[#eprint/STATUS/destroy:USERTYPE|eprint/destroy]], [[#eprint/STATUS/details:USERTYPE|eprint/details]], [[#eprint/STATUS/edit:USERTYPE|eprint/edit]], [[#eprint/STATUS/export:USERTYPE|eprint/export]], [[#eprint/STATUS/upsert:USERTYPE|eprint/upsert]], [[#eprint/STATUS/view:USERTYPE|eprint/view]], [[#eprint/STATUS/remove:USERTYPE|eprint/archive/remove]], [[#eprint/STATUS/edit:USERTYPE|eprint/archive/edit]], [[#file/destroy|file/destroy]], [[#file/export|file/export]], [[#file/view|file/view]], [[#import/view|import/view]], [[#import/edit|import/edit]], [[#saved_search/destroy|saved_search/destroy]], [[#saved_search/details|saved_search]], [[#saved_search/edit|saved_search/edit]], [[#saved_search/export|saved_search/export]], [[#saved_search/view|saved_search/view]], [[#user/remove:USERTYPE|user/remove]], [[#user/edit:USERTYPE|user/edit]], [[#user/view:USERTYPE|user/view]], [[#user/details:USERTYPE|user/details]], [[#user/destroy:USERTYPE|user/destroy]], [[#user/history:USERTYPE|user/history]], [[#user/staff/edit|user/staff/edit]], [[#repository/epm|repository/epm]]
;change-email
: ''Currently empty''
;change-user
: ''Currently empty''
;deposit
: [[#items|items]], [[#create_eprint|create_eprint]], [[#user/history:USERTYPE|user/history:owner]], [[#eprint/STATUS/view:USERTYPE|eprint/inbox/view:owner]], [[#eprint/STATUS/export:USERTYPE|eprint/inbox/export:owner]], [[#eprint/STATUS/summary:USERTYPE|eprint/inbox/summary:owner]], [[#eprint/STATUS/destroy:USERTYPE|eprint/inbox/destroy:owner]], [[#eprint/STATUS/deposit:USERTYPE|eprint/inbox/deposit:owner]], [[#eprint/STATUS/edit:USERTYPE|eprint/inbox/edit:owner]], [[#eprint/STATUS/remove:USERTYPE|eprint/inbox/remove:owner]], [[#eprint/STATUS/details:USERTYPE|eprint/inbox/details:owner]], [[#eprint/STATUS/history:USERTYPE|eprint/inbox/history:owner]], [[#eprint/STATUS/messages:USERTYPE|eprint/inbox/messages:owner]], [[#eprint/STATUS/issues:USERTYPE|eprint/inbox/issues:owner]], [[#eprint/STATUS/use_as_template:USERTYPE|eprint/inbox/use_as_template:owner]], [[#eprint/STATUS/derive_version:USERTYPE|eprint/inbox/derive_version:owner]], [[#eprint/STATUS/view:USERTYPE|eprint/buffer/view:owner]], [[#eprint/STATUS/export:USERTYPE|eprint/buffer/export:owner]], [[#eprint/STATUS/summary:USERTYPE|eprint/buffer/summary:owner]], [[#eprint/STATUS/move_inbox:USER_TYPE|eprint/buffer/move_inbox:owner]], [[#eprint/STATUS/details:USERTYPE|eprint/buffer/details:owner]], [[#eprint/STATUS/history:USERTYPE|eprint/buffer/history:owner]], [[#eprint/STATUS/messages:USERTYPE|eprint/buffer/messages:owner]], [[#eprint/STATUS/request_removal:USERTYPE|eprint/buffer/request_removal:owner]], [[#eprint/STATUS/use_as_template:USERTYPE|eprint/buffer/use_as_template:owner]], [[#eprint/STATUS/derive_version:USERTYPE|eprint/buffer/derive_version:owner]], [[#eprint/STATUS/view:USERTYPE|eprint/archive/view:owner]], [[#eprint/STATUS/export:USERTYPE|eprint/archive/export:owner]], [[#eprint/STATUS/summary:USERTYPE|eprint/archive/summary:owner]], [[#eprint/STATUS/details:USERTYPE|eprint/archive/details:owner]], [[#eprint/STATUS/history:USERTYPE|eprint/archive/history:owner]], [[#eprint/STATUS/messages:USERTYPE|eprint/archive/messages:owner]], [[#eprint/STATUS/request_removal:USERTYPE|eprint/archive/request_removal:owner]], [[#eprint/STATUS/use_as_template:USERTYPE|eprint/archive/use_as_template:owner]], [[#eprint/STATUS/derive_version:USERTYPE|eprint/archive/derive_version:owner]], [[#eprint/STATUS/view:USERTYPE|eprint/deletion/view:owner]], [[#eprint/STATUS/export:USERTYPE|eprint/deletion/export:owner]], [[#eprint/STATUS/summary:USERTYPE|eprint/deletion/summary:owner]], [[#eprint/STATUS/details:USERTYPE|eprint/deletion/details:owner]], [[#eprint/STATUS/history:USERTYPE|eprint/deletion/history:owner]], [[#eprint/STATUS/messages:USERTYPE|eprint/deletion/messages:owner]], [[#eprint/STATUS/use_as_template:USERTYPE|eprint/deletion/use_as_template:owner]], [[#eprint/STATUS/derive_version:USERTYPE|eprint/deletion/derive_version:owner]]
;general
: [[#user/view:USERTYPE|user/view:owner]], [[#user/details:USERTYPE|user/details:owner]], [[#user/history:USERTYPE|user/history:owner]]
;edit-config
: [[#config/edit/FILETYPE|config/edit]], [[#config/edit/FILETYPE|config/edit/xml]], [[#config/edit/FILETYPE|config/edit/workflow]], [[#config/edit/FILETYPE|config/edit/citation]], [[#config/edit/FILETYPE|config/edit/phrase]], [[#config/edit/FILETYPE|config/edit/namedset]], [[#config/edit/FILETYPE|config/edit/template]], [[#config/edit/FILETYPE|config/edit/static]], [[#config/edit/FILETYPE|config/edit/autocomplete]], [[#config/reload|config/reload]]
;edit-own-record
: [[#user/edit:USERTYPE|user/edit:owner]]
;editor
: [[#datasets|datasets]], [[#editorial_review|editorial_review]], [[#eprint/STATUS/view:USERTYPE|eprint/inbox/view:editor]], [[#eprint/STATUS/export:USERTYPE|eprint/inbox/export:editor]], [[#eprint/STATUS/summary:USERTYPE|eprint/inbox/summary:editor]], [[#eprint/STATUS/export:USERTYPE|eprint/inbox/export:editor]], [[#eprint/STATUS/details:USERTYPE|eprint/inbox/details:editor]], [[#eprint/STATUS/history:USERTYPE|eprint/inbox/history:editor]], [[#eprint/STATUS/messages:USERTYPE|eprint/inbox/messages:editor]], [[#eprint/STATUS/remove_with_email:USERTYPE|eprint/inbox/remove_with_email:editor]], [[#eprint/STATUS/move_archive:USERTYPE|eprint/inbox/move_archive:editor]], [[#eprint/STATUS/move_buffer:USERTYPE|eprint/inbox/move_buffer:editor]], [[#eprint/STATUS/use_as_template:USERTYPE|eprint/inbox/use_as_template:editor]], [[#eprint/STATUS/derive_version:USERTYPE|eprint/inbox/derive_version:editor]], [[#eprint/STATUS/edit:USERTYPE|eprint/inbox/edit:editor]], [[#eprint/STATUS/takelock:USERTYPE|eprint/inbox/takelock:editor]], [[#eprint/STATUS/view:USERTYPE|eprint/buffer/view:editor]], [[#eprint/STATUS/export:USERTYPE|eprint/buffer/export:editor]], [[#eprint/STATUS/summary:USERTYPE|eprint/buffer/summary:editor]], [[#eprint/STATUS/export:USERTYPE|eprint/buffer/export:editor]], [[#eprint/STATUS/details:USERTYPE|eprint/buffer/details:editor]], [[#eprint/STATUS/history:USERTYPE|eprint/buffer/history:editor]], [[#eprint/STATUS/messages:USERTYPE|eprint/buffer/messages:editor]], [[#eprint/STATUS/issues:USERTYPE|eprint/buffer/issues:editor]], [[#eprint/STATUS/remove_with_email:USERTYPE|eprint/buffer/remove_with_email:editor]], [[#eprint/STATUS/reject_with_email:USERTYPE|eprint/buffer/reject_with_email:editor]], [[#eprint/STATUS/move_inbox:USERTYPE|eprint/buffer/move_inbox:editor]], [[#eprint/STATUS/move_archive:USERTYPE|eprint/buffer/move_archive:editor]], [[#eprint/STATUS/use+as_template:USERTYPE|eprint/buffer/use_as_template:editor]], [[#eprint/STATUS/derive_version:USERTYPE|eprint/buffer/derive_version:editor]], [[#eprint/STATUS/edit:USERTYPE|eprint/buffer/edit:editor]], [[#eprint/STATUS/takelock:USERTYPE|eprint/buffer/takelock:editor]], [[#eprint/STATUS/view:USERTYPE|eprint/deletion/view:editor]], [[#eprint/STATUS/export:USERTYPE|eprint/deletion/export:editor]], [[#eprint/STATUS/summary:USERTYPE|eprint/deletion/summary:editor]], [[#eprint/STATUS/export:USERTYPE|eprint/deletion/export:editor]], [[#eprint/STATUS/details:USERTYPE|eprint/deletion/details:editor]], [[#eprint/STATUS/history:USERTYPE|eprint/deletion/history:editor]], [[#eprint/STATUS/messages:USERTYPE|eprint/deletion/messages:editor]], [[#eprint/STATUS/move_archive:USERTYPE|eprint/deletion/move_archive:editor]], [[#eprint/STATUS/use_as_template:USERTYPE|eprint/deletion/use_as_template:editor]], [[#eprint/STATUS/derive_version:USERTYPE|eprint/deletion/derive_version:editor]], [[#eprint/STATUS/takelock:USERTYPE|eprint/deletion/takelock:editor]],
;rest
: [[#eprint/STATUS/rest/get:USERTYPE|eprint/archive/rest/get:editor]], [[#eprint/STATUS/rest/put:USERTYPE|eprint/archive/rest/put:editor]], [[#eprint/STATUS/rest/get:USERTYPE|eprint/buffer/rest/get:editor]], [[#eprint/STATUS/rest/put:USERTYPE|eprint/buffer/rest/put:editor]], [[#eprint/STATUS/rest/get:USERTYPE|eprint/inbox/rest/get:editor]], [[#eprint/STATUS/rest/put:USERTYPE|eprint/inbox/rest/put:editor]], [[#eprint/STATUS/rest/get:USERTYPE|eprint/deletion/rest/get:editor]], [[#eprint/STATUS/rest/put:USERTYPE|eprint/deletion/rest/put:editor]], [[#eprint/STATUS/rest/get:USERTYPE|eprint/inbox/rest/get:owner]], [[#eprint/STATUS/rest/put:USERTYPE|eprint/inbox/rest/put:owner]], [[#eprint/STATUS/rest/get:USERTYPE|eprint/buffer/rest/get:owner]], [[#eprint/STATUS/rest/get:USERTYPE|eprint/archive/rest/get:owner]], [[#eprint/STATUS/rest/get:USERTYPE|eprint/deletion/rest/get:owner]], [[#user/rest/get:USERTYPE|user/rest/get:owner]], [[#subject/rest/get|subject/rest/get]]
;saved-searches
: [[#saved_search|saved_search]], [[#create_saved_search|create_saved_search]], [[#saved_search/view:USERTYPE|saved_search/view:owner]], [[#saved_search/edit:USERTYPE|saved_search/edit:owner]], [[#saved_search/destroy:USERTYPE|saved_search/destroy:owner]]
;set-password
: [[#set-password|set-password]]
;staff-view
: [[#eprint/STATUS/view:USERTYPE|eprint/inbox/view]], [[#eprint/STATUS/summary:USERTYPE|eprint/inbox/summary]], [[#eprint/STATUS/export:USERTYPE|eprint/inbox/export]], [[#eprint/STATUS/details:USERTYPE|eprint/inbox/details]], [[#eprint/STATUS/history:USERTYPE|eprint/inbox/history]], [[#eprint/STATUS/view:USERTYPE|eprint/buffer/view]], [[#eprint/STATUS/summary:USERTYPE|eprint/buffer/summary]], [[#eprint/STATUS/export:USERTYPE|eprint/buffer/export]], [[#eprint/STATUS/details:USERTYPE|eprint/buffer/details]], [[#eprint/STATUS/history:USERTYPE|eprint/buffer/history]], [[#eprint/STATUS/view:USERTYPE|eprint/archive/view]], [[#eprint/STATUS/export:USERTYPE|eprint/archive/export]], [[#eprint/STATUS/details:USERTYPE|eprint/archive/details]], [[#eprint/STATUS/history:USERTYPE|eprint/archive/history]], [[#eprint/STATUS/view:USERTYPE|eprint/deletion/view]], [[#eprint/STATUS/summary:USERTYPE|eprint/deletion/summary]], [[#eprint/STATUS/export:USERTYPE|eprint/deletion/export]], [[#eprint/STATUS/details:USERTYPE|eprint/deletion/details]], [[#eprint/STATUS/history:USERTYPE|eprint/deletion/history]], [[#eprint/search/staff:USERTYPE|eprint/search/staff]]
;toolbox
: [[#toolbox|toolbox]]
;view-status
: [[#status|status]]

== Roles used by User Types (as of EPrints 3.4.x) ==
;minuser
:general, edit-own-record, saved-searches, set-password, lock-username-to-email
;user
:general, edit-own-record, saved-searches, set-password, deposit, change-email
;editor
:general, edit-own-record, saved-searches, set-password, deposit, change-email, editor, view-status, staff-view
;admin
:general, edit-own-record, saved-searches, set-password, deposit, change-email, editor, view-status, staff-view, admin, edit-config

== User Privileges ==
=== config ===
==== config/add_field ====
Add a bespoke field to a data object, using the web browser interface.
==== config/delete/FILETYPE ====
Delete a configuration file. This can optionally be restricted to a file of a particular '''FILETYPE''': ''autocomplete, citation, namedset, perl, phrase, static, template, workflow, xml''. Some of these types can overlap, e.g. ''workflow'' is also ''xml''.
==== config/edit/FILETYPE ====
Edit a configuration file. This can optionally be restricted to a file of a particular '''FILETYPE''': ''autocomplete, citation, namedset, perl, phrase, static, template, workflow, xml''. Some of these types can overlap, e.g. ''workflow'' is also ''xml''.
==== config/imports ====
Unused by default. Intended for managing bulk imports to a repository archive.
==== config/regen_abstracts ====
Drops the abstract pages cache so abstract pages can be regenerated.
==== config/regen_citations ====
Drops the citations cache so citations can be regenerated.
==== config/regen_views ====
Drops the browse view cache so browse view pages can be regenerated.
==== config/reload ====
Reload the repository configuration.
==== config/remove_field ====
Remove a field from a data object. (Only fields created via the web browser interfaces, not pre-created through archive configuration).
==== config/test_email ====
View the "Send test email" page to send a test email to a specified address to confirm email sending is working as expected.
==== config/view/FILETYPE ====
View a configuration file. This can optionally be restricted to a file of a particular '''FILETYPE''': ''autocomplete, citation, namedset, perl, phrase, static, template, workflow, xml''. Some of these types can overlap, e.g. ''workflow'' is also ''xml''.

=== eprint ===
Some eprint privileges can be specialised by the '''STATUS''' of the the eprint (e.g. ''inbox'', ''buffer'', ''archive'' or ''deletion'' and the '''USERTYPE''' (e.g. ''owner'' or ''editor''). The privilege ''eprint/view'' would allow the user to view any eprint, ''eprint/archive/view'' would only allow them to view eprints in the live archive and ''eprint/inbox/view:owner'' would only allow them to view eprints in the user workarea if they were owned by the user.
==== create_eprint ====
Create a new eprint, which will initial appear in that user's workarea.
==== eprint_search ====
View and use eprint search across live archive.
==== eprint/reject_with_email ====
Reject the eprint under review (returning to user's workarea) and email eprint's owner about this.
==== eprint/remove_once_archived ====
Completely remove an eprint even if it is or has been in the live archive.
==== eprint/remove_with_email ====
Completely remove an eprint and email eprint's owner to about this.
==== eprint/staff/search ====
View and use full eprint search across all statuses of eprint.
==== eprint/STATUS/deposit:USERTYPE ====
Deposit an eprint. Typically this would be just changing it status from ''inbox'' to ''buffer'', so the eprint can be reviewed.
==== eprint/STATUS/derive_version:USERTYPE ====
Create a new version of a chosen eprint. Copying the metadata and setting the ''succeeds'' field to that of that chosen eprint.
==== eprint/STATUS/destroy:USERTYPE ====
Completely delete an existing eprint via "Manage records" page.

==== eprint/STATUS/details:USERTYPE ====
View the ''Details'' tab for an eprint.
==== eprint/STATUS/edit:USERTYPE ====
Edit the metadata for an eprint
==== eprint/STATUS/export:USERTYPE ====
Export the metadata for an eprint in one or more different formats.
==== eprint/STATUS/history:USERTYPE ====
View the ''History'' tab for an eprint.
==== eprint/STATUS/issues:USERTYPE ====
View the ''Issues'' tab for an eprint.
==== eprint/STATUS/messages:USERTYPE ====
View the ''Messages'' tab for an eprint.
==== eprint/STATUS/move_archive:USERTYPE ====
Move an eprint to the live archive. (I.e. change its status, normally from ''buffer'' to ''archive'').
==== eprint/STATUS/move_buffer:USERTYPE ====
Move an eprint back to the review buffer. (I.e. change its status to ''buffer'').
==== eprint/STATUS/move_deletion:USERTYPE ====
Retire an eprint. (I.e. change its status, normally from ''archive'' to ''deletion'').
==== eprint/STATUS/move_inbox:USERTYPE ====
Move an eprint back to a user's workarea. (I.e. change its status, normally from ''buffer'' to ''inbox'').
==== eprint/STATUS/remove:USERTYPE ====
Completely remove an eprint.
==== eprint/STATUS/request_removal:USERTYPE ====
Request that an existing eprint is removed, (e.g. because it is a duplicate or has been added erroneously).
==== eprint/STATUS/rest/get:USERTYPE ====
An eprint's metadata can be retrieved using the REST API.
==== eprint/STATUS/rest/put:USERTYPE ====
An eprint's metadata can be set using the REST API.
==== eprint/STATUS/summary:USERTYPE ====
View the ''Summary''' tab of an eprint.
==== eprint/STATUS/takelock:USERTYPE ====
Take the edit lock on an eprint.
==== eprint/STATUS/upsert:USERTYPE ====
Overwrite the existing metadata for an eprint. Typically with a PUT request via an API not through the repository's web browser interface.
==== eprint/STATUS/use_as_template:USERTYPE ====
Use metadata from a chosen eprint to create a new eprint, which is not a new version of that chosen eprint.
==== eprint/STATUS/view:USERTYPE ====
View an eprint and a rendering of its metadata

=== event_queue ===
==== event_queue/destroy ====
Completely delete an event queue task.
==== event_queue/details ====
View the ''Details'' tab for an event queue task.
==== event_queue/edit ====
Edit an event queue task. (E.g. change the time it should run or reset its status if it has failed.)
==== event_queue/export ====
Export the metadata for an event queue task.
==== event_queue/view ====
View the metadata for an event queue task.

=== file ===
==== file/destroy ====
Completely delete a file record via "Manage records" page.

==== file/export ====
Export the metadata for a file record.
==== file/view ====
View the metadata for a file record.

=== import ===
==== import/view ====
View the metadata for an import.
==== import/edit ====
Edit the metadata for an import.

=== indexer ===
==== indexer/force_start ====
Force start the indexer, if the repository thinks it is still running but no event queue tasks are being processed.
==== indexer/start ====
Start the indexer if it is not currently running.
==== indexer/stop ====
Stop the indexer if it is currently running.

=== saved_search ===
Some saved search privileges can be specialised by '''USERTYPE''' (e.g. ''owner''). The privilege ''saved_search/edit'' would allow the user to view any saved search record, ''saved_search/edit:owner'' would only allow them to edit their own saved search records.
==== create_saved_search ====
Create a new saved_search record.
==== saved_search ====
View listing or a user's saved searches.
==== saved_search/destroy:USERTYPE ====
Completely delete a saved search record.
==== saved_search/details:USERTYPE ====
View the ''Details'' tab for a saved search record.
==== saved_search/edit:USERTYPE ====
Edit the metadata for a saved search record.
==== saved_search/export:USERTYPE ====
Export the metadata for a saved search record.
==== saved_search/view:USERTYPE ====
View the metadata for a saved search record.

=== staff ===
==== staff/user_search ====
View and use the search over user records.
==== staff/history_search ====
View and use the search over eprint history records.
==== staff/issue_search ====
View and use the search over eprint issue records.

=== subject ===
==== subject/edit ====
View and edit the subject tree.
==== subject/rest/get ====
A subject's metadata can be retrieved using the REST API.

=== user ===
Some user privileges can be specialised by '''USERTYPE''' (e.g. ''owner''). The privilege ''user/edit'' would allow the user to view any user record, ''user/edit:owner'' would only allow them to edit their own user record.
==== create_user ====
Create a new user.
==== user/destroy:USERTYPE ====
Completely delete a user record.
==== user/details:USERTYPE ====
View the ''Details'' tab of a user.
==== user/edit:USERTYPE ====
Edit a user's profile.
==== user/history:USERTYPE ====
View the ''History'' tab of a user. This includes the changes (revisions) they made to any eprint record.
==== user/mediate ====
Whether a user can mediate for (i.e. act as) another user. Required feature of [[SWORD]] API.
==== user/remove:USERTYPE ====
Unused by default. Intended for removing a user record. Use [[#user/destroy:USERTYPE|user/destroy:USERTYPE]] instead.

==== user/staff/edit ====
Unused by default. Intended for restricting parts of a user's profile to be edited by a repository admininistrator.
==== user/view:USERTYPE ====
View a user record's metadata.

=== Miscellaneous ===
==== datasets ====
View the "Manage records" page.
==== editorial_review ====
View the "Review" page.
==== items ====
View the "Manage deposits" page.
==== repository/epm ====
View the "EPrints Bazaar" page and install Bazaar plugins.
==== set-password ====
Unused by default. Intended for restricting whether a user can set their own password.
==== status ====
View the "Status" and "Database Schema" pages.
==== storage/manager ====
View the "Storage Manager" page.
==== toolbox ====
Use the toolbox CGI script (i.e. ''/cgi/toolbox/toolbox'') to carry out a operation provided by EPrints::Toolbox. '''Dangerous''': Do not enable without good reason.

== Public Role User Privileges ==
These privileges available to users without them needing to login. This mainly pertains to REST requests you may or may not want accessible.
;+eprint/archive/rest/get
:REST request to get metadata for an eprint in the live archive
;+subject/archive/rest/get
:REST request to get metadata for a subject in the archive's subject tree.

User Roles and Privileges

2022-12-14T08:57:03Z

Libjlrs:

[[Category:User Roles]]
This page is intended to provide a useful guide on how [[EPrints Glossary#User role|user roles]] and [[EPrints Glossary#User privilege|privileges]] work within EPrints repository software, expanding on the information already available at [[user_roles.pl]].

A role in EPrints is made up of 1 or more privileges. Giving a user a role gives them all the privileges associated with that role. You can also give users additional privileges without giving them the full role.

==Creating a role==
To create the role <code>approve-hat</code> you would do the following:
<pre>
$c->{roles}->{"approve-hat"} = [
"eprint/buffer/view:editor",
"eprint/buffer/summary:editor",
"eprint/buffer/details:editor",
"eprint/buffer/move_archive:editor",
];
</pre>
The privileges listed above means the users given the <code>approve-hat</code> role can see the View, Summary, Details and Move to archive screen as an editor. Note because they cannot edit items [[Standard names |in the buffer]] they can't correct any mistakes they find. However they do have the power to move items to the archive. This means the <code>approve-hat</code> allows a user to see the metadata of an item and if they think it is correct move it to the archive. They cannot return it to the user or edit the metadata themselves.

The quoting around the role name approve-hat is required, eprints will generate an error if the text is simply {approve-hat}.

Tip: Ensure the role is in {roles} not {user_roles}!

== Anatomy of a privilege ==
Many pre-existing privileges have a specific structure so they can be tested for generically. Privileges on data objects use the dataset ID as the first part of the privilege and the last part as the action that can be carried out on that data object. E.g.
* eprint/view
* user/edit
* saved_search/export
As the eprint data object also has virtual datasets that are subsets of the eprint dataset, based on the status of the eprints these are often used as the second part of the privilege. E.g.
* eprint/archive/view
* eprint/inbox/edit
* eprint/buffer/export
eprint and user data objects can also have an additional modifier to restrict the context in which the privilege permits access:
; eprint/inbox/view:owner
: A user can only view eprints that they own in the user workarea.
; eprint/buffer/edit:editor
: Only users with editorial scope for the eprint can edit it when it is in the review buffer
; user/view:owner
: A user can only view their own user profile.
config privileges are typically use the specfic privilege they give access. E.g.
* config/indexer
* config/regen_abstracts
* config/view
However, ''config/view'' and ''config/edit'' can be specialized to allow specific types of configuration file to be viewed or edited. E.g.
* config/view/phrase
* config/edit/autocomplete

== Creating a privilege ==
There is no special step to creating a privilege, simply define it where you would like it tested for. Equally, there is no specified format for new privileges tying them to (for example) screens. As a result the following are all valid:
* "eprint/coindoi"
* "eprint/coindoiffff"
* "eprint/coindoi:editor"
However, to make sure the privilege is as intuitive as possible, it is best to stick as closely to the conventions described in "[[#Anatomy of a privilege|Anatomy of a privilege]]".

==Assigning a role==
Now that you have created a role you want to give that to class of users. To give every regular user of the repository the <code>approve-hat</code> you add it to the list of roles for the user.

<pre>
$c->{user_roles}->{user} = [
'general',
'edit-own-record',
'saved-searches',
'set-password',
'deposit',
'change-email',
'approve-hat',
],
</pre>

Rather than giving every user the role you can give it to individual users. Administer a users profile and add the name of the role to their list of additional roles.

[[File:Approve-hat.jpg]]

==Assigning a user privilege==
You do not have to give a user a full role you can give them a privilege. The syntax is slightly different. Add the name of the privilege prefixed with a '+' to the list of roles. You can remove a privilege by prefixing it with a '-'.

<pre>
$c->{user_roles}->{user} = [
'general',
'edit-own-record',
'saved-searches',
'set-password',
'deposit',
'change-email',
'approve-hat',
'+eprint/archive/edit:owner',
],
</pre>

You can also assign privileges to individual users through the web interface in the same way you can assign a role, remembering they will be listed as "roles". (remember the '+' or '-')

There is no need for users to log in again following a privilege change, eprints will pick it up automatically.

== See Also ==
* [[Listings of User Roles and Privileges]] - A reference to role and privileges and what they allow a user to do.
* [[User_roles.pl|user_roles.pl]] - Describe the configuration file and how it may be edited/extended to modify/add new roles and privileges.
* [[How to make a Screen for the Admin Section#Making the page appear|Screen plugin visibility]] - Example of making a new Screen Plugin appear using roles.

[[Category:Manual]]

How to make a Screen for the Admin Section

2022-12-14T08:56:29Z

Libjlrs:

[[Category:Howto]]
[[Category:Plugins]]
[[Category:User Roles]]
Known to work for EPrints 3.2+

== The basic structure ==
To make a Screen plugin, you create a Perl Module in <code>[eprints]/archives/<ARCHIVE_ID>/cfg/plugins/EPrints/Plugin/Screen/</code> with the following basic structure
<pre>

package EPrints::Plugin::Screen::Mypackage;

use EPrints::Plugin::Screen;

@ISA = ( 'EPrints::Plugin::Screen' );

use strict;

sub new
{
my( $class, %params ) = @_;
my $self = $class->SUPER::new(%params);
$self->{priv} = undef;
$self->{appears} = [
{
place => "admin_actions_editorial", # see notes below
position => 1450,
},
];
return $self;
}

sub can_be_viewed
{
my( $self ) = @_;
return $self->allow( "my/conf/value" );
}

sub render
{
my( $self ) = @_;
my $session = $self->{session};
my $user = $session->current_user;

my $p = $session->make_doc_fragment;

# create page contents:
my $h = $session->make_element( "h3" );
$h->appendChild($session->make_text( "Look up organisations known to OA-RJ" ));
$p->appendChild($h);

return $p
}
</pre>

In theory, one should be able to have multiple bits of functionality (view a little, view a lot, edit, etc), simply by testing for different values of <code>$self->allow( "my/conf/value" )</code>

== The locations ==
Where the link for the page appears is defined by <code>$self->{appears}->[''n'']->{place}</code> (in the <code>new</code> function.)

We are defining a screen that appears in the "admin" area, and there are 4 tabs defined within the admin screen:
* admin_actions_editorial
* admin_actions_system
* admin_actions_config
* admin_actions_misc

Other places the link can appear are
* unknown to me

== Making the page appear ==
There are three steps to making a page appear:

1. The screen plugin should test for ''view-ability''
<pre>
# in EPrints::Plugin::Screen::Mypackage
sub can_be_viewed
{
my( $self ) = @_;
return $self->allow( "my/conf/value" );
}
</pre>
2 The ''User'' DataObject needs to list the privilege under a role:
<pre>
# In EPrints::DataObj::User
foo_bar => [
"my/view/value",
],
foo_baz => [
"my/view/value",
"my/conf/value",
],
</pre>
3 The user_roles.pl file needs to make the role available to the user-type:
<pre>
# in [eprints]/archive/<ARCHIVE_ID>/cfg/cfg/user_roles.pl
$c->{user_roles}->{user} = [qw{
// truncated
foo_bar
}],
$c->{user_roles}->{admin} = [qw{
// truncated
foo_baz
}],
</pre>

Return to the main [[Screen_Plugins]] page.

== See Also ==
* [[Listings of User Roles and Privileges]] - A reference to role and privileges and what they allow a user to do.
* [[User_roles.pl|user_roles.pl]] - Describe the configuration file and how it may be edited/extended to modify/add new roles and privileges.

User Roles and Privileges

2022-12-14T08:51:34Z

Libjlrs:

This page is intended to provide a useful guide on how [[EPrints Glossary#User role|user roles]] and [[EPrints Glossary#User privilege|privileges]] work within EPrints repository software, expanding on the information already available at [[user_roles.pl]].

A role in EPrints is made up of 1 or more privileges. Giving a user a role gives them all the privileges associated with that role. You can also give users additional privileges without giving them the full role.

==Creating a role==
To create the role <code>approve-hat</code> you would do the following:
<pre>
$c->{roles}->{"approve-hat"} = [
"eprint/buffer/view:editor",
"eprint/buffer/summary:editor",
"eprint/buffer/details:editor",
"eprint/buffer/move_archive:editor",
];
</pre>
The privileges listed above means the users given the <code>approve-hat</code> role can see the View, Summary, Details and Move to archive screen as an editor. Note because they cannot edit items [[Standard names |in the buffer]] they can't correct any mistakes they find. However they do have the power to move items to the archive. This means the <code>approve-hat</code> allows a user to see the metadata of an item and if they think it is correct move it to the archive. They cannot return it to the user or edit the metadata themselves.

The quoting around the role name approve-hat is required, eprints will generate an error if the text is simply {approve-hat}.

Tip: Ensure the role is in {roles} not {user_roles}!

== Anatomy of a privilege ==
Many pre-existing privileges have a specific structure so they can be tested for generically. Privileges on data objects use the dataset ID as the first part of the privilege and the last part as the action that can be carried out on that data object. E.g.
* eprint/view
* user/edit
* saved_search/export
As the eprint data object also has virtual datasets that are subsets of the eprint dataset, based on the status of the eprints these are often used as the second part of the privilege. E.g.
* eprint/archive/view
* eprint/inbox/edit
* eprint/buffer/export
eprint and user data objects can also have an additional modifier to restrict the context in which the privilege permits access:
; eprint/inbox/view:owner
: A user can only view eprints that they own in the user workarea.
; eprint/buffer/edit:editor
: Only users with editorial scope for the eprint can edit it when it is in the review buffer
; user/view:owner
: A user can only view their own user profile.
config privileges are typically use the specfic privilege they give access. E.g.
* config/indexer
* config/regen_abstracts
* config/view
However, ''config/view'' and ''config/edit'' can be specialized to allow specific types of configuration file to be viewed or edited. E.g.
* config/view/phrase
* config/edit/autocomplete

== Creating a privilege ==
There is no special step to creating a privilege, simply define it where you would like it tested for. Equally, there is no specified format for new privileges tying them to (for example) screens. As a result the following are all valid:
* "eprint/coindoi"
* "eprint/coindoiffff"
* "eprint/coindoi:editor"
However, to make sure the privilege is as intuitive as possible, it is best to stick as closely to the conventions described in "[[#Anatomy of a privilege|Anatomy of a privilege]]".

==Assigning a role==
Now that you have created a role you want to give that to class of users. To give every regular user of the repository the <code>approve-hat</code> you add it to the list of roles for the user.

<pre>
$c->{user_roles}->{user} = [
'general',
'edit-own-record',
'saved-searches',
'set-password',
'deposit',
'change-email',
'approve-hat',
],
</pre>

Rather than giving every user the role you can give it to individual users. Administer a users profile and add the name of the role to their list of additional roles.

[[File:Approve-hat.jpg]]

==Assigning a user privilege==
You do not have to give a user a full role you can give them a privilege. The syntax is slightly different. Add the name of the privilege prefixed with a '+' to the list of roles. You can remove a privilege by prefixing it with a '-'.

<pre>
$c->{user_roles}->{user} = [
'general',
'edit-own-record',
'saved-searches',
'set-password',
'deposit',
'change-email',
'approve-hat',
'+eprint/archive/edit:owner',
],
</pre>

You can also assign privileges to individual users through the web interface in the same way you can assign a role, remembering they will be listed as "roles". (remember the '+' or '-')

There is no need for users to log in again following a privilege change, eprints will pick it up automatically.

== See Also ==
* [[Listings of User Roles and Privileges]] - A reference to role and privileges and what they allow a user to do.
* [[User_roles.pl|user_roles.pl]] - Describe the configuration file and how it may be edited/extended to modify/add new roles and privileges.
* [[How to make a Screen for the Admin Section#Making the page appear|Screen plugin visibility]] - Example of making a new Screen Plugin appear using roles.

[[Category:Manual]]

User Roles and Privileges

2022-12-14T08:50:56Z

Libjlrs: Additional see-also link

How to make a Screen for the Admin Section

2022-12-14T08:43:48Z

Libjlrs: Formatting changes; additional links

[[Category:Howto]][[Category:Plugins]]
Known to work for EPrints 3.2+

== The basic structure ==
To make a Screen plugin, you create a Perl Module in <code>[eprints]/archives/<ARCHIVE_ID>/cfg/plugins/EPrints/Plugin/Screen/</code> with the following basic structure
<pre>

package EPrints::Plugin::Screen::Mypackage;

use EPrints::Plugin::Screen;

@ISA = ( 'EPrints::Plugin::Screen' );

use strict;

sub new
{
my( $class, %params ) = @_;
my $self = $class->SUPER::new(%params);
$self->{priv} = undef;
$self->{appears} = [
{
place => "admin_actions_editorial", # see notes below
position => 1450,
},
];
return $self;
}

sub can_be_viewed
{
my( $self ) = @_;
return $self->allow( "my/conf/value" );
}

sub render
{
my( $self ) = @_;
my $session = $self->{session};
my $user = $session->current_user;

my $p = $session->make_doc_fragment;

# create page contents:
my $h = $session->make_element( "h3" );
$h->appendChild($session->make_text( "Look up organisations known to OA-RJ" ));
$p->appendChild($h);

return $p
}
</pre>

In theory, one should be able to have multiple bits of functionality (view a little, view a lot, edit, etc), simply by testing for different values of <code>$self->allow( "my/conf/value" )</code>

== The locations ==
Where the link for the page appears is defined by <code>$self->{appears}->[''n'']->{place}</code> (in the <code>new</code> function.)

We are defining a screen that appears in the "admin" area, and there are 4 tabs defined within the admin screen:
* admin_actions_editorial
* admin_actions_system
* admin_actions_config
* admin_actions_misc

Other places the link can appear are
* unknown to me

== Making the page appear ==
There are three steps to making a page appear:

1. The screen plugin should test for ''view-ability''
<pre>
# in EPrints::Plugin::Screen::Mypackage
sub can_be_viewed
{
my( $self ) = @_;
return $self->allow( "my/conf/value" );
}
</pre>
2 The ''User'' DataObject needs to list the privilege under a role:
<pre>
# In EPrints::DataObj::User
foo_bar => [
"my/view/value",
],
foo_baz => [
"my/view/value",
"my/conf/value",
],
</pre>
3 The user_roles.pl file needs to make the role available to the user-type:
<pre>
# in [eprints]/archive/<ARCHIVE_ID>/cfg/cfg/user_roles.pl
$c->{user_roles}->{user} = [qw{
// truncated
foo_bar
}],
$c->{user_roles}->{admin} = [qw{
// truncated
foo_baz
}],
</pre>

Return to the main [[Screen_Plugins]] page.

== See Also ==
* [[Listings of User Roles and Privileges]] - A reference to role and privileges and what they allow a user to do.
* [[User_roles.pl|user_roles.pl]] - Describe the configuration file and how it may be edited/extended to modify/add new roles and privileges.

Contribute: Plugins/ImportPluginsAWS

2021-05-24T11:13:59Z

Libjlrs: Code formatting

[[Category:Contribute]]
[[Category:Plugins]]
= Import Plugin Tutorial 2: Amazon Web Services =

In the [[Contribute:_Plugins/ImportPluginsCSV|last tutorial]] we created an import plugin that took data which needed very little modification to import into the respository. The column names in the [http://en.wikipedia.org/wiki/Comma-Separated_Values CSV] file matched the names of metadata fields present in the repository. In this tutorial we'll look at importing data that needs some modification to be imported, needs more error checking and is obtained in a different way.

We will be using Amazon's E-Commerce Webservice to import books from their website into our respository given a list of [http://en.wikipedia.org/wiki/ASIN ASIN].

We will be accessing the service using a [http://en.wikipedia.org/wiki/REST REST] approach, communicating with the server using URL parameters and retrieving an XML document in response to our request. It is also possible to access their services using [http://en.wikipedia.org/wiki/SOAP SOAP], but that will not be discussed here.

= Before You Start =

== Amazon Web Services ==
To use Amazon's web services you must first signup for an account [http://aws.amazon.com here]. Their site has extensive documentation on the services that they offer as well as example programs including some written in Perl.

== Required Modules ==
To prepare for this tutorial you should make sure the [http://search.cpan.org/~gaas/libwww-perl-5.805/lib/LWP/UserAgent.pm LWP::UserAgent] module is installed. The following command as root, or using sudo should work.

<pre>
cpan LWP::UserAgent
</pre>

= AWS.pm =
The code in the section below should be placed in a file called CSV.pm in the directory created previously, and MyPlugins should be changed to the name of that directory.

<syntaxhighlight lang="perl">
package EPrints::Plugin::Import::MyPlugins::AWS;

use EPrints::Plugin::Import::TextFile;
use strict;
use URI::Escape;

our @ISA = ('EPrints::Plugin::Import::TextFile');

my $endpoint = 'http://ecs.amazonaws.co.uk/onca/xml';
my $accesskey = '<YOURAMAZONWSKEY>';
my $service = 'AWSECommerceService';
my $operation = 'ItemLookup';
my $version = '2007-07-16';
my $responsegroup = 'Large';

sub new
{
my( $class, %params ) = @_;
my $self = $class->SUPER::new( %params );

$self->{name} = 'AWS';
$self->{visible} = 'all';
$self->{produce} = [ 'list/eprint' , 'dataobj/eprint'];

my $rc = EPrints::Utils::require_if_exists('LWP::UserAgent');
unless ($rc)
{
$self->{visible} = '';
$self->{error} = 'Unable to load required module LWP::UserAgent';
}

return $self;
}

sub input_fh
{
my( $plugin, %opts ) = @_;
my @ids;
my $fh = $opts{fh};

my @records = <$fh>;
foreach my $input_data (@records)
{
my $epdata = $plugin->convert_input($input_data);
next unless defined $epdata;

my $dataobj = $plugin->epdata_to_dataobj($opts{dataset},$epdata);
if( defined $dataobj )
{
push @ids, $dataobj->get_id;
}
}

return EPrints::List->new(
dataset => $opts{dataset},
session => $plugin->{session},
ids=>\@ids );
}

sub convert_input
{
my ($plugin, $input) = @_;
my %output = ();

$input =~ m/([A-Za-z0-9]+)/;
$input = $1;

my $request =
"$endpoint?".
"Service=$service&".
"AWSAccessKeyId=$accesskey&".
"Operation=$operation&".
"ItemId=$input&".
"Version=$version&".
"ResponseGroup=$responsegroup";

my $ua = LWP::UserAgent->new;
$ua->timeout(30);
my $response = $ua->get($request);

my $dom = EPrints::XML::parse_xml_string($response->content);

my $rep =
$dom->getElementsByTagName('Items')->item(0)->
getElementsByTagName('Request')->item(0);

my $reptext =
EPrints::Utils::tree_to_utf8($rep->getElementsByTagName('IsValid')->item(0));

unless ($reptext eq 'True')
{
$plugin->error('Invalid AWS Request');
return undef;
}

#Get Item Object
my $item =
$dom->getElementsByTagName('Items')->item(0)->
getElementsByTagName('Item')->item(0);

unless (defined $item)
{
$plugin->error('No Item element found');
return undef;
}

my $attr = $item->getElementsByTagName('ItemAttributes')->item(0);

my $pg = EPrints::Utils::tree_to_utf8($attr->getElementsByTagName('ProductGroup')->item(0));

unless ($pg eq 'Book')
{
$plugin->error('Product is not a book.');
return undef;
}

$output{type} = 'book';
$output{refereed} = 'FALSE';
$output{ispublished} = 'pub';

my $title = $attr->getElementsByTagName('Title')->item(0);
$output{title} = EPrints::Utils::tree_to_utf8($title);

my $url = $item->getElementsByTagName('DetailPageURL')->item(0);
$output{official_url} = uri_unescape(EPrints::Utils::tree_to_utf8($url));

my $isbn = $attr->getElementsByTagName('ISBN')->item(0);
if (defined $isbn)
{
$output{isbn} = EPrints::Utils::tree_to_utf8($isbn);
}

my $pages = $attr->getElementsByTagName('NumberOfPages')->item(0);
if (defined $pages)
{
$output{pages} = EPrints::Utils::tree_to_utf8($pages);
}

my $publisher = $attr->getElementsByTagName('Publisher')->item(0);
if (defined $publisher)
{
$output{publisher} = EPrints::Utils::tree_to_utf8($publisher);
}

my $pubdate = $attr->getElementsByTagName('PublicationDate')->item(0);
if (defined $pubdate)
{
$output{date} = EPrints::Utils::tree_to_utf8($pubdate);
}

return \%output;
}

1;
</syntaxhighlight>

= In More Detail =
We will use the URI::Escape module in this plugin. As it is included with EPrints we don't need to check if it exists first.
<pre>
use URI::Escape;
</pre>

Here we setup a number of values for parameters that will be part of our web service requests. The endpoint variable determines which server will be sent the request. Here we have used the UK server, but by changing the [http://en.wikipedia.org/wiki/TLD TLD] we can use the US, Canadian, German or French servers.

The accesskey variable stores the access key you will have gained from signing up to Amazon earlier. You should use the normal access key and not the secret one.

Here we use the ItemLookup operation of the AWSECommerceService with the 2007-07-16 version of the API. Other operations allow searching for items, but here we want to look up specific products. Finally the variable responsegroup determines the amount and nature of the information returned, we select "Large" in this case, which gives us more information about the item.

<pre>
my $endpoint = 'http://ecs.amazonaws.co.uk/onca/xml';
my $accesskey = '<YOURAMAZONWSKEY>';
my $service = 'AWSECommerceService';
my $operation = 'ItemLookup';
my $version = '2007-07-16';
my $responsegroup = 'Large';
</pre>

== Constructor ==
The constructor is similar to the one used for the [Contribute:_Plugins/ImportPluginsCSV CSV plugin], except this one will import individual eprints, given an [http://en.wikipedia.org/wiki/ASIN ASIN].
<pre>
$self->{produce} = [ 'list/eprint' , 'dataobj/eprint'];
</pre>

Like we imported Text::CSV in the [Contribute:_Plugins/ImportPluginsCSV last tutorial], here we import LWP::UserAgent which will be used for making requests to the web service.
<pre>
my $rc = EPrints::Utils::require_if_exists('LWP::UserAgent');
unless ($rc)
{
$self->{visible} = '';
$self->{error} = 'Unable to load required module LWP::UserAgent';
}
</pre>

== Input ==
=== input_fh ===
This method is similar to the one used in the [Contribute:_Plugins/ImportPluginsCSV CSV plugin], but doesn't have to do quite so much work.

First we create the array to hold our imported eprint ids.
<pre>
my @ids;
</pre>

Next we read all the lines in the supplied file handle into our records array.
<pre>
my $fh = $opts{fh};

my @records = <$fh>;
</pre>

Then we iterate over each record, running convert_input on it, importing it into our repository and adding the id to our array.
<pre>
foreach my $input_data (@records)
{
my $epdata = $plugin->convert_input($input_data);
next unless defined $epdata;

my $dataobj = $plugin->epdata_to_dataobj($opts{dataset},$epdata);
if( defined $dataobj )
{
push @ids, $dataobj->get_id;
}
}
</pre>

Then we return a List object of the items imported.
<pre>
return EPrints::List->new(
dataset => $opts{dataset},
session => $plugin->{session},
ids=>\@ids );
</pre>

=== convert_input ===

[http://en.wikipedia.org/wiki/ASIN ASINs] are strings which identify a product. Here we remove any non-alphanumerical characters which are surrounding the [http://en.wikipedia.org/wiki/ASIN ASIN].
<pre>
$input =~ m/([A-Za-z0-9]+)/;
$input = $1;
</pre>

We form the request from the variables we created earlier and the [http://en.wikipedia.org/wiki/ASIN ASIN] we have just obtained.
<pre>
my $request =
"$endpoint?".
"Service=$service&".
"AWSAccessKeyId=$accesskey&".
"Operation=$operation&".
"ItemId=$input&".
"Version=$version&".
"ResponseGroup=$responsegroup";
</pre>

We now send the request, by creating a new LWP::UserAgent object, setting its timeout to 30 seconds and then performing the request using HTTP GET.
<pre>
my $ua = LWP::UserAgent->new;
$ua->timeout(30);
my $response = $ua->get($request);
</pre>

We then create a [http://en.wikipedia.org/wiki/Document_Object_Model DOM] object from the XML document returned.
<pre>
my $dom = EPrints::XML::parse_xml_string($response->content);
</pre>

Each request contains an Items element within the root element of the document which contains a Request element. This element contains an element IsValid. This element will contain the value True or False depending on whether a valid request was made or not.

Here we obtain the Request element and check that the IsValid element within it contains the value True. If it doesn't we call the error method and return undef.
<pre>
my $rep =
$dom->getElementsByTagName("Items")->item(0)->
getElementsByTagName('Request')->item(0);

my $reptext =
EPrints::Utils::tree_to_utf8($rep->getElementsByTagName('IsValid')->item(0));

unless ($reptext eq 'True')
{
$plugin->error('Invalid AWS Request');
return undef;
}
</pre>

The product found with the ItemLookup method is contained within an Item element within the Items element. Here we attempt to get that element and raise the error and return undef if we can't.
<pre>
my $item =
$dom->getElementsByTagName('Items')->item(0)->
getElementsByTagName('Item')->item(0);

unless (defined $item)
{
$plugin->error('No Item element found');
return undef;
}
</pre>

Each item contains an ItemAttributes element which contains most of the metadata about an item.
<pre>
my $attr = $item->getElementsByTagName('ItemAttributes')->item(0);
</pre>

For some specialised repositories it might make sense to import DVDs, computer games and electronic equipment, but we're just going to deal with books. The ProductGroup element within the ItemAttributes element tells you what sort of item we're dealing with. We're looking for the value 'Book'.
<pre>
my $pg = EPrints::Utils::tree_to_utf8($attr->getElementsByTagName('ProductGroup')->item(0));

unless ($pg eq 'Book')
{
$plugin->error('Product is not a book.');
return undef;
}
</pre>

Here we set a few fields without consulting the imported data. We know this is a book, so we set the type. We assume that it has not been refereed. We also assume it has been published, because we can buy it.
<pre>
$output{type} = 'book';
$output{refereed} = 'FALSE';
$output{ispublished} = 'pub';
</pre>

We get and set the title.
<pre>
my $title = $attr->getElementsByTagName('Title')->item(0);
$output{title} = EPrints::Utils::tree_to_utf8($title);
</pre>

Here we set the official URL to the Amazon product page. We have to do a bit of extra work using the uri_unescape method from the URI::Escape package to convert URI escape codes into characters.
<pre>
my $url = $item->getElementsByTagName('DetailPageURL')->item(0);
$output{official_url} = uri_unescape(EPrints::Utils::tree_to_utf8($url));
</pre>

We can set the [http://en.wikipedia.org/wiki/ISBN ISBN]. Note that the [http://en.wikipedia.org/wiki/ISBN ISBN] is often the same as the [http://en.wikipedia.org/wiki/ASIN ASIN].
<pre>
my $isbn = $attr->getElementsByTagName('ISBN')->item(0);
if (defined $isbn)
{
$output{isbn} = EPrints::Utils::tree_to_utf8($isbn);
}
</pre>

We can set the number of pages.
<pre>
my $pages = $attr->getElementsByTagName('NumberOfPages')->item(0);
if (defined $pages)
{
$output{pages} = EPrints::Utils::tree_to_utf8($pages);
}
</pre>

We can set the publisher.
<pre>
my $publisher = $attr->getElementsByTagName('Publisher')->item(0);
if (defined $publisher)
{
$output{publisher} = EPrints::Utils::tree_to_utf8($publisher);
}
</pre>

We can set the publication date and finally return our output hash.
<pre>
my $pubdate = $attr->getElementsByTagName('PublicationDate')->item(0);
if (defined $pubdate)
{
$output{date} = EPrints::Utils::tree_to_utf8($pubdate);
}

return \%output;
</pre>

= Testing Your Plugin =
After restarting your webserver go to the Import Items screen from the Manage Deposits screen. If you can't find this, make sure you're logged in.

We'll start by collecting a few ASINS. Go to [http://www.amazon.co.uk Amazon] and pick a few books. The URL for each project page is in the form http://www.amazon.co.uk/Combination-of-title-an-author/dp/ASIN... Collect a few different ASINS.

Now we'll demonstrate importing from Amazon with a few sample ASINs.
Type this into the "Cut and Paste Records" box:
<pre>
0946719616
0297843877
</pre>

Select "AWS" from the Select import format drop down menu and click "Test Run + Import". You should end up at the Manage Deposits screen with the following message being displayed "Import completed: 2 item(s) imported.".

Frequently Asked Questions

2021-05-21T11:19:21Z

Libjlrs: Source formatting

[[Category:FAQ]]
[[Category:Management]]
[[Category: Out of Date]]
[[Category: Obsolete]]

This all needs sorting out, it's just being grabbed from the old wiki for now.

* [[Copyright and License FAQ]]
* [[Metadata FAQ]]
* [[Searching FAQ]]
* [[OAI FAQ]]
* [[How much will it cost?]]

== What operating systems can we use? ==

EPrints should work on any Linux operating system. We use Ubuntu (Debian) and Redhat Enterprise Linux.

Running EPrints on Microsoft Windows is possible but strongly not recommended. It can be very difficult to get all the necessary dependencies in place. If you want to get EPrints running but do not have as computer running a Linux operating system. You could install [https://www.virtualbox.org/wiki/Downloads VirtualBox] and then create a Ubuntu or Redhat "virtual machine" (VM) to run on top of your Windows operating system. Alternatively, you could install [https://docs.docker.com/docker-for-windows/install/ Docker Desktop for Windows] and [[Installing EPrints using Docker|install EPrints using Docker]]. However, both these methods are only recommended for testing or demoing EPrints. If you intend to run EPrints long-term you should install on a dedicated Linux server or virtual machine.

== What computer do we need? ==
Any modern physical PC (server or desktop) or a virtual machine should be more than capable of running EPrints. A suggested minimum specification for running a live service:
* 2GB RAM
* 20GB disk space
* 100Mb/s network speed

== How much will it cost to set up? ==

Most of the costs are staff time. Equipment costs are a PC, an internet connection and a BACKUP STRATEGY. Please remember to budget for backups.

EPrints, and all the other software required to make it work, are available for no cost. At some point in the future EPrints may offer some pay-services, but the core software will remain zero cost and freely available to all.

See [[How much will it cost?]]

== How much disk space will we need? ==
The main usage of disk space will be the uploaded files for the publications, (e.g. PDF, Word documents, etc.). On average an eprint item will have associated files (e.g. uploaded PDF and thumbnail and preview images of that PDF) that take up 2MB of disk space. So for every extra 500 eprint items you will need an extra 1GB of disk. However, if you intend to upload lots of videos, images, are large documents, then this requirement will be higher. On top of the space needed for uploaded documents and associated files you will need approximately 5GB for installing the operating system. The disk space required by the database is difficult to determine, as this is dependent on a number of different factors but 1MB per eprint item.
=== Example usage requirements ===
* Small repository: 1000 eprint items
** Operating system: 5GB
** Upload and associated files: 2MB x 1000 = 2GB
** Database: 1MB x 1000 = 1GB
** '''TOTAL:''' 8GB (15GB to give room for expansion)
* Medium-sized repository: 10,000 eprint items
** Operating system: 5GB
** Upload and associated files: 2MB x 10,000 = 20GB
** Database: 1MB x 10,000 = 10GB
** '''TOTAL:''' 35GB (50GB to give room for expansion)
* Large repository: 100,000 eprint items
** Operating system: 5GB
** Upload and associated files: 2MB x 10,000 = 200GB
** Database: 1MB x 10,000 = 100GB
** '''TOTAL:''' 305GB (350-400GB to give room for expansion)

== Is it possible when depositing a document, to just point to an "alternative location" rather than have the full text copied and held in the eprint archive? ==

Yes, and to suppress the normal warning about no documents attached look in '''[archive_root]/cfg/cfg.d/eprint_warnings.pl'''.

== I need to run apache as a user other than "eprints", what do I do to make EPrints work in this situation? ==

Example, apache is running as user "apache".
* Make all the eprints files owned by "apache" instead of "eprints"
* Edit SystemSettings?.pm to tell eprints to run as user "apache"
* You'll need to run all command line scripts as user "apache"
* All eprints cron jobs should be owned by user "apache"

If you are installing a new copy of eprints, you can specify the user and group to use when you run 'configure'. Do
<syntaxhighlight lang="bash">
./configure --help
</syntaxhighlight>
for details.

== How do I get the body HTML of a page without the template around it? ==
This is handy for dynamically linking EPrints content into other sites.

For "view" pages you need to add the option <code>include=>1</code> to the view configuration. This will cause generate_views to make a ''.include'' page in addition to the ''.html'' page. The ''.include'' page will have no template around it.

For dynamic pages, those under ''/cgi/'', you can add the cgi parameter <code>mainonly=yes</code>. E.g. <code>http://tryme.demo.eprints-hosting.org/cgi/latest?mainonly=yes</code>

== How do I get statistics on number of deposits per month? ==

This rather grim bit of SQL should work, although datestamp is the last modified date, not the submission OR creation date, it should still give a good indication.
<syntaxhighlight lang="sql">
select count(*), year(datestamp), month(datestamp)
from archive
group by year(datestamp),month(datestamp)
order by year(datestamp),month(datestamp);
</syntaxhighlight>

== I've edited the template (or other config file) but nothing seems to have changed - why? ==

While EPrints tries to automatically reload when a configuration file is changed you may need to reload the Web server for changes to take effect. See also the [[API:bin/epadmin|epadmin reload]], the [[API:bin/generate_static|generate_static]] and [[API:bin/generate_views|generate_views]] commands.

= Installation Related Questions =

== When running a script I get the error; "Insecure dependency in mkdir while running with -T switch" ==

This usually indicates you are running an eprints script as root. Don't do that; become user 'eprints' instead.

== title and fulltext search returns no results, but date search does ==

The indexer daemon is probably not running or is not working correctly, see [[API:bin/indexer]].

== I don't want to give epadmin my mysql root password. What is the alternative? ==
<syntaxhighlight lang="sql">
mysql> CREATE DATABASE myrepo;
Query OK, 1 row affected (0.06 sec)

mysql> GRANT ALL PRIVILEGES ON myrepo.* TO myrepo@localhost IDENTIFIED BY 'secret';
Query OK, 0 rows affected (0.52 sec)
</syntaxhighlight>

Then provide the database name, user name and password to the '''[[API:bin/epadmin|epadmin]] create''' command.

== How do I get a value for a field of an eprint (without using any SQL)? ==

(assuming the eprint is in the main archive, and has eprintid number 23)

<syntaxhighlight lang="perl">
my $ds = $repo->dataset( "eprint" );
my $eprint = $ds->dataobj( 23 );
my $value = $eprint->value( "editors" );
</syntaxhighlight>

See [[API:EPrints/DataObj]].

== How can I get a utf8 string of the name of a subject, given its subjectid? ==

<syntaxhighlight lang="perl">
sub get_subject_name_string
{
my( $session, $subjectid ) = @_;
my $subj = EPrints::Subject->new( $session, $subjectid );
if( !defined $subj )
{
return "errer, unknown subject: $subjectid";
}
return EPrints::Utils::tree_to_utf8( $subj->render_description() );
}
</syntaxhighlight>

Setting up HTTPS using Let's Encrypt

2021-05-21T11:15:10Z

Libjlrs:

{{Manual}}
By default EPrints does not come setup to use HTTPS. This is because you need to generate a SSL certificate and if this is not signed by a known Certificate Authority a user's web browser is likely to complain vigorously. In the past it has typically costed a fair amount of money to obtain a SSL certificate from your hosting provider. However, now there is [https://letsencrypt.org/ Let's Encrypt] it is possible to get a certificate for free. This is not to say you should use Let's Encrypt in all cases. UK academic institutions should continue to obtain their SSL certificates through Jisc and other institutions/organisations may already have similar arrangements for obtaining SSL certificates.

As well as being free, Let's Encrypt has an automated way for renewing certificates. However, it should be noted that the length of its certificates is a lot shorter at just 3 months. As the renewal process is automatic, this time period is more appropriate to maximise security. Let's Encrypt's certificate generation requires your EPrints repository to be publicly accessible. Beneath are instructions on how to set up EPrints to enable HTTPS with a Let's Encrypt certificate.

1. Go to the https://certbot.eff.org/ and follow the instructions for your web server and operating system (the former will almost always be Apache) and follow the instructions provided.

2. When you get to the point of running the certbot command you want the certificate only so should type as the root user:

<syntaxhighlight lang="bash">
certbot --apache certonly
</syntaxhighlight>

3. Take a note of the path to were your certificate, key and CA chain have been saved. This will probably be something like

<syntaxhighlight lang="bash">
/etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/
</syntaxhighlight>

4. If you have not already done so, create an directory called <tt>ssl</tt> inside your archive's directory, i.e.

<syntaxhighlight lang="bash">
mkdir EPRINTS_PATH/archives/REPOID/ssl/
</syntaxhighlight>

5. Create a file inside the new ssl directory called <tt>securevhost.conf</tt> and include the following contents, amending the <tt>ServerName</tt>, <tt>SSLCertificateFile</tt>, <tt>SSLCertificateKeyFile</tt> <tt>SSLCertificateChainFile</tt> and <tt>Include</tt> as appropriate at least. You will note that this configuration also enables [https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security HTTP Strict Transport Security (HSTS)] for additional security. This ensures that after the first time you visit HTTPS for a particular site in your web browser, all future HTTP requests for this hostname will automatically be converted by your browser to HTTPS.

<syntaxhighlight lang="apache">
<VirtualHost *:443>

ServerName YOUR-REPOSITORY-DOMAIN:443

# Enable HSTS
Header always set Strict-Transport-Security "max-age=63072000;"

SSLEngine on
SSLProtocol all -SSLv2 -SSLv3
SSLHonorCipherOrder on
SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH

SSLCertificateFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/chain.pem

SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

LogLevel warn
ErrorLog logs/ssl_error_log
TransferLog logs/ssl_access_log
CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Include EPRINTS_PATHH/cfg/apache_ssl/REPOID.conf

PerlTransHandler +EPrints::Apache::Rewrite

</VirtualHost>
</syntaxhighlight>

6. If you have not already done so, add a configuration file at <tt>/opt/eprints3/archives/REPOID/cfg/cfg.d/https.pl</tt> with the following configuration:

<syntaxhighlight lang="perl">
$c->{securehost} = $c->{host};
$c->{secureport} = 443;
$c->{http_root} = undef;
</syntaxhighlight>

7. Now you will need to regenerate the rest of your Apache configuration for EPrints with the following command run as the EPrints user. (Substitute the path as appropriate):

<syntaxhighlight lang="bash">
/opt/eprints3/bin/generate_apacheconf --system --replace
</syntaxhighlight>

8. Apache will not yet have been setup to include the Apache configuration file you created in step 5. To include this, you will need to edit the file in your Apache configuration directory (<tt>/etc/httpd/</tt> on RHEL/CentOS/Fedora and <tt>/etc/apache2/</tt> on Debian/Ubuntu) and find the file that contains the line <tt>cfg/apache.conf</tt>, e.g.

<syntaxhighlight lang="bash">
cd /etc/httpd/
grep -r "cfg/apache.conf" *
</syntaxhighlight>

9. Once you have found it you will need to edit it and add the following line, changing the path as appropriate:

<syntaxhighlight lang="apache">
Include EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf
</syntaxhighlight>

10. Now, (as root or using sudo) test that the Apache configuration is correct and fix any issues if necessary:

<syntaxhighlight lang="bash">
apachectl configtest
</syntaxhighlight>

11. Restart Apache and check whether you can access your EPrints repository using HTTPS in a web browser:

<syntaxhighlight lang="bash">
apachectl restart
</syntaxhighlight>

12. If the guide on cerbot.eff.org you used in step 1 tells you to to setup a cron job then follow those instructions. The easiest way to do this is probably to run <tt>crontab -e</tt> as root and add the following cron job, substituting the minute (43) and hours (6,18) for you own choice maintaining a 12 hour gap between the hours:

<syntaxhighlight lang="bash">
43 6,18 * * * certbot renew
</syntaxhighlight>

== Additional Notes ==

The default EPrints Apache Rewrite handler declines any requests to a URL containing <code>/.</code>.

This means that the challenge/response for a LetsEncrypt certificate renewal that uses the <code>/.well-known/acme-challenge/</code> path will fail.

To make this work you could add a location block to your Apache config, to ensure the <code>/.well-known/</code> are not handled by EPrints, or use an EPrints URL rewrite trigger to handle the request:

<syntaxhighlight lang="perl">
#this could be saved into e.g. [EPRINTS_ROOT]/lib/cfg.d/z_rewrite_url_LetsEncrypt.pl

# import Apache constant e.g. 'OK'
use EPrints::Apache::AnApache;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %o ) = @_;

# if the incoming request matches the LetsEncrypt challenge URL...
if( $o{uri} =~ m!^${o{urlpath}}/\.well-known/acme-challenge/! )
{
# and the LetsEncrypt renewal process has put the file in EPRINTS_ROOT/archives/ARCHIVEID/html/.well-known/acme-challenge/
if( -f $o{repository}->get_conf( "htdocs_path" ).$o{uri} )
{
# reply with an HTTP '200'
${$o{return_code}} = OK;
# and return the file reqested
$o{request}->filename( $o{repository}->get_conf( "htdocs_path" ).$o{uri} );
}
# and say that we've handled the request - so no more triggers should be run.
return EP_TRIGGER_DONE;
}
} );
</syntaxhighlight>

Setting up HTTPS using Let's Encrypt

2021-05-21T11:12:34Z

Libjlrs:

{{Manual}}
By default EPrints does not come setup to use HTTPS. This is because you need to generate a SSL certificate and if this is not signed by a known Certificate Authority a user's web browser is likely to complain vigorously. In the past it has typically costed a fair amount of money to obtain a SSL certificate from your hosting provider. However, now there is [https://letsencrypt.org/ Let's Encrypt] it is possible to get a certificate for free. This is not to say you should use Let's Encrypt in all cases. UK academic institutions should continue to obtain their SSL certificates through Jisc and other institutions/organisations may already have similar arrangements for obtaining SSL certificates.

As well as being free, Let's Encrypt has an automated way for renewing certificates. However, it should be noted that the length of its certificates is a lot shorter at just 3 months. As the renewal process is automatic, this time period is more appropriate to maximise security. Let's Encrypt's certificate generation requires your EPrints repository to be publicly accessible. Beneath are instructions on how to set up EPrints to enable HTTPS with a Let's Encrypt certificate.

1. Go to the https://certbot.eff.org/ and follow the instructions for your web server and operating system (the former will almost always be Apache) and follow the instructions provided.

2. When you get to the point of running the certbot command you want the certificate only so should type as the root user:

<syntaxhighlight lang="bash">
certbot --apache certonly
</syntaxhighlight>

3. Take a note of the path to were your certificate, key and CA chain have been saved. This will probably be something like

<syntaxhighlight lang="bash">
/etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/
</syntaxhighlight>

4. If you have not already done so, create an directory called <tt>ssl</tt> inside your archive's directory, i.e.

<syntaxhighlight lang="bash">
mkdir EPRINTS_PATH/archives/REPOID/ssl/
</syntaxhighlight>

5. Create a file inside the new ssl directory called <tt>securevhost.conf</tt> and include the following contents, amending the <tt>ServerName</tt>, <tt>SSLCertificateFile</tt>, <tt>SSLCertificateKeyFile</tt> <tt>SSLCertificateChainFile</tt> and <tt>Include</tt> as appropriate at least. You will note that this configuration also enables [https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security HTTP Strict Transport Security (HSTS)] for additional security. This ensures that after the first time you visit HTTPS for a particular site in your web browser, all future HTTP requests for this hostname will automatically be converted by your browser to HTTPS.

<syntaxhighlight lang="apache">
<VirtualHost *:443>

ServerName YOUR-REPOSITORY-DOMAIN:443

# Enable HSTS
Header always set Strict-Transport-Security "max-age=63072000;"

SSLEngine on
SSLProtocol all -SSLv2 -SSLv3
SSLHonorCipherOrder on
SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH

SSLCertificateFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/chain.pem

SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

LogLevel warn
ErrorLog logs/ssl_error_log
TransferLog logs/ssl_access_log
CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Include EPRINTS_PATHH/cfg/apache_ssl/REPOID.conf

PerlTransHandler +EPrints::Apache::Rewrite

</VirtualHost>
</syntaxhighlight>

6. If you have not already done so, add a configuration file at <tt>/opt/eprints3/archives/REPOID/cfg/cfg.d/https.pl</tt> with the following configuration:

<syntaxhighlight lang="perl">
$c->{securehost} = $c->{host};
$c->{secureport} = 443;
$c->{http_root} = undef;
</syntaxhighlight>

7. Now you will need to regenerate the rest of your Apache configuration for EPrints with the following command run as the EPrints user. (Substitute the path as appropriate):
<syntaxhighlight lang="bash">
/opt/eprints3/bin/generate_apacheconf --system --replace
</syntaxhighlight>

8. Apache will not yet have been setup to include the Apache configuration file you created in step 5. To include this, you will need to edit the file in your Apache configuration directory (<tt>/etc/httpd/</tt> on RHEL/CentOS/Fedora and <tt>/etc/apache2/</tt> on Debian/Ubuntu) and find the file that contains the line <tt>cfg/apache.conf</tt>, e.g.

<syntaxhighlight lang="bash">
cd /etc/httpd/
grep -r "cfg/apache.conf" *
</syntaxhighlight>

9. Once you have found it you will need to edit it and add the following line, changing the path as appropriate:
<syntaxhighlight lang="apache">
Include EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf
</syntaxhighlight>
10. Now, (as root or using sudo) test that the Apache configuration is correct and fix any issues if necessary:
<syntaxhighlight lang="bash">
apachectl configtest
</syntaxhighlight>

11. Restart Apache and check whether you can access your EPrints repository using HTTPS in a web browser:
<syntaxhighlight lang="bash">
apachectl restart
</syntaxhighlight>

12. If the guide on cerbot.eff.org you used in step 1 tells you to to setup a cron job then follow those instructions. The easiest way to do this is probably to run <tt>crontab -e</tt> as root and add the following cron job, substituting the minute (43) and hours (6,18) for you own choice maintaining a 12 hour gap between the hours:
<syntaxhighlight lang="text">
43 6,18 * * * certbot renew
</syntaxhighlight>

== Additional Notes ==

The default EPrints Apache Rewrite handler declines any requests to a URL containing <code>/.</code>.

This means that the challenge/response for a LetsEncrypt certificate renewal that uses the <code>/.well-known/acme-challenge/</code> path will fail.

To make this work you could add a location block to your Apache config, to ensure the <code>/.well-known/</code> are not handled by EPrints, or use an EPrints URL rewrite trigger to handle the request:

<syntaxhighlight lang="perl">
#this could be saved into e.g. [EPRINTS_ROOT]/lib/cfg.d/z_rewrite_url_LetsEncrypt.pl

# import Apache constant e.g. 'OK'
use EPrints::Apache::AnApache;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %o ) = @_;

# if the incoming request matches the LetsEncrypt challenge URL...
if( $o{uri} =~ m!^${o{urlpath}}/\.well-known/acme-challenge/! )
{
# and the LetsEncrypt renewal process has put the file in EPRINTS_ROOT/archives/ARCHIVEID/html/.well-known/acme-challenge/
if( -f $o{repository}->get_conf( "htdocs_path" ).$o{uri} )
{
# reply with an HTTP '200'
${$o{return_code}} = OK;
# and return the file reqested
$o{request}->filename( $o{repository}->get_conf( "htdocs_path" ).$o{uri} );
}
# and say that we've handled the request - so no more triggers should be run.
return EP_TRIGGER_DONE;
}
} );
</syntaxhighlight>

Setting up HTTPS using Let's Encrypt

2021-05-21T11:11:27Z

Libjlrs: Syntax highlighting

{{Manual}}
By default EPrints does not come setup to use HTTPS. This is because you need to generate a SSL certificate and if this is not signed by a known Certificate Authority a user's web browser is likely to complain vigorously. In the past it has typically costed a fair amount of money to obtain a SSL certificate from your hosting provider. However, now there is [https://letsencrypt.org/ Let's Encrypt] it is possible to get a certificate for free. This is not to say you should use Let's Encrypt in all cases. UK academic institutions should continue to obtain their SSL certificates through Jisc and other institutions/organisations may already have similar arrangements for obtaining SSL certificates.

As well as being free, Let's Encrypt has an automated way for renewing certificates. However, it should be noted that the length of its certificates is a lot shorter at just 3 months. As the renewal process is automatic, this time period is more appropriate to maximise security. Let's Encrypt's certificate generation requires your EPrints repository to be publicly accessible. Beneath are instructions on how to set up EPrints to enable HTTPS with a Let's Encrypt certificate.

1. Go to the https://certbot.eff.org/ and follow the instructions for your web server and operating system (the former will almost always be Apache) and follow the instructions provided.

2. When you get to the point of running the certbot command you want the certificate only so should type as the root user:

<syntaxhighlight lang="bash">
certbot --apache certonly
</syntaxhighlight>

3. Take a note of the path to were your certificate, key and CA chain have been saved. This will probably be something like

<syntaxhighlight lang="bash">
/etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/
</syntaxhighlight>

4. If you have not already done so, create an directory called <tt>ssl</tt> inside your archive's directory, i.e.

<syntaxhighlight lang="bash">
mkdir EPRINTS_PATH/archives/REPOID/ssl/
</syntaxhighlight>

5. Create a file inside the new ssl directory called <tt>securevhost.conf</tt> and include the following contents, amending the <tt>ServerName</tt>, <tt>SSLCertificateFile</tt>, <tt>SSLCertificateKeyFile</tt> <tt>SSLCertificateChainFile</tt> and <tt>Include</tt> as appropriate at least. You will note that this configuration also enables [https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security HTTP Strict Transport Security (HSTS)] for additional security. This ensures that after the first time you visit HTTPS for a particular site in your web browser, all future HTTP requests for this hostname will automatically be converted by your browser to HTTPS.

<syntaxhighlight lang="apache">
<VirtualHost *:443>

ServerName YOUR-REPOSITORY-DOMAIN:443

# Enable HSTS
Header always set Strict-Transport-Security "max-age=63072000;"

SSLEngine on
SSLProtocol all -SSLv2 -SSLv3
SSLHonorCipherOrder on
SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH

SSLCertificateFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/chain.pem

SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

LogLevel warn
ErrorLog logs/ssl_error_log
TransferLog logs/ssl_access_log
CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Include EPRINTS_PATHH/cfg/apache_ssl/REPOID.conf

PerlTransHandler +EPrints::Apache::Rewrite

</VirtualHost>
</syntaxhighlight>

6. If you have not already done so, add a configuration file at <tt>/opt/eprints3/archives/REPOID/cfg/cfg.d/https.pl</tt> with the following configuration:

<syntaxhighlight lang="perl">
$c->{securehost} = $c->{host};
$c->{secureport} = 443;
$c->{http_root} = undef;
</syntaxhighlight>

7. Now you will need to regenerate the rest of your Apache configuration for EPrints with the following command run as the EPrints user. (Substitute the path as appropriate):
<syntaxhighlight lang="bash">
/opt/eprints3/bin/generate_apacheconf --system --replace
</syntaxhighlight>

8. Apache will not yet have been setup to include the Apache configuration file you created in step 5. To include this, you will need to edit the file in your Apache configuration directory (<tt>/etc/httpd/</tt> on RHEL/CentOS/Fedora and <tt>/etc/apache2/</tt> on Debian/Ubuntu) and find the file that contains the line <tt>cfg/apache.conf</tt>, e.g.

<syntaxhighlight lang="bash">
cd /etc/httpd/
grep -r "cfg/apache.conf" *
</syntaxhighlight>

9. Once you have found it you will need to edit it and add the following line, changing the path as appropriate:
<syntaxhighlight lang="apache">
Include EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf
</syntaxhighlight>
10. Now, (as root or using sudo) test that the Apache configuration is correct and fix any issues if necessary:
<syntaxhighlight lang="bash">
apachectl configtest
</syntaxhighlight>

11. Restart Apache and check whether you can access your EPrints repository using HTTPS in a web browser:
<syntaxhighlight lang="bash">
apachectl restart
</syntaxhighlight>

12. If the guide on cerbot.eff.org you used in step 1 tells you to to setup a cron job then follow those instructions. The easiest way to do this is probably to run <tt>crontab -e</tt> as root and add the following cron job, substituting the minute (43) and hours (6,18) for you own choice maintaining a 12 hour gap between the hours:
<syntaxhighlight lang="cron">
43 6,18 * * * certbot renew
</syntaxhighlight>

== Additional Notes ==

The default EPrints Apache Rewrite handler declines any requests to a URL containing <code>/.</code>.

This means that the challenge/response for a LetsEncrypt certificate renewal that uses the <code>/.well-known/acme-challenge/</code> path will fail.

To make this work you could add a location block to your Apache config, to ensure the <code>/.well-known/</code> are not handled by EPrints, or use an EPrints URL rewrite trigger to handle the request:

<syntaxhighlight lang="perl">
#this could be saved into e.g. [EPRINTS_ROOT]/lib/cfg.d/z_rewrite_url_LetsEncrypt.pl

# import Apache constant e.g. 'OK'
use EPrints::Apache::AnApache;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %o ) = @_;

# if the incoming request matches the LetsEncrypt challenge URL...
if( $o{uri} =~ m!^${o{urlpath}}/\.well-known/acme-challenge/! )
{
# and the LetsEncrypt renewal process has put the file in EPRINTS_ROOT/archives/ARCHIVEID/html/.well-known/acme-challenge/
if( -f $o{repository}->get_conf( "htdocs_path" ).$o{uri} )
{
# reply with an HTTP '200'
${$o{return_code}} = OK;
# and return the file reqested
$o{request}->filename( $o{repository}->get_conf( "htdocs_path" ).$o{uri} );
}
# and say that we've handled the request - so no more triggers should be run.
return EP_TRIGGER_DONE;
}
} );
</syntaxhighlight>

HTTPS-only and HSTS

2021-05-21T11:06:32Z

Libjlrs: /* Add the HSTS header */

{{manual}}

[[Category:Authentication]]

== HTTPS with EPrints ==

See the pages in [[:Category:Authentication|Category Authentication]] for how to setup up HTTPS on EPrints, for example:

*[[How_to_use_EPrints_with_HTTPS|How to use EPrints with HTTPS]]
*[[Setting_up_HTTPS_using_Let%27s_Encrypt|Setting up HTTPS using Let's Encrypt]]

The following is a description of how to configure EPrints so that all content, not just login pages, is served over HTTPS.

== Google Best Practices for HTTPS==

The following are the best practices specified by [https://support.google.com/webmasters/answer/6073543?hl=en&ref_topic=6001951 Google]

* HSTS Headers on HTTPS
* No “Mixed Content” warnings/errors
* Links point to HTTPS locations
* 301 Redirects from HTTP to HTTPS

== HSTS ==

To summarize how HSTS works, if a browser (Chrome, Firefix, IE) sees the HSTS header in the HTTPS response, and there are no certificate errors or mixed content warnings or anything (if it is green), then the next time a user of that browser requests the HTTP page of that site, the browser will modify the request from an HTTP to a HTTPS request. The browser will remember that setting for as long as you specify <tt>max-age</tt> to be. This means that even with HSTS, it is still possible to request and receive content over HTTP. To close that down, a server redirect is necessary, so those browsers that haven’t seen the HSTS header in the past that happen to try to go to HTTP will get that initial redirect to HTTPS.

== Implementing HTTPS-only with HSTS on an EPrints repository ==

=== Changes to archive's cfg.d/10_core.pl ===

Initialize the following variables to be the https URL (i.e., https://<nowiki>YOUR-REPOSITORY-DOMAIN</nowiki>)

<source lang="perl">
$c->{host} = "YOUR-REPOSITORY-DOMAIN";
$c->{http_url} = 'https://YOUR-REPOSITORY-DOMAIN';
$c->{http_cgiurl} = 'https://YOUR-REPOSITORY-DOMAIN/cgi';
$c->{base_url} = "https://$c->{host}";
</source>

=== Changes to archive's <tt>cfg/lang/LANGID/templates/default.xml</tt>, and <tt>/cfg/lang/LANGID/static/*.XPAGE</tt> files ===

* Remove any hard coded links to HTTP
* If you have Google Search included as an XPAGE file, call on the Google API (and any other APIs) using HTTPS.

=== Changes to Apache config files ===

==== Add the HSTS header ====

Edit [[Template:Securevhost.conf|EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf]] and add the following HSTS header after ther <tt>ServerName</tt> line. The max-age variable is a time in seconds for how long the HSTS settings should be remembered by the browser. 15780000 is six months, which is a long time, you may want to set it to a shorter time while testing.

<syntaxhighlight lang="apache">
Header set Strict-Transport-Security "max-age=15780000"
</syntaxhighlight>

Include this file from the core apache conf file for the secure port (443) in <tt>/etc/</tt>

==== Add 301 redirects to secure port from HTTP (port 80) ====

By making the above changes to the archive's <tt>cfg.d/10_core.pl</tt>, if you use [https://github.com/eprints/eprints/commit/c29574dbdcd49c67f3aea522998960f2eb19f544 this patch] or are running [https://github.com/eprints/eprints the latest revision of EPrints on GitHub], <tt>/bin/generate_apacheconf</tt> will generate an <tt>/cfg/apache/REPOID.conf</tt>, which automatically redirects HTTP to HTTPS. Otherwise, this can be achieved by modifying <tt>/cfg/apache/REPOID.conf</tt> to the following, substituting your domain as appropriate:

<source lang="xml">
<VirtualHost *:80>
RedirectPermanent / https://YOUR-REPOSITORY-DOMAIN/
</VirtualHost>
</source>

HTTPS-only and HSTS

2021-05-21T11:04:32Z

Libjlrs: /* Changes to archive's cfg/lang/LANGID/templates/default.xml, and /cfg/lang/LANGID/static/*.XPAGE files */

{{manual}}

[[Category:Authentication]]

== HTTPS with EPrints ==

See the pages in [[:Category:Authentication|Category Authentication]] for how to setup up HTTPS on EPrints, for example:

*[[How_to_use_EPrints_with_HTTPS|How to use EPrints with HTTPS]]
*[[Setting_up_HTTPS_using_Let%27s_Encrypt|Setting up HTTPS using Let's Encrypt]]

The following is a description of how to configure EPrints so that all content, not just login pages, is served over HTTPS.

== Google Best Practices for HTTPS==

The following are the best practices specified by [https://support.google.com/webmasters/answer/6073543?hl=en&ref_topic=6001951 Google]

* HSTS Headers on HTTPS
* No “Mixed Content” warnings/errors
* Links point to HTTPS locations
* 301 Redirects from HTTP to HTTPS

== HSTS ==

To summarize how HSTS works, if a browser (Chrome, Firefix, IE) sees the HSTS header in the HTTPS response, and there are no certificate errors or mixed content warnings or anything (if it is green), then the next time a user of that browser requests the HTTP page of that site, the browser will modify the request from an HTTP to a HTTPS request. The browser will remember that setting for as long as you specify <tt>max-age</tt> to be. This means that even with HSTS, it is still possible to request and receive content over HTTP. To close that down, a server redirect is necessary, so those browsers that haven’t seen the HSTS header in the past that happen to try to go to HTTP will get that initial redirect to HTTPS.

== Implementing HTTPS-only with HSTS on an EPrints repository ==

=== Changes to archive's cfg.d/10_core.pl ===

Initialize the following variables to be the https URL (i.e., https://<nowiki>YOUR-REPOSITORY-DOMAIN</nowiki>)

<source lang="perl">
$c->{host} = "YOUR-REPOSITORY-DOMAIN";
$c->{http_url} = 'https://YOUR-REPOSITORY-DOMAIN';
$c->{http_cgiurl} = 'https://YOUR-REPOSITORY-DOMAIN/cgi';
$c->{base_url} = "https://$c->{host}";
</source>

=== Changes to archive's <tt>cfg/lang/LANGID/templates/default.xml</tt>, and <tt>/cfg/lang/LANGID/static/*.XPAGE</tt> files ===

* Remove any hard coded links to HTTP
* If you have Google Search included as an XPAGE file, call on the Google API (and any other APIs) using HTTPS.

=== Changes to Apache config files ===

==== Add the HSTS header ====

Edit [[Template:Securevhost.conf|EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf]] and add the following HSTS header after ther <tt>ServerName</tt> line. The max-age variable is a time in seconds for how long the HSTS settings should be remembered by the browser. 15780000 is six months, which is a long time, you may want to set it to a shorter time while testing.

Header set Strict-Transport-Security "max-age=15780000"

Include this file from the core apache conf file for the secure port (443) in <tt>/etc/</tt>

==== Add 301 redirects to secure port from HTTP (port 80) ====

By making the above changes to the archive's <tt>cfg.d/10_core.pl</tt>, if you use [https://github.com/eprints/eprints/commit/c29574dbdcd49c67f3aea522998960f2eb19f544 this patch] or are running [https://github.com/eprints/eprints the latest revision of EPrints on GitHub], <tt>/bin/generate_apacheconf</tt> will generate an <tt>/cfg/apache/REPOID.conf</tt>, which automatically redirects HTTP to HTTPS. Otherwise, this can be achieved by modifying <tt>/cfg/apache/REPOID.conf</tt> to the following, substituting your domain as appropriate:

<source lang="xml">
<VirtualHost *:80>
RedirectPermanent / https://YOUR-REPOSITORY-DOMAIN/
</VirtualHost>
</source>

HTTPS-only and HSTS

2021-05-21T11:04:07Z

Libjlrs: /* Changes to archive's cfg/lang/LANGID/templates/default.xml, and /cfg/lang/LANGID/static/*.XPAGE files */

{{manual}}

[[Category:Authentication]]

== HTTPS with EPrints ==

See the pages in [[:Category:Authentication|Category Authentication]] for how to setup up HTTPS on EPrints, for example:

*[[How_to_use_EPrints_with_HTTPS|How to use EPrints with HTTPS]]
*[[Setting_up_HTTPS_using_Let%27s_Encrypt|Setting up HTTPS using Let's Encrypt]]

The following is a description of how to configure EPrints so that all content, not just login pages, is served over HTTPS.

== Google Best Practices for HTTPS==

The following are the best practices specified by [https://support.google.com/webmasters/answer/6073543?hl=en&ref_topic=6001951 Google]

* HSTS Headers on HTTPS
* No “Mixed Content” warnings/errors
* Links point to HTTPS locations
* 301 Redirects from HTTP to HTTPS

== HSTS ==

To summarize how HSTS works, if a browser (Chrome, Firefix, IE) sees the HSTS header in the HTTPS response, and there are no certificate errors or mixed content warnings or anything (if it is green), then the next time a user of that browser requests the HTTP page of that site, the browser will modify the request from an HTTP to a HTTPS request. The browser will remember that setting for as long as you specify <tt>max-age</tt> to be. This means that even with HSTS, it is still possible to request and receive content over HTTP. To close that down, a server redirect is necessary, so those browsers that haven’t seen the HSTS header in the past that happen to try to go to HTTP will get that initial redirect to HTTPS.

== Implementing HTTPS-only with HSTS on an EPrints repository ==

=== Changes to archive's cfg.d/10_core.pl ===

Initialize the following variables to be the https URL (i.e., https://<nowiki>YOUR-REPOSITORY-DOMAIN</nowiki>)

<source lang="perl">
$c->{host} = "YOUR-REPOSITORY-DOMAIN";
$c->{http_url} = 'https://YOUR-REPOSITORY-DOMAIN';
$c->{http_cgiurl} = 'https://YOUR-REPOSITORY-DOMAIN/cgi';
$c->{base_url} = "https://$c->{host}";
</source>

=== Changes to archive's <tt>cfg/lang/LANGID/templates/default.xml</tt>, and <tt>/cfg/lang/LANGID/static/*.XPAGE</tt> files ===

Remove any hard coded links to HTTP
If you have Google Search included as an XPAGE file,
call on the Google API (and any other APIs) using HTTPS.

=== Changes to Apache config files ===

==== Add the HSTS header ====

Edit [[Template:Securevhost.conf|EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf]] and add the following HSTS header after ther <tt>ServerName</tt> line. The max-age variable is a time in seconds for how long the HSTS settings should be remembered by the browser. 15780000 is six months, which is a long time, you may want to set it to a shorter time while testing.

Header set Strict-Transport-Security "max-age=15780000"

Include this file from the core apache conf file for the secure port (443) in <tt>/etc/</tt>

==== Add 301 redirects to secure port from HTTP (port 80) ====

By making the above changes to the archive's <tt>cfg.d/10_core.pl</tt>, if you use [https://github.com/eprints/eprints/commit/c29574dbdcd49c67f3aea522998960f2eb19f544 this patch] or are running [https://github.com/eprints/eprints the latest revision of EPrints on GitHub], <tt>/bin/generate_apacheconf</tt> will generate an <tt>/cfg/apache/REPOID.conf</tt>, which automatically redirects HTTP to HTTPS. Otherwise, this can be achieved by modifying <tt>/cfg/apache/REPOID.conf</tt> to the following, substituting your domain as appropriate:

<source lang="xml">
<VirtualHost *:80>
RedirectPermanent / https://YOUR-REPOSITORY-DOMAIN/
</VirtualHost>
</source>

How to customise thumbnails

2021-05-21T11:02:08Z

Libjlrs:

Based on EPrints-3.3.10.

To customise the size and type of thumbnails generated by eprints you can create archive-based configuration.
The steps below show how to add a new thumbnail size, and render it the way *I* want it.

The default thumbnails are generated by: <code>~/perl_lib/EPrints/Plugin/Convert/Thumbnails.pm</code>

I wanted to add a new size 160x90px, called 'homepage' (to fit in with the institution's branding).
To make your own set of thumbnail sizes, edit <code>~/archives/ARCHIVEID/cfg/cfg.d/plugins.pl</code>.
I added the following to the file:
<syntaxhighlight lang="perl">
$c->{plugins}->{'Convert::Thumbnails'}->{params}->{sizes} = {(
small => [66,50],
homepage => [160, 90], # new size - others are copied from Thumbnails.pm
medium => [200,150],
preview => [400,300],
lightbox => [640,480],
)};
$c->{thumbnail_types} = sub {
my( $list, $repo, $doc ) = @_;
push @$list, qw( homepage ); # add new size to list of files to be generated
};
</syntaxhighlight>

By default this will produce a thumbnail that will fit into a box 160x90px - a proportionally scaled down version of the original. The 'small' thumbnail size produces a cropped version of the original. This is a better option for my needs, but it has a grey 1px border around it - that I don't want.

To alter the thumbnails I need to add the following to <code>~/archives/ARCHIVEID/cfg/cfg.d/plugins.pl</code> - which is a slightly modified version of the <code>sub call_convert</code> copied from Thumbnails.pl
<syntaxhighlight lang="perl">
$c->{plugins}->{'Convert::Thumbnails'}->{params}->{call_convert} = sub {
my( $self, $dir, $doc, $src, $geom, $size ) = @_;

my $convert = $self->{'convert'};
my $version = $self->convert_version;

if (!defined($geom)) {
EPrints::abort("NO GEOM");
}

my $fn = $size . ".jpg";
my $dst = "$dir/$fn";

$geom = "$geom->[0]x$geom->[1]";
# JPEG
# Read this: http://www.imagemagick.org/script/command-line-processing.php#geometry
# for details of the convert geom options.
#
if( $size eq "small" )
{
# attempt to create a thumbnail that fits within the given dimensions
# geom^ requires 6.3.8
if( $version > 6.3 )
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom^", "-gravity", "center", "-extent", $geom, "-bordercolor", "gray", "-border", "1x1", $src."[0]", "JPEG:$dst");
}
else
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom>", "-extract", $geom, "-bordercolor", "gray", "-border", "1x1", $src."[0]", "JPEG:$dst");
}
}
elsif( $size eq "homepage" ) # This is the new section to deal with the new 'homepage' size
{
# attempt to create a thumbnail that fits within the given dimensions
# geom^ requires 6.3.8
if( $version > 6.3 )
{
# homepage thumbnails don't want a border on them!
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom^", "-gravity", "center", "-extent", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}
else
{
# homepage thumbnails don't want a border on them!
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom>", "-extract", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}
}
elsif( $size eq "medium" )
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-trim", "+repage", "-size", "$geom", "-thumbnail","$geom>", "-background", "white", "-gravity", "center", "-extent", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}
else
{
$self->_system($convert, "-strip", "-colorspace", "RGB", "-background", "white", "-thumbnail","$geom>", "-extract", $geom, "-bordercolor", "white", "-border", "0x0", $src."[0]", "JPEG:$dst");
}

if( -s $dst )
{
return ($fn);
}

return ();
};
</syntaxhighlight>

To test the new thumbnail generation, find an eprint with some good images attached to it. In the example below I'll use '1234', and assume the original image is called 'file.jpg' and is the first document in the eprint (this only matters for the URL to view the image in the browser with).

Run <code>~/bin/epadmin redo_thumbnails ARCHIVEID 1234 --verbose</code>

You should see the convert command being run - and the new size filename being created e.g.
<syntaxhighlight lang="bash">
Starting EPrints Repository.
Connecting to DB ... done.
Redoing thumbnails for document 1234
/usr/bin/convert -strip -colorspace RGB -background white -thumbnail 160x90^ -gravity center -extent 160x90 -bordercolor white -border 0x0 /opt/eprints3/archives/digitallibrary/documents/disk0/00/00/12/34/01/file.jpg[0] JPEG:/tmp/_NyUoqmsuZ/homepage.jpg
/usr/bin/convert ... JPEG:/tmp/XR51ieKBCj/lightbox.jpg
/usr/bin/convert ... JPEG:/tmp/fCOP2BPoa2/preview.jpg
/usr/bin/convert ... JPEG:/tmp/zLEip1ewUq/medium.jpg
/usr/bin/convert ... JPEG:/tmp/weRJwQPgNT/small.jpg
</syntaxhighlight>

NB The lines for lightbox, preview, medium and small.jpg have been truncated for clarity.

You should now be able to view the new thumbnails in a browser:
<code><nowiki>http://your.repo.url/1234/1.hashomepageThumbnailVersion/file.jpg</nowiki></code>

[[Category:Howto]][[Category:Snippets]][[Category:Contribute]]

How to display specific contributors

2021-05-21T10:07:41Z

Libjlrs: /* Method 2 - EPScript logic - foreach */

Based on this question, asked on the Tech list:
''How can I add the field “Thesis Advisor” from Contributors to the Abstract Pages?''

'''Note:''' The question on the tech list specified EPrints 3.4.2. The below is based on 3.3.16, but may be useful as a starting point.

Below are three approaches that may do what you need.

== Method 1 - EPScript function ==
1) In EPScript, there is an undocumented function - <code>filter_compound_list</code> which accepts:
* a field (''contributors'')
* a sub-field name to filter on (''type'')
* a value to filter to (''http://www.loc.gov/loc.terms/relators/THS'')
* the field to return (''name'')

This can produce a text-string of one field from the compound field. If a thesis had two supervisors, the following example would produce:

''Smith, John and Bond, James''

<source lang="xml">
<epc:if test="contributors">
<epc:print expr="filter_compound_list(contributors,'type','http://www.loc.gov/loc.terms/relators/THS','name')" />
</epc:if>
</source>

== Method 2 - EPScript logic - ''foreach'' ==

This method is a bit more flexible, but you have to construct the values from the parts manually. It does allow you to reference the <code>id</code> sub-field if required.
It also may leave empty wrapping elements in the output (e.g. the <code>ul</code> in the example below if there are contributors, but none are the required type.

<source lang="xml">
<epc:if test="contributors">
<ul>
<epc:foreach expr="contributors" iterator="contr">
<epc:if test="$contr{type}='http://www.loc.gov/loc.terms/relators/THS'">
<li>
<epc:print expr="$contr{name}{given}" /> <epc:print expr="$contr{name}{family}" />
<epc:if test="$contr{id}">(<epc:print expr="$contr{id}"/>)</epc:if>
</li>
</epc:if>
</epc:foreach>
</ul>
</epc:if>
</source>

== Method 3 - Custom EPScript function ==
This is the most complex, but also offers the most flexibility - if you're able to understand the <code>EPrints::Script::Compiled</code> module and write your own functions.

There are two parts - adding custom methods to EPScript, and calling them from the citation file.

<syntaxhighlight lang="perl" line>
### This should be added to a file e.g. EPRINTS_ROOT/archives/ARCHIVEID/cfg/cfg.d/z_epscript_additions.pl

# Open block
{

# Write into EPrints::Script::Compiled
package EPrints::Script::Compiled;

use strict;

# Example usage in citation file:
#
# <epc:if test="$item.render_contributors_filtered('http://www.loc.gov/loc.terms/relators/THS',1)">
# <h2><epc:phrase ref="contributor_type_typename_http://www.loc.gov/loc.terms/relators/THS"/></h2>
# <epc:print expr="$item.render_contributors_filtered('http://www.loc.gov/loc.terms/relators/THS')"/>
# </epc:if>
#
# The first call includes the 'test' parameter, which can be used to determine whether surrounding
# elements need to be displayed - in the above example the <h2>.

sub run_render_contributors_filtered
{
my( $self, $state, $eprint, $contributor_type, $test ) = @_;

if( !defined $eprint->[0] || ref($eprint->[0]) ne "EPrints::DataObj::EPrint" )
{
$self->runtime_error( "Can only call render_contributors_filtered() on eprint objects not ".
ref($eprint->[0]) );
}

if( !defined $contributor_type )
{
$self->runtime_error( "You need to specify a contributor type you want to render." );
}

my @filtered_contributors = grep{ defined $_->{type} && $_->{type} eq $contributor_type->[0] } @{ $eprint->[0]->value( "contributors" ) };

if( $test )
{
return [ 0, "BOOLEAN" ] if( scalar @filtered_contributors < 1 );
return [ 1, "BOOLEAN" ];
}

# NB this is based on EPrints::Extras::render_related_url
# It is over-complicated for this use-case, as we could just use
# $state->{session}->render_name( $row->{name} )
# but if other compound fields are being used with similar code
# being able to get to the 'render_value' for the sub fields is useful.

my $field = $eprint->[0]->dataset->field( "contributors" );
my $f = $field->get_property( "fields_cache" );
my $fmap = {};
foreach my $field_conf ( @{$f} )
{
my $fieldname = $field_conf->{name};
my $field = $field->{dataset}->get_field( $fieldname );
$fmap->{$field_conf->{sub_name}} = $field;
}

my $ul = $state->{session}->make_element( "ul" );

foreach my $row ( @filtered_contributors )
{
my $li = $state->{session}->make_element( "li" );
$li->appendChild( $fmap->{name}->render_single_value( $state->{session}, $row->{name} ) );
if( defined $row->{id} )
{
$li->appendChild( $state->{session}->make_text( " (" ) );
$li->appendChild( $state->{session}->make_text( $row->{id} ) );
$li->appendChild( $state->{session}->make_text( ")" ) );
}
$ul->appendChild( $li );
}
return [ $ul, "XHTML" ];
}

} #End block
</syntaxhighlight>

The above example is also available at: https://gist.github.com/jesusbagpuss/2efc96ed05cf9121b925063a20677120

[[Category:Howto]][[Category:Snippets]][[Category:Contribute]]

How to display specific contributors

2021-05-21T10:06:21Z

Libjlrs: /* Method 3 - Custom EPScript function */

How to display specific contributors

2021-05-20T23:03:49Z

Libjlrs: /* Method 3 - Custom EPScript function */

Based on this question, asked on the Tech list:
''How can I add the field “Thesis Advisor” from Contributors to the Abstract Pages?''

'''Note:''' The question on the tech list specified EPrints 3.4.2. The below is based on 3.3.16, but may be useful as a starting point.

Below are three approaches that may do what you need.

== Method 1 - EPScript function ==
1) In EPScript, there is an undocumented function - <code>filter_compound_list</code> which accepts:
* a field (''contributors'')
* a sub-field name to filter on (''type'')
* a value to filter to (''http://www.loc.gov/loc.terms/relators/THS'')
* the field to return (''name'')

This can produce a text-string of one field from the compound field. If a thesis had two supervisors, the following example would produce:

''Smith, John and Bond, James''

<source lang="xml">
<epc:if test="contributors">
<epc:print expr="filter_compound_list(contributors,'type','http://www.loc.gov/loc.terms/relators/THS','name')" />
</epc:if>
</source>

== Method 2 - EPScript logic - ''foreach'' ==

This method is a bit more flexible, but you have to construct the values from the parts manually. It does allow you to reference the <code>id</code> sub-field if required.
It also may leave empty wrapping elements in the output (e.g. the <code>ul</code> in the example below if there are contributors, but none are the required type.

<source lang="xml">
<epc:if test="contributors">
<ul>
<epc:foreach expr="contributors" iterator="contr">
<epc:if test="$contr{type}='http://www.loc.gov/loc.terms/relators/THS'">
<li>
<epc:print expr="$contr{name}{given}" /> <epc:print expr="$contr{name}{family}" />
<epc:if test="$contr{id}">(<epc:print expr="$contr{id}"/>)</epc:if>
</li>
</epc:if>
</epc:foreach>
</ul>
</epc:if>
</source>

== Method 3 - Custom EPScript function ==
This is the most complex, but also offers the most flexibility - if you're able to understand the <code>EPrints::Script::Compiled</code> module and write your own functions.

There are two parts - adding custom methods to EPScript, and calling them from the citation file.

<source lang="perl">
### This should be added to a file e.g. EPRINTS_ROOT/archives/ARCHIVEID/cfg/cfg.d/z_epscript_additions.pl

# Open block
{

# Write into EPrints::Script::Compiled
package EPrints::Script::Compiled;

use strict;

# Example usage in citation file:
#
# <epc:if test="$item.render_contributors_filtered('http://www.loc.gov/loc.terms/relators/THS',1)">
# <h2><epc:phrase ref="contributor_type_typename_http://www.loc.gov/loc.terms/relators/THS"/></h2>
# <epc:print expr="$item.render_contributors_filtered('http://www.loc.gov/loc.terms/relators/THS')"/>
# </epc:if>
#
# The first call includes the 'test' parameter, which can be used to determine whether surrounding
# elements need to be displayed - in the above example the <h2>.

sub run_render_contributors_filtered
{
my( $self, $state, $eprint, $contributor_type, $test ) = @_;

if( !defined $eprint->[0] || ref($eprint->[0]) ne "EPrints::DataObj::EPrint" )
{
$self->runtime_error( "Can only call render_contributors_filtered() on eprint objects not ".
ref($eprint->[0]) );
}

if( !defined $contributor_type )
{
$self->runtime_error( "You need to specify a contributor type you want to render." );
}

my @filtered_contributors = grep{ defined $_->{type} && $_->{type} eq $contributor_type->[0] } @{ $eprint->[0]->value( "contributors" ) };

if( $test )
{
return [ 0, "BOOLEAN" ] if( scalar @filtered_contributors < 1 );
return [ 1, "BOOLEAN" ];
}

# NB this is based on EPrints::Extras::render_related_url
# It is over-complicated for this use-case, as we could just use
# $state->{session}->render_name( $row->{name} )
# but if other compound fields are being used with similar code
# being able to get to the 'render_value' for the sub fields is useful.

my $field = $eprint->[0]->dataset->field( "contributors" );
my $f = $field->get_property( "fields_cache" );
my $fmap = {};
foreach my $field_conf ( @{$f} )
{
my $fieldname = $field_conf->{name};
my $field = $field->{dataset}->get_field( $fieldname );
$fmap->{$field_conf->{sub_name}} = $field;
}

my $ul = $state->{session}->make_element( "ul" );

foreach my $row ( @filtered_contributors )
{
my $li = $state->{session}->make_element( "li" );
$li->appendChild( $fmap->{name}->render_single_value( $state->{session}, $row->{name} ) );
if( defined $row->{id} )
{
$li->appendChild( $state->{session}->make_text( " (" ) );
$li->appendChild( $state->{session}->make_text( $row->{id} ) );
$li->appendChild( $state->{session}->make_text( ")" ) );
}
$ul->appendChild( $li );
}
return [ $ul, "XHTML" ];
}

} #End block
</source>

The above example is also available at: https://gist.github.com/jesusbagpuss/2efc96ed05cf9121b925063a20677120

[[Category:Howto]][[Category:Snippets]][[Category:Contribute]]

How to display specific contributors

2021-05-20T23:00:04Z

Libjlrs: Created page with "Based on this question, asked on the Tech list: ''How can I add the field “Thesis Advisor” from Contributors to the Abstract Pages?'' '''Note:''' The question on the tech..."

Based on this question, asked on the Tech list:
''How can I add the field “Thesis Advisor” from Contributors to the Abstract Pages?''

'''Note:''' The question on the tech list specified EPrints 3.4.2. The below is based on 3.3.16, but may be useful as a starting point.

Below are three approaches that may do what you need.

== Method 1 - EPScript function ==
1) In EPScript, there is an undocumented function - <code>filter_compound_list</code> which accepts:
* a field (''contributors'')
* a sub-field name to filter on (''type'')
* a value to filter to (''http://www.loc.gov/loc.terms/relators/THS'')
* the field to return (''name'')

This can produce a text-string of one field from the compound field. If a thesis had two supervisors, the following example would produce:

''Smith, John and Bond, James''

<source lang="xml">
<epc:if test="contributors">
<epc:print expr="filter_compound_list(contributors,'type','http://www.loc.gov/loc.terms/relators/THS','name')" />
</epc:if>
</source>

== Method 2 - EPScript logic - ''foreach'' ==

This method is a bit more flexible, but you have to construct the values from the parts manually. It does allow you to reference the <code>id</code> sub-field if required.
It also may leave empty wrapping elements in the output (e.g. the <code>ul</code> in the example below if there are contributors, but none are the required type.

<source lang="xml">
<epc:if test="contributors">
<ul>
<epc:foreach expr="contributors" iterator="contr">
<epc:if test="$contr{type}='http://www.loc.gov/loc.terms/relators/THS'">
<li>
<epc:print expr="$contr{name}{given}" /> <epc:print expr="$contr{name}{family}" />
<epc:if test="$contr{id}">(<epc:print expr="$contr{id}"/>)</epc:if>
</li>
</epc:if>
</epc:foreach>
</ul>
</epc:if>
</source>

== Method 3 - Custom EPScript function ==
This is the most complex, but also offers the most flexibility - if you're able to understand the <code>EPrints::Script::Compiled</code> module and write your own functions.

There are two parts - adding custom methods to EPScript, and calling them from the citation file.

<source lang="perl">
# Open block
{

# Write into EPrints::Script::Compiled
package EPrints::Script::Compiled;

use strict;

# Example usage in citation file:
#
# <epc:if test="$item.render_contributors_filtered('http://www.loc.gov/loc.terms/relators/THS',1)">
# <h2><epc:phrase ref="contributor_type_typename_http://www.loc.gov/loc.terms/relators/THS"/></h2>
# <epc:print expr="$item.render_contributors_filtered('http://www.loc.gov/loc.terms/relators/THS')"/>
# </epc:if>
#
# The first call includes the 'test' parameter, which can be used to determine whether surrounding
# elements need to be displayed - in the above example the <h2>.

sub run_render_contributors_filtered
{
my( $self, $state, $eprint, $contributor_type, $test ) = @_;

if( !defined $eprint->[0] || ref($eprint->[0]) ne "EPrints::DataObj::EPrint" )
{
$self->runtime_error( "Can only call render_contributors_filtered() on eprint objects not ".
ref($eprint->[0]) );
}

if( !defined $contributor_type )
{
$self->runtime_error( "You need to specify a contributor type you want to render." );
}

my @filtered_contributors = grep{ defined $_->{type} && $_->{type} eq $contributor_type->[0] } @{ $eprint->[0]->value( "contributors" ) };

if( $test )
{
return [ 0, "BOOLEAN" ] if( scalar @filtered_contributors < 1 );
return [ 1, "BOOLEAN" ];
}

# NB this is based on EPrints::Extras::render_related_url
# It is over-complicated for this use-case, as we could just use
# $state->{session}->render_name( $row->{name} )
# but if other compound fields are being used with similar code
# being able to get to the 'render_value' for the sub fields is useful.

my $field = $eprint->[0]->dataset->field( "contributors" );
my $f = $field->get_property( "fields_cache" );
my $fmap = {};
foreach my $field_conf ( @{$f} )
{
my $fieldname = $field_conf->{name};
my $field = $field->{dataset}->get_field( $fieldname );
$fmap->{$field_conf->{sub_name}} = $field;
}

my $ul = $state->{session}->make_element( "ul" );

foreach my $row ( @filtered_contributors )
{
my $li = $state->{session}->make_element( "li" );
$li->appendChild( $fmap->{name}->render_single_value( $state->{session}, $row->{name} ) );
if( defined $row->{id} )
{
$li->appendChild( $state->{session}->make_text( " (" ) );
$li->appendChild( $state->{session}->make_text( $row->{id} ) );
$li->appendChild( $state->{session}->make_text( ")" ) );
}
$ul->appendChild( $li );
}
return [ $ul, "XHTML" ];
}

} #End block
</source>

The above example is also available at: https://gist.github.com/jesusbagpuss/2efc96ed05cf9121b925063a20677120

[[Category:Howto]][[Category:Snippets]][[Category:Contribute]]

Setting up HTTPS using Let's Encrypt

2020-12-14T12:06:07Z

Libjlrs: /* Additional Notes */

{{Manual}}
By default EPrints does not come setup to use HTTPS. This is because you need to generate a SSL certificate and if this is not signed by a known Certificate Authority a user's web browser is likely to complain vigorously. In the past it has typically costed a fair amount of money to obtain a SSL certificate from your hosting provider. However, now there is [https://letsencrypt.org/ Let's Encrypt] it is possible to get a certificate for free. This is not to say you should use Let's Encrypt in all cases. UK academic institutions should continue to obtain their SSL certificates through Jisc and other institutions/organisations may already have similar arrangements for obtaining SSL certificates.

As well as being free, Let's Encrypt has an automated way for renewing certificates. However, it should be noted that the length of its certificates is a lot shorter at just 3 months. As the renewal process is automatic, this time period is more appropriate to maximise security. Let's Encrypt's certificate generation requires your EPrints repository to be publicly accessible. Beneath are instructions on how to set up EPrints to enable HTTPS with a Let's Encrypt certificate.

1. Go to the https://certbot.eff.org/ and follow the instructions for your web server and operating system (the former will almost always be Apache) and follow the instructions provided.

2. When you get to the point of running the certbot command you want the certificate only so should type as the root user:

certbot --apache certonly

3. Take a note of the path to were your certificate, key and CA chain have been saved. This will probably be something like

/etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/

4. If you have not already done so, create an directory called <tt>ssl</tt> inside your archive's directory, i.e.

mkdir EPRINTS_PATH/archives/REPOID/ssl/

5. Create a file inside the new ssl directory called <tt>securevhost.conf</tt> and include the following contents, amending the <tt>ServerName</tt>, <tt>SSLCertificateFile</tt>, <tt>SSLCertificateKeyFile</tt> <tt>SSLCertificateChainFile</tt> and <tt>Include</tt> as appropriate at least. You will note that this configuration also enables [https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security HTTP Strict Transport Security (HSTS)] for additional security. This ensures that after the first time you visit HTTPS for a particular site in your web browser, all future HTTP requests for this hostname will automatically be converted by your browser to HTTPS.

<VirtualHost *:443>

ServerName YOUR-REPOSITORY-DOMAIN:443

# Enable HSTS
Header always set Strict-Transport-Security "max-age=63072000;"

SSLEngine on
SSLProtocol all -SSLv2 -SSLv3
SSLHonorCipherOrder on
SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH

SSLCertificateFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/YOUR-REPOSITORY-DOMAIN/chain.pem

SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

LogLevel warn
ErrorLog logs/ssl_error_log
TransferLog logs/ssl_access_log
CustomLog logs/ssl_request_log \
"%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"

Include EPRINTS_PATHH/cfg/apache_ssl/REPOID.conf

PerlTransHandler +EPrints::Apache::Rewrite

</VirtualHost>

6. If you have not already done so, add a configuration file at <tt>/opt/eprints3/archives/REPOID/cfg/cfg.d/https.pl</tt> with the following configuration:

$c->{securehost} = $c->{host};
$c->{secureport} = 443;
$c->{http_root} = undef;

7. Now you will need to regenerate the rest of your Apache configuration for EPrints with the following command run as the EPrints user. (Substitute the path as appropriate):

/opt/eprints3/bin/generate_apacheconf --system --replace

8. Apache will not yet have been setup to include the Apache configuration file you created in step 5. To include this, you will need to edit the file in your Apache configuration directory (<tt>/etc/httpd/</tt> on RHEL/CentOS/Fedora and <tt>/etc/apache2/</tt> on Debian/Ubuntu) and find the file that contains the line <tt>cfg/apache.conf</tt>, e.g.

cd /etc/httpd/
grep -r "cfg/apache.conf" *

9. Once you have found it you will need to edit it and add the following line, changing the path as appropriate:

Include EPRINTS_PATH/archives/REPOID/ssl/securevhost.conf

10. Now, (as root or using sudo) test that the Apache configuration is correct and fix any issues if necessary:

apachectl configtest

11. Restart Apache and check whether you can access your EPrints repository using HTTPS in a web browser:

apachectl restart

12. If the guide on cerbot.eff.org you used in step 1 tells you to to setup a cron job then follow those instructions. The easiest way to do this is probably to run <tt>crontab -e</tt> as root and add the following cron job, substituting the minute (43) and hours (6,18) for you own choice maintaining a 12 hour gap between the hours:

43 6,18 * * * certbot renew

== Additional Notes ==

The default EPrints Apache Rewrite handler declines any requests to a URL containing <code>/.</code>.

This means that the challenge/response for a LetsEncrypt certificate renewal that uses the <code>/.well-known/acme-challenge/</code> path will fail.

To make this work you could add a location block to your Apache config, to ensure the <code>/.well-known/</code> are not handled by EPrints, or use an EPrints URL rewrite trigger to handle the request:

<syntaxhighlight lang="perl">
#this could be saved into e.g. [EPRINTS_ROOT]/lib/cfg.d/z_rewrite_url_LetsEncrypt.pl

# import Apache constant e.g. 'OK'
use EPrints::Apache::AnApache;

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %o ) = @_;

# if the incoming request matches the LetsEncrypt challenge URL...
if( $o{uri} =~ m!^${o{urlpath}}/\.well-known/acme-challenge/! )
{
# and the LetsEncrypt renewal process has put the file in EPRINTS_ROOT/archives/ARCHIVEID/html/.well-known/acme-challenge/
if( -f $o{repository}->get_conf( "htdocs_path" ).$o{uri} )
{
# reply with an HTTP '200'
${$o{return_code}} = OK;
# and return the file reqested
$o{request}->filename( $o{repository}->get_conf( "htdocs_path" ).$o{uri} );
}
# and say that we've handled the request - so no more triggers should be run.
return EP_TRIGGER_DONE;
}
} );
</syntaxhighlight>