Bulk Updater (v.4+)
Beginning in ArchivesSpace 4.0, the as_spreadsheet_bulk_updater plugin (also known as The New School Bulk Updater) has been folded into core code.
Atlas will automatically uninstall this plugin for any institution already using it upon updating to version 4.0 or beyond. The original code for the plugin is unsupported as of v4.0's release.
This feature provides the capability to download a spreadsheet containing Archival Objects (AOs) from a specified Resource record. A user can then modify the spreadsheet to make changes to selected Archival Objects and a limited number of their fields. Once the changes are made, they can be implemented by uploading the spreadsheet back into ArchivesSpace in a new background job.
To download the spreadsheet, a Bulk Update Spreadsheet option has been added to the More menu in Resource records, available in either View or Edit modes. You'll need to select the AOs to include in the spreadsheet and then download the Excel file in order to make your edits.
See below for more details and optional configurations.
Things to know
Some things to note about this background job as of its introduction in 4.0.0:
- This job only works on Archival Objects and no other record types.
- The spreadsheet can only be accessed via a Resource record and only one Resource record worth of Archival Objects can be downloaded at once.
- Users will need Edit and Background Job permissions in order use the template.
- The template is only available as a .xlsx file. There is no equivalent csv version as of v4.0.0.
- You cannot modify the template to add new columns. The column options (i.e. which fields you can edit) are fixed and modifying the template will not change this. You may request new options by Submitting a Feature Request to ArchivesSpace.
- Be careful that only one user is attempting to update a record at one time. The job will fail if updates have been made to a record since the last time that record was updated.
How it works
Using this functionality is a three step process:
- Download a spreadsheet of the Archival Objects you wish to edit in bulk
- Make edits outside ArchivesSpace
- Upload spreadsheet to ingest changes
1. Download a spreadsheet of the Archival Objects you wish to edit in bulk
Navigate to the Resource record that contains the Archival Objects you wish to edit in bulk.
You will be brought to a new screen where you can select which components (archival objects) you wish to export for editing:
If you select the top-most box, you are selecting the entire collection and all of its components.
If you select a level with components nested underneath, like selecting a Series with children, you will automatically select everything under that level. You may wish to consider selecting only the components you wish to edit (and not every component) to reduce the likelihood of unintentional mistakes/edits to components you did not intend to update.
You cannot modify the template to add new columns. The column options (i.e. which fields you can edit) are fixed and modifying the template will not change this. You may request new options by Submitting a Feature Request to ArchivesSpace.
The following are the fields and sub-records that can be modified:
| Editable Fields/Subrecords | Editable Note Types |
|---|---|
| Level of Description | Abstract |
| Component Unique Identifier | Accruals |
| Ref ID | Biographical / Historical |
| Repository Processing Note | Conditions Governing Access |
| Publish? | Dimensions |
| Dates | Existence and Location of Copies |
| Extents | General |
| Instances | Physical Characteristics and Technical Requirements |
| Digital Objects | Physical Description |
| Related Accessions | Processing Information |
| Languages | Related Materials |
| Scope and Contents | |
| Separated Materials |
You have additional options about the fields you want included:
-
Minimum Sub-records: The minimum number of each of the sub-records to include on the spreadsheet.
- For example, if Date is selected and the minimum sub-record is set to 3, there will be three instances of the Date sub-record and its fields (Label, Expression, Begin, End, Certainty) in the resulting spreadsheet. If you had more than three extant "Date" sub-records, only the first three would be included.
-
Extra Sub-records: The number of sub-records to include in addition to the greatest number found in any of the selected records. This option allows for the creation of new sub-records in the archival object record in the resulting spreadsheet.
- For example, if you have one Date sub-record and you set 2 in this field, the resulting spreadsheet would have three Date sub-records total: the one extant date, plus the two extra.
-
Minimum Notes: The minimum number of each type of Note to be included on the spreadsheet.
- For example, if the note Abstract is selected and the minimum notes is set to 3, there will be three instances of the Abstract sub-record and its fields (Label, Content) in the resulting spreadsheet. If you have more than three extant Abstract notes, only the first three would be included.
2. Make edits outside ArchivesSpace
The resulting file is a Microsoft Excel Workbook with a frozen pane including the first three columns:
id = the archival object id, a number used by ArchivesSpace to reference the record
version = the lock version of the file, which is a value meant to track edits. If another user edits one of the components listed in this file, its lock version number will change and will no longer match the value in this field. In that scenario, ArchivesSpace will reject the changes when you go to upload this spreadsheet, in order to prevent a change to a changed record. This behavior is intentional and is not considered an error.
title = the title of the record, which is always included for your reference
The rest of the spreadsheet will contain the columns and numbers of columns based on the selections you made in Step 1.
3. Upload spreadsheet
You can upload the saved spreadsheet by clicking on the Create menu, select Background Job and selecting Bulk Archival Object Updater.
You will see an additional option:
Upon uploading, your upload will be attempted. Read the background job log carefully to track successes and be sure and check on your changes afterwards, especially when getting used to new functionality.
Configurations
Please note that there are two configurations (available in the configuration file) that are relevant to the bulk importer functionality:
AppConfig[:bulk_archival_object_updater_apply_deletes]
The default value is false.
If enabled, the importer will drop subrecords (dates, extents, instances or notes) when all spreadsheet columns for that existing subrecord have no values. As not all subrecord fields have a corresponding column in the spreadsheet, you may unwittingly drop a subrecord which has data in other fields. Thus the recommended default is false, which is safer for data.
AppConfig[:bulk_archival_object_updater_create_missing_top_containers]
The default value is false.
This configuration relates to the default value of the Create Missing Top Container checkbox available when creating the job. When set to false (default behavior), the checkbox will be unchecked by default. When set true, the checkbox will be checked by default. A user may always override this value when initiating the job.
Please note that this configuration doesn't enable or disable this functionality, it only sets the default value of the checkbox.