Updating to ArchivesSpace Version 2.7+ FAQ

Print Friendly and PDF Follow

Please note that the one hour webinar Preparing for ArchivesSpace 2.7.0 is available to view at anytime. The webinar provides an overview, with examples, of most of the content below. Please read on for additional details.

What is happening in ArchivesSpace v2.7.0 and beyond?

Among other changes in AS v2.7.0 (release notes), the most substantial is that there are three new *required* fields for Resource records, each having to do with language. The three required fields are:

  • Language of Materials (a new sub-record)
  • Language of Description (an updated field under Finding Aid Information)
  • Script of Description (a new field under Finding Aid Information)

Do I still have to worry about this if I'm going into v.2.7.1, or if I wait for v.2.8.0?

If you are transitioning from any version of ArchivesSpace that is v.2.6.0 or prior into any version of ArchivesSpace that is v.2.7.0 or after then you still need to consider the factors listed in this FAQ. If you've already passed the 2.7.0 barrier and enacted whatever changes you needed to make, you do not need to take any additional actions for Languages from that point on.

Can you tell me more about these fields?

Language of Materials refers to the materials being described (i.e. the collection itself) and is required by DACS 4.5. In both EAD2002 and EAD3, it is represented by the EAD tag <langmaterial> and attribute @lang.

Language of Description and Script of Description refer to the description itself (i.e. a collection in Russian can be described in the English language using Latin script; conversely, a collection of English language materials can be described in Russian using Cyrillic script).  In EAD2002 these were handled by <langusage> and its sub-elements and attributes; in EAD3 these are handled by <languagedeclaration> and its sub-elements and attributes.

For more on these elements in EAD, see other sections of this FAQ.

What exactly is changing?

Prior to v2.7.0 there were two ways of recording Language of Materials:

1. A Language of Materials field has always been present in Resource records, found under Basic Information > Language. Users could select a single Language of Materials from a drop-down menu, ex. English. Only one language could be selected even if multiple languages were represented in a collection.

Prior to v2.7.0, saving a record without a value in the Language of Materials field would prompt a yellow warning message.

In v2.7.0 and after, the Language of Description is now its own sub-record, like Dates and Extents, and allows for more than one language to be listed (by creating multiple sub-records). The new sub-record has two note options: Add Language (controlled value list- *required*) and Add Language Note (free text field - optional). You will no longer see the old field listed under Basic Information. You will not be able to save a record without providing this information, as it will prompt a red (required) warning message.

2. A Language of Materials note has also always been present in Resource records, found under Notes > Language of Materials. This was a free text field like any other note. Multiple languages could be listed in the free text note, ex. “This collection has materials in English, Russian, and German.”

The new sub-record Add Language Note option (free text) is the new equivalent to this note. You will no longer see the Language note as an option under Notes.

Language of Description has also always been present in Resource records, found under Finding Aid Information > Language of Description. This was a free text field that was not controlled by a dropdown list. Institutions that imported or migrated from EAD might have encoded info in this field, such as, “This collection was described in <language langcode= "eng">English</language>.”

This field has now split into two different fields that offer parallel ways of recording this information: a controlled value drop-down list (*required*), and a free-text note field (optional).

Script of Description is entirely new to ArchivesSpace as of v2.7.0. This field is now present alongside the Language of Description under Finding Aid Information > Script of Description and is controlled by a dropdown list of all scripts. It is *required*.

You can see these fields on the ArchivesSpace Sandbox (currently at v2.7.1 as of this writing), which can assist in previewing how you may wish to use this sub-record in the future. The login information is username/password admin/admin.

Why is this happening?

In short, these changes support better adherence to standards, including DACS and EAD3. Prior to v2.7.0, EAD3 exports could not supply this data because it was not recorded in a way that was actionable, or not recorded at all.

For technical details about this work and the specification itself, please review this JIRA ticket and its accompanying documentation. This is a great look at the community + ArchivesSpace in action.

What records will be affected?

Please review this document provided by ArchivesSpace for a list of all record types that now include the Languages sub-record. Since the most important changes only affect Resource records, Resource records will be the main topic of this FAQ

What exactly is happening to my pre-existing Resource records?

