What's new in ArchivesSpace v3+
Please note that there are two ArchivesSpace webinars detailing the new Agents model. The first, An Introduction to ArchivesSpace v3.0.0 and the Expanded Agents Module provides an overview of the changes associated with v3.0+. That webinar featured explanations around the origins of the re-design including a presentation from the SNAC Project. A later webinar, Understanding the Changes to the ArchivesSpace Agents Module repeated some of the info in the first, but with more detail and examples. Atlas recommends watching both webinars, but if you only have time for one, we recommend the second.
ArchivesSpace v3.0.0 was released on May 10, 2021 with four subsequent point releases, the last of which was 3.1.1 on November 19, 2021. ASpace v3.0.0 is the first major version release since 2.0. in April 2017 and includes major changes to the Agents module. AS users interested in Agents and especially in MARCXML, Encoded Archival Context – Corporate bodies, Persons and Families (EAC-CPF) and Social Networks and Archival Context (SNAC) will be interested in the changes in this major version change. Atlas highly recommends that users always read the official release notes in their entirety, as this article will only highlight specific changes. We also strongly suggest watching one or both of the webinars linked above if you are new to 3+.
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. The last release of ASpace prior to v3.0.0 was 2.8.1, and since 3.0.0 there have been four releases, the most recent of which was 3.1.1. Here are convenient links to Atlas articles on previous versions. Information about 3+ point releases are below. Staff at ArchivesSpace Member Institutions are encouraged to reference the ArchivesSpace Help Center for additional documentation.
What do you mean by 3+?
If you see reference to v3+, 3.0+, 3.x or any similar notation, that is a way of referring to all the versions after a major release. The major release version being referred to in this article was 3.0.0, but subsequent point releases were 3.0.1., 3.0.2, 3.1.0, and 3.1.1. That can get confusing! When a statement is very specific to a version, the most specific version number is used, such as 3.1.1; but when a statement is broad enough to apply to any version in the "3 universe," that is when you'll see the broader v3+ used.
Improvement Highlights for v3+
The Expanded Agents module!
The expanded Agents module steals the show for v3+ and is the biggest change to a major record type in ASpace history. Explanations and examples of these substantial changes and improvements are included in two separate webinars: An Introduction to ArchivesSpace v3.0.0 and the Expanded Agents Module and Understanding the Changes to the ArchivesSpace Agents Module.
Changes include:
- Better compliance with EAC-CPF (link)
- Support for the MARC 21 Format for Authority Data (link)
- Updates to import and export mappings
- Improved record merging options for Agents
- A new background job for importing MarcXML Authorities
- Light Mode, an abbreviated version of any Agent record for simplified data entry and maintenance
- Additional permissions to control staff access and views of the Agent module
PUI considerations:
- Additional search support, including faceting on the characteristics of Agents
- New Agent record display
Social Networks and Archival Context (SNAC) integration, including:
- The ability include SNAC identifiers in Agent records
- A link out to SNAC in the PUI when a SNAC ID is present
New LCNAF Plugin Behavior
Though not a new feature, seasoned users of the LCNAF plugin will detect different behavior as a result of the expanded Agents module. The LCNAF plugin has been updated to import any Subject records associated with Agents. This may create near-duplicate records for any Subjects that already exist.
A new spreadsheet template for linking top containers!
v3.0+ comes with a new two-step process to generate and then use a template for linking top containers to archival objects. First, download a container template for an existing resource record:
This will generate a spreadsheet of all the archival objects in that resource along with blank columns for adding container information, including container profiles and locations! This spreadsheet, saved locally to your computer, then acts as a template for the next step.
Once you add the relevant container info, you can upload the spreadsheet template back to the same resource record via a new option in the Load Via Spreadsheet menu:
Note that while this process is intended for linking top containers, users of the Digital Objects spreadsheet may also find this new template useful for grabbing archival object ids! Here's a video explaining that trick.
Unpublish All and Publish at any level functionality!
This button will now appear next to Publish All:
More than just the ability top Unpublish All, 3+ also allows you to both Publish All or Unpublish All at any level of the hierarchy, so if you want to publish/unpublish just a series and all its children, you can!
Please note that because of the inclusion of this functionality, Atlas will uninstall any similar plugins, namely child_publisher and publish_partial_trees.
3.1.1 Updates
3.1.1 was released on November 19, 2021. The main focus of development for AS 3.1.1 were bug fixes and regressions discovered by the community (including you, our customers!). This means there there is no new functionality in 3.1.1 versus its predecessor (3.1.0), only bug fixes. The most disruptive bugs were those associated with reorder mode in the staff interface. 3.1.1 is the current recommended version.
3.1.0 Updates
3.1.0 was released on September 20, 2021. The main focus of development for AS 3.1.0 were a number of accessibility improvements, particularly for the PUI. There may be some impacts on display plugins as a result. As always, Atlas recommends that all customers read the release notes in detail.
Some improvements in 3.1.0:
- Users will notice higher contrast lines around all fields; this is the most obvious change that comes with the accessibility improvements.
- Users can now see Related Accessions on published accession pages in the PUI, where previously they would only see related Resources.
- Users can now link Classifications to Digital Objects.
- Deaccession subrecords for Resources will now display on the PUI by default. If users wish to disable this feature, that is possible in the config. Please write to us at support@atlas-sys.com.
- Buggy behavior in the Staff-side user preferences for setting Language settings has been improved.
- Users can now sort the Users list by username.
- Fields for language and script of description have been added to accession records, but are not required.
- There is a new status for user accounts that allows a user record to be set as Active or Inactive by the admin or another account with sys admin privileges. This status is set via a checkbox in the user record or via a button in the users list (these two options do the same thing).
- Setting a user to Inactive immediately revokes all their permissions, though the user record does stay a member of whatever User Groups they were in.
- If the User is ever deemed to be Active again, all prior permissions are back in place as soon as the status is changed back to Active.
- Users are Active by default.
FAQs for v3+
Are there new requirements?
Actually, there are fewer! Agent records no longer require either a Source or Rules. Happily, the changes that come with v3+ add options, not requirements. Staff will not have to make immediate changes to existing or new data unless they want to. Your existing local practices can remain the same until such time as you wish to change them based on the new options available.
Do I have to do anything upon updating?
There are no required actions upon updating, but do consider the following:
- There will be a change in permission options with 3+, so you may want to consider adjusting permission groups based on these new permission options.
- Namely two new permissions:
- ☑ view contact details for agent records
- ☑ work with agents in full mode
- Namely two new permissions:
- Imports and Exports involving agents will change, so if you rely on importing or exporting in your workflows, test those procedures immediately after updating, or if you use a Sandbox, test in the Sandbox before updating Production. Only some of the ArchivesSpace data maps have been updated to reflect 3+; the most recent versions are here.
- Test the LCNAF Importer if your institution relies on that plugin.
- See Impacts on Plugins section below, but simply put, test any plugin that touches the Agents module.
What's going to happen to my existing Agent records?
The structured date record will be undergoing a transformation in AS 3+ that is best summarized visually. The below contrasts a structured date record in an Agent record before 3.0. and after. Please use the color coding to help understand the changes. The fields framed in red are the fields that actually undergo parsing.
Atlas has published a separate article for a deeper dive on changes to preexisting date expressions for Range dates in your Agent records.
Other than the change to structured dates, all existing Agent data will remain the same, but you will see a lot more fields and options in your preexisting records. None of the new fields is required, so your older records can remain as-is until such time as you decide to augment them with new fields. Whether or not to do that is entirely up to you.
Note that you will have a Light Mode option. Should staff find the array of new fields distracting or unnecessary, switch to Light Mode for easier viewing.
What are the differences between 3.0.0, 3.0.1, 3.0.2, 3.1.0 and 3.1.1?
Here is a short explanation, followed by a longer one:
Short Explanation
- 3.0.0 had a database migration bug that needed to be addressed; it was addressed in 3.0.1 and other than that, those two versions were the same. 3.0.0 is no longer available.
- 3.0.1 solved the 3.0.0 bug, but some community members expressed concerns about a specific action that takes place when updating to 3.0.1. There was also another bug uncovered in this same span of time. Both the community feedback and the second bug fix were incorporated into 3.0.2.
- 3.1.0 has its own sections above and below, and brought changes in functionality and display as well as bug fixes.
- 3.1.1 was mostly bug fixes for 3.1.0 and did not introduce new functionality. 3.1.1 is the current recommended version.
Longer Explanation
- 3.0.0 was found to drop a column of information when migrating preexisting data from an older version. Due to this data loss, 3.0.0 was pulled from GitHub and that is why it is no longer available.
- After 3.0.1 debuted, some community members expressed concerns about how Agent date expressions were handled. After receiving feedback from the community, the developers folded new parsing and new code into 3.0.2.
- This means that if you took your pre-3.0 data and migrated it into both 3.0.1 and 3.0.2 and compared them, you would see substantial differences in how preexisting date expressions in Agent records were handled in these two versions.
- Finally, a bug having to with the the digital object import template was introduced in 3.0.0/3.0.1 that was later caught in time to be part of the 3.0.2 release.
Please note that there is an accompanying article on Structured Agent Dates in ArchivesSpace v3.0.2+. That article and accompanying video are recommended for customers that are curious or heavily invested in understanding the structured date changes in 3.0+.
Please see the sections for 3.1.0 and 3.1.1 for longer explanations of these differences.
Where can I find more details on Agents?
The Agent changes in v3+ are the result of many years of work by both community members and AS developers. That work has been documented in JIRA Ticket ANW-429 and its related comments and linked tickets. Visit that ticket for the most in-depth look at the specifications and detailed work involved, there is a lot there!
There are also more details on the changes to the way date fields look and how date expressions migrate in 3.0.2 versus 3.0.1.
What else is there to know?
- A few users of ArchivesSpace versions 2.8.0 and 2.8.1 might encounter a bug fix upon updating to ArchivesSpace 3.0+, which is documented here. Atlas will be checking for this scenario upon updating, so if you don't hear from us, it does not apply to you!
- There was a bug in 3.0.1 that affected linking AOs to DOs using the DO_import spreadsheet. This bug has been resolved in 3.0.2.
- There was a bug related to the spreadsheet importer that switched XLink attributes for DOs in the spreadsheet importer; that bug has been resolved in 3.1.0.
- There were bugs in reorder mode in versions of 3+ up until 3.1.1, which solved the issues.
Impacts on Plugins for v3+
For any version past v3+
Since the Agents module is being completely refactored, any plugin that touches or relies on that module may be affected by the changes. Sites with plugins installed should ideally test their plugin behavior in a Sandbox before updating Production. Enterprise-hosted customers will have the option to test v3.0+ in their Sandboxes before updating Production, but should check to see if their plugins are also installed in their Sandboxes. Enterprise customers can email us at support@atlas-sys.com for assistance with your Atlas-hosted Sandbox.
For any version past 3.1.0
From the 3.1.0 release notes:
Due to some needed accessibility improvements for the public interface, some relatively minor styling changes have been made to views in some places. This may impact plugins used for styling these areas. Check plugins used to theme the public interface to determine if you need to make any changes locally to preserve your desired styling.
Configurations for v3+
Below are links to the default configuration files for the following versions. By clicking on one of these links you can modify the address in your address bar to navigate to the version of ArchivesSpace you are most interested in:
Please note that these links lead to the default view of that file; your actual config files lives on your ASpace server here at Atlas. If you wish to view the actual config file being used on your server you may request a copy by writing an email to support@atlas-sys.com.
Setting new configurations is not required as part of the update, but here is a summary of the new configuration options in AS v3+. Atlas can adjust these settings at any time, whether while updating to v3.0+ or afterward:
| Configuration Setting | Explanation |
|---|---|
AppConfig[:export_eac_agency_code] = false | This is a new configuration for v3+ that is set to false by default. You will not need to care about this configuration unless you will be exporting EAC records. |
Please let Atlas know if you would like to modify any of the above configurations as part of your update to 3+. All values listed above are the defaults.
API Endpoint Deprecations
Please see the official release notes for v3.0.1 for more information about the following deprecated API endpoints:
Endpoint.get('/repositories/:repo_id/archival_contexts/softwares/:id.xml')Endpoint.get('/repositories/:repo_id/archival_contexts/softwares/:id.:fmt/metadata')
Additionally, the following API endpoints remain deprecated, and will be removed from the core code of ArchivesSpace on or after 2021-10-30:
Endpoint.get_or_post('/search/subjects')Endpoint.get('/repositories/:repo_id/resources/:id/tree')Endpoint.get('/repositories/:repo_id/digital_objects/:id/tree')Endpoint.get('/repositories/:repo_id/classifications/:id/tree')
For more information, please review the official release notes. If you have any questions about preparing for the update or new features, please contact Atlas Support staff at 800-567-7401 x1 or email us at support@atlas-sys.com.