ArchivesSpace data tools

Eventually this repository will contain code to generate documentation of the ArchivesSpace data model, along with the generated documentation.

Until then, please see: Interim data reference recommendations.

We are also adding tools used to convert/ingest ArchivesSpace data to this repository.

Table of Contents

• Setup and usage
  • Setup
    • Local copy of ArchivesSpace code
    • Get dependencies
    • Configuration
    • Notes for Dockerized ArchivesSpace
  • Usage
    • Thor CLI
    • Console
  • Documentation/reference

Setup and usage

Setup

Local copy of ArchivesSpace code

If you have not already cloned the ArchivesSpace GitHub repository (or a fork of it), you will need to do that.

You will need to add the path to this local repository in your config file, described below.

⚠️

Note that you will need to clone the ArchivesSpace repo even if you’re using a Dockerized instance of ArchivesSpace. The main reason is that the Docker image is a compiled distribution rather than a source tree. The data tools don’t have any way to access the "filesystem" inside Docker. See Notes for Dockerized ArchivesSpace below.

If you need to "use" a specific version of ArchivesSpace to pull info using this tool, you will need to check out the branch/tag for that version in your repo before using this tool.

Get dependencies

bundle install

Configuration

Copy sample_config.json to ~/.config/aspace-data-tools/config.json.

Update the copied file as needed. For use of this tool to generate data documentation, you shouldn’t need to make any changes.

With no modifications to the config, the tool will connect to the ArchivesSpace test instance, which is built from the master branch of ArchivesSpace.

If significant changes have been pushed to master, but not yet released, you may wish to switch to a locally-running instance of the latest release.

⚠️	You should switch to a locally-running instance, or a real target instance online, before using any commands that post data to the instance.

💡	thor config show will write your current config to STDOUT.

Notes for Dockerized ArchivesSpace

There are two configuration changes you’ll need to make in order to use this tool with Dockerized instances of ArchivesSpace.

1. In ~/.config/aspace-data-tools/config.json, change client_base_uri to http://localhost/staff/api (not https, and not 127.0.0.1).

2. Uncomment these lines (currently lines 48-50) in proxy-config/default.conf within your local copy of the Dockerized ArchivesSpace. (For example, ~/aspace-docker/archivesspace/proxy-config):

location /staff/api/ {
  proxy_pass http://app_api/;
}

Note: It’s possible to configure multiple Dockerized ArchivesSpace instances by changing the NGINX_PORT variable (see .env in the root directory of the Docker package) and ensuring different instance names by editing docker-compose.yml for each instance. It’s also necessary to change the MySQL and Solr host port mappings to something unique. (See also "Setting Up Multiple Local ASpace Instances for Client Projects" in data-migration-docs.) If you switch configurations, make sure that you edit ~/.config/aspace-data-tools/config.json to reflect the correct instance before using aspace-data-tools.

Usage

Thor CLI

This application has a Thor-based CLI.

Do thor list to see all command groupings.

To see individual commands in a group, do something like thor repo.

To see all options/help for an individual command, follow this pattern:

thor create help resources

Console

You can also use the bin/console command to interact with the code. This is useful for experimenting, development, or doing ad-hoc stuff with existing pieces of code for which no Thor command exists.

ADT is a shortcut/alias for AspaceDataTools.

# Pull all record type schemas and convert to RecordType objects
# Useful for querying across the record types
rts = ADT::Doc.rectypes

# Example query across record types to find those with a `position` field,
#   but no `ancestors` field
rtna = rts.select do |rectype|
  rectype.schema["properties"].key?("position") &&
    !rectype.schema["properties"].key?("ancestors")
end

# Get a specific record type
r = ADT::Doc.get_rectype("resource")

# Get an archivesspace-client instance with which to do make ad hoc API calls
client = ADT.client

Documentation/reference

See the /doc folder.

This includes (of note):

fields.csv

Listing of all(ish) fields. See known issues relating to this file. More columns, indicating things like data type and cardinality, will be added as we figure it out/have time.

data_model_problems.adoc

Just a note that these are "problems" for making this tool do what we want, not necessarily fundamental data model problems.

dev_decisions.adoc

This is important to read if you need to be sure you understand what is included/excluded in various output, or how certain things are determined.