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

DSpace hosting, support, development and consulting

  1. 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.

  2. 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.

    Export link in the University of
				      Waikato's repository Export link in the AgResearch repository

    To see this functionality in action, visit any thesis record in the University of Waikato's repository, Research Commons.

  3. 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>
      <!-- other dependencies go here -->
      <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">
        <!-- existing readers go here -->	      
        <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:
      <!-- Bitstream pipeline -->
      <map:pipeline type="noncaching">
        <!-- Existing pipeline blocks go here -->
        <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>