Automatically build PDS objects from template

Owned by Julie Wetherill
Last updated: Jun 28, 2018 by Paul Aloisio
7 min read

 

Overview

This is a description of the procedure to automatically build a batch of PDS Document objects from template using Batch Builder 2 (BB). Use this method if you have more than two PDS Document objects in your batch.

Procedure summary:

  1. Create a new project.
  2. Enter DRS deposit settings.
  3. Create object template.
  4. Add directories to template.
  5. Move/copy files into template directory.
  6. Create an new object batch
  7. Process the batch.

What you need before you start:

  • Prepare a batch of page images and (optionally) accompanying machine readable text files and put them in a directory of your choice somewhere on local hard disk or network drive. If you have more than one file per page image (e.g.: an archival master and a deliverable or an archival master, a deliverable and a thumbnail) make sure file names match (e.g.: file1.tif, file1.jp2 and file1.jpg). The file names of text files should match the file names of the page images files as well (e.g.: file1.tif, file1.jp2 file1.jpg, file1.txt).
  • Make sure all the files names have appended PDS sequence numbers. The syntax used in BB2: [fileBaseName]_ [sequence_number].[extension]. E.g.: file1 1.jpg, file2 _2.jpg, etc. Alternatively, instead of supplying appended sequence numbers you can provide them via the external mapping file called mapping.txt. See Section 6. Using External Mapping Files for more information.
  • Decide what you will use for Owner Supplied Names (OSNs) for your object and the digital image files it consists of. For instance, you could use local classification or local accession numbers or an ALEPH or Alma ID.
  • Make sure that the object OSNs are supplied for each file by one of the following methods:
    • Append the object prefix to each file name (the syntax is [objprefix]--[fileBaseName]_ _[pageSeq].[ext]). Set the desired file name pattern objects in the BB Options dialog (see File name pattern options in the Installation and Setup section for more information).
    • Supply an external mapping file that maps each file to object (see Using mapping.txt File for more information).

Procedure:

Start at Step 5 if you are reusing a project to generate a new batch.

  1. Create new project in Batch Builder
    1. From main menu select Project > New.
    2. Enter project data:
      Project Name: enter a name for your project (used for internal tracking only).
      Project Directory: select the directory where project will be saved (click ellipsis button to browse for or create a directory). 
      Content Model: select the "PDS document" value from the dropdown.
    3. Click OK to continue.

  2. Enter DRS deposit settings:
    1. Click on "Deposit Settings" in Project Panel tree.
    2. Enter deposit data in the form:
      Batch Name Pattern: default - {owner}{batchDir}{yyyy}{mo}{dd}_{hh24}{mm}{ss}
      (This is the name for a batch that appears on DRS deposit reports. Batch name must be at least 3 characters long.)

      Success Email: type email and press enter. 
      Failure Email: type email and press enter. 
      Success Method: choose how you will receive load report. 
      Deposit Agent: type your HUID.
      Deposit Agent Email: type your official Harvard email address.

  3. Create object template:
    Note: Metadata added at this level will be applied to every object in a batch, unless overridden by specific object-level metadata that you define in later steps.
    1. Click on "Object Template" in Project Panel tree:
    2. Enter required object metadata in the form:

      Owner Code: your owner code (use all caps). 
      Billing Code: your billing code (use all caps). 
      File Access Flags: the DRS access flag for the files. At this level, select the least restrictive value if the batch will contain a mix of public and restricted files. 
      URN Authority Path: your NRS authority path. Use all caps. Look up your Path here if needed: http://nrs.harvard.edu/urn-3:hul.ois:nrsstatusprod. 
      File URN Resource Name Pattern: type “{n}” to generate a random unique number for IDS file delivery URN. Note that a value in this field is required even if you elect not to have Batch Builder generate IDS URNs for deliverable images. Hover over the field or see Metadata Reference for more values for this field.
      Object URN Resource Name Pattern: leave at default “{n}” to generate a random unique number for PDS object delivery URN. Type “{objectName}” to have the PDS object delivery URN derived from the object name. Hover over the field or see Metadata Reference for more values for this field.

    3. Enter optional admin and descriptive metadata to the object template. Click the "optional" tab.

      IDS URN for Deliverable JPG and JP2: Select "Yes" if you need IDS URNs for all deliverable images in the batch.

  4. Add directories to template:
    In automatic object workflow, you create role-based directories (archival master, deliverable) and in a later step, Batch Builder will create the objects for you.

    Image directories

    For one image file per page image:
    1. Add directory: right click on "Object Template" in Project Panel tree. The new directory name will start with "image" but you can append a custom suffix.
    2. Add metadata: click to select the new directory, then add metadata to the form:
      Required:
           First Generation in DRS: select "yes". 
           Usage Class: select "HIGHUSE".
      Optional: scroll down to "Still Image File Metadata":
           Role: use Ctrl Click to select ARCHIVAL_MASTER and DELIVERABLE roles. Note that in order to get a delivery URN on deposit a file needs to have a role DELIVERABLE set in BB.

    For multiple image files per page image (e.g., archival master, deliverable), you need to create a directory for the master file and a nested sub-directory for each derivative file.

    1. Add a master directory: right click on "Object Template" in Project Panel tree to create an "image" directory. In the text field, enter "-archival_master" or a similar suffix that describes the role.
    2. Add metadata for the master directory: click to select the new directory, then add required metadata to the form:

      Required: 
           First Generation in DRS: select "yes".
           Usage Class: select "LOWUSE".
      Optional: scroll down to "Still Image File Metadata":
           Role: select ARCHIVAL_MASTER.

    3. Add a nested directory for derivative: right click on the directory you just created and create another directory nested inside it (e.g., a directory for deliverable images). Add a suffix for this derivative (e.g., "-deliverable").
    4. Add metadata for this derivative subdirectory: click to select the new subdirectory, then add metadata to the form:

      Required:
           First Generation in DRS: select "no". 
           Usage Class: select "HIGHUSE".
      Optional: scroll down to "Still Image File Metadata":
           Role: select appropriate value for derivative (e.g., DELIVERABLE). Note that in order to get a delivery URN on deposit a file needs to have a role DELIVERABLE set in BB.

    5. Repeat previous steps to create additional nested directories if you have more files derived from the current one.
    6. Save your work (Project > Save on main menu).

  Text directories

    1. Right click on "Object Template" in the Project Panel to add a file directory. Enter the directory name in the dialog box. The directory name starts with "text" but you can append a custom suffix.
    2. In the Project Panel on the left select the directory you just created.
    3. In the Content Panel on the right choose "yes" from the dropdown list for the field "First Generation in DRS".
    4. Choose "HIGHUSE" for Usage Class.

   Layout directories (for Alto coordinates files)

    1. Right click on "Object Template" in the Project Panel to add a file directory. Enter the directory name in the dialog box. The directory name starts with "layout" but you can append a custom suffix.
    2. In the Project Panel on the left select the directory you just created.
    3. In the Content Panel on the right choose "yes" from the dropdown list for the field "First Generation in DRS".
    4. Choose "LOWUSE" for Usage Class.

     5.  Copy files into Batch Builder template directories on disk (can be done inside or outside of Batch Builder).

