Child pages
  • KE Usage Statistics Guidelines

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Host name

 

Description

An identification of the institution that is responsible for the repository in which the requested document is stored.

XPath

ctx:context-object/ctx:resolver/ctx:identifier

Usage

Mandatory

Format

The baseURL of the repository must be used. This must be a URI, and not only the domain name.

Example

http://wwwopenaccess.worldcatleidenuniv.orgnl/librariesdspace-oai/53238request

<resolver/identifier> | Location of OpenURL Resolver

...

Description

When the IP-address is obfuscated, this will have the disadvantage that information on the geographic location, for instance, can no longer be derived. For this reason, the C-Class subnet must be provided. The C-Class subnet, which consists of the three most significant bytes from the IP-address, is used to designate the network ID. The final (most significant) byte, which designates the HOST ID, is replaced with a '0'. The C-class Subnet may optionally be hashed using MD5 encryption.

XPath

ctx:context-object/ctx:requester/ctx:identifier If the C-Class subnet is hashed, the MD5 hash must be provided in the following element: ctx:context-object/ctx:metadata/dini:requesterinfo/dini:hashed-c If this element is used, the <metadata> element must be preceded by ctx:requester/ctx:metadata-by-al/ctx:format with value "http://dini.de/namespace/oas-requesterinfo"

Usage

Optional

Format

A data-URI, consisting of the prefix "data:,", followed either by a 32-digit hexadecimal number, or by three hexadecimal numbers separated by a dot, followed by a dot and a '0'.

Examples

data:,118208.9477.150188.0
data:,ec17f0564f32240c0a9d848d4b823ef2a

...

All data providers have to provide support for <context-object> documents or <context-objects> aggregations, respectively.This choice also has to be announced in the response to the "listMetadataFormats" query OAI-PMH, 4.4 by the data provider. While a specific "metadataPrefix" is not required, the information about "metadataNamespace" and "schema" is fixed for implementations:


 

Code Block
xml
xml
linenumbertrue
titleOAI-PMH listMetadataFormats
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<OAI-PMH>
...
<metadataFormat>
  <metadataPrefix>ctxo</metadataPrefix>
  <schema>http://www.openurl.info/registry/docs/xsd/info:ofi/fmt:xml:xsd:ctx</schema>
  <metadataNamespace>info:ofi/fmt:xml:xsd:ctx</metadataNamespace>
</metadataFormat>
...
</OAI-PMH>

...

Code Block
xml
xml
linenumbertrue
titlemethod 1 : all Context Objects in one OAI-PMH record : OAI-PMH listRecords metadataPrefix=ctxo
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<OAI-PMH>
...
<record>
    <header>
        <identifier>urn:uuid:e5d037a0-633c-11df-a08a-0800200c9a66 <0800200c9a66</identifier>
        <datestamp>2009-06-02T14:10:02Z</datestamp>
    </header>
    <metadata>
        <context-objects xmlns="info:ofi/fmt:xml:xsd:ctx">
            <context-object datestamp="2009-06-01T19:20:57Z">
              ...
            </context-object>
            <context-object datestamp="2009-06-01T19:21:07Z">
              ...
            </context-object>
        </context-objects>
    </metadata>
</record>
...
</OAI-PMH>

In the aforementioned example, the OAI-PMH record is identified by a UUID (in form of a URI), see RFC 4122. When offering single <context-object> documents rather than an aggregation using <context-objects> containers like above, a conformal OAI-PMH record may look like the following:

Code Block
xmlxml
linenumbertrue
titlemethod 2 : each Context Object in separate OAI-PMH records : OAI-PMH listRecords metadataPrefix=ctxo
collapsetrue

<?xml version="1.0" encoding="UTF-8"?>
<OAI-PMH>
...
<record>
    <header>
        <identifier>urn:uuid:fd23522e-c447-4801-9be4-c93c60a2d550 </identifier>
        <datestamp>2009-06-02T14:10:02Z</datestamp>
    </header>
    <metadata>
        <context-object xmlns="info:ofi/fmt:xml:xsd:ctx" datestamp="2009-06-01T19:20:57Z">
          ...
        </context-object>
    </metadata>
</record>
<record>:20:57Z">
      <header>         <identifier>urn:uuid:1ad69103-6bd0-4a90-ae75-e4b644c136a6 </identifier>...
        <datestamp>2009-06-02T14:10:04Z</datestamp>     </header>
context-object>
   <metadata>         <context-object xmlns="info:ofi/fmt:xml:xsd:ctx" datestamp="2009-06-01T19:21:07Z">
              ...
            </context-object>
        </context-objects>
    </metadata>
</record>
...
</OAI-PMH>

4.2. SUSHI

OAI-PMH is a relatively light-weight protocol which does not allow for a bidirectional traffic. If a more reliable error-handling is required, the Standardised Usage Statistics Harvesting Initiative (SUSHI) must be used. SUSHI http://www.niso.org/schemas/sushi/ was developed by NISO (National Information Standards Organization) in cooperation with COUNTER. This document assumes that the communication between the aggregator and the usage data provider takes place as is explained in figure 4.


...

If the begin date and the end date in the request of the log aggregator form a period that exceeds one day, an error message must be sent. In the SUSHI schema, such messages may be sent in an <Exception> element. Three types of errors can be distinguished. Each error type is given its own number. An human-readable error message is provided under <Message>.


 

