How to Integrate with ArchivesSpace

Owned by Max Eckard
Last updated: Sept 19, 2023 by Paige Monlux
6 min read

You’ve taken a look at all the benefits of integration with ArchivesSpace and you’re ready to get started with an integration of your own. This resource will take you through a step-by-step guide to integrating with ArchivesSpace, suggest various methodologies for integration and, for those not quite ready for an integration, point to resources for programmatically working with data and systems like ArchivesSpace. This document attempts to provide a general overview of what is involved when considering an integration project and helps with requirements, advocacy, and planning.

Step-by-Step Guide

Integrate with ArchivesSpace in seven easy steps!

Keep in mind that the following steps might not apply to each and every integration project, or they might manifest in different ways depending on institutional context, but regardless they should be helpful aspects to consider at the outset.

Step 1: Identify need for an integration

Your first step should be to identify a potential need for an integration, whether at your institution or in the community at large. It is often helpful to identify the institutional need for an integration and explore potential use cases, user stories, or preliminary requirements.

Check to see if an integration with a particular system (or the function that system performs) already exists (at any stage of development) or is being planned. The Integrations with ArchivesSpace page on the ArchivesSpace website and Awesome ArchivesSpace list are good places to start.

Step 2: Reach out to the community for ideas and/or support

Reach out to the community via the ArchivesSpace Users Group and Member Representatives lists, as well as the ArchivesSpace Google Group, or find a potential partner with Who’s Using Archivesspace. You may be able to generate additional ideas or use cases for your integration, or even find partners to help with development resources. This process can also help you identify whether the integration you have in mind is generalizable so that it can be used by other institutions.

Step 3: Build a case for integration and define technical requirements

The following section will differ for each institution and integration, but the following provides a rough guide for beginning your integration work. Requirements gathering and advocacy are not always linear tasks, so one may happen before the other, or concurrently.

3A:  Define the requirements and/or create a specification for the integration

Define the requirements for your integration, focusing especially on “what” needs to happen (“how” it happens can wait for later stages) and/or create a specification that outlines one or more aspects of the work to be done. Our suggested best practice is to gather user stories, create personas, make functional requirements, and create preliminary data maps for each integration. However, such work might not be necessary for every integration.

Here are a couple of examples you can use to model your requirements or specification.

Requirements:

Specifications:

Note: Be wary of any integration that changes your backend database, as it could be hard to keep updated. If your specification requires a change to the ArchivesSpace data model, contact the ArchivesSpace Technical Lead (Laney McGlohon, laney [dot] mcglohon [at] lyrasis [dot] org) for advice, guidance and possible assistance.

Furthermore, if the ArchivesSpace Program Team decides that this integration should be worked into the ArchivesSpace core code due to universal applicability and use, you will need to work closely with LYRASIS, the Organizational Home of ArchivesSpace as well as a Registered Service Provider, and Hudson Molonglo, an ArchivesSpace development partner.

3B: Build a case for the integration and gain support at your institution

Building a case for supporting integration work will differ at each institution, but there are some strategies and talking points to help you make the case for institutional support.

  • Tying the work to institutional values and mission can prove invaluable in garnering resource support for your work. If your institution has community development as part of its mission, you could tie the open source software development back to that part of the mission. It is often easier to secure support when the work is supported by your institution’s ideology.

  • Estimating the resources required in a formal way can create a useful advocacy document for superiors to refer to. Removing as much uncertainty from the process as possible makes it easier for someone to say yes to the work.

  • Consider suggesting multiple types of funding methods. Not all work has to be completely funded by an institution. Funding methods to consider: grant, working with a vendor, open source collaboration, do it yourself in your spare time (not ideal).

Step 4: Design and develop according to your project specification

Document and, if possible, be open about your process and code, and encourage any third-party partners to be open as well. Consider posting updates to the user listserv periodically and include links to your project documentation if publicly available. Likewise, strive to make your integration generalizable so that it can be used by other institutions. These aren’t absolutely necessary, but both are important parts of what it means to be a member of an Open-Source Software community.

If you haven’t already, this is also a good time to plan for the ongoing maintenance of your project after development is completed. Is your institution committing to ongoing maintenance? If so, plan for and designate those responsibilities. How will you ensure that your integration does not tie you to outdated versions of any particular system? How will users reports bugs or request enhancements?

Step 5: Test your integration

As with the two previous steps, testing your integration is an important part of any software development project. Get in contact with stakeholders to ensure that your integration meets the requirements that guided its design and development. You should test your integration with “test” or “fixture” data that closely resembles real data (even “weird” data), for example. Likewise, your integration should: perform its functions efficiently; be usable, even for those that weren’t intimately involved with its design and development; and be able to be installed and run in its intended environments. Of course, test in a development environment first!

Step 6: Go live with a full release!

Hurray! Time to celebrate!

Step 7: Announce the completion of your integration to ArchivesSpace community

ArchivesSpace strives to maintain an architecture that is integration-friendly and the program is always interested in hearing from developers and software projects interested in building connections and integrating their applications with ArchivesSpace. If possible, make your code publicly available so others can test or add to it.

The ArchivesSpace REST API

The ArchivesSpace RESTful Application Programming Interface (API) is a programmatic interface to the ArchivesSpace backend, and consists of a number of exposed endpoints used by the backend server to edit records in the application.

Note: Using the API may be better than doing direct SQL updates to the backend server, as it helps to shield you from accidentally failing to update a related table, creating broken links or using receiving errors when using SQL code written for a previous version of the database.

Software Development Kits

There are a number of ArchivesSpace Software Development Kits (SDKs), libraries that allow ArchivesSpace to interface with a particular programming language, available for developers:

Common Metadata Standards

ArchivesSpace makes use of common metadata standards. Using common metadata standards (or systems that make use of them) such as EAD, PREMIS (and PREMIS Rights Statements), MARC and MODS, as well as content standards like DACS, helps to ensure that your data is portable between systems.

Since an integration necessarily means that you’ll be maintaining data in one or more systems, be sure to think about Systems of Record. That is, you should know which system you’ll turn to as the authoritative data source for a given data element or piece of information.

Not Quite Ready for an Integration?

Perhaps you make use of a number of disparate systems in your workflows, but you're not quite ready for an integration. It may be time to invest in some tools and skills to programmatically work with your data so that you can move data back-and-forth between systems more efficiently. Here are a couple of general and ArchivesSpace-specific resources to get you started...

General:

ArchivesSpace-specific: