Frequently Asked Questions

What is the Archivists' Toolkit?

The Archivists’ Toolkit™, or the AT, is the first open source archival data management system to provide broad, integrated support for the management of archives. It is intended for a wide range of archival repositories. The main goals of the AT are to support archival processing and production of access instruments, promote data standardization, promote efficiency, and lower training costs.

Currently, the application supports accessioning and describing archival materials; establishing names and subjects associated with archival materials, including the names of donors; managing locations for the materials; and exporting EAD finding aids, MARCXML records, and METS, MODS and Dublin Core records. Future functionality will be built to support repository user/resource use information, appraisal for archival materials, expressing and managing rights information, and interoperability with user authentication systems.

A single-page, double-sided informational sheet that provides an overview of the Archivists' Toolkit, including hardware and software requirements, is attached below.

The AT project is a collaboration of the University of California San Diego Libraries, the New York University Libraries and the Five Colleges, Inc. Libraries, and is generously funded by The Andrew W. Mellon Foundation.

If you are interested in identifying yourself and your repository to the larger AT community, please send us (info@archiviststoolkit.org) the name of your repository, the URL of the repository, and the name and contact information of the person best to contact with questions about your implementation of the AT.

Why should I use the AT?
  • It is open source. You can download the application for free and have access to the source code.
  • It is designed for archivists by archivists. All members of the AT team have a significant amount of experience working in libraries and archives across the United States. The team also strives to include community feedback into the design and functionality of the program as much as possible.
    It keeps your data in one place. Accessions information exists in the same database as descriptive information, and data re-use is prevalent throughout the application. Even donor information and location management is possible.
  • It makes authority control possible. The AT not only allows you to create authorized name and subject headings, thus reducing spelling and variant errors, but also enables you to see what materials in your repository are linked to those authorized headings.
  • It produces EAD with the click of a button. It also exports MARC XML, and METS, MODS, and DC records for digital objects. In addition, there are 32 different reports available within the application, each of which is customizable.
  • It is the ideal application for consortial environments. You can share your authority records with other repositories in your parent organization, thus providing data standardization at even higher levels.
  • The interface and workflow are highly customizable. Set up your own custom data entry screens, re-label the fields to your choosing and more.
Who's using the AT?

A list of self-identifying AT users can be found here. If you are interested in identifying yourself and your repository to the larger AT community, please send us (info@archiviststoolkit.org) the name of your repository, the URL of the repository, and the name and contact information of the person best to contact with questions about your implementation of the AT.

What are the system requirements for the AT?

System Requirements for the AT Client

PC:

  • Operating System: Windows 2000/XP/Vista
  • Java 6 JRE or JDK
  • CPU: Pentium 3, 500Mhz (recommend Pentium 4 2.4GHz+ or AMD 2400xp+)
  • System Memory (RAM): 128MB (recommend 512MB)
  • Hard Disk: 100MB free space
  • Screen: 1024x768

Mac:

  • Operating System: Mac OS X 10.3.9
  • Java 6 JRE or JDK
  • CPU: G3 500Mhz (recommend G4 1.2Ghz)
  • System Memory (RAM): 256MB (recommend 512MB)
  • Hard Disk: 100MB free space
  • Screen: 1024x768

Supported Database Backends:

  • MySQL 5.0 or 5.1 (with the InnoDB storage engine) NOTE: Only AT 2.0 update 11 and higher is compatible with MySQL 5.5
  • MS SQL Server 2005 (or higher)
  • Oracle 10g
How do I access the Sandbox?

We have provided a Sandbox so you can see the Toolkit interface without having to set up a backend database. Directions can be found here.

How do I create a good bug report?

In order for the AT team to fix bugs, it is essential that we be able to replicate them. This means that when you report bugs, it is critical that you include as much detail about the actions you completed prior to receiving a bug message. We realize that it may be difficult to remember those actions, and ask that once you receive a bug, to try and immediately replicate it and capture the actions upon replication.