Your Resource records will migrate from whatever version of AS you are in to v2.7.0. You will be able to view your Resource record data as usual from either within the staff interface or on the PUI. However, there will be two effects:

  • New values will have been assigned to fields that either had no values in them before (i.e. missing Language of Materials or Description of Materials) or which did not exist before (i.e. Script of Description), and these values will be in your data when you open a pre-existing resource record. These values will also display in the PUI. 
    DescriptionValues.png
  • While you can view your data, you will not be able to edit and save your Resource records without populating any required fields that are missing. Which required fields are missing depends on your pre-existing data. Expected scenarios are covered in the “Which plugins do I need?” section of this FAQ.

To address both these effects, ArchivesSpace has created three plugins to assist in populating all the now-required fields. Atlas will install the plugins you request, and your local ArchivesSpace administrator will be able to run them.

What do the plugins do?

ArchivesSpace has developed three plugins to help make global changes to pre-existing data. These plugins get installed on v2.7.0 and beyond are not intended to be installed on prior versions of ASpace. Note that the plugins are only designed to help institutions meet the new minimum requirements in resource records; they are not intended to account for every scenario or to assist in cleanup. Whether or not you will need to undertake additional cleanup after running the plugins will depend on your data.

Which plugins do I need?

Since practices vary widely by the institution, there are a lot of variables in determining which plugins are right for you. This comprehensive section is meant to address all the different variables that may apply to your data.

Start by reviewing the following grid, which should help you to isolate what of the below information is actually applicable to your situation. This grid is meant to act as a matrix for decision making, and you can even print it out and select which plugins you want Atlas to install after reviewing this entire section below. With this grid in mind, please read on to determine which plugins you need.

 

Requirement

 

Relevant Plugin

Atlas to Install

Language of Description Optional in prior versions, now required. batch_update_lang_and_script Recommended for all customers.
Script of Description Did not exist prior to 2.7.0
Language of Materials If you only have values in Basic Information > Language of Materials No plugin required! These will migrate and fulfill the requirement.
If you only have notes under Notes > Language of Materials

batch_update_langmaterials_from_note*

Let Atlas know whether to install
If you have values in both Basic Information > Language of Materials and under Notes > Language of Materials No plugin required! These will migrate and fulfill the requirement.
If you have zero Language of Materials information in any of your resource records batch_update_langmaterials* Let Atlas know whether to install
*- Please note that Atlas does not recommend installing both batch_update_langmaterials_from_note and batch_update_langmaterials. If you believe that you need both, you should run batch_update_langmaterials_from_note BEFORE batch_update_langmaterials, because one cancels the other.

Before you begin determining which plugins are necessary for your data, remember to consider whether your instance of ArchivesSpace has multiple repositories and whether languages were recorded in different ways in each. Each plugin will give options on whether to enact changes to one or all repositories.

Selecting plugins:

It is expected that one of the plugins will be useful to pretty much everyone. It will handle two of the fields, Language of Description and Script of Description, which will be the easiest to start with.

2 of the 3 required fields can be addressed with just one plugin:

  • Language of Description and Script of Description

If your institution has only ever written finding aids in one language, then you can take quick action without a lot of analysis. The batch_update_lang_and_script  plugin will handle both the Language of Description and Script of Description fields in one action. If all your finding aids have been written in English, you can set English and Latin as the two values and run the plugin. This is the only action you’ll need to take for these fields if all your records are written in the same language. Please see the plugin page linked above for instructions.

1 of the 3 required fields can be addressed by two different plugins:

  • Language of Materials has more considerations:

Language of Materials is expected to be highly variable (since collection materials themselves and prior practices are highly variable), so it is recommended that you review a) whether you have recorded this information in the past, and b) how you recorded this information in the past.

There are two primary ways of recording the Language of Materials information: the controlled dropdown menu found in Basic Information > Language of Materials, and a Language of Materials free text note, found under Notes > Language of Materials. In upgrading to v2.7.0 you should assess whether and how your legacy description recorded this information:

If you only have values in Basic Information > Language of Materials in any version prior to v2.7.0:

  • If you already have values in Basic Information > Language of Materials, this information will migrate as part of the update to v2.7.0. The pre-existing values will migrate to the new controlled value list under the new Languages sub-record in your Resource records. The presence of this information fulfills the requirement of the sub-record. You will not have to take any additional action for these records. You will not need a plugin for this requirement.
  • To aid in your analysis of this before updating, this field can be viewed as part of a pre-existing report. From the staff side, navigate to Create > Background Job > Create Report > Resource List Report. These Language fields will be available for analysis in that report.

If you only have notes under Notes > Language of Materials in any version prior to v2.7.0:

  • Those notes will move from under the Notes heading to under the new Language of Materials sub-record as part of the update to v2.7.0. They will display as text. However, the presence of this note does not meet the new requirements of the sub-record, which means you will be able to view your resource records as usual but will be prevented from editing and saving them until you add a Language value using the drop-down menu in the Languages sub-record.
  • The batch_update_langmaterials_from_note* plugin was designed to assist in this scenario. Please see the plugin page for instructions.
  • Note that this solution will not work if you recorded multiple languages in a note, such as, “This collection contains materials in English, German, and Russian.” The plugin will match the text, but you can only select one language and the plugin will not work on a repeat cycle, i.e. you cannot run it first for English, then for German, then for Russian.

If you have values in both Basic Information > Language of Materials and under Notes > Language of Materials in any version prior to v2.7.0:

  • The values in Basic Information > Language of Materials will migrate to the new controlled value list under the new Languages sub-record in your Resource records as part of the update to v2.7.0. The presence of this information fulfills the requirement of the sub-record. You will not have to take any additional action for these records.
  • The notes in Notes > Language of Materials will move from under the Notes heading to under the Language of Materials sub-record. They will display as text. Though this note alone does not meet the requirements of the sub-record, since it is paired with a Language (per the above), so you will not need to take any additional actions on these records.

If you have zero Language of Materials information in any of your resource records:

  • The new Language of Materials sub-record will be blank after updating to v2.7.0, which means you will be able to view your resource records as usual but will be prevented from saving them until you add value.
  • The batch_update_langmaterials* plugin was designed for cases where there is no data, however, since it will take global action, it will use a single language across all holdings. If you believe your repository holds materials in more than one language, the use of this plugin will create an inaccurate description. Please see the plugin page for instructions.
* Please note that Atlas does not recommend installing both batch_update_langmaterials_from_note and batch_update_langmaterials. If you believe that you need both, you should run batch_update_langmaterials_from_note BEFORE batch_update_langmaterials, because one cancels the other.

What if a language isn't listed?

The languages in the new drop-down fields are sourced from Language ISO 639-2, and for that reason the list cannot be edited in the interface. There is a range of values that would allow for local values, but their definition and use would have to be handled via a custom plugin and database addition.

If a language is not listed, be sure and browse for language options that are plural and may include the language you are trying to describe, such as Afro-Asiatic languages and Otomian languages as examples.

There is also Uncoded languages and an Undetermined value that would fulfill the drop-down requirement in cases where a language is not listed or not known.

An additional language note can be added to provide the accurate language information once the drop-down requirement is fulfilled.

What if I have multiple languages?

There is a drop-down value of Multiple languages. The alternative is to list each language individually, which the language sub-record allows for.

We import and/or export records. What effect does this have on imports and exports? What effect does this have on EAD?

Per this document, the following exports will be affected: MARCXML, EAD and PDF for resource records and METS, MODS and Dublin Core for digital objects.

If you import/export EAD, please note the following differences between EAD2002 and EAD3 regarding Language and Script of Description (Language of Materials will import/export the same):

  • In EAD2002, the Language of Description and Script of Description were handled by the <langusage> and its subelements. This element is now obsolete in EAD3.
  • In EAD3, Language of Description and Script of Description are handled by <languagedeclaration> and its subelements:
 <languagedeclaration>
      <language langcode="eng">English</language>
      <script scriptcode="Latn">Latin</script>
</languagedeclaration>

Is there anything else I should know?

Response and load time changes

Atlas would like to alert hosted customers currently running any version prior to v.2.6.0 that there are known speed differences between v.2.5.2 and all subsequent versions. Atlas has worked directly with ArchivesSpace  and investigations have resulted in code changes that will be included in the next release (expected in early 2020). However, there are still significant speed differences that will be detected by customers moving from v.2.5.2 or before. ArchivesSpace is aware of these concerns and Atlas will continue to work on behalf of our customers to address these ongoing issues however possible.

Pre-existing plugins

Due to the scale of the changes in this version, it is expected that some pre-existing plugins may be either incompatible with v.2.7.0 or will need to be updated to a more recent version. If you currently have plugins installed on any version prior to v2.7.0, Atlas recommends checking the code repository (usually GitHub) to see if the developer of your plugin(s) has recent release notes or any other information on whether the plugin is compatible with v.2.7.0. If you experience any strange behavior of the application upon updating to v2.7.0 or beyond, please email support@atlas-sys.com.

Questions?

If this article didn’t resolve your issue, please take a moment and answer a few questions to help improve our documentation:

Feedback