When a user clicks on a link to an item page (i.e. to view item metadata) or an associated file (i.e. requests a download) from a Repository with the tracker protocol in operation, if HTTP Status code 200 or 304 is returned for that request, an OpenURL log entry is sent to an endpoint on the IRUS server for further processing.
Constructing the OpenURL log entry
The OpenURL log entry should be based on a subset of the NISO OpenURL 1.0 standard KEV ContextObject Format. The OpenURL string values must be URL encoded, with key-value pairs separated by an ampersand (&)
| Element | OpenURL Key | OpenURL Value (example) | Notes |
|---|---|---|---|
| OpenURL version | url_ver | Z39.88-2004 | Identifies data as OpenURL 1.0. String constant: Z39.88-2004 (Mandatory) |
| Usage event datestamp | url_tim | 2010-10-17T03%3A04%3A42Z | Date/time of usage event (Mandatory) |
| Usage event type | rft_dat | Request | Valid values are ‘Investigation’ for item page/metadata views and ‘Request’ for file downloads (Mandatory) |
| Client IP address | req_id | 138.250.13.161 | IP Address of the client requesting the article (Mandatory) |
| UserAgent | req_dat | Mozilla%2F4.0+%28compatible%3B+MSIE+7.0%3B+Windows+NT+5.1%3B+Trident%2F4.0%3B+GoogleT5%3B+.NET+CLR+1.0.3705%3B+.NET+CLR+1.1.4322%3B+Media+Center+PC+4.0%3B+IEMB3%3B+InfoPath.1%3B+.NET+CLR+2.0.50727%3B+IEMB3%29 | The UserAgent is used to identify and eliminate, by applying COUNTER rules, accesses by robots/spiders (Mandatory) |
| Item OAI identifier | rft.artnum | oai%3Adspace.lib.cranfield.ac.uk%3A1826%2F936 | Canonical identifier for retrieving item metadata from the source repository (Mandatory) |
| FileURL | svc_dat | https%3A%2F%2Fdspace.lib.cranfield.ac.uk%2Fbitstream%2F1826%2F936%2F4%2FArtificial_compressibility_Pt2-2005.pdf | The URL of the item page for an Investigation or the URL of the file downloaded for a Request (Mandatory) |
| HTTP Referer | rfr_dat | https%3A%2F%2Fscholar.google.com%2F | (Mandatory) The HTTP header field that identifies the address of the webpage (i.e. the URI) that linked to the resource being requested, which is used to help identify and eliminate accesses by robots/spiders |
| Source repository | rfr_id | dspace.lib.cranfield.ac.uk | (Mandatory) |
Eliminating robots
Information about robot downloads need not be transmitted to the IRUS server. Before attempting to transmit the OpenURL, a check may be carried out to eliminate robots as defined in the COUNTER official list, which is available as a series of user-agent regexes in a text file maintained and available on github.
Checking against these regexes should be case insensitive.
OpenURL Transmission
Once the OpenURL has been constructed, it will need to be transmitted to the IRUS server where it will be stored and processed.
Example:
https://irus.jisc.ac.uk/counter/test/?url_ver=Z39.88-2004&url_tim=2010-10-17T03%3A04%3A42Z&rft_dat=Request&req_id=138.250.13.161&req_dat=Mozilla%2F4.0+%28compatible%3B+MSIE+7.0%3B+Windows+NT+5.1%3B+Trident%2F4.0%3B+GoogleT5%3B+.NET+CLR+1.0.3705%3B+.NET+CLR+1.1.4322%3B+Media+Center+PC+4.0%3B+IEMB3%3B+InfoPath.1%3B+.NET+CLR+2.0.50727%3B+IEMB3%29&rft.artnum=oai%3Adspace.lib.cranfield.ac.uk%3A1826%2F936&svc_dat=https%3A%2F%2Fdspace.lib.cranfield.ac.uk%2Fbitstream%2F1826%2F936%2F4%2FArtificial_compressibility_Pt2-2005.pdf&rfr_dat=https%3A%2F%2Fscholar.google.com%2F&rfr_id=dspace.lib.cranfield.ac.uk
If the transmission is successful the IRUS server will return a 200 OK code.
If the transmission is not successful, e.g. a 4xx or 5xx code is returned, the OpenURL string should be queued for processing later, e.g. appended to a file held on the local server. A script, that can be scheduled to run periodically, should check if there are queued entries and, if there are, re-transmit them.