What's new in ArchivesSpace v3.0.x

Webinar Resources

Please note that there are two ArchivesSpace webinars detailing the new Agents module. The first, An Introduction to ArchivesSpace v3.0.0 and the Expanded Agents Module provides an overview of the changes associated with v3.0.x. 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 two subsequent point releases. ASpace v3.0.x 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.x in general. Staff at ArchivesSpace Member Institutions are encouraged to reference the ArchivesSpace Help Center for additional documentation.

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.x was 2.8.1 and there have been minor releases since 3.0.x debuted. Here are convenient links to Atlas articles on previous and subsequent versions. Information about 3.0.x point releases is included in this article.

Improvement Highlights for v3.0.x

The Expanded Agents module!

The expanded Agents module steals the show for v3.0.x 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.x comes with a new two-step process to generate and then use a template for linking top containers to archival objects; we recommend you read the original documentation provided by Harvard here.

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.0.x 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.

FAQs for v3.0.x

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.0.x 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.0.x, 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
• 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.0.x; 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.0.x 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, and 3.0.2?

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.

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 are heavily invested in understanding the structured date changes in 3.0+.

Where can I find more details on Agents?

The Agent changes in v3.0.x 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.

Impacts on Plugins for v3.0.x

For any version past v3.0.x

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.

Configurations for v3.0.x

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:

• Default config for 3.0.2

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.0.x. 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.0.x that is set to false by default. You will not need to care about this configuration unless you will be exporting EAC records.

info

Please let Atlas know if you would like to modify any of the above configurations as part of your update to 3.0.x. 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.