Export citation to EndNote (RIS) · IRR Team at ITS, the University of Waikato

What does it do?

"As an EndNote user browsing the repository, I want to be able to import an individual item's bibliographic information so that I can be confident I'm citing it correctly."

The EndNote export add-on for DSpace makes available a new URL endpoint of the form [your-dspace-url]/citation/handle/123456789/123. When a repository user follows a link to this endpoint, the item's metadata will be crosswalked into the RIS format and the result will be made available for download / import into the user's citation manager. The RIS format is supported by many citation managers including EndNote, JabRef, Mendeley and Zotero.
How does it work?

You will need to create an export link in a suitable spot on the item page. This could be near the location of the item's citation metadata, or elsewhere on the item page.

To see this functionality in action, visit any thesis record in the University of Waikato's repository, Research Commons.
How do I use it?

Pull in the code

Follow the instructions for the XMLUI-Extras module. You may find that the dependency to the API-Extras module is outdated, in which case you will need to define an exclusion in the dspace/modules/xmlui/pom.xml file and add a dependency to a more recent version directly. In that case, you will also need to obtain, build and install the corresponding version of API-Extras.

As an example, in a repository running DSpace 5.1, the relevant part of the dspace/modules/xmlui/pom.xml file might look like this:
```
<dependencies>
  
  <dependency>
    <groupId>nz.ac.waikato.its</groupId>
    <artifactId>xmlui-extras</artifactId>
    <version>5.1.2</version>
    <exclusions>
      <exclusion>
        <groupId>nz.ac.waikato.its</groupId>
        <artifactId>api-extras</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
  <dependency>
    <groupId>nz.ac.waikato.its</groupId>
    <artifactId>api-extras</artifactId>
    <version>5.1.3</version>
  </dependency>
</dependencies>
```
Change DSpace sitemap

The citation exporter produces a non-HTML file. Unfortunately this means that you will need to add a reference to the main sitemap.xmap file for DSpace XMLUI.
1. Copy the [dspace-src]/dspace-xmlui/src/main/webapp/sitemap.xmap file to the corresponding overlay directory ([dspace-src]/dspace/modules/xmlui/src/main/webapp/sitemap.xmap) and change the latter. (Alternatively, you can edit the file in place, but then you will need to use the full build option for DSpace rather than the quick build option.)
2. In the map:readers section of the sitemap, add an additional line to reference the class that provides the export:
```
<map:readers default="resource">
  	      
  <map:reader name="ItemListCitationExporter" src="nz.ac.waikato.its.dspace.exportcitation.ItemListCitationExporter"/>
</map:readers>
```
3. In the bitstream pipeline section of the sitemap, add an additional map:match block that links the export to the URL pattern:
```

<map:pipeline type="noncaching">
  
  <map:match pattern="citation/handle/*/*">
    <map:read type="ItemListCitationExporter">
      <map:parameter name="handle" value="{1}/{2}"/>
      <map:parameter name="format" value="{request-param:format}"/>
    </map:read>
  </map:match>
</map:pipeline>
```
Configure fields and types mappings

The metadata fields used in DSpace will need to be mapped to the RIS fields. Some metadata values will need to receive special treatment in order to follow conventions in the RIS format; this is most notably the case for the metadata values used for item types, but other metadata fields may be affected as well (e.g. dates, page ranges).

Thomson Reuters publishes documentation about the RIS format that includes information on the item types supported by RIS and the fields that should be included for each item type.

The mapping itself depends to a great deal on the metadata fields used in your DSpace repository. DSpace does not provide metadata fields for typical biographic information such as the title of the journal/proceedings, pagination, volume/issue information, etc. As a result, these fields vary greatly across DSpace repositories.

Note: You will need to have granular bibliographic metadata in your DSpace repository in order to use this add-on, with a separate field for each component.

The field mappings are defined in a configuration file, dspace/config/modules/endnote-export.cfg. There are three types of settings in this file:

field.XY = schema.element[.qualifier][,schema2.element2[.qualifier2]][(CONVERTER)]
Field mapping, where XY stands for the two-letter RIS name of the field, schema.element[.qualifier] is the corresponding DSpace metadata field, and (CONVERTER) is an optional reference to a converter definition, see below. You can list multiple comma-separated DSpace metadata fields; they will be checked in order and the first value found will be exported.

converter.NAME = class
Converter definition, where NAME is the name of the converter and class is the fully qualified name of a Java class that extends the Converter interface.

converterconfig.NAME.key = value
Configuration option for an individual converter identified by NAME, where key is the name of the property and value the value.

The API-Extras module contains example converters in the nz.ac.waikato.its.dspace.exportcitation.converters package. Place any additional converters into the dspace/modules/additions/src/main/java directory tree.

A sample configuration file might look like this:
```
field.AB = dc.description.abstract
field.AU = dc.contributor.author
field.DO = dc.identifier.doi(DOI)
field.KW = dc.subject
field.M3 = thesis.degree.level
field.PB = dc.publisher
field.PB = thesis.degree.grantor
field.PY = agresearch.event.date,dc.date.issued,dc.date.available(YEAR)
field.SN = agresearch.relation.patent,agresearch.relation.report
field.T2 = dc.relation.ispartof,agresearch.event.title
field.TI = dc.title
field.TY = dc.type(TYPE)
field.UR = dc.identifier.uri(MOREURLS)
field.VL = thesis.degree.name

converter.DOI = nz.ac.waikato.its.dspace.exportcitation.converters.EndnoteDOIConverter
converter.TYPE = nz.ac.waikato.its.dspace.exportcitation.converters.AgResearchEndnoteTypeConverter
converter.YEAR = nz.ac.waikato.its.dspace.exportcitation.converters.DateFormatConverter
converter.MOREURLS = nz.ac.waikato.its.dspace.exportcitation.converters.UrlFromIdentifierAndRelationConverter

converterconfig.DOI.prefix = ""
converterconfig.YEAR.format = "y"
converterconfig.MOREURLS.otherfield = dc.relation.uri
```
Add export link to item page

Anywhere on the item page, add a link constructed to match the URL pattern of the citation export. For example, your item-view.xsl file (which operates on the mets representation of the item's metadata) could contain a block such as:
```
<a class="btn btn-default btn-xs">
  <xsl:attribute name="href">
    <xsl:value-of select="$context-path"/>
    <xsl:text>/citation</xsl:text>
    <xsl:value-of select="//mets:METS/@OBJID"/>
    <xsl:text>?format=endnote</xsl:text>
  </xsl:attribute>
  <span class="glyphicon glyphicon-export"></span>
  <xsl:text> </xsl:text>
  <i18n:text>xmlui.dri2xhtml.METS-1.0.item-citation-endnote</i18n:text>
</a>
```
with a corresponding entry in messages.xml to define the translation:
```
<message key="xmlui.dri2xhtml.METS-1.0.item-citation-endnote">Export to EndNote</message>
```

What does it do?

How does it work?

How do I use it?

Pull in the code

Change DSpace sitemap

Configure fields and types mappings

Add export link to item page