Skip to main content

ArchivesSpace Plugin Responsibility and Troubleshooting

This article was drafted in anticipation of ArchivesSpace 4.0+, which are versions of ArchivesSpace known to be very disruptive for pre-4.0 plugins due to much needed infrastructure upgrades that came with those versions. Though this article has that release as its context, the information in this article applies to all ArchivesSpace hosted customers regardless of version.

info

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

tip

Please see our other articles on plugins including What to Consider when Evaluating Third-Party ArchivesSpace Plugins and Managing your ArchivesSpace Plugins.

Responsibility​

One thing that can be difficult when tackling the issues inherent with plugins is: who is responsible for what? The party responsible for both maintaining and troubleshooting a plugin is the author or authors of that plugin, and that is generally the person or people who maintain the repository (almost always on GitHub) where that plugin is stored.

For the purposes of this article and your hosting experience here at Atlas, there are three parties of responsibility when discussing plugins:

  1. First party: Atlas Systems (your hosting provider)

    • Atlas is responsible for the plugins that we create for managing your ArchivesSpace instance for you and for integrating with Aeon. This includes the plugins called atlas_hosting, custom_locales, and aeon_fulfillment.
    • We are also responsible for keeping your ASpace server up and running, which means that our primary approach to issues with plugins is to remove plugins that cause ArchivesSpace to malfunction and then replace them at your request when (and if) a fix is issued.

  2. Second party: The customer (you and your institution)

    • You the customer are responsible for any plugins that you create or contract to have created and then supply to us. The most common example of a plugin like this is a branding or theming plugin, like those that change the PUI to your institution's colors or fonts or make other superficial changes to ArchivesSpace. These plugins should have a name specific to your institution.
    • You are also responsible for changes made in the local plugin (a plugin literally called "local"). This plugin is blank by default, but over time some customers either use the local plugin to create changes and just never rename it, or have asked us at Atlas to make changes that then get added to the local plugin.

  3. Third party: Anyone who is not the first or second party (everyone else)

    • The vast majority of ArchivesSpace plugins are third-party plugins, meaning that neither Atlas nor your institution was responsible for their creation. These are the universe of plugins that have become widely available since ArchivesSpace debuted as an open-source application in 2005.
    • The plugin developer(s) are the party responsible for changes to these plugins.

The party responsible for a plugin isn't usually an issue until something goes wrong.

What happens when something goes wrong?​

The reality of using plugins in ArchivesSpace means that it isn't whether a plugin will fail, but when. ArchivesSpace is an ever-evolving application and changes big and small can and will affect how plugins function.

info

For advice on how to identify which plugins you have installed on your server(s), please see our article Managing your ArchivesSpace Plugins.

The following flowchart can be referenced while reading the following content:

Troubleshooting Plugins after a Transition

Determine Responsibility per Plugin

Click either flowchart above to open the interactive version in Whimsical

When something goes wrong, the responsibility for a plugin is suddenly much more relevant. However, first we must identify which plugin or plugins failed. This is sometimes very obvious and sometimes not.

How plugins fail and the urgency of the failure​

Learning that a plugin failed is usually tied to a discrete event:

  • an update to ArchivesSpace core code (installing a new version of the application);
  • an update to a plugin (installing a new version of a plugin),
  • an addition of a plugin (wherein a new plugin comes in conflict with either the application or with another otherwise functioning plugin).

Without these major events occurring, a healthy plugin will keep on functioning.

In all three cases above, ArchivesSpace must be restarted for the changes to take effect. This is a key moment in testing a plugin.

Plugins initialize when ArchivesSpace loads, so the worst of errors occurs when ASpace cannot launch at all. This means ASpace cannot load until the failed plugin or plugins have been removed, and this represents real downtime, meaning neither staff nor patrons can access ArchivesSpace. In these cases, Atlas acts as quickly as possible to try and determine which plugin is failing and remove it.

Other plugin failures are not so dramatic. The author of this article has observed a situation where a plugin came in conflict with an HTML page that changed due to a recent ASpace release. The effect was that the specific page had weird formatting and would not scroll. While that was an inconvenience, it was not on the scale of ArchivesSpace being completely inaccessible and thus the urgency was less. When these less catastrophic errors occur, it is up to you the customer whether you'd like to remove the problematic plugin or not.

Whether a plugin will fail catastrophically or not cannot be predicted without deeper knowledge of exactly what the plugin is trying to override and what changed in core code to invalidate that. However there some generalities that can help guide you:

  • Plugin changes to the PUI fail more often than plugin changes to the SUI. PUI plugins tend to be branding or theming plugins.
  • The less a plugin does, the less likely it will fail. If a plugin just suppresses one field or changes just one thing, it's less likely to fail catastrophically. This also makes it easier to fix.
  • The reverse is also true: the more a plugin tries to override, and the deeper in the application those changes are made, the more likely a catastrophic failure.
  • The bigger the change in core code (like those with major release milestones, like 3.0 and 4.0), the more likely the impact on plugins.

Whether catastrophic or not, the solution is always the same. Read on for more information.

Determine which plugin(s) failed and remove them​

The good news is, even if a plugin fails catastrophically, the solution is simple: Atlas will remove the plugin(s) and ASpace will revert to normal behaviors. That is not to say it is not still disruptive; staff may rely on plugins for their work, and most patrons would be confused to see a familiar interface suddenly revert back to defaults if, for example, an entire branding plugin needed to be removed. Still, this is the only way to move forward and is why Atlas requires updates be made to Sandbox servers before Production servers, if a Sandbox is available. If you do not have a Sandbox server hosted with Atlas Systems, you can either upgrade to one, or launch a development server locally.

Once a failed plugin is removed, it's time to address the issue of how to move forward.

Who fixes it? Will it be fixed?​

These are the most vital questions when moving forward with failed plugins.

Atlas Plugins​

Atlas is responsible for testing and fixing Atlas plugins. We do test our plugins with each new release of ArchivesSpace, but if we find that we have missed something, we will address it as soon as possible and roll out the changes to all affected customers. You will not have to take any action beyond letting us know that you've discovered a problem. If the problem has already been discovered by the time you request an ArchivesSpace version upgrade, you likely won't even feel the change, as we will automatically update our plugins when upgrading your server.

warning

Please note that Atlas only tests for compatibility of our plugins against the core code of ArchivesSpace and against each other; we are not testing against second or third party plugins.

Customer Plugins​

Customers are responsible for continued compatibility of the plugins they are responsible for. Whether or not you can fix a plugin will be an internal matter at your institution.

To make a change, you will need to download the directory for the affected plugin, make the change, and send us the entire directory back, at which point Atlas will put the improved plugin in place.

Atlas has endeavored to make this process as easy as possible by enabling customers to download the exact plugin code running on their servers from within the staff interface. See our articles Managing your ArchivesSpace Plugins and Delivering and Maintaining your ArchivesSpace Plugins for more information.

Third Party Plugins​

info

Please see our article What to Consider when Evaluating Third-Party ArchivesSpace Plugins for more information on this topic.

Whether or not a third party plugin will be fixed is up to the party responsible for it (or, another party if someone steps in to fork the code and maintain the fork). A few things need to be determined:

  1. Is the plugin abandoned? If so, you should not expect a fix. You may need to stop using this plugin entirely, or wait and see if someone else takes over responsibility for the code.
  2. Assuming it's not abandoned, does the maintainer know it's broken? Sometimes, especially in the first few weeks of a new ArchivesSpace release, a maintainer doesn't know that their plugin is incompatible with the current version until they are informed. In this case, simply checking back in on the repository is the best option, to see if a change comes.
  3. Does the maintainer wish to update it? This seems obvious, but one consideration is that some institutions purposefully choose to stay behind on ArchivesSpace updates. In cases like this, the plugin author may acknowledge that the plugin is not compatible with the current version, but because they don't plan on updating to the current version in the near future, they have no motivation to update the plugin yet.

Atlas is not responsible for third party plugins, but in the course of providing support we do learn the status of plugin issues as they arise. We will do our best to inform you of possible plugin issues when we know about them, but this information is changeable and always evolving, especially during the early weeks of a release.

We encourage customers to be proactive in determining the status of plugins.

  1. Check the GitHub page for the plugin recent releases or updates to the plugin code
  2. 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.