1. Installation and Setup

Installing Batch Builder

Batch Builder (BB) is a Java-based application compatible with Windows, Mac and Linux operating systems.

The Batch Builder application package includes a Graphical User Interface (GUI) and a separate Command Line Interface (CLI) for automated deposit workflows. The application package is bundled as a zip file, which must be downloaded, unzipped, and installed on your computer.

Download the current Batch Builder client. 

System Requirements

• Operating System: 64 bit Windows 10, 11; 64 bit Mac OS X 10.7 or higher; 64 bit Linux Red Hat, CentOS, Ubuntu.
• Physical Memory: 8 GB RAM or higher
• Java OpenJDK 11: https://www.openlogic.com/openjdk-downloads
  
  • Batch Builder 2.2.21 and later runs on Java OpenJDK - it has not been tested on Oracle Java due to Oracle licensing restrictions.
  • For instructions on installing Java Open/JDK 11, see this Stack Overflow article.
  • Using the '.msi' version rather than the '.zip' is generally easier
  • See additional instructions if using Windows
• Python version 2.7 or 3.x (preferred)
  • Mac users, please see Installation Note for Mac Users for additional Python information

Installation

1. Download the Batch Builder zip archive. A Google Drive window entitled "BatchBuilder-2-current.zip" will display. 
2. Roll your cursor over the top menu bar and click the download icon.
   
