The Archival Request Form

Brittany De Gail

Updated May 15, 2024 13:01

Aeon 5.2 includes a new Archival Request box picker form (ArchivalRequest.html) that can be configured to accept requests from ArchivesSpace using the updated, 5.2-compatible version of the ArchivesSpace Request Fulfillment via Aeon plugin ( v20230302). The Archival Request form will accept the plugin request, display the request information and allow users to select which containers to submit for requesting rather than automatically sending requests for all boxes associated with a record.

Overview | Configuring the Archival Request Form

Overview

The ArchivesSpace Request Fulfillment plugin will not send requests to the Archival Request form by default. For more information on configuring the plugin to send requests to this form from ArchivesSpace, see Configuring the Archival Request Form. This form is only compatible with Aeon v5.2 or later and ArchivesSpace Request Fulfillment plugin v20230302 or later.

When the ArchivesSpace Request Fulfillment plugin is configured to send requests to the Archival Request form, clicking the Aeon Request button on a requestable record in ArchivesSpace will bring the user to the box picker page. This form has the following features:

Breadcrumb Navigation

The top of the request form will display a breadcrumb trail indicating the location of the requested record in your ArchivesSpace repository to make it easier for users to navigate back and forth between Aeon and ArchivesSpace. Details for the requested record will display below:

Container Selection

The Containers section below the request details will display the containers associated with the record. Users can use the checkbox controls next to each container to select the specific boxes they would like to request. Field notes with configurable messages will display under the name of a container if it is offsite or restricted. Restricted containers will not be requestable and will have the checkbox disabled:

If a container is both offsite and restricted, only the restricted message will show.

Request Information

The bottom of the form will contain a Request Information section where users can add more information to the Aeon request. If appointment scheduling features have been configured for Aeon, the appointment scheduling controls will appear here once configured on the form.

Request Submission

The Archival Request form includes all repository-level fields sent from the ArchivesSpace plugin as hidden inputs on the web page. When the Archival Request form is submitted, Aeon will use the External Request Endpoint to validate and submit the selected containers and information in the hidden inputs as individual requests.

The endpoint will submit requests up to the user's request limit (if request limits are enabled) and move any remaining requests to the Awaiting User Review status. If all requests have been successfully submitted, the user will be returned to the Aeon home page. If some requests were not submitted due to the user's request limit or failed validation, the user will be directed to the Saved Requests page.

The request form used is determined by the DocumentType entry configured for the plugin in the OpenURLMapping table. For more information on configuring this table, see ArchivesSpace Request Fulfillment via Aeon.

Enforcing Web Validation on the Archival Request Form

The WebValidation and WebFormValidationLinks tables in the Aeon Customization Manager can be used to enforce server-side validation for the fields displayed on the Archival Request form. For example, you can configure these tables to require the user to input a value into fields you have marked as 'required' before they can submit the form. The method for configuring web validation on the Archival Request form will vary based on whether the photoduplication toggle (described below) has been enabled on the form:

When the photoduplication toggle has not been enabled on this form, web validation is configured by adding an entry in the WebFormValidationLinks table with the Form Name 'ExternalRequest' and a Rule Set value matching a rule set configured in the WebValidation table for the fields for which you would like to enforce validation. For more general information on configuring entries in the WebValidation table, see Field Validation and Required Fields
When the photoduplication toggle has been enabled on this form, web validation is configured by modifying the include_photodup_toggle_enabled.html file to add a FormValidationOverride hidden input that specifies the Rule Set in the WebValidation table that should be used to enforce web validation for the fields controlled by each photoduplication toggle option. For detailed instructions, see Enforcing Field Validation for Fields Displayed by the <#PHOTOTOGGLE> Tag

Note: When configuring web validation for the fields displayed by the photoduplication toggle options, the entry for the 'ExternalRequest' form in the WebFormValidationLinks table should be removed, if present, as this will apply blanket validation for all fields on the Archival Request form and will not selectively apply validation based on the fields included in the photoduplication toggle option selected by the user.

For an example of each web validation configuration method, see step 2b. Add WebValidation for ReadingRoomID (Only required when appointment scheduling is enabled) in the Archival Request form configuration documentation below.

Support for Photoduplication Requests

The Archival Request form can be configured with a photoduplication toggle to support the submission of photoduplication requests directly from the box picker form. When the photoduplication toggle is enabled in the Aeon Customization Manager, the Archival Request form will display a Request Type section at the bottom of the web page containing toggle options allowing the patron to choose between submitting either a reading room request or a photoduplication request from the request form. Based on the option selected by the user, the form with either display the scheduled date/appointment scheduling fields (based on your web page configuration) or the photoduplication fields used to submit photoduplication requests.

For more information on configuring this feature in the Aeon Customization Manager, see the Enable the Photoduplication Toggle section below.

Note: The optional SkipOrderEstimate functionality used to skip the order estimate step in the Aeon photoduplication request processing workflow is not supported for use with photoduplication requests submitted via the Archival Request form.

Configuring the Archival Request Form

To use the Archival Request form, several web pages and customization keys will first need to be configured in Aeon. Once the Aeon configuration is complete, the plugin settings in ArchivesSpace should be modified to enable the new functionality and begin sending requests to the box picker form following the instructions below.

Minimum Server Requirement

You must be on Aeon Server v5.2.4 to configure the Archival Request form according to the instructions below.

Configuration Overview

The configuration steps for the Archival Request form should be performed in the following order:

[Aeon]: Configure the Archival Request form web page files in your Aeon web directory
[Aeon]: Configure the Archival Request customization keys in the Aeon Customization Manager
[Aeon] (optional): Configure the status line that displays on the Archival Request form
[ArchivesSpace]: Configure the ArchivesSpace plugin to enable the :top_container_mode setting

Step One: Configuring the Archival Request Form Web Pages

Several new files first available in the Aeon 5.2 default web pages and feature-specific web pages are used to configure the Archival Request box picker form on the Aeon web interface. The web page configuration process, including the specific files used to implement the Archival Request form, will vary depending on if appointment scheduling features have been enabled in Aeon. An overview of the web page files and the configuration steps are detailed below.

Web Page File Names and Descriptions

The Archival Request form is configured using the web page files listed below. These files can be downloaded from the Aeon Downloads page.

Each file is marked with Default if the file is used in a default Aeon configuration with no appointment scheduling enabled and Appointment Scheduling if the file is used in an Aeon configuration that uses appointment scheduling features.

File Name	Description
js\ArchivalRequest.js *(Default & Appointment Scheduling)*	The JavaScript file that is used with the ArchivalRequest.html file both when appointment scheduling functionality is enabled and when appointment scheduling is not enabled in Aeon.
templates\DataRow_ ArchivalRequestContainer.html (Default & Appointment Scheduling)	The DataRow file that is used with the ArchivalRequest.html file both when appointment scheduling functionality is enabled and when appointment scheduling is not enabled in Aeon. This file: Contains the code to display the checkboxes and related information on the box picker form Includes all container-level fields sent from the ArchivesSpace plugin as hidden inputs
ArchivalRequest.html (Default & Appointment Scheduling)	The file used to display the Archival Request box picker form on the Aeon web interface. The same file is used both when appointment scheduling functionality is enabled and when appointment scheduling is not enabled in Aeon. This form: Includes all repository-level fields sent from the ArchivesSpace plugin as hidden inputs Includes the <#PHOTOTOGGLE> tag that will enable support for easily configuring a photoduplication toggle on the Archival Request form, which will allow patrons to choose between making a reading room or photoduplication request from the Archival Request form If the photoduplication toggle is not enabled, then the <#PHOTOTOGGLE> tag will display the content of the include_photodup_toggle_disabled.html file on the Archival Request form If the photoduplication toggle is enabled, then the <#PHOTOTOGGLE> tag will display the content of the include_photodup_toggle_enabled.html file on the Archival Request form The form number associated with this web page is 35. For more information on web page form numbers, see Aeon Web Action, Form, and Type Numbers.
include_appointment_ info_no_site.html (Appointment Scheduling)	The include file that is used with ArchivalRequest.html when appointment scheduled is enabled in Aeon. This file adds the appointment scheduling controls to the box picker form while also allowing the plugin to send the Site field as a hidden input. Note that though this file is only used exclusively with ArchivalRequest.html by default, it can also be used to add the appointment scheduling controls to any of your request forms where the Site field is expected to be a constant hidden input on the request rather than a selectable option.
*include_photodup_toggle_disabled.html (Default)*	The include file that is used with ArchivalRequest.html when appointment scheduling functionality is not enabled in Aeon and when the photoduplication toggle is not enabled on the Archival Request form. This file will: Display the Request For and Scheduled Date fields on the Archival Request form Add the buttons used to submit the Archival Request form
*include_photodup_toggle_enabled.html (Default)*	The include file that is used with ArchivalRequest.html when appointment scheduling functionality is not enabled in Aeon and when the photoduplication toggle is enabled on the Archival Request form. This file will: Display the toggle controls used to switch between making a reading room or photoduplication request from the Archival Request form Display the Request For and Scheduled Date fields on the Archival Request form when a reading room request is selected Display the photoduplication fields on the Archival Request form when a photoduplication request is selected using the include_photoduplication_ archival_request.html file Add the buttons used to submit the Archival Request form
*include_photodup_toggle_disabled.html (Appointment Scheduling)*	The include file that is used with ArchivalRequest.html when appointment scheduling functionality is enabled in Aeon and when the photoduplication toggle is not enabled on the Archival Request form. This file will: Display the appointment scheduling fields on the Archival Request form using the include_appointment_ info_no_site.html file Add the buttons used to submit the Archival Request form
*include_photodup_toggle_enabled.html (Appointment Scheduling)*	The include file that is used with ArchivalRequest.html when appointment scheduling functionality is enabled in Aeon and when the photoduplication toggle is enabled on the Archival Request form. This file will: Display the toggle controls used to switch between making a reading room or photoduplication request from the Archival Request form Display the appointment scheduling fields on the Archival Request form when a reading room request is selected using the include_appointment_ info_no_site.html file Display the photoduplication fields on the Archival Request form when a photoduplication request is selected using the include_photoduplication_ archival_request.html file Add the buttons used to submit the Archival Request form
include_photoduplication_archival_ request.html (Default & Appointment Scheduling)	The include file that is used with ArchivalRequest.html to add the photoduplication fields to the Archival Request form when the photoduplication toggle is enabled. The same file is used both when appointment scheduling functionality is enabled and when appointment scheduling is not enabled in Aeon.

Web Page Configuration Steps

The web page files for the Archival Request form should be added to the Aeon web directory using a separate set of configuration steps depending on whether or not appointment scheduling features have been enabled for your instance of Aeon:

Configuring the Archival Request Form on All Aeon Web Directories

To ensure that the Archival Request form is configured consistently across the Aeon web interface, the web page configuration steps below should be performed in each of the web directories configured on your Aeon server. Note that the names used below to refer to each directory may differ from the names used for those directories on your Aeon server based on your institution's specific web configuration:

The Aeon/AeonAuth web directory containing the live, production web page files accessed by users authenticated through basic Aeon authentication
The Aeon_TestWeb/AeonAuth_TestWeb web directory containing the TestWeb files used to test the web pages accessed by basic Aeon authentication users
If remote authentication has been configured for Aeon, ensure that the web directories configured for these users are updated with the new files:
- The RemoteAuth web directory containing the live, production web page files accessed by users authenticated through remote authentication
- The RemoteAuth_TestWeb web directory containing the TestWeb files used to test the web pages accessed by remote authentication users

Configuration Steps (No Appointment Scheduling)

If you are not using the appointment scheduling features and web pages in Aeon:

Download the latest version of the Aeon 5.2 or 6.0 default web pages from the Aeon Downloads page if you have not done so already
Locate the ArchivalRequest.html, include_photodup_toggle_disabled.html, include_photodup_toggle_enabled.html, and include_photoduplication_archival_request.html files within the downloaded web page files and add/overwrite these files within your Aeon web directory (in GitHub or at the default location on the Aeon server: C:\Program Files (x86)\Aeon\Web)
Locate the DataRow_ArchivalRequestContainer.html file in the templates subfolder within the downloaded web page files and add/overwrite this file within the templates subfolder in your Aeon web directory
Locate the ArchivalRequest.js file in the js subfolder within the downloaded web page files and add/overwrite this file within the js subfolder in your Aeon web directory
Locate the billingAccountsOptionHandler.js, billingContextOptionHandler.js, and duplicationPermissionToggle.js files in the js subfolder within the downloaded web page files and use these files to overwrite the existing version of these files in the js subfolder in your Aeon web directory to ensure that the most recent versions of these files are being used on your web pages

Configuration Steps (Appointment Scheduling Enabled)

If you are using the appointment scheduling features and web pages in Aeon:

Download the latest version of the Aeon 5.2 or 6.0 default web pages from the Aeon Downloads page if you have not done so already
Locate the ArchivalRequest.html and include_photoduplication_archival_request.html files within the downloaded web page files and add/overwrite these files within your Aeon web directory (in GitHub or at the default location on the Aeon server: C:\Program Files (x86)\Aeon\Web)
Locate DataRow_ArchivalRequestContainer.html in the templates subfolder within the downloaded web page files and add/overwrite this file within the templates subfolder in your Aeon web directory
Locate the ArchivalRequest.js file in the js subfolder within the downloaded web page files and add/overwrite this file within the js subfolder in your Aeon web directory
Locate the billingAccountsOptionHandler.js, billingContextOptionHandler.js, and duplicationPermissionToggle.js files in the js subfolder within the downloaded web page files and use these files to overwrite the existing version of these files in the js subfolder in your Aeon web directory to ensure that the most recent versions of these files are being used on your web pages
Download the latest set of Aeon 5.2 or 6.0 feature-specific web pages from the Aeon Downloads page
Locate the include_appointment_info_no_site.html, include_photodup_toggle_disabled.html, and include_photodup_toggle_enabled.html files within the downloaded web page files in the AppointmentScheduling folder and add/overwrite these files within your Aeon web directory
Locate the appointments.js file in the js subfolder within the downloaded web page files and overwrite the appointments.js file located in the js subfolder in your Aeon web directory to ensure that the most recent version of this file is used

Advanced Configuration Options

Several advanced settings are also available to configure within the code on the Archival Request web pages to adjust the information displayed on the Archival Request form. These configuration options are intended for advanced users and do not need to be modified from the default settings to use the Archival Request form.

Advanced Configuration Options

<#ARCHIVE> Tag

The <#ARCHIVE> tag can be used on the Archival Request form (ArchivalRequest.html) to display the value of an Aeon field that has been passed a value from the ArchivesSpace record. The tag should only be used on ArchivalRequest.html and is configured as follows:

<#ARCHIVE field="[fieldname]" display="" disabledValue="" enabledValue="">

Replace [fieldname] with the name of the Aeon field that should have its value displayed
Configure the display parameter according to one of two options:
- If the display parameter has no value, the <#ARCHIVE> tag will be replaced with the value of the field. If the field does not have a value, nothing will display.
- If the display parameter is set to display="CheckHasValue" then the <#ARCHIVE> tag will be replaced with the text configured in the enabledValue parameter if that field has a value or the text displayed in the disabledValue parameter if it does not.

<#DATAROW> Tags

<#DATAROW> tags are used within the DataRow_ArchivalRequestContainer.html file to configure the container information and checkboxes on the Archival Request form. The tag takes the name of a DataRow field to return or display specific information:

<#DATAROW field="[fieldname]">

The Archival Request DataRow (DataRow_ArchivalRequestContainer.html) uses the following unique fields that can only be used within the DataRow_ArchivalRequestContainer.html file:

DataRow_ID: Returns the id value in the list of containers. This option is mostly used to append an id to other field ids for request grouping
Aria-Described-By: Returns an aria-describedby attribute containing the id of any conditional notes for the container
Container-Checkbox-State: Returns the default state of the container checkbox based on the information sent from the plugin. Checkboxes will be disabled if the container is not requestable. If there is only one container, the checkbox will be checked by default.
Container-Message: Returns the values in ArchivalRequestOffsiteContainerMessage or ArchivalRequestContainerRestricted as field notes on the Archival Request web page if the container is offsite or restricted, respectively. If both apply, only the restricted message will show.

Note: The ArchivalRequest.html and DataRow_ArchivalRequestContainer.html files contain hidden inputs for all possible fields that can be submitted from the plugin. Unused fields can be removed to reduce the size of the Archival Request form and improve performance if the repository contains archival objects with a large number of top containers.

Step Two: Configuring Aeon Customization Keys

After the web page files have been added to your Aeon web directory, the following keys should be configured in the Aeon Customization Manager under Web Interface | Archival Request:

ArchivalRequestOffsiteLocations

This key should be configured with a semicolon-separated list of the names of the archival buildings that are offsite.

The names configured in this customization key should match the name of the buildings as they are configured in the instance_top_container_location_building setting in ArchivesSpace.

The plugin will check the value of this setting for each container and display the message in the ArchivalRequestOffsiteContainerMessage key if the value matches a name configured in this key.

ArchivalRequestOffsiteContainerMessage

Sets the message that will be shown next to archival containers listed on the Archival Request form that have an offsite building name that has been specified in the ArchivalRequestOffsiteLocations key.

Default: <span class="fa fa-info-circle" aria-hidden="true"></span> This container is stored offsite and may take longer to retrieve

ArchivalRequestContainerRestricted

Sets the message that will be shown next to archival containers listed on the Archival Request form that are restricted and cannot be requested.

Default: <span class="fa fa-ban" aria-hidden="true"></span> This container is restricted and is not requestable

For detailed information on how access restrictions are set in ArchivesSpace and configured for use with the plugin, please see Impact of ArchivesSpace Local Access Restrictions on Requesting Top Containers.

2a. Enable the Photoduplication Toggle (Optional)

You can opt to enable the photoduplication toggle on the Archival Request form using the PhotoduplicationEnabled key in the Customization Manager under Web Interface | System. This step is optional and is not required to configure the Archival Request form:

When the photoduplication toggle is enabled:
- The <#PHOTOTOGGLE> tag used on ArchivalRequest.html will display the toggle controls that will allow users to choose between submitting either a reading room request or a photoduplication request from the Archival Request form
- The scheduled date or appointment scheduling fields (depending on your web page configuration) will display on the form when a reading room request is selected
- The photoduplication fields will display on the form when a photoduplication request is selected
When the photoduplication toggle is not enabled:
- The <#PHOTOTOGGLE> tag used on ArchivalRequest.html will display only the scheduled date or appointment scheduling fields (based on your web page configuration)

The text used for the photoduplication toggle content and the fields displayed by each toggle option can be modified by editing the HTML files used to configure the toggle. For more information, see Implementing a Photoduplication Toggle Option on Request Forms.

PhotoduplicationEnabled

Determines if photoduplication fields should be enabled on web request forms using the <#PHOTOTOGGLE> tag:

Set this key to Yes to enable the toggle controls and photoduplication fields that will allow users to choose between making a photoduplication request or a reading room request from the Archival Request form
Leave this key at the default value of No if you do not want to enable the photoduplication toggle options and fields on the Archival Request form (i.e., if users should not be allowed to submit photoduplication requests from this form)

2b. Add WebValidation for ReadingRoomID (Only required when appointment scheduling is enabled)

If appointment scheduling features have been enabled for your instance of Aeon and you have implemented the appointment scheduling version of the web pages in Step One: Configuring the Archival Request Form Web Pages above, you will need to set up an entry in the Aeon Customization Manager's WebValidation table to enforce server-side validation for the required Reading Room field. The steps for configuring the WebValidation entry will vary based on whether or not you have enabled the photoduplication toggle in Step 2a: Enable the Photoduplication Toggle (Optional) above.

Configuration Steps - Photoduplication Toggle Disabled

If you have not enabled the photoduplication toggle on the Archival Request form, follow the steps below to configure the WebValidation table for the ReadingRoomID field:

Open the Aeon Customization Manager
From the Customization tab, navigate to the WebValidation table (located under Web Interface | Validation)
Click New Record

Create a validation rule for the ReadingRoomID field as follows:

Rule Set	ArchivalRequest Note: The rule set name does not have to match "ArchivalRequest" and can be any unique value not previously used for a rule set in the WebValidation table.
Fieldname	ReadingRoomID
Validation	.+
Error	You must select a reading room
Error Tag	ERRORReadingRoomID

Click Save
Navigate to the WebFormValidationLinks table (located under Web Interface | Validation) in the Aeon Customization Manager
Click New Record

Create an entry linking the ExternalRequest form to the new rule created in the WebValidation table in step 4 above:

Form Name	ExternalRequest This value must be entered in exactly as is and cannot be customized.
Rule Set	ArchivalRequest This value must match the Rule Set value for the ReadingRoomID entry in the WebValidation table you configured in step 4 above.

Click Save
Validation is now configured for the ReadingRoomID field on the Archival Request form.

Configuration Steps - Photoduplication Toggle Enabled

If you have enabled the photoduplication toggle on the Archival Request form, follow the steps below to configure the WebValidation table for the ReadingRoomID field:

Open the Aeon Customization Manager
From the Customization tab, navigate to the WebValidation table (located under Web Interface | Validation)
Click New Record

Create a validation rule for the ReadingRoomID field as follows:

Rule Set	ReadingRoomToggle Note: The rule set name does not have to match "ReadingRoomToggle" and can be any unique value not previously used for a rule set in the WebValidation table.
Fieldname	ReadingRoomID
Validation	.+
Error	You must select a reading room
Error Tag	ERRORReadingRoomID

Click Save
Edit the include_photodup_toggle_enabled.html file and add the following line for the FormValidationOverride hidden input under the <input type="hidden" name="RequestType" value="Loan"> line (default line 20):
```
<input type="hidden" name="FormValidationOverride" value="ReadingRoomToggle">
```
The value used in the value attribute must match the Rule Set value for the ReadingRoomID entry in the WebValidation table you configured in step 4 above. If you used a rule set name other than "ReadingRoomToggle" in step 4, please ensure that you update the code to reflect this name.
Save the file
Validation is now configured for the ReadingRoomID field on the Archival Request form.

If you have made customizations to require any additional photoduplication toggle fields, see Enforcing Field Validation for Fields Displayed by the <#PHOTOTOGGLE> Tag for more information on configuring web validation for these fields.

Step Three: Configuring the Archival Request Status Line

The status line that appears at the top of the Archival Request form can be modified in the Aeon Customization Manager under Web Interface | Status Lines. Editing this status line is an optional step in the configuration process that should only be performed if the default text needs to be modified:

SLShowArchivalRequest

Sets the web status line that appears at the top of the archival request form.

Default text: Use the checkboxes below to indicate which containers you would like to request. Add any request details in the Request Information section below before submitting your request.

Step Four: ArchivesSpace Plugin Configuration

Once the Archival Request form has been fully configured in Aeon, the :top_container_mode setting of the ArchivesSpace Request Fulfillment plugin setting must be enabled to direct users to this form from ArchivesSpace. This is a true/false setting that controls whether or not the top container mode is active for your ArchivesSpace repository. When top container mode is enabled (set to 'true'):

Clicking the Aeon Request button in ArchivesSpace will take the user to the new Archival Request box picker form to submit their request(s)
Only top containers associated with the current record will be requestable.

If no top containers are associated with the current record, then the request button will be replaced by the default No requestable containers message or by a custom message, if one has been configured in the plugin's :no_containers_message setting (see ArchivesSpace Request Fulfillment via Aeon for more details).

Activating Top Container Mode

Activating top container mode in ArchivesSpace and enable the new Archival Request box picker form requires making the following changes to the plugin settings in ArchivesSpace:

Change the :top_container_mode setting for the plugin to 'true'
Change the :requests_permitted_for_containers_only setting for the plugin to 'true'

The :requests_permitted_for_containers_only setting must be set to 'true' when :top_container_mode is set to 'true.'
Save and apply your changes
Top container mode is now enabled. The plugin will direct users to the Archival Request form when submitting requests from ArchivesSpace to Aeon.

These settings are not configured in Aeon but are configured in the ArchivesSpace plugin settings. For detailed information on configuring the settings for the plugin, see the GitHub documentation.

If your ArchivesSpace repository is hosted by Atlas Systems, contact support@atlas-sys.com to request these changes to your plugin settings.