Jump to Content
September 22, 2014
 
 
 
 
 

Submitting EAD and Supplemental PDF Collection Guides

Institutions can contribute EAD collection guides (also known as finding aids) using our voroEAD system. voroEAD is also used to preview and publish collection guides in the OAC.

Institutions can also attach one or more supplemental PDFs -- comprising box lists, inventories, or legacy finding aids -- to an EAD collection guide. Any full-text embedded within the PDFs is indexed and searchable within the OAC. This is useful for cases where you have inventories that have not been encoded in EAD -- and are in other formats (print, MS Word) that could more easily be scanned or saved into PDF, in lieu of converting them to EAD.

Below are instructions for submitting collection guides. See also our brief screencast [MP4].

Obtain a voroEAD Account

Contact us at oacops@cdlib.org to request a voroEAD account, in order to submit collection guides for publication in the OAC. The account also provides administrative privileges such as access to your institution's collection usage and extent statistics. Contributing member institutions must request accounts on behalf of vendors providing EAD encoding and uploading services. Supply the following information in your request:

  • Name of each individual requesting the account
  • Complete contact information (phone, e-mail, etc.)
  • Institution name

Preparing Files for Submission

EAD files must conform to the OAC Best Practice Guidelines for EAD (OAC BPG EAD).

Any supplemental PDFs you attach to an EAD file will also be full-text searchable within the OAC—meaning they will appear in OAC search results when users hit on any words within. This only applies to PDFs that have “embedded text,” for example those that have been generated from Word documents or have been scanned using OCR. PDFs that will not be indexed are those that are simply images of the document. Not sure about your PDF? Open it in a PDF reader. If you can copy and paste text to another document, or conduct a search using CTRL + F, it should be indexed in OAC. Also, in order to ensure users have some context for the PDF, we suggest adding some preliminary information on the first page of the PDF. For example: a title for the inventory/box list/container list/etc.; the name of your repository; contact information for your repository, for reference questions.

Submitting EAD Files

1. You will need to configure your computer to connect to our server, using a WebDAV connection. Consult the WebDAV setup and troubleshooting page. Once you've completed this one-time setup process, you'll have WebDAV connections to two different EAD directories on our server (as described further below).

2. Upload EAD files from your workstation to your EAD directories on our server, using the WebDAV connection. You have two different voroEAD directories:

  • EAD Testing Directory: Use this directory to upload in-process EAD files. Use of this directory is optional.
  • EAD Production Directory: Use this directory to upload completed EAD files.

3. Once you've uploaded the EAD files to a directory, process them online using the voroEAD interface associated with the directory:

  • off site linkvoroEAD Testing Interface [password-protected]:
    • Use this interface to validate and preview in-process EAD files. A file must be present in this directory to be processed.
    • Select the file to process, using the interface. The system will validate the file against the EAD DTD (if submitting DTD-based files), or validate the file against the EAD XSD schema (if submitting schema-based files), and report any errors. Note that some browsers may not display the validation errors, resulting in a "The XML page cannot be displayed" message; if you receive this message, select "View->Source" from your browser menu.
    • If there are no errors, you will be able to preview the file in the OAC display.
    • Files should not be stored in this directory for long-term management purposes. Files left in this directory for more than three weeks may be removed.
  • off site linkvoroEAD Production Interface [password-protected]:
    • Use this interface to validate and publish completed EAD files. A file be present in this directory to be processed.
    • Select the file to process, using the interface. The system will validate the file against the EAD DTD (if submitting DTD-based files), or validate the file against the EAD XSD schema (if submitting schema-based files), and report any errors. Note that some browsers may not display the validation errors, resulting in a "The XML page cannot be displayed" message; if you receive this message, select "View->Source" from your browser menu.
    • If there are no errors, the file will be automatically queued for publication. Files are generally published the following day.

Submitting Supplemental PDF Files

1. You will need to configure your computer to connect to our server, using a WebDAV connection, through a one-time setup process. Consult the WebDAV setup and troubleshooting page.

2. Publish the EAD file (that is associated with the PDF files), following the Submitting EAD Files instructions above.

3. Upload the PDF files from your workstation to your PDF Production Directory on our server, using the WebDAV connection. The PDF files should be uploaded to the specific directory named after the EAD file, with which the PDF file(s) should be associated. Do not upload non-PDF file formats into the directory, or alter the directory (e.g., change the directory name, add subdirectories).