3. At the "Google can't scan ..." message, click "Download anyway". 
4. When prompted, save the zip archive to your computer (e.g. a download directory or your desktop)
5. Unzip the archive and extract the files to a directory of your choice (e.g. Program Files or Applications). The installer will create a "batchbuilder-2.x" directory and copy the files to it
   • On Mac, use Mac native Archive Utility or Keka (http://www.kekaosx.com/en/) to unzip the Batch Builder package on Mac.
6. To start the GUI, double click the OS appropriate file in the batchbuilder-2.x directory:

• • On Windows use batchbuildergui.bat 
    
    • Note: it is normal to see a Windows Command window open when BatchBuiilder starts
  • On Mac use BatchBuilder.command
    
    • Note: it is normal to see Terminal window when Batch Builder starts up on Mac
  • On Linux use batchbuildergui.sh

If you are using BB v2.3.0 (the storage class-enabled version) and the BB executable won't start the client, see this Installation Note for Mac Users for a work-around. 

To start the Command Line Interface (CLI):

• • On Windows: run the command prompt (CMD), change directory to the BB home directory, type batchbuildercli with required parameters and press Enter. See Creating Batches Using Command Line Interface for examples of required parameters.
  • On Mac or Linux: run the Terminal, change directory to the BB home directory and type: sh batchbuildercli.sh with required parameters and press Enter.

Setting options

Pointing Batch Builder at a DRS instance

When first installed, Batch Builder is configured to work with the production instance of DRS. This instance configuration is controlled by settings in the \conf\bb.properties file in the BB installation directory. The Batch Builder \conf directory comes with separate copies of the bb.properties file that point at alternate DRS instances (a QA instance for staff testing and a Dev instance used only by LTS staff). This section describes how to repoint Batch Builder at another DRS instance (e.g., when staff need to test batch deposits in QA DRS). 

These are the properties files that come with the Batch Builder installation: 

bb.properties.dev	(points at dev instance)
bb.properties.qa	(points at qa instance)
bb.properties.prod	(points at prod instance)
bb.properties		(active bb.properties file; points at prod instance)

The properties file without extension -- bb.properties -- is the active configuration file and since it's pointed at production that is what Batch Builder will be pointed at when you first start it up. 

To point Batch Builder at the qa instance of DRS (for testing or training):
    - Rename bb.properties to bb.properties.orig
    - Rename bb.properties.qa to bb.properties
    - Then restart the BB client

To repoint Batch Builder back to production DRS, reverse the renaming steps: 

    - Rename bb.properties to bb.properties.qa
    - Rename bb.properties.orig to bb.properties (or you can delete the .orig version and rename bb.properties.prod to bb.properties)
    - Then restart the BB client

General Batch Builder options

There are a few Batch Builder features that are controlled by using View > Options on the file menu. These options will affect all projects.

Screenshot: Batch Builder Default Options

• Auto-increment new batch directory names. (Unselected by default.) When selected, if you create a batch directory name that ends with a number, the next time you click Batch->New … Batch Builder will use the same directory name but will increment the number to the next value.

• Ignore file validation errors. (Unelected by default.) When selected, this option forces Batch Builder to create a batch even when the FITS tool has detected errors in one or more files in the batch. Even if BatchBuilder is set to ignore the errors, DRS may reject the batch on ingest if there is an invalid file, such as an invalid JP2 image file.         

• Open last project on application startup. (Unselected by default.) When selected, on Batch Builder startup the most recently used project will open automatically.

• Verbose logging. (Selected by default.) This option is exposed specifically for testing purposes. Leave it checked during this testing phase so that LTS staff can troubleshoot Batch Builder processing errors.

• Delete object and directory contents when removing. (Unselected by default). If this option is checked, the object and directory contents are removed from disk when removed from within BB. This applies to Template directories as well. When this option is not selected, directories will remain on your local computer, but will disappear from the BB project window.

• Copy files when dragging and dropping onto project tree. (Selected by default). Batch Builder 2 introduces drag-and-drop functionality for files. If this option is checked, when files are dragged and dropped from a directory on disk onto a file directory in the BB Project Panel the files are copied rather than moved.

File name pattern options

Batch Builder allows users to set file name pattern options to be used when either automatically building objects from template or creating objects manually. Note that this option should not be used in conjunction with using external mapping files to supply file OSNs (an alternate method of supplying file OSNs). The following file name patterns can be set, and these will persist for each Batch Builder project.

Screenshot: file name pattern options

Derive File OSN from File Name (set by default) – this option, when set, results in Batch Builder using file name for the file owner supplied name according to one of the options checked below:

• Use full file name (minus the extension) as file OSN – results in full file name being used as OSN.

• • For all objects, except PDS Document objects this accomplishes the following:

• When building objects automatically – this option captures the full file name, including the object name prefix, as file OSN. (e.g.: obj1- -file1.jpg will result in file OSN “obj1- -file1”.)

• When building objects manually - this option captures the full supplied file name as file OSN. (e.g.: file1.jpg will result in file OSN "file1".)

• For PDS Document objects using the file name used as OSN option, this accomplishes the following :

• • • When building objects automatically – this option captures the full file name, including the object name prefix and the page sequence number, as file OSN. (e.g.: obj1- -file1_ _seq1.jpg will result in file OSN obj1- -file1_ _seq1. )

• • • When building objects manually - this option, when set, captures the full file name, including the page sequence number, as file OSN. (e.g: file1_ seq1.jpg will result in file OSN file1 _seq1.)

• Use baseName as file OSN – this option results in Batch Builder using file base name, excluding the object name prefix, as the file OSN. Don't use this option for PDS Objects if the file basename is the same for all the files and only the sequence number is different.

• • For all objects, except PDS Document objects, this accomplishes the following:

• • • When building objects automatically – this option captures the file base name, discarding the object name prefix, as file OSN. (e.g.: obj1- -file1.jpg will result in file OSN "file1". )

• • • When building objects manually this option captures the file base name as file OSN. (e.g: file1.jpg will results in file OSN "file1".)

• • For PDS Document objects

• • • Do not use.

• Use baseName_ _pageSeq as file OSN – this option results in Batch Builder using file base name and page sequence suffix – if present, but excluding the object name prefix, as the file OSN

• • For all objects, except PDS Document objects, this accomplishes the following:

• • • When building objects automatically – this option captures the file base name, discarding the object name prefix, as file OSN. (e.g.: obj1- -file1.jpg will result in file OSN "file1".)

• • • When building objects manually - this option captures the file base name as file OSN. (e.g: file1.jpg will results in file OSN "file1".)

• • For PDS Document objects

• • • When building objects automatically – this option captures the file base name and page sequence number as file OSN, discarding the object name prefix. (e.g.: obj1- -file1_ seq1.jpg will result in file OSN "file1 _seq1".)

• • • When building objects manually this option captures the file base name and the page sequence number as file OSN. (e.g.: file1_ seq1.jpg will result in file OSN "file1 _seq1".)

• Use only pageSeq as file OSN – this option only applies to PDS Document Objects

• • When building objects automatically – this option captures the page sequence number as file OSN, discarding the object name prefix and the file name. (e.g.: obj1- -file1_ _seq1.jpg will result in file OSN "seq1".)

• • When building objects manually this option captures the page sequence number as file OSN. (e.g: file1_ _seq1.jpg will result in file OSN "seq1".)

Setting options for processing large batches

When processing large batches – either from large file sizes or the sheer number of files – you may get "out of memory errors". The threshold is around 30GB. If you do get memory errors, you will need to make adjustments to BB configuration files to assign more memory to Java.

Note for Windows users: If you find that you need more than 3GB of RAM to run Batch Builder, you will also need to use a 64-bit version of Windows.

Assigning more memory to Java

1. In the main BB program directory use a text editor to open batchbuildergui.bat (Windows) or batchbuildergui.sh (Mac)
2. Find line starting with 'java –cp'
3. In that line, find the section '-Xmx1024m' and do one of the following:

• • To assign 2GB of RAM, change it to '-Xmx2048m' or '-Xmx2g'
  • To assign 3GB of RAM, change it to '-Xmx3072m' or '-Xmx3g'
  • To assign 4GB of RAM, change it to '-Xmx4096m' or '-Xmx4g'
  • etc...

    4.   Save the file

Use the smallest amount of RAM to get rid of the error to avoid performance problems with your local computer.

When you need to process a large batch, start Batch Builder using the batchbuildergui.bat or batchbuildergui.sh instead of the executable file.