openbookpublishers/world_reader_driver repository overview

⁠World Reader Driver

• Documentation: https://metrics.operas-eu.org/docs/world-reader⁠

This driver allows programmatic retrieval and normalisation of World Reader usage reports.

The driver is made of two modules: the first one scrapes usage reports from World Reader and stores them in a directory (CACHEDIR); the second reads from cache, normalises the reports, and outputs to a different directory (OUTDIR). We recommend running this driver in a docker container and mapping both CACHEDIR and OUTDIR to persistent volumes.

⁠Setup

⁠Requirements

Identifier normalisation is performed using an instance of hirmeos/identifier_translation_service⁠ - you must first setup this API.

World Reader provides geographical data using the country name, so we normalise it to iso-2 format using an instance of hirmeos/countries_api⁠ - you must also setup this API.

⁠World Reader reports

Unfortunately, World Reader does not have a proper reporting API or interface for publishers hosting books with them. They do however send a monthly email with a unique link to an interface where publishers can review usage for the previous month. These links are completely random, so in order for the driver to work one must input the each link in the driver's configuration file as soon as they receive it.

The report links are not persistent, and indeed most of our own ones for the past year are not active at the moment. The drive caches all requests in CACHEDIR for future use, so this is not too much of a problem, but it's worth having in mind.

⁠Environment variables

The following environment variables must be set. You can find a template in ./config/config.env.example.

⁠Example config.env file

MODES=[{"measure":"https://metrics.operas-eu.org/world-reader/users/v1","name":"world-reader","startDate":"2018-05-01","config":[{"name":"report-url","value":"https://mb.wrdr.io/embed/dashboard/random_string#bordered=true&titled=true"}]}]
WORK_TYPES=["book","book-series","book-set","dissertation","edited-book","journal","journal-issue","journal-volume","monograph","posted-content","proceedings","reference-book","report","report-series","standard","standard-series"]
OUTDIR=/usr/src/app/output
CACHEDIR=/usr/src/app/cache
URI_API_ENDP=https://identifier.translation.service/translate
AUTH_API_ENDP=https://authentication.service/tokens
COUNTRY_API_ENDP=httsp://countries.api/countries
[email protected]
URI_API_PASS=some_secret_password
URI_SCHEME=info:doi
URI_STRICT=true

⁠The MODES env variable

You must define a JSON array inMODES, with at least one record. The driver will iterate through the array, performing its task once per mode; in a typical case there will only be one entry in the array.

Each entry of the MODES array must contain values for measure, name, startDate, and config.

Example:

MODES=[{"measure":"https://metrics.operas-eu.org/world-reader/users/v1","name":"world-reader","startDate":"2018-05-01","config":[{"name":"report-url","value":"https://mb.wrdr.io/embed/dashboard/random_string#bordered=true&titled=true"}]}]

⁠Run via crontab

0 0 * * 0 docker run --rm --name "world_reader_driver" --env-file /path/to/config.env -v world_reader_cache:/usr/src/app/cache -v metrics:/usr/src/app/output openbookpublishers/world_reader_driver:1