PIRUS 'PUSH' implementation

Provide data for COUNTER R5 compliant usage statistics.

By default this package is configured to send data to the IRUS-UK tracker.

UPDATE March 2019: The default URL used by this code has been updated to https://irus.jisc.ac.uk/counter/.

If you are looking for a version of this plugin that does have the latest IRUS tracker URL, but doesn't have the counter R5 updates see https://github.com/eprintsug/irus/tree/irus-jisc-ac-uk

Upgrading

Please see the separate Notes on upgrading IRUS for details on how to upgrade your IRUS integration to the latest version.

Installation

This EPrints plugin should be available from the EPrints Bazaar, and can be installed from within your repository.

To manually install it, you can use the GitHub repository and the Gitaar tool.

Sending data to other trackers

If you need to send data to a tracker other than IRUS-UK, please add the following to a file in the archive specific configuration e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_pirus.pl

$c->{pirus}->{tracker} = "https://THE-URL-OF-THE-OTHER/tracker/";

Testing / use on development servers

In the file lib/cfg.d/pirus.pl there is a URL for a test COUNTER server in the comments.

#$c->{pirus}->{tracker} = "https://irus.jisc.ac.uk/counter/test/";

if you are testing the plugin, or have it installed on a test/development machine, you can add the configuration above to a file in the archive specific configuration e.g. ~/archives/ARCHIVEID/cfg/cfg.d/z_pirus.pl.

Troubleshooting

From v1.2.2, more information about a failed transfer of data to the tracker will be logged in the description of the Event::PIRUS event (that then replays the data to the tracker). To view the event, go to 'Manage records' -> 'Tasks' as an admin user in the EPrints interface. If there are a lot of items in the list, you may want to filter for Plugin = Event::PIRUS.

There is also a configuration option to add the same information to the Apache error log. This can can be quite verbose as it would log for every failed transmission, whereas the replay event is created once.

The Event::PIRUS replays may only exist for a short amount of time in the event queue if the initial transmissions fail, but the replay events work. To scrutinise the replay event you may need to temporarily stop the EPrints indexer to allow you to see the details of the failure.

Implementation

This code will PING the configured tracker server whenever a full-text or item summary page is requested from EPrints.

These pings can be aggregated together with data from other sources (publishers, other repositories) to create a fuller picture of the usage of individual articles.

The data transferred are:

• url_ver - set to Z39.88-2004 (OpenURL)
• url_tim - the datestamp of the 'access' dataobject
• req_id - requesting IP address
• req_dat - User-agent making request
• rft.artnum - the OpenArchives OAI identifier for the accessed item
• rfr_id - the hostname of the repository
• svc_dat - the URL requested
• rfr_dat - the HTTP referrer (when set)
• rft_dat - whether it was a full-text download, or a summary page access.

OAI-PMH IRUS / ORCID set

The file lib/cfg.d/z_oai_irus.pl.example contains an example configuration for an OAI-PMH custom set irus-orcid that will include items which have an ORCID defined for a creator. It is based on the standard EPrints implementation for ORCIDs.

To activate this set, copy the file into archives/ARCHIVEID/cfg/cfg.d/, but without the .example on the end of the filename. Reload the webserver, and test using the URL:
https://YOUR-SERVER-NAME/cgi/oai2?verb=ListIdentifiers&metadataPrefix=oai_dc&set=irus-orcid

The default oai_dc metadata profile does not contain ORCIDs, but if you have a metadata profile that can include them (and has been confiigured to include them) e.g. RIOXX, then use that, and a 'ListRecords' request e.g.
https://YOUR-SERVER-NAME/cgi/oai2?verb=ListRecords&metadataPrefix=rioxx&set=irus-orcid

Changes

• 1.2.2 John Salter J.Salter@leeds.ac.uk

Additional information added to replay event and error log when a data transfer fails. This information may help diagnose the problem.

• 1.2.1 John Salter J.Salter@leeds.ac.uk

Update to default tracker URL.

• 1.2.0 John Salter J.Salter@leeds.ac.uk

Update to COUNTER R5:

Set rft_dat to Request (for fulltext downloads)

Set rft_dat to Investigation (for summary page views)

• 1.1.0 ???

• 1.06 Justin Bradley jb4@ecs.soton.ac.uk

Perl syntax bug Fix.

• 1.05 Sebastien Francois sf2@ecs.soton.ac.uk

• 1.04 Tim Brody tdb2@ecs.soton.ac.uk

Set svc_format to mime_type (was commented out???)

Set svc_dat to the requested URL (works only for live)

• 1.03 ???

• 1.02 Justin Bradley jb4@ecs.soton.ac.uk

Compatibility fixes for 3.2.

• 1.01 Tim Brody tdb2@ecs.soton.ac.uk

Fixed reference to 'jtitle' instead of 'publication'

• 1.00 Tim Brody tdb2@ecs.soton.ac.uk

Initial version

Reuse / licence information

Copyright 2012 University of Southampton

Released to the public domain (or CC0 depending on your juristiction).

Updated 2018 John Salter on behalf of White Rose Libraries and IRUS-UK CAG.

With thanks to Alan Stiles (Open University) and Paul Needham (Cranfield University)

USE OF THIS EXTENSION IS ENTIRELY AT YOUR OWN RISK