A command line interface plugin for exporting data from the Archivists' Toolkit
Java
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/org/archiviststoolkit/plugin/cli
.gitignore
CLIExportPlugin.zip
README.textile
makep
plugin.xml

README.textile

CLI Export Plugin for Archivists’ Toolkit

This plugin stemmed from a need to periodically export resources from AT without user interaction. Originally I modified the AT source directly to support this but the core developers were very helpful, responsive and added command line support for plugins.

Plugin features

  • export of resources in EAD and/or MARC format
  • individual file per resource
  • many options to limit scope of resources to export

Requirements

  • Archivists’ Toolkit version 2.0.6 or greater
  • ensure that database settings have been saved through the GUI client

Compilation and set up

Install an appropriate version of the Archivists’ Toolkit. You will need to ensure that all the jar files under the /lib directory of the AT installation directory are a part of the Java class path when compiling this plugin.

If you are using an IDE such as Eclipse you can download this plugins’ source and create a new Java Project referencing this source. Add external libraries and select the jar files from AT. Eclipse should create the CLIExportPlugin.class file under bin/org/archiviststoolkit/plugin/cli

If you are using a POSIX compatible OS you should be able to run makep to package the class file into an appropriate plugin format for AT. You can place the generated zip file under the plugins/ directory of the AT installation.

You can view the Support and For Developers section of the AT website http://archiviststoolkit.org/ for detailed information on plugins.

A precompiled and package version of the plugin is included, CLIExportPlugin.zip. This should work but if you encounter problems try compiling from source.

Note: This has only been tested under OS X

Usage

Once the plugin is installed you can execute atcli.command with appropriate parameters from the AT installation directory.

This plugin requires 3 parameters

  1. DATABASE PASSWORD
  2. a task name (export)
  3. a location for the export files (must include an ending /)
  4. type of export (-ead and or -marc)
  5. options

Example:

atcli.command mydatabasepassword export ~/path/for/exported/files/ -fas Completed -ead -marc

Each exported resource will be named according to the resources id, the type of export and have an xml extension (ex. 0190-EAD.xml).

A file named resourceIndex.txt will be generated for every resource (including one not being exported) with fields for resourceIdentifier, getFindingAidStatus, title and lastUpdated.

Options

When converting a resource to a file the following four options are disabled by default but can be enabled by using the corresponding switch:

Suppress Internal Only (suppresses components and notes when marked “internal only”)
-suppressInternalOnly

Include DAOS (not supported for MARC export)
-includeDaos

Numbered Components (number component levels, not supported for MARC export)
-numberedComponents

Use DOID as HREF (not supported for MARC export)
-useDOIDAsHREF

The following options pertain to filtering when selecting resources.

Currently the only well tested option is for finding aid status.

Options are additive; a record must meet the requirements of all options in order to be exported.

Each option has a tag and sometimes parameters which are invoked as follows: -tag param1 param2 param3

Finding Aid Status
tag: -fas
params: match any of the passed params

Author
tag: -author
params: match any of the passed params

EAD finding aid unqiue identifier
tag: -eadfauid
params: match any of the passed params

Resource identifier
tag: -rid
params: match any of the passed params

Resource identifier 1
tag: -rid1
params: match any of the passed params

Resource identifier 2
tag: -rid2
params: match any of the passed params

Resource identifier 3
tag: -rid3
params: match any of the passed params

Resource identifier 4
tag: -rid4
params: match any of the passed params

Repository Name
tag: -rn
params: match any of the passed params

Internal only
tag: -io
params: none needed

Last Modified Date
tag -lmd
params: less than or greater than (LT | GT) and a date specified in the format dd-MM-yyyy, ex: -lmd GT 01-31-2007

Example with multiple options: atcli.command mydatabasepassword export ~/path/for/exported/files/ -ead -fas Completed InProcess -rid1 someid otherid eventhisid -io

This would exports resources with a finding aid status of Completed or InProcess AND resouce ID1 of someid or otherid or eventhisid AND Internal Only (true)

Note: params with multiple words can be enclosed in quotes, “firstname lastname” etc.

Possible Issues

If you encounter a problem exporting large resources due to out of memory errors (particularly due to heap space) you can pass memory settings to the jvm by editing the atcli.command file.

For OSX I had to add options="$options -Xms32m -Xmx512m" before the VM is launched (near the end of the file, line 1492 in my case). The sizes you set will be dependent on the size of your largest resource since AT constructs the object in memory before writing to a file.

License

I personally withhold no license to any of this code, however parts of this work may be a derivative of work from the Archivists’ Toolkit and may be subject to terms I am unaware of. This was developed while under the employ of the University of Southern California and there may be implications stemming from that which I am also unaware of.