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 later?
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.
- 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. Note that the plugins only work for Resource records, since those are the only records where requirements must be met.
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 | 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 | |
Before you begin determining which plugins are necessary for your Resource records, 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), 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 values.
- 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 inaccurate description. Please see the plugin page for instructions.
Running Plugins
Please see the individual website for each plugin you need to run for screenshots and instructions:
batch_update_langmaterials_from_note
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>Recommended: Set defaults
After you update to AS v.2.7.0 or later, you can save time in the future by setting Language defaults. If your most commonly used Language is English and your most commonly used Script is Latin, you can:
Navigate to System > Manage Controlled Value Lists >
Language ISO 639-2 > Set English as default, pause for AS to save
Language Script ISO 15924 > Set Latin as default, pause for AS to save
If you are unable to see any of those menus, someone with a higher level of permission (usually a Sys admin) will need to set those defaults.
You can also add your default languages to your Resources template, by navigating to Browse > Resources > Edit Default Values > Resource > set defaults > Save. To make sure this functionality works for you, you'll also need to navigate to any of the Preferences Menus in the upper rightmost corner of the staff interface:
In any of those menus, check Pre-populate Records? > Save and the Resource template will populate when you create a new Resource record.
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.