Code Block
xml
xml
titleListing 4
linenumberstrue
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
				xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/ http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ReportResponse xmlns:ctr="http://www.niso.org/schemas/sushi/counter"
						xsi:schemaLocation="http://www.niso.org/schemas/sushi/counter http://www.niso.org/schemas/sushi/counter_sushi3_0.xsd"
						xmlns="http://www.niso.org/schemas/sushi"
						xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
			<Requestor>
				<ID>www.logaggregator.nl</ID>
				<Name>Log Aggregator</Name>
				<Email>logaggregator@surf.nl</Email>
			</Requestor>
			<CustomerReference>
				<ID>www.leiden.edu</ID>
				<Name>Leiden University</Name>
			</CustomerReference>
			<ReportDefinition Release="urn:DRv1" Name="Daily Report v1">
				<Filters>
					<UsageDateRange>
						<Begin>2009-12-22</Begin>
						<End>2009-12-23</End>
					</UsageDateRange>
				</Filters>
			</ReportDefinition>
			<Exception>
				<Number>1</Number>
				<Message>The range of dates that was provided is not valid. Only daily reports are
				available.</Message>
			</Exception>
		</ReportResponse>
	</soap:Body>
</soap:Envelope>

...

When the repository is in the course of producing the requested report, a response will be sent that is very similar to listing 6. The estimated time of completion will be provided in the <Data> element. According to the documentation of the SUSHI XML schema, this element may be used for any other optional data.


 

Code Block
xml
xml
titleListing 6
linenumberstrue
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
				xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				xsi:schemaLocation="http://schemas.xmlsoap.org/soap/envelope/ http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<ReportResponse xmlns:ctr="http://www.niso.org/schemas/sushi/counter"
						xsi:schemaLocation="http://www.niso.org/schemas/sushi/counter http://www.niso.org/schemas/sushi/counter_sushi3_0.xsd"
						xmlns="http://www.niso.org/schemas/sushi"
						xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
			<Requestor>
				<ID>www.logaggregator.nl</ID>
				<Name>Log Aggregator</Name>
				<Email>logaggregator@surf.nl</Email>
			</Requestor>
			<CustomerReference>
				<ID>www.leiden.edu</ID>
				<Name>Leiden University</Name>
			</CustomerReference>
			<ReportDefinition Release="urn:DRv1" Name="Daily Report v1">
				<Filters>
					<UsageDateRange>
						<Begin>2009-12-22</Begin>
						<End>2009-12-23</End>
					</UsageDateRange>
				</Filters>
			</ReportDefinition>
			<Exception>
				<Number>3</Number>
				<Message>The report is not yet available. The estimated time of completion is
				provided under "Data".</Message>
				<Data>2010-01-08T12:13:00+01:00</Data>
			</Exception>
		</ReportResponse>
	</soap:Body>
</soap:Envelope>

...

Error number

Error message

1

The range of dates that was provided is not valid. Only daily reports are available.

2

The file describing the internet robots is not accessible

3

The report is not yet available. The estimated time of completion is provided under "Data"

5. Normalisation

 

5.1. Double Clicks

If a single user clicks repeatedly on the same document item within a given amount of time, this should be counted as a single request. This measure is needed to minimise the impact of conscious falsification by authors. There appears to be some difference as regards the time-frame of double clicks. The table below provides an overview of the various timeframes that have been suggested.

COUNTER

10 seconds sec for a HTML-resource; 30 sec for a PDF

LogEC

1 month

AWStats

1 hour

IFABC

30 minutes

...

Code Block
xml
xml
titleAppendix A: Sample OpenURL Context Object File
linenumberstrue
collapsetrue
<?xml version="1.0" encoding="UTF-8"?>
	<context-objects xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
						xmlns:dcterms="http://dublincore.org/documents/2008/01/14/dcmi-terms/"
						xmlns:sv="info:ofi/fmt:xml:xsd:sch_svc"
						xsi:schemaLocation="info:ofi/fmt:xml:xsd:ctx [http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:ctx]"
						xmlns="info:ofi/fmt:xml:xsd:ctx">
		<context-object timestamp="2009-07-29T08:15:46+01:00" identifier="b06c0444f37249a0a8f748d3b823ef2a">

			<referent>
				<identifier>https://openaccess.leidenuniv.nl/bitstream/1887/12100/1/Thesis.pdf</identifier>
				<identifier>http://hdl.handle.net/1887/12100</identifier>
			</referent>

			<referring-entity>
				<identifier>http://www.google.nl/search?hl=nl&amp;q=beleidsregels+artikel+4%3A84&amp;meta="</identifier>
				<identifier>info:sid/google</identifier>
			</referring-entity>

			<requester>
				<identifier> b505e629c508bdcfbf2a774df596123dd001cee172dae5519660b6014056f53a</identifier>

				<metadata-by-val>
					<format>http://dini.de/namespace/oas-requesterinfo</format>
					<metadata>
					<requesterinfo xmlns="http://dini.de/namespace/oas-requesterinfo">
						<hashed-ip>b505e629c508bdcfbf2a774df596123dd001cee172dae5519660b6014056f53a</hashed-ip>
						<hashed-c>d001cee172dae5519660b6014056f5346d05e629c508bdcfbf2a774df596123d</hashed-c>
						<hostname>uni-saarland.de</hostname>
						<classification>institutional</classification>
						<hashed-session>660b14056f5346d0</hashed-session>
						<user-agent>mozilla/5.0 (windows; u; windows nt 5.1; de; rv:1.8.1.1) gecko/20061204</user-agent>
					</requesterinfo>
				</metadata>
			</metadata-by-val>
		</requester>

		<service-type>
			<metadata-by-val>
				<format>http://dublincore.org/documents/2008/01/14/dcmi-terms/</format>
				<metadata>
					<dcterms:format>objectFile</dcterms:format>
				</metadata>
			</metadata-by-val>
		</service-type>

		<resolver>
			<identifier>http://www.worldcat.org/libraries/53238</identifier>
		</resolver>

		<referrer>
			<identifier>info:sid/dlib.org:dlib</identifier>
		</referrer>

	</context-object>
</context-objects>

...