Skip to main content

What to Consider when Evaluating Third-Party ArchivesSpace Plugins

info

Please see the webinar Proactive Change Management for Plugins for critical advice about the use of plugins in ArchivesSpace.

This article brings together advice and practical steps to consider when selecting plugins to add to your instance of ArchivesSpace or when evaluating plugins you already have installed, in preparation for a new release.

The number of plugins available for the ArchivesSpace application is one of its strengths as an open source application, but also one of its pitfalls, as it can be difficult or impossible to tell whether a plugin is maintained and compatible for the version you're on. As the ArchivesSpace application matures and improves, the plugin landscape becomes populated with outdated and unnecessary plugins, or worse, plugins that are abandoned and ultimately fail.

Consider the commitment you are making​

For every plugin installed in ArchivesSpace, you increase the risk that your instance may eventually become incompatible with the plugins you have installed. That is because each plugin represents the work and commitment of a developer that must maintain that code in a timely way to keep the plugin up-to-date, and with each update to core code (i.e. each new version) there is a chance that your plugins will either need to be updated or uninstalled.

Atlas encourages customers to consider the accumulation of risk in installing multiple plugins, and also encourages annual or semi-annual reviews of installed plugins and their relevance, especially in conjunction with new releases of ArchivesSpace.

Confirm that the functionality doesn't already exist​

ArchivesSpace changes frequently, and over time some of the most popular plugins and their feature sets have been wrapped into core code, meaning you no longer need to install a plugin to get your desired behavior. Knowing whether a plugin has been incorporated into core code isn't obvious; announcements of such integrations are included in the ArchivesSpace release notes but not on the plugin repositories themselves. This means that you could navigate to a GitHub page for a plugin and see no evidence that the plugin is moot; instead, you'd have to make a habit to read the ArchivesSpace release notes for each version as they are made available. Knowing exactly what a plugin does helps with the ambiguity here.

If you are not already certain, Atlas recommends that you first confirm that the behavior you are seeking in a plugin is not already part of the most recent version of ArchivesSpace.

If you are not already on the most recent version, Atlas recommends that Enterprise customers at Atlas request your Atlas-hosted Sandbox be updated to that version. If you do not host a sandbox with us, you can use the official ArchivesSpace Sandbox at https://sandbox.archivesspace.org/staff/, where the username/password is admin/admin.

The following are examples of plugins known to have been wrapped into core code and are no longer relevant:

  • as_spreadsheet_bulk_updater (aka the New School updater)
  • aspace-import-excel (aka the Harvard spreadsheet importer)
  • component_levels
  • ArchivesSpace Box Search Plugin
  • as_accession_links
  • additional_contact_details
  • component_levels
  • publish_partial_trees
  • Container management

The list above is not comprehensive.

Inspect the source repository for statements or clues to its status​

Plugin are often left online despite the code being out-of-date or irrelevant and the only way to determine each plugin's status is by reading the repository (repo) for clues to its compatibility with your version. This information is also in a state of flux near new releases, where the weeks or months after a new release represent a time when the repository may be updated, but the time-frame is unclear. This section of the article is meant to help you determine whether the plugin is:

  • Abandoned versus actively maintained
  • On the main branch or a fork
  • Compatible with your version of ArchivesSpace

We recommend you read all these sections for the best possible outcome in making determinations about plugins. For example, you may determine something is maintained, but also that it is not compatible with your version.

Try to determine if a plugin is abandoned or actively maintained​

Plugins must be actively maintained in order to remain compatible with ArchivesSpace over time, so the first thing to try and determine is whether the plugin is abandoned (which may be easier than determining whether it is actively maintained).

A plugin's developer may abandon a plugin for any number of reasons:

  • the plugin functionality has become moot
  • the institution it was developed for no longer has need for it
  • the developer has taken another approach in a different plugin
  • the plugin has changed maintainers and its source code is now in another repository
  • the developer has moved to another institution or has left the field entirely

The following are things to look for on a GitHub page:

This message reliably informs us that this repo is no longer updated and should not be used:

