Delivering and Maintaining your ArchivesSpace Plugins
Please see the webinar Proactive Change Management for Plugins for critical advice about the use of plugins in ArchivesSpace.
This article is intended for users who aim to make changes to their plugins on their hosted server(s) at Atlas Systems, and specifically the plugins that customers are responsible for, such as custom branding or theming, or changes made in the local plugin. For more on this distinction, see our article Plugin Responsibility and Troubleshooting.
Atlas does not recommend forking (customizing) third-party plugins unless you are willing to assume the responsibility for those changes in perpetuity. This includes making changes to the Aeon Fulfillment plugin. Please rename forked plugins to make them distinct from their origin.
While Atlas does welcome changes made by customers, we also express caution about making these changes. As your hosting provider, the stability and reliability of your server(s) is our primary concern. The introduction of outside code is always occasion for caution, and our guidelines are informed by our experience in managing second and third-party plugins for customers.
Please read on to understand this process at Atlas.
Plugin names should be specific and distinct
When providing a plugin written by your own institution (usually branding or theming), it is considered best practice to name that plugin as distinct from other plugins (for example, distinct from local). The most common naming pattern is institutionname_branding or something equally as distinct, indicating its author and its purpose. This convention makes it much easier to update and troubleshoot the plugin in the future.
Many customers have such changes in the local plugin, which was a legacy practice. Atlas can assist you in moving your changes out of the local plugin and into your own distinct plugin directory.
Plugins must be delivered as entire directories
When providing a plugin to Atlas, whether for the first time or as the result of an edit, you must deliver the entire directory of the plugin and its structure. This is true even when the change that is being made is very small. You may also provide a link to download, such as from a GitHub repository.
In order to make a change to a plugin you have permission to change, please download the entire plugin directory, make your changes, and return the entire directory. Please do not deliver only the modified files, but instead the entire directory.
Please be aware that Atlas is not responsible for troubleshooting plugins, and any changes made should first be tested against a local test instance before being sent back to Atlas for installation.
Certain users can access your plugin directories from the staff interface
Customers whose accounts have sys admin privileges can easily download their plugins from within the staff interface of ArchivesSpace. This is a feature only available to Atlas Hosted customers.
While logged in as a sys admin, click the Plug-ins drop-down menu next to your username icon and select Atlas Hosting. (For information on Atlas Custom Text, see Managing your ArchivesSpace Customizations with Atlas Systems).
You will see a Download button on the left-hand side. Click Download to see the plugins available.
Plugin developers are welcome to download the Atlas Hosting plugin or the Atlas Custom Text plugin in order to recreate their Atlas hosted experience in a local testing environment. However, Atlas does not accept customer changes made to those plugins. If you wish to make changes to those behaviors, you can override in a different plugin that you maintain, such as the local plugin or your own plugin.
Troubleshooting Plugins
Please see our related article Plugin Responsibility and Troubleshooting.
Plugin order
Since plugins often override behavior, it is useful to know that the order that plugins are listed in the configuration file affects how they are deployed. This can be relevant when testing locally, and so this information is provided to advanced users who may need it.
Plugins are loaded first to last as listed except when a plugin has its own config.yml that identifies one or more dependent plugins (in depends_on_plugins). Dependent plugins load before the plugins that depend on them. If there is duplication between plugins, the last plugin loaded wins.
Atlas Systems uses a plugin called custom_locales to manage certain customizations (specifically the locales YML files). For this specific plugin, there is an exception to the statement above, in that any value in locales/enums (these control the values in the system-wide enumerations, or drop-down menus) are loaded first, despite the order of the plugins listed. These can be overridden by other plugins.
To determine your plugin order, please see our article on The System Information page.