Below is an example of a good bug report:

Resource index note item reference values unstable
Whenever index items are opened, their reference changes from the originally selected value to some other value. So if you set an index item to refer to an accruals note (ref7), close that index item and reopen it, the index item will no longer refer to an accruals note (ref7) but to some other note like the bibliography note (ref6).

The steps I went through were:
1. Open resource
2. Create an index note (add title and note)
3. Add an index item: item 1, corporate name, referencing accruals note (ref7)
4. OK
5. Add an index item: item 2, corporate name, referencing bioghist note (ref46)
5. OK
6. Close index note (OK)
7. Close resource record (OK)
8. Reopen resource record
9. Open index note. In this view the references are still correct (ref7 and ref46)
10. Open item 1. The reference is now to bibliography note (ref6)
11. I then closed and reopened several times, trying both cancel and OK, they both had the same result.
12. Reopening the item the reference changed to ref5, then ref106, then ref101.

If I cancel out of the whole resource record and do not save it, when I go back in the references are back to the values I originally set them to. But if the resource record is saved, the index values are incorrect.

In addition to including as much detail as possible in the bug report, it is also important to include your email address so that the team can contact you if we have further questions. We appreciate the extra effort it takes to create a good bug report; this effort reduces the amount of clarification needed by the AT team and helps us resolve bugs more quickly.

How do I transfer AT data from one installation to another?

The basic means for doing this consist of creating a backup of the data, and then using the data to create a new database in the desired location.

For MySQL:

  • Create a MySQL dump using:

    shell> mysqldump -u [username] -p[password] [database_name] > backup-file.sql

  • Load the SQL dump into a new (un-initialized) database:

    shell> mysql -u [username] -p[password] [database_name] < backup-file.sql

Refer to the MySQL Backup and Recovery Documentation for more information.

I transferred my data from a Windows instance to a Linux one and am receiving a "java.sql.SQLException: Table 'acaa.Constants' doesn't exist" error. What do I do?

In MySQL, the case sensitivity of the underlying operating system plays a part in the case sensitivity of database and table names. Details about this can be found at here. Windows is case insensitive, however all table names are forced to lower case. When a database is transferred, the lowercase table names are transferred to Linux which is case sensitive and causes connection to the AT to fail. The recommended solution is to do a search and replace on the sql file and change all references to the mixed case we use for our table names. We know that this is tedious and we are thinking about adding a utility that can do this as part of our Maintenance Program.

Help! I lost my password!

If you log on as a superuser, you can see all of the usernames and reset any password you do not know. If you do not know the username or password of any superuser then you can find it by looking at the actual Users table in the database (you would most likely need to use a MySQL GUI to do this- Navicat or MySQL Administrator). If you know the password for a non superuser then you can make that user a superuser through the MySQL GUI program by changing the user's permission level to 5.

If you do not know the username or password for any user, there is no way to access the data without using the source code and programing a way around the password requirement. For security purposes, passwords are not stored in the database.

I keep receiving a "Could not find a valid Java virtual machine to load" message, even though I chose the version bundled with the Java virtual machine.

Currently (July, 2009) there is a problem with the bundled version of the program. If you receive this message, please do the following: 1. Uninstall the AT 2. Download the latest version of Java: http://www.java.com/en/ 3. Re-install the AT, selecting the version that does not include Java

I am receiving a message stating that my AT version will not work with the database. What does this mean?

For the AT to function, both the client and the database need to be at the same version. If you are running an older client on a database that has been upgraded, you will need to upgrade your client by downloading and installing the appropriate version from the AT download page.

Contact your database administrator if your database needs to be upgraded. Database upgrades are performed using the Maintenance Program located in the Toolkit program files. Please see our detailed upgrade instructions.

I'm trying to set up the Archivists' Toolkit™, and I keep receiving a message about a problem with the database connection.

