7. Using External Mapping Files

Owned by Julie Wetherill
Last updated: Oct 12, 2022
6 min read


Overview

Batch Builder can use external mapping files to:

  1. Associate Owner Supplied Names with existing files and new (to be built automatically by BB) objects (mapping.txt)
  2. Associate Aleph or Alma IDs with new (to be built automatically by BB) objects (mapping.txt)
  3. Determine page sequence numbers for PDS Document objects (mapping.txt)
  4. Associate Harvard Metadata Links (links to discovery systems) and Related Links (links to any system or website) with new objects or existing objects in a batch (mapping.txt)
  5. Associate Aleph or Alma IDs with existing objects (object_mapping.txt)
  6. Associate Owner Supplied Names with existing objects (object_mapping.txt)

Mapping files can be used in two ways:

  • To interact with files and objects during automatic object building from template.
  • To interact with files and objects during batch processing.

Batch Builder will display an INFO message in the message panel when any of the auxiliary input files are discovered, e.g.:

INFO - found mapping.txt in E:\Testing\ DRS_2.2\BatchBuilderProjects\StillImage-2-3-11_aux\batch1\ObjwJP2

Using mapping.txt File

Rules for using mapping.txt file

File name: mapping.txt
Function:
  • Objects that are built by BB automatically from template will inherit the following property values specified in this file: File Owner Supplied Name, PDS Document sequence number, Object Owner Supplied Name, Aleph or Alma ID, Harvard Metadata Links, Related Links.
  • Objects that are created manually will inherit the following property values specified in this file: File Owner Supplied Name, PDS Document sequence number, Harvard Metadata Links, Related Links.
Placement:
  • For use during automatic object building, place the file in the {project_dir}/_aux/template/ directory. When used with the automatic object building function the file will be automatically copied to {project_dir}/_aux/{batch_name}/{object_name}/ for each object created.
  • For use during manual object building, place the file in the {project_dir}/_aux/{batch_name}/{object_name}/ directory
Syntax: 
relative_file_path,file_OwnerSuppliedName,PDS_sequence number(optional),object_OwnerSuppliedName(optional),
Aleph or Alma Number(optional),Harvard_metadata_identifier_type|metadata_identifier|Harvard_metadata_label,
relatedlink_relationship_type|relationship_uri
Note for Related Links and Harvard Metadata Links:

Harvard metadata links can be repeatable, in which case multiple links are separated by a double pipe character ‘||’:

Harvard_metadata_identifier_type|metadata_identifier|Harvard_metadata_label||Harvard_metadata_identifier_type|metadata_identifier|
Harvard_metadata_label

The LinkType value for harvardMetadataLinks comes from a controlled list. The following are valid link types (case sensitive):

  • Aleph
  • Alma
  • Finding Aid
  • Gale
  • HLSL
  • HULPR
  • Local
  • OCLC
  • RLIN
  • URI
  • DASH
  • Shared Shelf

Related links can also be repeatable, in which case multiple links are separated by a double pipe character ‘||’:

relatedlink_relationship_type|relationship_uri||relatedlink_relationship_type|relationship_uri

There should be no spaces between a comma “,” and the next character. If an optional element value is skipped it still needs to be designated by a comma “,” so Batch Builder can associate the right value with the right element. Harvard metadata links and related links only need to be specified once per object. Once they are specified once, they can be omitted for other files in the object (no need to mark their absence with commas in that case).

Examples:

Example 1:

image_arch\DDC003144.tif,DDC003144,,obj_DDC003144,524391,Aleph|524391|Label||
Finding Aid| hou02239|Label,Google|http://www.google.com||Gale|http://www.gale.com
image_arch\image-del\DDC003144.tif,DDC003144,,obj_DDC003144,524391

In this example, there is a skipped PDS sequence number indicated by two commas. There are two values for Harvard metadata links and two values for related links.

Note that Harvard metadata links and related links only need to be specified once per object. If the object has more than one file, Harvard metadata links and related links can be specified for any file in the object and they will end up as properties for the object. In the line that specifies properties for the deliverable file, no related links and Harvard metadata links need to be specified because they were already specified for the archival master file in the object.

Example 2:

image-arch\DDC003144.tif,DDC003144,,obj_DDC003144,524391,,Google|http://www.google.com
image-arch\image_del\DDC003144_dynmc.jp2,DDC003144,,DDC003144,524391

In this example, there is a skipped PDS sequence and a skipped Harvard metadata link value. Both missing values are indicated by two commas. The related link value is specified only for the first file in the object.

Example 3:

image_arch-master\379129.tif,ac1234,1,PDSObj1,,, 
image_arch-master\379130.tif,ac1234,2,PDSObj1,,,

In this example, there is a PDS sequence number for the each file and the Aleph/Alma ID, the DRS Metadata link and the related link values are skipped.

