ArchivesSpace Repository Move Tools

Export a repository from one ArchivesSpace instance. Import it into another ArchivesSpace instance.

Table of Contents

• Warnings/caveats
• Requirements for use of this tool
• Initial setup
  • Clone this repo to your local machine
  • Set up an ArchivesSpace development environment
    • Get the source code for the target version of ArchivesSpace
    • Replace streaming_import.rb file in source code
    • Run ArchivesSpace development environment
      • Database
  • Configure your repo move project
  • Ensure correct Ruby version is installed
  • Get required Ruby dependencies
  • Get ArchivesSpace common library for this app to use
• Usage
• Code history / credit

Warnings/caveats

Original use case of this tool was:

• Export a repo from one ArchivesSpace instance

• Import it into a new, empty ArchivesSpace instance

🔥	Expect trouble if you are moving a repo into a non-empty ArchivesSpace. Expect even more trouble if you are moving multiple repos from one ArchivesSpace into another ArchivesSpace.

⚠️

There are known and potential issues with this tool related to: Mismatch between original use case and the uses to which it is now being applied Odd data that may be hiding out in the exported records, but will not validate on import See: Known issues, unresolved Potential/suspected issues still untested Also: All imported records will have a created/updated date of when they were imported. The created/updated by user will be the user who performed the import. The URIs of imported records will change. If you have external systems or documents referring to records in repos that will be moved, have a plan for that.

Requirements for use of this tool

• API access to the ArchivesSpace instance (source) from which repo will be exported and the ArchivesSpace instance into which the repo data will be imported (target)

• Target ArchivesSpace only: Ability to replace the existing backend/app/lib/streaming_import.rb file with this repo’s /support/streaming_import.rb file for the duration of the import process. In practice, this means you will need to run ArchivesSpace on your machine, with the real target ArchivesSpace database loaded. After import is complete, you can export the database to load back into the actual target ArchivesSpace instance.

• Source and target ArchivesSpace instances should be the same ArchivesSpace version. Trying to import data into a different version of ArchivesSpace may result in validation errors that this tool will not handle.

• An operating system currently supported for ArchivesSpace development, as listed in the ArchivesSpace Tech Docs > Development environment overview. You _may be able to use this tool on other systems, but the setup and commands to achieve it will be different.

• Java. If you will be running the target ArchivesSpace in a development environment, setting that up environment includes installing Java. If you will be running the target ArchivesSpace in Docker, you may need to install Java yourself. We recommend you follow the Java installation instructions in the ArchivesSpace Tech Docs > Development environment overview, using .

• rbenv

Initial setup

Clone this repo to your local machine

All other instructions/commands assume you are in the base directory of the local repo (where this README file lives).

Set up an ArchivesSpace development environment

ℹ️

We use ArchivesSpace development environment because: We need to replace a code file inside the ArchivesSpace application itself Typically we only need to run the backend of ArchivesSpace to use this tool If issues arise, we may wish to use pry debugging to explore what is happening in the ArchivesSpace code.

Get the source code for the target version of ArchivesSpace

You can:

• Clone https://github.com/archivesspace/archivesspace (or your fork of it) and create a branch from the commit tagged with your release (Find the commit/tag on the Releases page)

• Download the source code for the release from the Releases page and decompress it locally.

Replace streaming_import.rb file in source code

Copy this repo’s support/streaming_import.rb file into your ArchivesSpace source code at backend/app/lib/streaming_import.rb.

Run ArchivesSpace development environment

cd into the base of your source code location and follow ArchivesSpace Tech Docs instructions for running development environment.

Recommended: Install mise and use it to install Java as per the Tech Docs instructions.

Unless you need to view records in staff UI, public UI, or Solr for some reason, just run the backend/API:

./build/run backend:devserver

Database

See: Loading data fixtures into dev database

If you have API access to the source ArchivesSpace instance and want to export directly from that instance, use the target ArchivesSpace database in your dev instance.

You can also:

• Start with the source ArchivesSpace database in your dev instance

• Export repo(s) from source

• Stop dev instance

• Load target ArchivesSpace database in dev instance

• Restart dev instance

• Import

Configure your repo move project

Copy ./sample_config.json to ~/.config/aspace-repo-move-tools/config.json and customize your settings.

When you indicate the aspace_version, make sure it begins with "v", e.g. "v4.1.1".

The sample file assumes you’ll be switching from source to target ArchivesSpace database in your dev instance, so the login settings are the same for both source and target.

The source section has the ArchivesSpace test server base_uri commented out. If want to export from that, uncomment that line and comment out the initially active line.

You can also enter the base_uri and login credentials of any source site you have API access to, in order to export from that site.

See Checks and fixes configuration for details on that section of the config.

❗	If you are using a real site with real credentials as source, you are putting those credentials in a plain text file on your computer, which is not great security practice. Make sure you delete the project config or revert it back to the dummy admin/admin logins as soon as you can!

Ensure correct Ruby version is installed

Installs the version of ruby from this project’s .ruby-version file if you don’t already have it

rbenv install -s

Get required Ruby dependencies

bundle install

Get ArchivesSpace common library for this app to use

If you don’t already have the common library for your configured aspace_version, this command retrieves it and puts it in the /vendor folder.

thor setup common

Usage

See Usage documentation page.

Code history / credit

This code initially started off as a fork of hudmol/repository-importer, which was developed by Hudson Molonglo Pty Ltd in 2016.

Mark Cooper and Jacob Shelby made changes and additions to support Lyrasis use cases and ArchivesSpace in April 2022.

Jacob Shelby made changes to include Event records in the export process, and to fix resulting import errors by making changes to streaming_import.rb

In December 2024, Kristina Spurgin assumed responsibility for this repository. Because we identified significant changes needed for new use cases, and Hudson Molonglo did not want to maintain the tool/deal with PRs on it, we unforked the project and renamed it to aspace-repo-move-tools. At this time an issue where tree records were not added in the correct order was fixed.

In early 2026, Olivia Solis began to contribute test data to address known and suspected issues given the changes in use case for this tool.

In March 2026, Kristina converted the project to pure Ruby (or JRuby) with a Thor CLI.