If the stacktrace (details) of the message you are receiving contains a line that reads: "java.sql.SQLException: Table '[whatYouNamedYourDatabase].constants' doesn't exist" then you have not initialized the database. To initialize the database in AT version 1.1, use the Maintenance Program. To initialize the database in AT version 1.0, use the AT Initialize Database program. Both of these programs can be found in the same directory as the AT program files.

Error when installing on Linux

When installing on some flavors of Linux the following error message can come up. "awk: error while loading shared libraries: libdl.so.2". An AT user has posted the fix for this on his blog.

Here is an edited version.

The problem is, when you try to open and fix the .bin file in a text editor such as vi, it somehow mangles the code.

To fix the program:

  • Backed up the installer to make sure that I didn’t have to re-download.
  • Installed GHex, the Gnome Hex editor. If you’re using SUSE, you can install it with Yast. If you’re using Fedora, you can probably install it with Yum.
  • Launch GHex, Click on File, then Open, and open the InstallArchivistsToolkit.bin install file.
  • Left click on the right panel (ie. the one with characters that make sense.)
  • Click on Edit, then replace.
  • Type export LD in the right panel of the find section and #xport LD in the right panel of the replace section.
  • Click on replace all.
  • Cancel out of the replace dialog and save the file.

You should be able to run the file now. However, if you have to make this modification, you will also have to modify more of the Archivists’ Toolkit™ files in the exact same manner. I had to enter my Archivists_Toolkit directory and change both the Archivists_Toolkit and the AT_Initialize_Database files as well in order to get the program to run correctly. If in doubt about any part of the program, run that part from the command line, and watch for the results. If it fails because of this error, you will see awk: error while loading shared libraries: libdl.so.2 when it fails. If you see that, you know you need to edit the file.

Why should I backup my database before upgrade?

It is essential to backup your database before upgrade. Should the upgrade process fail, the database will be corrupted and a backup is necessary to continue the upgrade process. In short, should the upgrade process fail and there is no backup, all of your data may be lost.

AT upgrades and support

The AT Maintenance Program bundled with the currently available AT 2.0 client application is designed to support upgrading an AT database from previous AT versions.

With the release of AT 2.0, the AT project team no longer works on new development, but does build maintenance releases when necessary. While the team will continue to support previous production versions of the AT, we encourage users to upgrade to the latest version, AT 2.0.14, and enjoy its improved functionality.

Please feel free to contact the AT team at info@archiviststoolkit.org if you have any questions or concerns.

Receiving initialization error using XAMPP distribution.

The XAMPP distribution does not ship with InnoDB tables enabled in MySQL. This is required for the AT. To solve this problem, edit c:\xampp\mysql\bin\my.cnf, commenting out the "skip-innodb" line and uncommenting the other innodb configuration lines. Then restart the MySQL service, and the installation should go smoothly.

How can I import legacy data into the Toolkit?

There are two types of legacy data that can be imported into the Toolkit: accessions data and description information. Accessions data can be imported by using a tab-delimited file or the XML schema included with the Toolkit program files. More information about both types of accessions data import can be found in the AT User Manual.

Descriptive data can be imported using valid EAD files or MARCXML. The AT development team may be able to assist with other types of data import, but there would be consulting costs associated with them. Please email info@archiviststoolkit.org for more information.

Can I use SQL commands to import legacy data into the database?

Importing data in any fashion other than through the Import menu is highly discouraged. Using SQL commands to populate the database is especially fraught with problems and support cannot be guaranteed if that import method is chosen.

The AT API may be used to import legacy data, however the API is in fairly rough form at the moment and this type of import has not been tested. The AT technical staff may be able to assist with import for a negotiated fee.

How do I use a new stylesheet with the AT?

First, locate the current stylesheets within the AT program directory. The file path will be something like: C:/Program Files /Archivists' Toolkit 2.0/Reports/Resources/eadToPDF

Both old and new stylesheets should have the exact same file name: at_eadToHTML.xsl and at_eadToPDF.xsl

Overwrite the old files with the new ones. It's not a bad idea to back up the default stylesheets, but these are included with the AT client so they can be retrieved by re-downloading the client, if necessary.

If the AT client is open, use the Reports drop-down option "Reload reports" to load the new stylesheets. This is located at the top title bar, in between the Setup and Help drop-down menus. This functionality is only available to high-level users. If you do not have the necessary access, you can close the AT and re-open it to reload the reports.

Test the new stylesheets by running finding aid reports.

When I try and import an EAD file I get a message saying the document failed to import and that "The system cannot find the file specified". What does this mean?

For EAD file conformant to the EAD DTD version 2002 (rather than the schema) the AT must be able to access the DTD.

The header of the EAD should include a doctype statement something like the following:

The last bit of text in quotations (above "ead.dtd") indicates where the AT should look for the DTD, this can be a url or file path. The example above indicates that the DTD is in the same folder as the EAD file. If the file is not in the location indicated you will be unable to import the file and get a message like this:

The document failed to import
C:\Documents and Settings\ahutt\Desktop\AT\AT Imports\ead\ead.dtd (The system cannot find the file specified)

If you are having problems with this, the easiest solution is to use the notation above ("ead.dtd") and place the DTD in the same folder as your EAD. The DTD can be accessed from the EAD web site. It is the first link in the list of files. Right click on the link and select "Save Link As…" to download.

I am unable to import my EAD file, what could the problem be?

Is the EAD valid? Import of EAD's which do not validate against the EAD 2002 DTD or Schema is not supported by the AT. You can check this using an xml editor, which will list any validation errors present.

Do you have any extremely long chunks of text? While many of the AT's fields accommodate large amounts of data (roughly 10,000 words) they do have a limit on space. Check to see if you have any notes or other elements which have very long values. You can test this by (temporarily) removing large chunks of text and then seeing if the EAD can be imported. If this is the source of the problem, you can try splitting long notes into parts so the text is spread across multiple fields.

Have you edited your EAD document in Microsoft word? Word can sometimes interject characters which aren't supported by standard XML processors. An example being smart or curly quotes, rather than straight quotes. If possible, it is best to use an XML editor for working with EAD files to avoid such problems.

Why can't I list bulk and inclusive date with finer granularity than just the year?

Sadly this is a pretty complicated issue. The heart of it is that the ISO 8601 date standard is not implemented in any programming languages or relational database (to my knowledge). Even xml schema does not support all of it. Date ranges specifically are not supported in schema. This is why if you look at the declaration in the ead schema for normalized dates that the date datatype is not used. Since the normalized dates can't be stored or manipulated in anything other that a string field we would have write a bunch of custom programming and datatypes to handle the full range of the ISO standard. This would be a considerable amount of programming and testing to make sure we handled everything correctly. Actually I keep hoping that someone else will do the work in java and publish it as open source. Without that we have decided to only support the granularity of a 4 digit year for the normalized version. This way we can store them as integers and get strict typing without having to write extra code. We can always revisit this in the future but my guess is that it will be hard for it to float to the top of the priority list.

Why does the program put 0's in front of my years dates when I type in something like 12/13/45? Why does the system allow more than four digits to be entered for the year?

This is actually the correct behavior. After the Y2K issue the general consensus is that for years you have to explicitly enter all of the digits for the year you want. In this case if you simply enter "45" you are referring to the year 45 AD. The reason that you can enter more digits is that these are legitimate dates. Granted they are way in the future, but since we do not limit what the fields are used for there could be a reason to enter a year that far in the future. For most dates in the AT we do not allow entry of dates in the future. For the user defined dates this is not enforced again because we do not know what they are going to be used for.

Why is it important to save my work frequently?

Saving your work frequently helps guarantee that it will indeed be saved. Just like with any other software application, unexpected events can occur- computer crashes, power outages, etc., which can cause a loss of data. If you are using the Toolkit in any type of networked installation, it is especially necessary to save your work often as network connections can timeout or otherwise be interrupted. If you leave your computer for a long time, it is likely that the connection will time out and your data will be lost. Likewise, if your computer goes to sleep and the network connections are cut off, you will lose your data. It is recommended that you save your work often and especially anytime you get pulled away from your desk.