4. Next, update the EAD finding aid (that is associated with the PDF files) to include the outbound links to the PDF files. The following EAD encoding "template" can be used to build the link from the EAD file to supplemental PDFs, using the <otherfindaid> tag (within the top-level <archdesc> section) and a nested <extref> tag.

Within the <extref> HREF attribute: add a forward slash, followed by the exact name of the PDF file with the .pdf extension (e.g., "/ms104.pdf"). Note the specific use of the <extref> ROLE attribute, which must be set to "http://oac.cdlib.org/arcrole/supplemental". Within the <extref> tag itself, provide a descriptive title for the supplemental PDF file (e.g., "Business correspondence inventory").

<otherfindaid>
<head>Additional collection guides</head>
<list>
<item>
<extref href="/[PDF filename, with .pdf extension]" role="http://oac.cdlib.org/arcrole/supplemental">[Descriptive title for the PDF file]</extref>
</item>

[For any additional PDFs, use additional <item>s, with a nested <extref>]

</list>
</otherfindaid>

For schema-based finding aids, Xlink-specific attribute values need to be pre-pended with "xlink" to reference the Xlink namespace:

<extref xlink:href="/[PDF filename, with .pdf extension]" xlink:role="http://oac.cdlib.org/arcrole/supplemental">[Descriptive title for PDF file]
</extref>

In cases where finding aids are generated from the Archivists' Toolkit, in particular, the attribute values need to be pre-pended with "ns2":

<extref ns2:href="/[PDF filename, with .pdf extension]" ns2:role="http://oac.cdlib.org/arcrole/supplemental">[Descriptive title for PDF file]
</extref>

5. Re-publish the EAD file (that is associated with the PDF files), following the Submitting EAD Files instructions above.

Validation of Files

voroEAD validates every EAD file for conformance to the EAD DTD or schema. After submitting a file for processing, voroEAD will send an email to your e-mail account with the subject line "voroEAD: File Processed". The body of the email will contain a URL for accessing a detailed view of the processing results log. The log will contain a list of any encoding errors. Each log entry is linked to a specific line in the EAD file, where the error appears.

All collection guides should be valid EAD instances, and conform to the EAD DTD or schema, at minimum. Files rejected by voroEAD due to errors should be corrected and resubmitted. Files should meet the following minimum requirements:

  • Be well-formed XML.
  • Successfully validate against the EAD Version 2002 Document Type Definition or EAD 2002 Schema. The Schema is available in two syntaxes: Relax NG Schema (RNG) and W3C Schema (XSD).
  • Have a valid filename.
  • Contain a second <titleproper> with a type attribute set to "filing".
  • Contain valid attribute values in <eadheader> and <eadid>.
  • Contain ISO compliant scriptcode and langcode attributes in <language>.
  • Contain only one <unittitle> in the top-level <did>.
  • Have a valid attribute value in <archdesc>.
  • Have the top-level <unitdate>, within <did>, encoded outside of <unittitle>.
  • Contain valid repositorycode and countrycode attributes in the top-level <unitid>, within <did>.
  • If using the normal attributes in <data> or <unitdate>, they must be ISO 8601-compliant.
  • Not contain unnumbered (recursive) <c> in the <dsc>.
  • Not contain tabular markup (<drow>/<dentry>) in the <dsc>.

Consult the OAC BPG EAD for further guidance on correcting encoding errors.

Obtain Submitted Files

Your EAD Production Directory contains copies of your submitted EAD files. To obtain your files, simply access the directory and download copies of the files.

Removing Files from Publication

To remove an EAD or PDF file from the publication queue once successfully submitted, contact us and supply the file name for the collection guide. The file will be placed on an indefinite voroEAD Hold List to prevent it from entering the publication queue. If at any point you would like to publish the file again, resubmit a current version of the file through voroEAD -- using the same file name -- and notify us to release the file from the hold list.

Edit, Replace, and Rename Files

EAD and PDF collection guides should always be edited via a replacement process, using the same procedures for submitting new files.

To replace a file, ensure that the file name for the new collection guide matches the file name for the one to be replaced. Your collection guide file name serves as a unique identifier in our publication system: do not rename files when submitting replacements. (If you need to change the file names for collection guides that you've already submitted, contact us -- we will need to make the changes for you).

Last updated: June 04, 2014