Parameters in detail:
  • Relative file path: the relative path to the file (including the file name and extension), from either the _aux/{batch}/{object}, or _aux/template directory. This is the file that the next 3 parameters will be applied to. Use the POSIX (UNIX style) path when on Mac or Linux and Windows style path when on Windows.
  • File Owner Supplied Name: (Required) - The file owner supplied name
  • Sequence number: (Optional) - Alternate method to providing the sequence number as part of the file name pattern. This controls in which order page images and text appear in PDS Document objects when they are displayed in PDS.
  • Object Owner Supplied Name: (Optional) - When the object Owner Supplied Name is not provided as part of the file name pattern, then this property can be used to control which files are added to which objects when building objects from the template. This parameter is ignored when the mapping.txt file is placed directly into _aux/{batch}/{object}/ directory for a manually created object.

  • Aleph/Alma ID (Optional) - Aleph or Alma ID of the HOLLIS record where the object is described. Batch Builder imports MODS descriptive metadata from the HOLLIS record specified and places it into the object descriptor during batch processing.

    Note that Batch Builder supports multiple methods of receiving MODS descriptive metadata. These include supplying a custom MODS file, entering descriptive metadata directly in the graphical user interface and supplying an Aleph or Alma ID to import MODS from HOLLIS. Only one method at a time can be used. For instance, if you are supplying a custom MODS file you cannot provide Aleph or Alma ID to import MODS from HOLLIS.
     

  • Harvard metadata links (Optional) – link to a record in one of the discovery systems specified on the controlled list and a required label. Use the controlled list of discovery systems to specify what system is the link to: Aleph, Alma, Finding Aid, Gale, HULPR, Local, OCLC, RLIN. Currently, actionable links to HOLLIS and OASIS are created automatically when the record identifier for these systems is supplied. For OASIS use ‘Finding Aid’.
  •  Related links (Optional) – link to any discovery system or website. Full URL needs to be provided in order for the link to be actionable.

Procedure for creating and placing a mapping file

Create the mapping file:

  1. Create a text file called "mapping.txt". If your batch contains multiple objects, file mappings for all objects can go in this one file.
  2. Add a line of mapping values for every file to be mapped, using the syntax:
    relative_file_path,file_OSN,PDS_sequence_number(optional),object_OSN(optional),Aleph/Alma ID (optional),Harvard_metadata_identifier_type|metadata_identifier(optional),relatedlink_relationship_type|relationship_uri(optional)

    Example: 

    image_arch\DDC003144.tif,DDC003144,,obj_DDC003144,524391,Aleph|524391|Label||Finding Aid|hou02239|Label,Google|http://www.google.com||Gale|http://www.gale.com
    image_arch\image-del\DDC003144.tif,DDC003144,,obj_DDC003144,524391
     

  3. Save the mapping.txt file.

Add the mapping file to the batch:

  1. If using the manual object workflow:
    1. Create the batch with objects (Step 5 in the batch procedure). This will generate batch directory structure on disk.
    2. Copy mapping.txt into the object directory inside the BB project's auxiliary (_aux) path:
      {project_dir}/_aux/{batch_name}/{object_name}/
      If you have file mappings for multiple objects in a batch, place a copy of the same file into each corresponding object directory inside the BB project's auxiliary (_aux) path.
    3. Continue with your batch procedure.

  2. If using the automatic object workflow:
    1. Add directories to the template and copy content files into those directories (Steps 4-5 in the batch procedure).
    2. Place mapping.txt into the template directory in the BB project's auxiliary (_aux) path:
      {project_dir}/_aux/template/
    3. Continue with your batch procedure.

  3. When BB processes the batch, an INFO message displays in the message panel when the mapping file is discovered, for example:

    INFO - found mapping.txt in C:\drs2-beta2-training-BB\BB2-projects-2.0.19o\image-project_aux\batch-brueghel-skaters-3\object-skaters-3

Use object_mapping.txt File

File Name: object_mapping.txt
Function:

  • The objects contained in the batches processed by Batch Builder will inherit the property values (such as Aleph or Alma IDs and object owner supplied names) specified in the file (note that this file is not used for automatic object building). This file is accessed by Batch Builder during batch processing (generating the batch/xml file and the descriptor).

Placement:

  • There is one object_mapping.txt file per project. It needs to be placed in {project_dir}/_aux/template/ directory. It is read in once when the project is opened. If you created and placed the file while BB was open, you will need to restart BB so that the file can be accessed during batch processing.

Syntax: object_directory_name,ALEPH/Alma_number,Object_Owner_Supplied_Name

  • Object directory name: (Required) - The name of the directory in which object is contained. E.g.: birdsofasia
  • Aleph/Alma id: (Optional) - Aleph or Alma ID of the HOLLIS record where the object is described. Batch Builder imports MODS descriptive metadata from the HOLLIS record specified and places it into the object descriptor during batch processing.
  • Note that there are multiple methods of passing a MODS descriptive metadata file to Batch Builder. Only one method at a time can be used.
  • Object Owner Supplied Name: (Optional) - This property can be used to override the object Owner Supplied Name that is normally derived from object directory name. It will be applied to the object specified by in the object directory name property.

Example 1 (specifying object directory name and Aleph/Alma ID):

birdsofasia,005111819,
brighambulletin,90086637850203941,

The extra comma at the end represents the blank value for object owner supplied name. It is required even if object owner supplied name is not specified.

Example 2 (specifying object directory name, Aleph or Alma ID and object owner supplied name):

birdsofasia,005111819,BA_2348
brighambulletin,90086637850203941,BA_35559

In this example all three values are specified. 

Example 3 (specifying object directory name and object owner supplied name):

birdsofasia,,BA_2348
brighambulletin,,BA_35559

The extra comma in the middle represents the blank value of the Aleph/Alma ID for the object. Even if Aleph/Alma ID is not specified the comma delimited is required.

On this page: