Submitting Requests via EAD Finding Aids

Overview

Aeon supports automated requesting from archival finding aids that have been encoded according to the EAD (Encoded Archival Description) XML standard (see http://www.loc.gov/ead/).

Aeon provides features for grouping individual item requests into parent containers or series to facilitate retrievals, and for defining how various EAD elements are mapped to fields in the Aeon transactions table.

In order to take advantage of Aeon's EAD grouping and mapping features, the EAD/XML data must be transformed into a format that can be processed by the Aeon DLL. This transformation can be performed internally by Aeon or externally by other applications.

With the internal method, the site needs to provide Aeon with a network file pathway to the native EAD/XML file during the request process so that the Aeon DLL can retrieve and transform the file using its own XSLT stylesheet once the patron logs into his account. The patron is then presented with a web form which allows him to select the items he wishes to view and to submit his request.

With the external method, the site presents the patron with a version of the finding aid that already incorporates all of the required transformations prior to patron login, thus making the availability of automated requesting more immediately obvious and possibly more expedient for patrons.

Further details on both methods follow below. Your Aeon Customer Service Agent will help you determine which method is more appropriate for your site and will provide implementation assistance in accordance with the method you choose.

Internal Method

To take advantage of Aeon's internal EAD/XML transform capabilities, the site needs only to configure a link from its finding aid display to its Aeon web server.

The link can be placed either in the finding aid itself or in the finding aid database interface. Either way, the critical piece of information that the link needs to contain is a network file pathway to the native EAD/XML file.

If the link is to be placed in the finding aid itself, it can be added programmatically through whatever process is used to generate the display version of the finding aid. The link can be placed prominently at the top of the guide, repeated in a page header or footer, or added in some other location.

Alternatively, the link may be placed in the finding aid database interface. In the typical finding aid interface that uses HTML frames to present the patron with navigational options in the left-hand frame and the finding aid display in the right-hand frame, the link can be conveniently placed in the navigational frame. The link will need to include a variable that a javascript or another type of programming script can replace dynamically with the network file pathway of the finding aid display in the right-hand frame. The link can also be scripted as a button.

Regardless of where it is placed or how it is scripted, the URL that points to the site's Aeon web server should be constructed as follows:

http:///aeon/aeon.dll?Action=10&Form=31&Value=

The network file pathway (<pathway_to_ead.xml>) is generally expressed using HTTP, but it can also be a file pathway relative to the Aeon web server's local network or a filename that an intermediary script then resolves into a full pathway in order to enable Aeon to retrieve the required EAD/XML file. We recommend that the URL be URL encoded to ensure it works with all browsers since characters such as colons and slashes can still cause problems for some browsers that don't handle those automatically (see http://www.w3schools.com/TAGS/ref_urlencode.asp and http://en.wikipedia.org/wiki/Percent-encoding for further information.

Clicking on a request link formatted in the above manner will take the patron to the Aeon logon page or directly to the patron's account if he is already logged in. Once the patron is logged in, the Aeon DLL loads the EADRequest.html form (i.e., form "31" in the above URL), which includes a tag (<#PARAM name="EADRequests">) that prompts the DLL to execute the retrieval of the EAD/XML file using the network file pathway transmitted by the URL. The Aeon DLL then applies the aeon.xslt stylesheet to the EAD/XML file in order to render the finding aid for display in the context of the patron's account. In rendering the display, the EADRequest.html also applies the EADrequest.js javascript code it references in order to submit only items whose checkbox has been selected, which greatly increases the efficiency of submitting records from potentially very large EAD files.

In some cases, it may be necessary to modify the aeon.xslt stylesheet in order to accommodate variations in local EAD/XML encoding practices or to achieve desired formatting characteristics. In general, Atlas Systems will perform these modifications as part of its standard implementation and support services, though we cannot guarantee that we will be able to accommodate every type of encoding variation or desired formatting.

If you would like to explore this method of implementing EAD requesting, your Customer Service Agent will ask you to send a sampling of your EAD/XML encoded finding aids to determine whether modifications to the aeon.xslt stylesheet need to be made to achieve the desired transformations or whether any local encoding practices may limit the effectiveness of this method.

Configuring Document Type Definition Processing via the EADProhibitDTD Customization Key

Some EAD/XML encoded finding aids may use a document type definition (DTD) at the top of the file that links to an ead.dtd definition detailing the valid format for EAD XML. When included, this line of code will generally follow the format below:

<!DOCTYPE ead PUBLIC "+//ISBN 1-931666-00-8//DTD ead.dtd (Encoded Archival Description (EAD) Version 2002)//EN" "ead.dtd">

Before Aeon 6.0, DTDs were always expanded during Aeon's internal EAD processing method to support this feature. As of Aeon 6.0, the expansion and processing of DTDs can be prohibited for an additional layer of enhanced security against potentially untrusted XML files via the EADProhibitDTD customization key in the Aeon Customization Manager (located under Web Interface | EAD). When this key is set to Yes, the Aeon DLL will not process an EAD XML with an EAD DTD included and will log the following error-level messages when the processing of such an XML file is prevented:

Error loading EAD
DTD is prohibited.

External Method

With the external method, all the transformations that would be performed by the aeon.xslt stylesheet and EADRequest.js using Aeon's internal method must instead be performed by applications or stylesheets created by the site and applied to its finding aids before patrons are prompted to log into their accounts to submit their requests.

Several sites have accomplished this transform process using a variety of methods. There is no single method that your Customer Service Agent can recommend or can guide you in implementing as the requirements will depend on the characteristics of your local finding aid delivery system.

To use an external method to apply request checkboxes to their finding aids should be prepared to commit sufficient local IT resources to deconstruct the logic and output of the aeon.xslt to achieve the data mapping and HTML rendering the Aeon DLL requires in order to process requests appropriately. They should also review the following documentation sections, which explain how the DLL processes simultaneous requests for multiple selections, including the options it supports for automatically grouping item-level requests into requests for the containers in which they are kept in order to facilitate retrieval.

HTML Request Checkbox Options

The aeon.xslt stylesheet is configured to display HTML request checkboxes in conjunction with EAD container or component elements.

Most commonly, they are placed beside parent container elements, but they may also be positioned next to child elements, which is to say individual items within containers. For example, the sample EAD snippet:

<dsc type="in-depth">
<c01 level="series"><did>[...]</did>
    <c02>
        <did>
            <container type="box">3</container>
            <container type="folder">18</container>
            <unittitle>Parent-Teacher Association of Fondsville
                <unitdate type="inclusive">1959-1972</unitdate>
            </unittitle>
        </did>
    </c02>
    <c02>
        <did>
            <container type="box">3</container>
            <container type="folder">19</container>
            <unittitle>Pasta and Politics Club
                <unitdate type="inclusive">1967-1975</unitdate>
            </unittitle>
        </did>
    </c02>
    [other possible elements and text... ]
</c01>
    [other possible elements and text... ]
</dsc>

Could be rendered as either (Option 1):

[  ] Box 3

Parent-Teacher Association of Fondsville, 1959-1972 [Box 3; Folder 18]

Pasta and Politics Club 1967-1975 [Box 3; Folder 19]

Or (Option 2):

[  ] Box 3

[ ]  Parent-Teacher Association of Fondsville, 1959-1972 [Box 3; Folder 18]

[ ]  Pasta and Politics Club 1967-1975 [Box 3; Folder 19]

The Option 1 display above is the default configuration for the default aeon.xslt stylesheet. If you would prefer the Option 2 display, please contact your Customer Service Agent, who will provide you with an alternate aeon.xslt sytlesheet based on your specific EAD encoding practices.

In addition to these two display options, it is also possible to configure the stylesheet to position HTML request checkboxes in conjunction with EAD component tags instead of container tags, a potentially useful alternative especially if your finding aids do include container elements. To pursue this third option, please contact your Customer Service Agent, who will provide you with an alternate aeon.xslt sytlesheet based on your specific EAD encoding practices.

Please understand, however, that it may not be possible for Atlas to modify or create an aeon.xslt stylesheet that can accommodate all varieties of local EAD encoding practices, especially those that depart substantially from accepted best practices.

How EAD Requests are Grouped

The GroupRequestsByLocation Key

In order to group requests, you must set the GroupRequestsByLocation key to Yes.

When EAD requests are submitted, this key controls whether items that share a container are grouped into a single request.

If the key is set to No, then each selected item is treated as an individual request even if it shares a container with another item.

Determining the Grouping Identifier

By default, when an EAD request is submitted to the Aeon DLL, the Sublocation field is used to determine the grouping of individual items.

The EAD request system allows administrators the option of defining another field as a grouping identifier rather than always using the Sublocation field.

The grouping identifier can be an Aeon transaction field or a non-Aeon field used solely for grouping.

Requests grouped by Aeon transaction fields store the results of the grouping in the transaction, while requests grouped by other fields do not.

By default, if no grouping identifier field is used, the DLL will group using the Sublocation field. This maintains backward compatibility with earlier versions of Aeon (before 3.1).

Using a Field Other Than Sublocation as a Grouping Identifier

Changes to Make to the Aeon.xslt File

To group requests using a field other than the Sublocation field as a grouping identifier, including request specific fields and non-Aeon transaction fields, you will need to make two changes to the Aeon.xslt file:

1. Add a new FormDataField element, output as a hidden input element. The element should contain the following parameters:

• Id: GroupingIdentifier
• Name: FormDataField
• Value: Either an Aeon Transaction field or a non-Aeon Transaction field. The value defines what field the DLL looks for when attempting to group the requests.

Aeon Specific Field

<xsl:element name="input">
    <xsl:attribute name="type">hidden</xsl:attribute>
    <xsl:attribute name="id">GroupingIdentifier</xsl:attribute>
    <xsl:attribute name="name">FormDataField</xsl:attribute>
    <xsl:attribute name="value">ItemVolume</xsl:attribute>
</xsl:element>

Non-Aeon Specific Field

This example uses a non-Aeon Transaction field called GroupingField.

<xsl:element name="input">
    <xsl:attribute name="type">hidden</xsl:attribute>
    <xsl:attribute name="id">GroupingIdentifier</xsl:attribute>
    <xsl:attribute name="name">FormDataField</xsl:attribute>
    <xsl:attribute name="value">GroupingField</xls:attribute>
</xsl:element>

2. The second change involves how we are outputting EAD requests, specifically, adding a hidden input element that uses the field name as the prefix in the ID field followed by the currentID.  This is only necessary if you are grouping by a new field that is not already being output as part of the request. For example:

Aeon Specific Field

<!-- Output the item volume for the request -->
<!-- This example presumes you have a volume field in your EAD -->
<xsl:element name="input">
    <xsl:attribute name="type">hidden</xsl:attribute>
    <xsl:attribute name="id">ItemVolume_<xsl:value-of select="$itemID"/></xsl:attribute>
    <xsl:attribute name="name"><xsl:value-of select="$itemID"/></xsl:attribute>
    <xsl:attribute name="value"><xsl:value-of select="did/volume"/></xsl:attribute>
</xsl:element>

Non-Aeon Specific Field

<!-- Output the value typically written to SubLocation to GroupingField instead, so that it won't be saved in the transaction -->
<xsl:if test="$itemNode/did/container[@type != '']">
    <xsl:element name="input">
        <xsl:attribute name="type">hidden</xsl:attribute>
        <xsl:attribute name="id">GroupingField_<xsl:value-of select="$itemID"/></xsl:attribute>
        <xsl:attribute name="name"><xsl:value-of select="$itemID"/></xsl:attribute>
        <xsl:attribute name="value"><xsl:value-of select="translate($itemLocation, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')"/></xsl:attribute>
    </xsl:element>
</xsl:if>

In this case, we have the GroupingField field value set to a programatically defined string that identifies essentially where this request is in the EAD document.

The actual value has nothing to do with the SubLocation or any other Aeon Transaction field and therefore it does not make sense to store that field in the Aeon Transaction, which is why we use the GroupingField field.

If we choose to define the group identifier field to be an actual Aeon Transaction field such as ItemVolume or SubLocation, the grouping is handled the same as it does here (see Aeon Specific Example above).

The difference is that when it builds the transaction it will pick up that field and save the value to that transaction.

In the case of a non-Aeon field such as GroupingField, the value is only used to determine how to group the request. It is not stored in the transaction.

Changes Made to the Output on the EAD Submission Form

When group identifiers are defined, there are two changes made to the output on the EAD submission form.

• The FormDataField is output with the Value of the group identifier, in this example, GroupingField.
• The Value fields are defined for each of the requests, suffixed with the different IDs for the different requests. The Value field in this example is GroupingField. See image.

In this example, the values look similar to the IDs because the output is set up to output the request parent ID.

How a Request Grouped by a Non-Aeon Transaction Field Looks when Submitted

In this specific example, requests are submitted based on what level they are at in the EAD relative to the parent request.

Looking at Italy Clippings and Sources of French Renaissance Carving with a parent of Italian Architecture, they are at the same level in same container and should be grouped.

The Submitted requests yield one request.

This request contains 2 notes, 2 item volumes, one call number.

Note that the Sublocation field has not been populated (This is the Additional Location field in the Request form). Had the SubLocation or another Aeon specific field been used, that field would be populated in the Aeon request.

How Single EAD Requests are Output

When a single EAD request is processed in Aeon, the fields within the request are output to the fields in the Transaction Information form on the web and the Transaction table in the Database.

When Multiple Requests Exceed Request Limit

How Grouped EAD Requests are Output

The way grouped EAD requests are output by the web DLL changes with Aeon 3.

In prior versions of Aeon, when a group of requests was detected, a single transaction was created and in that transaction, notes were created for each individual request that was selected.

Aeon compiled a list of all the field values that were available for each individual request and created the transaction notes by concatenating all of those values delimited with a semicolon.

Aeon 3.1 allows users to add to their XSLT transform documents output which will allow them to configure how the grouped requests are stored in the Aeon Transaction table.

Specifically, when a group is detected, Aeon looks for specific values for each of the requests in the group and processes them using one of three settings.

The Three Settings for Transferring EAD Information

There are currently three settings sites can implement to transfer EAD information into an Aeon transaction request: the default setting, Concatenate, and FirstValue.

The default setting for transferring data creates a single transaction and adds transaction notes for each individual item in the grouped request.

The two other settings, Concatenate and FirstValue, were created so that transaction information for items selected as a group can be recorded for each item in the Transaction Information form on the web.

Transaction information is also stored in the Transaction table of the database so it can be used for reports.

The Default Grouping Option

When a group of requests is detected, a single transaction is created.

In that transaction, notes are created for each individual request selected.

In those notes is a list of all the field values that are available for each individual request.

The notes are created by concatenating the field values delimited with a semicolon, as shown in the example to the right.

The Concatenate and FirstValue Options

As stated above, Aeon 3.1 allows users to add to their xslt transform documents output which will allow them to configure how the grouped requests are stored in the Aeon Transaction table.

Theoretically when requests are submitted as group, the resulting Transaction Information form displays the ItemVolume field (Volume), as a concatenated value of each individual request's ItemVolume field.

A single value represents the CallNumber field (CallNumber), which should be similar from one request to the next within a group. It is generally configured with a FirstValue value.

In the example to the right, the ItemVolume is displayed as Volume: (1);(2) and the CallNumber is displayed as Call Number: MS1.

In grouped requests, the Notes field is still generated by default.

See The Mapping configuration using XSLT, below, for further information.

The FirstValue Grouping Option

The FirstValue grouping option takes the first value for the first request for a given transaction field and stores it in the Aeon transaction field.

The Mapping configuration for FirstValue using XSLT

The following mapping configuration shows example behavior for adding field mapping so that the call number for grouped EAD requests is pulled as the first value into the CallNumber field.

  
<xsl:element name="input">       
    <xsl:attribute name="type">hidden</xsl:attribute>
    <xsl:attribute name="id">GroupingOption_CallNumber</xsl:attribute>
    <xsl:attribute name="name">FormDataField</xsl:attribute>
    <xsl:attribute name="value">FirstValue</xsl:attribute>
</xsl:element>

The Concatenate Grouping Option

The Concatenate grouping option takes all values for a particular field from all grouped requests and concatenates them delimited by a semicolon, then puts that final value into an Aeon transaction field.

This allows sites to pull in more detailed information about grouped requests and have it available on the actual Aeon transaction rather than just in notes.

The Mapping configuration for Concatenate using XSLT

The following mapping configuration shows example behavior for adding field mapping so that the volume information for grouped EAD requests is concatenated into the ItemVolume field.

<xsl:element name="input">
    <xsl:attribute name="type">hidden</xsl:attribute>
    <xsl:attribute name="id">GroupingOption_ItemVolume</xsl:attribute>
    <xsl:attribute name="name">FormDataField</xsl:attribute>
    <xsl:attribute name="value">Concatenate</xsl:attribute>
</xsl:element>