Repository abandonment notice

The date since last update is a vital clue as to whether this repo is maintained, but is not definitive:

Repository last update date

If you see an update time that corresponds to the time frame of the last release, then you have a high probability that this plugin is maintained and that is it compatible with the version released at that time.

Recent repository update

But, just because a repo hasn't been updated in a long time does not itself indicate that the plugin is no longer maintained. Some plugins are so simple, or they touch aspects of the application that are so stable, that there isn't any need to update them over time.

Try to determine whether if a plugin is on the main branch or a fork​

"Main branch" and "fork" are terms that may confuse non-git users, but the main takeaway here is that you are looking for a message like the following, which will display prominently on a GitHub repository page:

Fork notification message

The above indicates that the page you are on is a fork, and notably, a fork that is significantly behind the main branch of the code. This means that the version you're looking at isn't part of the main code, a bit like a Save As document that someone else is working on. You do not need to fully understand these terms except to know that you should not install a fork unless you are personally working with the developer that has created the code. In essence, you are only looking to confirm that this message is not present in the plugin repo you are considering.

If you do see this message, you should seek the main branch of the plugin by Googling its name or being in contact with the developer.

If you don't see this message, you may proceed with your evaluation.

Try to determine whether a plugin is compatible with your version of ArchivesSpace​

ArchivesSpace version compatibility

A plugin may be maintained, but, for which version of ArchivesSpace? You cannot assume that even maintained plugins are compatible with the most recent release or the version you are on. Some institutions prefer to be one minor release behind core code, and they may only maintain their plugins on their update timelines.

You can attempt to ascertain version compatibility in one of two ways, but ultimately you will have to test.

Check the top of the README text for an explicit statement of compatibility. The README is the text block you see on a GitHub page that usually describes its scope and configuration. Here are some examples of explicit statements accurate as of the time this article was first written:

The latest version of timewalk is compatible with ArchivesSpace 3.0 and above, and is not compatible with ArchivesSpace 2.x. A version compatible with ArchivesSpace 2.x is available here

An ArchivesSpace (v1.5.x - v2.1.x) plugin that provides summary reports on Accessions.

Another place to look for version compatibility statements is on the Versions page, available via a link off the main GitHub view.

You should be aware of the version of ArchivesSpace that you are on when reviewing the plugin itself for compatibility. If you are unsure when version of ArchivesSpace you are in, check the lower-right hand footer of any page in ArchivesSpace.

Reach out for support​

Perhaps you found your answer by taking the steps above, but in the end, the only way to know for sure that a particular version of a plugin is compatible with a particular version of ArchivesSpace is to:

  • test the code in your Sandbox or Production server;
  • be in contact with the developer directly;
  • inquire to the ArchivesSpace community to see if any community members know its status or are already using it on the version you want to update to.

Atlas Systems does not support third-party plugins, but we can recommend that ArchivesSpace Members can contact the members listserv to inquire about plugins. Non-members can contact the Non-Member ArchivesSpace Google Group. If you are interested in ArchivesSpace membership for your organization, email the ArchivesSpace Program Team at ArchivesSpaceHome@lyrasis.org.

Be mindful of changes over time​

Remember that the successful configuration and installation of a third-party plugin on your ArchivesSpace server is only the first step. Every subsequent update to ArchivesSpace will be a risk to this plugin and its functionality, and plugins should be tested and evaluated after every update.

Atlas Systems will inform users if we know in advance that a plugin will break upon updating ArchivesSpace, and when Atlas knows that a new plugin version is available, we will proactively install it for customers affected by that change. However, Atlas usually only learns of compatibility issues when customers like you test and inform us. Atlas will be as proactive as possible, but ultimately we rely on you and we all rely on the efforts of the ArchivesSpace community and its developers to keep plugins and their repositories up-to-date.

If a plugin is found to be incompatible during a version update, Atlas will look for an updated version of the plugin. If none is available, Atlas will uninstall the plugin. If an updated version is later made available, Atlas relies on the customer to submit a request for that plugin to be installed.

We also recommend our related articles on this topic: