Repository Tools 2: Enabling deposit via Elements

This document describes how repository item data is crosswalked out of Elements, thus allowing users to deposit to the repository via Elements. This is also known as the outbound crosswalk.

This document is designed for repository managers and technical staff. It aims to provide an understanding of Repository Tools 2 (RT2) harvesting capabilities, both from a functional and technical standpoint. This documentation is repository-agnostic - specific implementation details for each supported repository should be referenced in repository-specific documents.

Symplectic Elements and repositories are all systems for managing different kinds of research information. Whilst they may collect similar information, that information will be stored and structured in different ways. In order to feed information from your repository into Elements, we need to tell the systems how that data from the repository should appear in Elements. Essentially we specify how each piece of metadata we want to copy from the repository into Elements should be mapped from its repository value into an Elements field. We use a crosswalk map file to specify how these fields are mapped.

Crosswalking data into Elements for RT2 involves 2 components:

1. The repository collection: Elements has no concept of a collection, so a crosswalk needs to specify which repository collection is to be used.

2. The field map: this defines how each source field (as defined in Elements) should be mapped to a destination (repository) field. For example an Elements title may be mapped to a repository dc.title field. This is specified using a <xwalk:field-map> element of a map file.

Crosswalks are defined using an XML file, which must conform to a schema supplied with Elements. See Updating and Testing Crosswalks for details of uploading and downloading crosswalk map files.

An outbound crosswalk map file contains a single <xwalkout:consolidated-maps> element. This defines the behaviour of the crosswalk, using the following sub-elements. Some sub-elements are required and others are optional as specified below:

The required <xwalk:field-maps> element contains all the field maps (<xwalk:field-map> elements) used in the crosswalk. Each field map has its own unique identifier (name attribute) and specifies a particular set of field mappings (at a simple level, ‘map repository field X to Elements field Y’ etc). Typically each Elements object type will have its own field map, although they can be shared across multiple types where the mapping is identical.

The required <xwalkout:field-map-selector> element is used to inspect an Elements object and specify the name of the field-map to apply (by selecting a <xwalk:field-map-selection> element). This typically will take the form of an <xwalk:choose> element. If no field-map-selection is made the item is not crosswalked.

The optional <xwalk:value-maps> element contains all the value maps (<xwalk:value-map> elements) used in the crosswalk. A value map provides a means to inspect a value being crosswalked and replace certain text strings with other text strings. Uses might be to interpret true/false from a free-format text string (i.e. ‘No’, ‘no’, ‘False’ etc are all replaced with ‘false’) or to map one set of Elements restricted values to equivalent (but different) values in the repository.

The optional <xwalk:parameters> element can be used to define specific parameters that affect the overall crosswalk process.

The optional <xwalk:elements-metadata> element can be used to define the Elements metadata definitions to be used during the crosswalk process. This data is currently not used for the outbound crosswalk.

For more information see the RT2 Defining Crosswalks guide

When creating your outbound crosswalk map you should follow the steps outlined below to identify the functionality required for the crosswalk:

1. Identify which Elements objects you want to be able to deposit into a repository (this will be used as the basis for defining the <xwalkout:field-map-selector> element of your crosswalk map file). You should identify the criteria that the crosswalk will use to decide whether an object should be crosswalked or not. Criteria may include:

   • Object type. You may only wish to crosswalk items of a given type or types

   • Any other metadata value that is available from Elements.

2. For each object to be deposited, identify which collection it should be deposited into (this will be used as the basis for defining each <xwalkout:collection-selector> element of your crosswalk map file). You should identify the criteria that the crosswalk will use to decide which collection to use (items which do not identify a collection will not be crosswalked). Criteria may include:

   • Object type. The destination collection may depend on the object type

   • Date. You may wish only to crosswalk items that were published after a given date

   • Any other metadata value that is available from Elements.

3. For each object type to be crosswalked, identify how each repository field should be populated from the Elements object field values (this will be used as the basis for defining each <xwalk:field-map> element of your crosswalk map file). This may be a simple one to one field mapping, or may involve more complex logic, such as:

   • Looking up individual values (these will usually require a <xwalk:value-map> element in your crosswalk map file)

   • Appending several values together

   • Using conditional logic to define a value.

Note: It is helpful to know exactly what the current data structure is in your instance of Elements when planning your Crosswalks. You can download a copy of your Elements data structure, go to the 'Module Admin' menu in Elements and click on 'Underlying fields' under the 'Publications' section. At the top of the 'Manage underlying fields' page is a link to download your Elements data structure.

Once the required functionality has been identified you are ready to define the crosswalk map file. Before amending your crosswalk map file, disable harvest capability for your repository within Elements. This is to ensure you are not harvesting data while the crosswalk map file is changing.

1. Specify which items are to be crosswalked.
   Edit the <xwalkout:field-map-selector> element so that a <xwalk:when> element exists for each set of criteria used to identify an item that is to be crosswalked into Elements (the criteria are defined using a <xwalk:condition> element). Within each of these a <xwalk:result> element should be defined, containing a single <xwalkout:field-map-selection> element which has an attribute to specify the name of the field map to be used.

2. Specify the field maps to be used.
   Each field map named in the <xwalkout:field-map-selection> elements above must be defined using an <xwalk:field-map> element (within the <xwalk:field-maps> element), with the name attribute set appropriately.
   

   

   
   Each repository field to be populated must be specified using a <xwalk:field-mapping> element, with the to attribute set to the underlying field name.
   The source of the data to be put into a repository field is defined using a <xwalk:field-source> element, with the from attribute set to the name of the field in the Elements.

   

   
   Additional attributes may be used to provide more information about how the data should be processed, e.g. format information.
   

   

   
   A wide variety of additional capabilities are available for specifying how to map individual fields.

3. Specify the destination collection to be used by the deposit.
   Edit the <xwalkout:collection-selector> element so that a <xwalk:when> element exists for each set of criteria used to identify a collection to be used when depositing from Elements (the criteria are defined using a <xwalk:condition> element). Within each of these a <xwalk:result> element should be defined, containing a single <xwalkout:collection-selection> element which has an attribute to specify the name of the collection to be used. If no collection is identified for an object, that object will not be deposited.

1. As always, it is strongly recommended that all testing occurs in a test or dev environment. We also recommend you back-up Elements before commencing testing.

2. When testing your crosswalks, it is recommended that the ‘Use verbose logging when harvesting’ setting for the repository is set on. This will instruct Elements to store a copy of each repository item before and after the crosswalk has been applied. This can be helpful when verifying behaviour. See Updating and Testing Crosswalks for details of downloading verbose log files.

1. The repository data source must be enabled via the repository’s Data Source Management page in Elements and ‘Allow deposit’ must be turned on for crosswalking to be performed.

2. Select your test publications in Elements and deposit to your repository via Elements. The outbound crosswalk is invoked by making a deposit to an RT2 repository. Immediately following the deposit Elements will fetch the newly deposited item from the repository as a new record in Elements (it is important that the inbound crosswalk has already been set up by this stage. See Repository Tools 2: Repository as Data Source).

3. Review the test publications in your repository. Make notes of any inaccuracies in the data transfer, using your list of required functionality as a reference point. You may then adjust your crosswalk and re-test as necessary.

For additional information about RT2 see:

• Repository Tools 2 - A Functional Overview

• Repository Tools 2 - Repository as Data Source

• Repository Tools 2 - Defining Crosswalks guide

• Repository Tools 2 - Updating and testing crosswalks