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
  • 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.

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.

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.