Why do I receive an error when I try to merge two records?

The most common reason for this is that one or both of the records you are trying to merge are not valid. This can also occur when you try to merge lookup list terms that are linked to invalid records. Invalid records are missing particular fields that are necessary for proper AT functioning. Currently the only invalid records that can be imported into the Toolkit are Name and Resource records. The import of invalid Names will be prevented in future versions of the AT.

To correct invalid records, open the record and add the information necessary to make it valid. To determine which fields are needed, simply try and save the record by clicking on the "OK" button. You will receive a message listing the fields necessary to produce a valid record.

I set all of my fields in one list screen to have a return screen value of 0, and now I can't access my database.

To fix this issue, you need to set at least one return screen value to something other than 0. The directions for this through Navicat are as follows:

  1. Find out the tableId of the table in the DatabaseTables table that is causing problems.
  2. In the DatabaseFields table use the Filter Wizard to filter for that tableId. It will look something like this tableId is equal to 43
  3. Set the return screen order of one of the fields to something other than 0.
  4. The database should now work.

    5. Alternativly you can run the following sql command:

    UPDATE DatabaseFields,DatabaseTables
    SET DatabaseFields.returnScreenOrder = [new return screen order]
    where DatabaseFields.fieldName='[field name]' and DatabaseFields.tableId = DatabaseTables.tableId and ->DatabaseTables.tableName='[table name]'

Why can't I add to the Name Type lookup list? Why is Conference not included in the default list?

Name records in the Archivists’ ToolkitTM are designed to conform with the International Council on Archives’ ISAAR(CPF): International Standard Archival Authority Record for Corporate Bodies, Persons, and Families, 2nd ed. and to support the proposed standard Encoded Archival Context (EAC). Name records also accommodate creation of names according to rules established in standards such as AACR2 and DACS.

The ISAAR (CPF) standard stands behind not only the AT but EAD as well. In compliance with the EAD standard, conferences are considered to be corporate names.

We recognize that choosing the international standard of ISAAR (CPF) over the national standard of AACR/MARC will force some modification of MARC records in which a conference name is encoded as a corporate name. Hopefully, that will be not either a great number of records or a very timely modification.

I keep receiving a bug that states: "java.lang.OutOfMemoryError: Java heap space." What does this mean?

On a Macintosh:

  1. Right click on the AT application and select show contents
  2. In the contents folder open info.plist (this should launch the Property list editor)
  3. Open root -> java -> VMOptions
  4. Change -Xmx256M to either -Xmx512M or -Xmx1G depending on how much memory you want to allocate

On Windows XP (this should be the same for Vista)

  1. Open the Archivists Toolkit lax file in your favorite text editor
  2. Find the following line:

    lax.nl.java.option.java.heap.size.max=

  1. Change the value which is expressed in bytes

    256M = 268435456

    512M = 536870912

    1G = 1073741824

If this does not solve the memory problem, switch to a 64-bit Windows 7 machine using 64-bit JRE (the version that is bundled with the Archivists' Toolkit is 32-bit) which has at least 6GB of memory and change settings to something like:
4GB = 4294967296

My screen is not re-painting correctly. The buttons at the bottom run together and the record information does not change when I select a different node within the collection hierarchy.

This type of behavior is common if you are running a Macintosh system using Java 1.6. The next Java for Mac update will hopefully fix the problem. If you are not running a Macintosh please inform the AT team at info@archiviststoolkit.org.

Why am I unable to batch export Digital Object records?

If there is a line break, or carriage return, after the value in the "Digital Object ID" field (formerly the METS ID field) the record can't be batch exported. The line break conflicts with the process for naming files generated from a batch export.

Removal of the line break will remedy the problem.

[This only applies to AT versions 2.0 and later since batch export of digital objects was not supported in previous versions.]