The directories you created in BB have been created on disk, in the project's template path:

{project_name}\template\

In order to tell BB which object each file should end up with you need to either add object name prefixes to each file name or supply a mapping.txt file that associates each file with its future object. See Section 3: Naming Rules for Objects for how to add an object name prefix. See Section 15.1: Using mapping.txt File for how to create a mapping file.

In the automatic workflow, files with the same role (archival master, deliverable, text, layout) are copied into the corresponding role-based directory. In a later step, Batch Builder will use the object name prefix for each file to create object directories and move files for each object into these directories.

Note: if you need to check where the directories are on disk, click on "Deposit Settings" in the Project Panel tree and look at the Project Path field at bottom.
** Quick way to copy content files: you can drag files from your file system onto the object template directories in the Batch Builder project panel.
** If using mapping.txt, this is when you should copy it to the auxiliary template path in the project.
** If including external MODS descriptive metadata, this is when you should copy it to the auxiliary template path in the project.

     6.  Create a new object batch.

You can create your new object batch in the Graphical User Interface or using the Command Line Interface (CLI).

In the Graphical User Interface

    1. From the Object menu in BB select "Create a new batch with objects from template"; enter the name of the batch directory to be created on disk and click OK. A new batch icon will be added to the Project Panel on the right (icon with a red letter B) and new objects will be built that are going to be part of this batch.
    2. In the Project Panel click on the "+" next to the Batch icon of the batch you just created to expand the tree – it will show the icons for the new objects (a blue letter O).
    3. (Optional) Select the object icon of your new object in the Project Panel and switch to "optional" tab in the Content Panel to enter any optional metadata that applies specifically to your object (for example descriptive metadata or Aleph/Alma ID, administrative categories, etc.). Note that any optional metadata that applies to all objects in the batch should be entered in the object template before your batch is created. For more about optional metadata see Sections 9. Adding Relationships, 10. Adding Descriptive Metadata, 11. Adding Supporting Content. Note that any metadata entered at the object level will override metadata entered at the template level.

     7.  Process the batch.

You can process your batch in the Graphical User Interface (GUI) or using the Command Line Interface (CLI).

In the Graphical User Interface

    1. In the Project Panel on the left right-click on the batch you want to process (batch icon with a red letter B) and select "Create descriptors and batch.xml."
    2. Builder will start processing the batch.
      When the batch is successfully processed you will see the following message: FINISHED - Creation of batch.xml and descriptors complete for batch: …

If you see any error messages, remedy the errors and re-process the batch.

On this page: