What's New in ArchivesSpace 4.0.0
ArchivesSpace v4.0 and beyond is extremely disruptive to plugins authored before 4.0. Please see the webinar Proactive Change Management for Plugins for critical advice for anticipating such changes, and our article Preparing to move into 4.0.0 or 4.1.0 for immediate next steps.
This article will cover the version itself. For information related to preparing for this version, please see our article Preparing to move into 4.0.0 or 4.1.0.
ArchivesSpace v4.0.0 was released on January 23, 2025. The official release notes are available here. Atlas highly recommends that users always read the official release notes in their entirety, as this article will only highlight specific changes. A list of all Jira tickets included in v4.0.0 is available here, with additional pull requests for v4.0.0 here.
ArchivesSpace v4.1.0 was released on May 5, 2025. Our article on that release is available here. If this is your first time moving into a version that begins with 4, this article is relevant to you.
Are you skipping over versions?
Changes to ASpace are cumulative so remember to read the official release notes for any versions you are skipping over. Here are convenient links to Atlas articles on previous versions. Staff at ArchivesSpace Member Institutions are encouraged to reference the ArchivesSpace Help Center for additional documentation corresponding to new and previous releases.
Improvement Highlights for v4.0.0
Most of the improvements in this major release are infrastructure changes made behind the scenes to update ArchivesSpace's codebase and dependencies, which is essential but mostly invisible work. Changes to the actual experience of using ArchivesSpace were few compared to prior releases, with one major exception. Read on for more details on selected changes in 4.0.0.
Bulk Updater
Beginning in ArchivesSpace 4.0.0, the as_spreadsheet_bulk_updater plugin (also known as The New School Bulk Updater) has been added to core code. Atlas will automatically uninstall this plugin if it is present on your server prior to 4.x and any prior users of this plugin should detect few changes.
Please see our article Bulk Updater (v.4+) for more information on this new feature.
Breaking changes for OAI-PMH
This is a direct quote from the v.4.0.0 release notes:
OAI identifiers are now being generated/expected with a colon between namespace and prefix, rather than slash.
So OAI URIs that used to look like:
/oai?verb=GetRecord&identifier=oai:archivesspace/#
{@test_resource_record}&metadataPrefix=oai_dcterms
now become:
/oai?verb=GetRecord&identifier=oai:archivesspace:{Resource ID}&metadataPrefix=oai_dcterms
This is now in conformance with oai-pmh guidelines, more about it in the oai gem release notes.
PUI Collection Organization sidebar can now be on the right or the left
The PUI Collection Organization sidebar (see screenshot below) has always been on the right-hand side on the ArchivesSpace PUI with no way to override that placement without a plugin. Beginning in v4.0 and beyond, you have the ability to configure this to appear on either the left or the right.
Notably, the new default is the left, meaning that if you do not request us to configure it otherwise, the PUI Collection Organization sidebar will automatically switch sides upon updating.
Improvements to PUI Collection Organization and loading and scrolling
Users of the Collection Organization view on the PUI will find improvements to the scrolling on that page, especially for larger collections. Additionally, for any collection with more than 40 components, there will be a new bar showing how much of the record is currently displayed as well as the ability to toggle all records. Please note that load times will be longer for larger collections.
Ability to allow all System Administrators to view System Information
Prior to ASpace 4.x, there was one feature of the staff interface that was only available to the admin account (the username spelled a-d-m-i-n), which was the System Information page. Beginning in 4.0.0 you may configure ArchivesSpace to allow any user with System Administrator privileges to access this page.
You must request this feature be enabled; it is disabled by default. You will be asked whether to enable it as part of your upgrade to v4+ and beyond.
System administrator permissions are set by the admin or by another System Administrator on an individual's user account:
Please read our related article on the System Information page for more details about what this page contains.
Ability to download a pre-filled Digital Object template
There are now two options for using a bulk import template to create and link Digital Objects to existing Archival Objects in a Resource:
-
You can download a blank template by navigating to the Gear Menu ⚙️ and selecting Bulk Import Templates and then selecting Bulk Import DO CSV or Bulk Import DO XLSX.
-
New as of 4.0: You can download a prefilled template by navigating to the Resource where you wish to add Digital Objects and then selecting Export and then Download Digital Object Template. This version of the template will have information about all archival objects prefilled and ready for digital object information to be added.
Please note that the exported template will be the CSV version of the template, and the template will be blank if no AOs exist in the selected Resource. You cannot create AOs using this template, only DOs. To create AOs, use the Archival Object template available via the Gear Menu ⚙️ and selecting Bulk Import Templates.
Public search highlighting
A feature request from 2018 has been implemented that shows highlighting on the PUI for keyword searches. However, this feature does have limitations, as can be seen in the following screenshot. While all the search results have "Correspondence" in them and that is why they returned in the search, it's not always the case that the word itself is going to appear in the blurbs that are returned with the search results.
Smaller Changes
Read on for details on smaller changes in 4.x.
New columns in the Digital Object import spreadsheet
A number of new columns were added to the digital object import spreadsheet. Users of that functionality should download the most recent version of the template once they are in v4.x by navigating to the Gear Menu ⚙️ and selecting Bulk Import Templates.
Ability to duplicate an Archival Object
Users wishing to quickly duplicate an archival object with a similar title and information can now select Add Duplicate from the tree menu while in Edit mode. ArchivesSpace will create a duplicate of the AO you are on immediately below your selection. Instances are not duplicated, but Dates, Notes, and other subrecords are. See this Jira ticket for more information.
Ability to associate a repository with Location imports
There is now a new checkbox option when using the Import Data background job for importing Locations:
Contextualization added to Permission Groups
There are new helpful labels in the Permission Group menus that make it clear at what level a permission applies. Nothing about the permissions themselves has changed.
Bug Fixes
ArchivesSpace releases always include bug fixes. Atlas staff have highlighted the following resolved bugs for this released based on the experience of our users or the significance of the bug.
Spreadsheet importer bug fixes:
- Spreadsheet bulk AO importer now respects Publish? status when using the CSV template (Jira ticket)
- Local access restriction types can now be imported without dates in the AO template (Jira ticket)
EAD bug fixes:
- Extraneous characters no longer added to Language of Material note in EAD export (Jira ticket)
- Correction for Revision Description in EAD exports (Jira ticket)
PDF bug fixes:
- Agent roles now correctly display on staff PDF (Jira ticket)
- Digital object instances now showing in Staff PDF (Jira ticket)
- Component identifier now displays in staff and public PDF (Jira ticket | Jira ticket)
Other fixes:
- Improvements to known mixed content PUI display bugs (Jira ticket)
- Agent roles are now preserved when Agents are merged (Jira ticket)
Plugin changes made by Atlas
Changes to _branding.html.erb in local
As part of this update, Atlas updated two class definitions in _branding.html.erb in the local plugin. If you have provided us with a _branding.html.erb file in the past (usually as part of a branding plugin), your file was also modified.
Before:
<div class="container-fluid navbar-branding">
<%= image_tag "/assets/images/atlas.png", :class=>"img-responsive" %>
</div>
After (4.0+):
<div class="navbar-branding flex-grow-1 align-self-stretch order-1 order-md-0 p-12px">
<%= image_tag "/assets/images/atlas.png", :class =>"header-logo" %>
</div>
Advanced plugin information
As Atlas becomes aware of specific information related to plugins we will put that information in this section, which we provide as a courtesy. This information is possibly useful to advanced users and developers, or any individuals responsible for updating plugins at your institution. Such users should also read our article Delivering and Maintaining your ArchivesSpace Plugins.
- This pull request
- This Jira ticket and pull request | https://github.com/archivesspace/archivesspace/pull/3276
- This Jira issue: Streamline and document adding gems to plugins
FAQs for v4.0.0
Are there new requirements?
There are no new required fields or actions for the 4.0.0 release.
Do I have to do anything upon updating?
There are no required actions for the 4.0.0 release, though Atlas always recommends users test the functionality of any installed plugins after any update, especially branding and theming plugins. Atlas Systems does not support third party plugins.
Configurations for v4.0.0
New configurations as well as any configurations that are being removed are available to view in the official ASpace Release Notes for 4.0.0.
Configuration Highlights for v4.0.0
| Configuration Setting | Explanation |
|---|---|
AppConfig[:allow_other_admins_access_to_system_info] = false | This configuration allows users with the 'administer_system' role to view the System Information page. By default, this route is only accessible to the 'admin' user, and no other admins. |
AppConfig[:pui_collection_org_sidebar_position] = 'left' | This configuration moves the PUI Collection Organization sidebar to the left or the right. It is set to left by default, whereas in the past the default was right. |
AppConfig[:bulk_archival_object_updater_create_missing_top_containers] | This configuration relates to the bulk updater functionality that is new to core code as of v4.0. This configuration controls the default value of the Create missing top containers? checkbox when starting a bulk update job. It is set to false by default, meaning the box is unchecked by default. Please note that this configuration doesn't enable or disable this functionality, it only sets the default value of the checkbox. |
AppConfig[:bulk_archival_object_updater_apply_deletes] | This configuration relates to the bulk updater functionality that is new to core code as of v4.0. This configuration controls whether you can delete subrecords as part of a bulk update job by leaving a value blank. It is set to false by default, meaning deletes are not allowed by default. Atlas does NOT recommend changing this configuration; it is very easy to accidentally delete subrecords when this is enabled. You will not be able to retrieve deleted records once they are gone. |
Please let Atlas know if you would like to modify any of the above configurations as part of your update. All values listed above are the defaults.