Skip to end of metadata
Go to start of metadata

On this page:

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

  • Note: 32 bit operating systems and 32 bit Java JVM are no longer supported
  • Operating System: 64 bit Windows 7/8/10; 64 bit Mac OS X 10.7 or higher; 64 bit Linux Red Hat, CentOS, Ubuntu.
  • Processing Power: Intel Core i3/i5/i7; AMD FX, Athlon, A series
  • Physical Memory: 8 GB RAM or higher
  • Java SE Development Kit 64 bit version 1.8.

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, it has been reported that the Unarchiver (https://theunarchiver.com/) unzipping tool is having issues on OSX Sierra and unzips a faulty package. Use Mac native Archive Utility or Keka (http://www.kekaosx.com/en/) instead to unzip the Batch Builder package on Mac.
  6. To start the GUI, double click the executable file in the batchbuilder-2.x directory:
    • On Windows use BatchBuilder.exe.
    • On Mac use BatchBuilder.command (note that it is normal to see Terminal window when Batch Builder starts up on Mac)
    • On Linux use batchbuildergui.sh

A message "Open File – Security Warning" may appear. If so, click on "Run" to continue.

Note for Harvard PC users: On most Harvard PC computers there is a security software called Parity which blocks “unapproved” applications from running. Some users’ configurations allow them to “unblock” the application and allow it to run. Other configurations don’t allow the “unblock” feature. If you see a Parity prompt when trying to run Batch Builder and Parity won’t allow you to unblock Batch Builder, call your HUIT field support and ask them to unblock it for you. Additionally, if you don't have local admin access to your desktop, you need to ask your IT support contact to grant you local read/write access to the whole Batch Builder directory as Batch Builder needs to write to log files when it is running.

Note for Mac users: on the Mac, the first time you run Batch Builder you will need to press and hold the Control key, and then click the Batch Builder icon. Then click on Open from the shortcut menu. This will save the application as an exception to Mac security settings (which by default only allow registered apps from Mac app store to run). Next time you need to run Batch Builder, simply double click on the Batch Builder icon.  

For Harvard Mac users: If you don't have local admin access to your desktop, you need to ask your IT support contact to grant you read/write access to the whole Batch Builder directory as Batch Builder needs to write to log files when it is running.

If you can't start BB using the executable, try the following alternative:

    • On Windows: double click on the file batchbuildergui.bat. A command prompt window will open and then BB Graphical User Interface will start up.
    • On Mac or Linux: open terminal, change directory to the BB home directory and type: sh batchbuildergui.sh and then press Enter. BB Graphical User Interface will start up.
  1. 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

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. (Selected 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.

          Note: this option must be selected when generating PDF Document objects as well as Opaque objects.

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

  • No labels