Managing your ArchivesSpace Customizations with Atlas Systems
This article explores configurable customizations for ArchivesSpace, details on how Atlas Systems manages configurable customizations for hosted ArchivesSpace customers, and how those steps have changed over time.
If you have landed on this article because you are seeking to learn how this process has changed, you can skip straight to that section.
Defining "Configurable Customizations"
This section is meant to differentiate between ArchivesSpace customizations as implemented by third-party plugins (hereafter referred to as plugin customizations) and ArchivesSpace customizations implemented as configuration or translation changes in native files (configurable customizations). This distinction is an important one for the context of this article as well as any discussion of customizations in the abstract because Atlas Systems supports configurable customizations for all customers, but does not write or support plugin customizations that are provided and maintained by the customer or third parties.
For the simplicity of this article, configurable customizations are defined as the changes that are possible in the ArchivesSpace application by modifying one of four potential files:
- config.rb found in \config
- en.yml found in \locales
- en.yml found in \locales\public
- en.yml found in \locales\enums
Please note that the "en" in en.yml refers to English and is the most common version of the YMLs that are modified here at Atlas; a customer wishing to switch ArchivesSpace to French as the primary language would use the following list instead:
- config.rb found in \config
- fr.yml found in \locales
- fr.yml found in \locales\public
- fr.yml found in \locales\enums
As of 3.5.1, ArchivesSpace supports localizations in English, Français, Español, 日本語 (Japanese), and Deutsch (German). It also supports Portuguese on the PUI.
What Those Files Contain
Each of the above files plays a different role in ArchivesSpace, and while the following is not a comprehensive list of all possible changes, it is meant to give a feeling for what types of changes each of those files makes possible.
config.rb
The file named config.rb (hereafter referred to as just "the config") is probably the most talked about file on the ArchivesSpace server. Please note that Atlas has two webinars on the config: Know Thy Config: Introduction and Know Thy Config: Inheritance, though some of the information in those webinars now contradicts how Atlas manages changes, which is the focus of this article.
The config tends to change how ArchivesSpace functions as opposed to how it looks, though there are definitely overlaps in managing the appearance of ArchivesSpace in the config and the YML files.
Here are some very common examples of things changed in the config:
- Session time, or how long until ArchivesSpace automatically logs out an inactive user
- Page size, or how many results display on any given search or browse screen
- Inheritance, or what information different records display from higher up the hierarchy
- The PUI Navigation bar, or what is available to click in the main header on the PUI
YAML Files
YAML files (pronounced "yah-mul") are the family of files with the .yml file extension. Wikipedia defines YAML as a very simple "human-readable data-serialization language...commonly used for configuration files and in applications where data is being stored or transmitted."
The role of these files in ArchivesSpace is to change how certain things in ArchivesSpace look as opposed to how they function. The changes in these files are often referred to as translations, and they serve a role in displaying ArchivesSpace in different languages.
Changing values in the YAML files only changes what the user sees and makes no other changes to ArchivesSpace. Here's an example:
Let's say you have a database value of cubic_feet that you use for extent values. A database likes a value like that: all one case, no spaces. But humans aren't expecting to encounter an extent statement that reads "45 cubic_feet."
The role of the YAML files is to provide the label, or translation, for the database value and doing so also allows you to customize how the values appear without changing the value itself. This means the value will continue to be cubic_feet in the database, but you can change the translation to Cubic Feet, or Cubic feet, or Watermelons using a YML file.
Compare this view of the Browse menu:
To this view of the Browse menu with some fun changes to translations:
The above changes don't actually change anything about how ArchivesSpace functions, and they don't actually change anything in the database itself, like the names of tables or the names of those file types. But what did change is how those values are labeled.
Different YAML files change labels in different places, with some overlap:
- en.yml found in \locales - Changes labels in the staff interface
- en.yml found in \locales\public - Changes labels on the public interface
- en.yml found in \locales\enums - Changes labels for enumeration values, like cubic_feet. Enumeration values are also called Controlled Values and are essentially anything that you select from a drop-down menu anywhere in the application. Certain users with appropriate permissions can view these on the staff side by navigating to System > Manage Controlled Value Lists. This is a commonly changed YAML file exactly because users want to control their enumeration labels.
How Atlas Manages Configurable Customizations
Beginning in March 2022, Atlas Systems began managing configurable customizations for customers by splitting out only the lines of each of the aforementioned files that had been actually been changed into separate files and storing them in a plugin called Custom Locales. This article was written to explain that change.
For example, if there are 200 possible configurations in any given config file, but a customer has only modified 15 of those, the 15 changes used to be maintained along with the other 185 lines in the config itself. But beginning in March 2022, the 15 changes are split out into a separate file called customer.rb. While the config is used in this paragraph, this is true for any changes in the following four files:
- config.rb found in \config
- en.yml found in \locales
- en.yml found in \locales\public
- en.yml found in \locales\enums
A second major change is that Atlas will no longer accept changes via full file replacement or the exchange of raw files, meaning that requested changes to these files can be made by either:
- Providing exactly the value(s) you wish to change as they appear in the file; or
- Requesting a change be made in plain language, such as, "Please modify the page size to be 50 results per page" or "Please change cubic_feet to Cubic Feet."
Atlas will make those changes unless they represent a system change (defined by certain lines in the config).
Accessing your Customization Files
Viewing and Downloading your YML files from within the Staff Interface
Customers whose accounts have sys admin privileges can now easily download their modified YML files 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 Custom Text. This information will inform you of whether you have customizations in place and act as download links if so.
In referring to the screenshot below, you can see this screenshot was taken on a server without customizations. This means nothing is downloadable because there are no relevant files in place:
This screenshot was taken on a server with customizations, and options are provided for downloading them:
If you do have customizations in place, you can proceed to downloading them:
- Combined means that you'll be downloading a YML file where your changes have been combined with the default file. This option will be beneficial to those setting up their own development environments or who want to see every option available to them. It will not be as helpful if all you're looking to do is confirm that you have customized.
- Modified means that you'll be downloading a YML file that shows only what is modified on your server. This option is beneficial to those seeking to understand what changes are already in place. These files are much shorter and easier to read than the Combined files.
The above options give you the chance to download your modified files as individual files. The following option gives you the option of downloading the entire custom_locales plugin, which is how Atlas controls your modified YML files for you. Downloading the plugin gives you not only the files, but the plugin itself, including the directory structure. This option is expected to be useful for developers looking to re-create their Atlas enrollment on a local test server. Casual users will likely not need this option.
While logged in as a sys admin, click the Plug-ins drop-down menu next to your username icon and select Atlas Hosting. Click Download Plugins in the upper right of that page. This page will list the plugins on your server. Downloading the custom_locales plugin will show you any custom YML files that are in place on your server.
Note: if you had no custom files listed under Atlas Custom Text, then there will not be any custom YML files in your downloaded custom_locales plugin.
Viewing the Default YML files
The default YML files (the raw files that ship with ArchivesSpace) can be viewed on GitHub, but they differ so much from the Distribution copies that they are confusing to use. See the bottom of this page for links to download version-specific YML files:
- en.yml found in \locales - Changes labels in the staff interface
- en.yml found in \locales\public - Changes labels on the public interface
- en.yml found in \locales\enums - Changes labels for enumeration values, like cubic_feet.
Viewing your Config.rb from within the Staff Interface
Did you know that you can see a read-only view of your config file right in the staff interface from the System Information page? This information is available to the admin account (and beginning in v4.0.0) can be configured to be accessible to any System Administrator). The admin account is the account with the username spelled literally a-d-m-i-n; other user accounts that have System Administrator privileges do not have access to the config via the Staff interface unless you have configured this option in a version past 4.0.0.
Please note that by following the instructions below you will see the version of the config that is actually in use by your institution right now and that reflects any and all changes that have already been made; information on viewing the default config.rb is available in the next section.
As the admin user, log into your Staff interface and then navigate to the following:
Here you will find a read-only view of the config file in use by that system:
Please note that this view is not available for the YML files; see the section titled Viewing and Downloading your YML files from within the Staff Interface.
Viewing the Default Config.rb
If you wish to view the default configuration file it is easy to do so on the ArchivesSpace GitHub or by scrolling to the bottom of this article. Please note that the version on GitHub is slightly different than the version that ships with ArchivesSpace: the version on GitHub has the configurations uncommented, whereas the version that ships with ArchivesSpace (the Distribution copy) has all lines commented; this is the only difference. The information that is most significant is which configurations exist for which version of ArchivesSpace, and this information is the same whether viewed on GitHub or on the server.
Check your version number (usually visible in the lower right-hand corner of any page in ArchivesSpace) and then refer to the following links to view the config on GitHub; alternatively, the Distribution versions of different config files have been attached to this article for download (scroll to the bottom).
Note that the Distribution versions of the configs are available at the very bottom of this article, please scroll down to download them.
Default Files for Download
Check your ArchivesSpace version number (usually visible in the lower right-hand corner of any page in ArchivesSpace) and then refer to the following links to download the default files for your version: