Release 2.3

From AtoM wiki

Main Page > Releases > Releases/Release announcements > Release 2.3

Release date: July 19, 2016

Download link: atom-2.3.0.tar.gz

Release 2.3 is the first major release since July 2015, and includes several new features, major redesigns of existing features (such as search/browse/advanced search), support for more tasks to be performed asynchronously to avoid browser timeouts during long-running operations, and many bug fixes. We've closed over 200 issues as part of this release – you can view more details on each ticket in our issue tracker at the following links:

Visit the Downloads page to download the most recent release, and consult the 2.3 Upgrading and Installation guides in our documentation for further information.


Some issues have been reported with the 2.3 release - see the Known Issues section below for more details. Artefactual is preparing a 2.3.1 Release that should resolve the issues.

Be sure to review the dependencies for every new major release in the Requirements page – sometimes new dependencies are added, or version requirements have changed. For example, 2.3 will require PHP 5.5 or higher, and we recommend PHP 7.0 if you are going to follow the instructions to install with Ubuntu 16.04. If you are generating finding aids in AtoM, we've also updated the Apache FOP library – AtoM can now use FOP 2.1. All details should be covered in the installation documentation – read carefully, please! If you have questions, why not make a post in the AtoM User Forum?


We now have installation instructions for users who want to use some of the latest stable releases of our dependencies, such as Ubuntu 16.04 and PHP 7.0. Check out the installation instructions here!

An overview of some of the major changes in the 2.3 release is included below, followed by a full list of links to relevant tickets, sponsors, and documentation for new features.

Known Issues

Since the 2.3 release was made available on July 19, 2016, some issues have been reported. Artefactual is preparing a 2.3.1 Release that should resolve some of these issues, particularly:

  • #10256 - Treeview does not appear when using certain cultures
  • #10276 - Global setting for reference code separator affects new user slug generation
  • #10417 - sfAPCuCache is broken
  • #10418 - Header fix for ArchivesCanada theme - include Clipboard link
  • #10426 - Results pagination not working in term index pages
  • #10633 - Investigate potential Ubuntu 16.04 compatibility issues with CSV import
  • #10602 - CSV import fails when using the accessionNumber column to link new descriptions to existing accession records
  • #10675 - PDF derivatives not generating correctly on Ubuntu 16.04
  • #10716 - Acquisition date in accession record behaving oddly

For a list of all issue tickets included in the 2.3.1 release, see:


For users who have encountered errors when trying to use a period or other characters as the reference code separator:

This issue has been identified in #10276. If you have tried to use a period as a reference code separator and are experiencing issues, the 2.3.1 release will include a fix for this issue going forward. To resolve the current issues in your AtoM instance, we have prepared a script that can be run from the command-line. The script is available at:

Instructions on how to run the script locally

  1. Follow the link above and download the script. Place it somewhere accessible from the root directory of your AtoM installation.
  2. From AtoM's root directory, use the tools:run command to execute the script, like so:

php symfony tools:run path/to/location/of/10276-separator-fix.php

The script will replace any periods used with the default dash separator in the database, which should resolve page load errors.

Summary of new features

Below a summary of some of the new major functionality has been included, with links to relevant documentation. This list is not exhaustive; for a full list of all features and bug fixes included in the 2.3 release, see our issue tracker:

Search and browse page redesign

Previously in AtoM, search, browse, and advanced search were 3 different page types in AtoM – meaning there were some inconsistencies between search and browse, and the advanced search filters could not be used on search/browse results, nor could the facets be applied to advanced searches.

Now all 3 page types have been combined and the advanced search options have been redesigned so they can be applied iteratively to any search or browse. Facets and filters can be used in conjunction, and new date range search options have been added. Users can also customize some field displays – if you are not using the Canadian RAD template, you can hide the General Material Designation filter, and if you are not using the PREMIS Rights module, you can hide the copyright status filter.

Actionable PREMIS Rights module enhanced

In AtoM 2.2, we introduced the actionable PREMIS rights module. Previously, users could pick one Rights Basis to be actionable, but in 2.3 you can now configure different rules per Rights basis, and supply a different custom user-friendly access statement for each Rights basis. There is also an option to add a customizable copyright pop-up warning that users must acknowledge before viewing a master digital object, and in the PREMIS rights template, the Statute field has been given a user-editable taxonomy and turned into an autocomplete field to make data entry easier.

New Clipboard module

A new module has been added to AtoM that allows end-users to "pin" archival descriptions to a Clipboard. This can be useful when browsing or searching for relevant records, or to print out results for reference or research. Authenticated users can also use the Clipboard to perform CSV exports from the user interface of the selected records, via the job scheduler.


Relevant 2.3 documentation:

Full width treeview option

Administrators can now select between 2 treeview options – the traditional AtoM 2 "sidebar" treeview, or a new full-width treeview that displays in the center column at the top of the archival description view page. This new treeview displays all levels of description in a frame that users can drag to expand for more viewing space, and uses simple icons to better indicate the level of description. It also supports keyboard navigation for enhanced accessibility


Relevant 2.3 documentation:

Configurable inventory list and more hierarchy browse options

A new configurable, table-based view of lower-level descriptions within an archival hierarchy, the Inventory list, has been added in AtoM 2.3. It allows users to select specific levels of description to be included, and then displays a link in the right-hand context menu of parent descriptions that will take users to a table-based view of lower-level descriptions. The table columns are sortable as well, making this a great way to list and explore large sets of file and item-level descriptions with minimal details added.

There are also links in the right-hand context menu allowing users to navigate directly to browse pages limited the current archival hierarchy, or to explore all digital objects included in a hierarchy – allowing users to take advantage of facets, filters, and sort options to better explore records contained within an archival unit.


Relevant 2.3 documentation:

Rename module to edit slugs and digital object filenames

Previously, when an archival description was created in AtoM, the permalink or "slug" (e.g. the unique part at the end of the URL) would be automatically generated from the title of the description, and could not be edited by users. In 2.3, a Rename module has been added that will users to change the slug of existing descriptions via the user interface. The same module will also allow users to edit the filenames of uploaded digital objects, and if you want to edit the description title at the same time you can (though the normal way of entering edit mode will also work for description title changes), and you can have AtoM automatically suggest a new slug based on the edited title.

Additionally, there is now an option in Admin > Settings to choose whether the slug for an archival description is derived from the title or the reference code.


Relevant 2.3 documentation:

Archival institution search and browse enhancements

AtoM 2.3 will now offer users 2 ways of browsing repositories – the traditional AtoM 2 "card" based view, or a table-based view with sortable columns, so users can see more information (such as region, locality, and thematic area) of the archival institutions as they explore. Users can switch easily between the 2 views via a user interface button. An administrator can also configure whether the card or table view is the default view when users first arrive on the page.

Additionally, some advanced search filters for archival institutions have been added – users can now filter the list by Thematic area, Archive type, and/or Region. While these options were already available as facets on the repository browse page, adding them as filters allows users to access the full list of options, instead of just the top 10 available in the facets.

Finally, the holdings list on the repository view page has been enhanced – it now includes a pager so all results are listed.

New CSV export options and improved roundtripping

AtoM 2.3 now includes a command-line task for full CSV export of archival descriptions, and several options for exporting via CSV from the user interface, supported by the job scheduler to avoid timeout issues. User interface CSV export options include the ability for authenticated users to export a full list of search/browse results, and to export clipboard results.

We've also made changes to the CSV import templates to better support non-creator actor and event roundtripping – for example, events such as accumulation, contribution, collection, etc now have better support. You can check out the latest change notes and CSV import templates on our wiki here:


Warning: The changes in the CSV templates are not backwards-compatible – meaning the 2.2 and earlier CSV templates will not work as expected for CSV imports. Always make sure you check our wiki for the latest CSV templates whenever there's a major version AtoM release. Be sure to use the new 2.3 archival description and accessions templates after you've installed or upgraded to 2.3.


Relevant 2.3 documentation:


We've included a simple API for archival descriptions and taxonomy terms in the 2.3 release, as another method of exposing data for use in other systems. Data is exposed in JSON format. The Browse information objects endpoint supports all parameters available in the Advanced search user interface, and the Read information object endpoint will expose all fields of the target information object. Meanwhile, the Browse taxonomy terms endpoint will return all terms of a target taxonomy. HTTP authentication is used by default, but for added security, administrators can also generate an API key associated with a user account and use this for authentication.

Accessibility enhancements

Better support for keyboard navigation and for users of screen readers has been added to 2.3 to improve its accessibility and usability. You can use the arrow keys to navigate and select in the global search box and in the full-width treeview, tab and arrow navigation should work generally better in view pages, and aria attributes have been added to much of the HTML to improve screen reader support.

Other enhancements and bug fixes

We've listed some of the major changes above, but there's a lot more in this release!

Other enhancements

  • #9401 - Add support for database transactions to prevent data corruption on failed requests
  • #8412 – Add setting to select start page no. in PDF derivatives - docs
  • #9304 – Update publication status asynchronously via the job scheduler to avoid timeouts - Docs
  • #8354 – Add CLI task to generate XML sitemap for web crawlers – Docs
  • #8466 – Add option to hide digital object carousel and language menu via settings – Docs
  • #9390 – Add Genre access point fields to ISAD(G) and DACS edit/view pages, and full CSV import/export for Genre terms
  • #8417 – Add facet for "Part of" to better explore child results of top-level descriptions in browse pages
  • #8393 – Add configurable menu options to static pages – Docs

And more!

Bug fixes and usability improvements

  • #9844 – When Flash is disabled, multi-uploader displays blank screen instead of warning
  • #9674 – Disable disk usage checks in Settings when set to unlimited
  • #9632 – ISAAR identifier field label is incorrect
  • #9608 – Improve response speed in OAI-PMH plugin requests
  • #9606 – EAC export includes empty EAC elements, will not validate
  • #9578 – Duplicate blank note rows created when adding translations
  • #9564 EAD exports empty bioghist elements when related actor has dates of existence
  • #9419 – Editor permissions to edit PREMIS rights inconsistent between accessions and archival descriptions
  • #9275 – Remove upload limit directory size check when editing archival descriptions
  • #9156 – EAD <originalsloc> drops nested address elements
  • #9000 – Cannot type opening parenthesis in global search box
  • #8522 – HTML escaping is affecting user interface elements that should not be escaped
  • #8672 – Treeview with six objects shows "0 more" in in tree on expand link

And more!


Remember, you can see a full list of issues included in the 2.2 release

Summary by category and sponsors

General usability enhancements

Sponsored by the World Bank Group Archives

  • #8393 - Static page navigation enhancements
  • #8410 - Add custom formatting to allow users to add hyperlinks to descriptive fields

Sponsored by the Canadian Museum for Human Rights

  • #5538 and #6111 - Add keyboard support for search box and autocomplete results
  • #8808 - Accessibility enhancements
  • #8538 - Allow keyboard navigation over header bar menu elements

Search and browse enhancements

Sponsored by Les archives de la Ville de Montréal

  • #9141 - Merge search, browse, and advanced search pages to support use of both facets and filters on results
  • #8687 - Improve search result matching behavior on diacritics and ellisions

Sponsored by the World Bank Group Archives:

  • #8408 - Add new browse options to right-hand context menu on archival description view pages
  • #8384 - Add new customizable inventory page for exploring lower-level descriptions
  • #8417 - Add facet for "Part of" to better explore child results of top-level descriptions

Sponsored by the Canadian Council of Archives

  • #8673 - Add advanced search options to the archival institution browse page
  • #8674 - Add a table view with sortable columns to the institution browse page, include admin setting to set default view

Sponsored by the City of Vancouver Archives

  • #8648 - Add date range searching to the Advanced search page
  • #9352 - Add date range toggle options and help text to Advanced search date range selection

Sponsored by Simon Fraser University Archives

  • #8941 - Add Clipboard interface to allow users to manage sets of records

Treeview enhancements

Sponsored by the Canadian Museum for Human Rights and the World Bank Group Archives

  • #6375 - Add full-width treeview to AtoM

Archival description enhancements

Sponsored by the University of Toronto

  • #9390 - Add Genre access point field to ISAD(G) and DACS edit and view pages, and full support for CSV import/export Genre terms

Sponsored by Simon Fraser University Archives

  • #8759 - Allow users to edit description titles, slugs, and/or attached digital object file names

Customization options

Sponsored by Les archives de la Ville de Montréal

  • #9202 - Add configuration option to remove General Material Designation and Copyright status filters from Advanced search

Sponsored by the Canadian Museum for Human Rights

  • #8466 - Add settings to hide digital object carousel and language menu

Sponsored by the World Bank Group Archives:

  • #8412 - Add new setting to select start page no. in PDF derivatives

Sponsored by Simon Fraser University Archives

  • #8781 - Add setting to determine whether reference code or title is used as the basis for archival description slugs


  • #9304 - Update publication status asynchronously via the job scheduler to avoid publication timeouts
  • #8228 - Finding aid generation should have message when successful with name of related description

Import / export

Sponsored by Bombardier Inc.

  • #8563 - Add CSV export of advanced search results for authenticated users via the user interface

Sponsored by the Council of Nova Scotia Archives

  • #8335 - Add support for bulk CSV export (archival descriptions) from the command-line
  • #9350 - Add CSV export of pinned items on the Clipboard to the Clipboard page

Sponsored by the Canadian Council of Archives

  • #8591 - Add CSV export for archival institutions from the command-line
  • #6145 - Remove unnecessary spacing between elements during EAD export


Sponsored by the Institut de Cultura de Barcelona

  • #9238 - Create AtoM REST API endpoints for search/browse and read information object

Search Engine Optimization

Sponsored by the World Bank Group Archives

  • #8354 - Add CLI task to generate XML sitemap for web crawlers
  • #8418 - Include scope and content in HTML meta description element for better indexing

PREMIS Rights and digital object management

Sponsored by Simon Fraser University Archives

  • #8768 - Convert Rights » Statute into an autocomplete field and add new Statute taxonomy to AtoM to store values
  • #8769 - Allow users to configure different PREMIS permissions settings per rights Basis
  • #8771 - Add configurable copyright warning page that will appear when users attempt to download digital objects with specific PREMIS rights associated
  • #8887 - Add individual user-friendly access statements per PREMIS Rights Basis; move access statements to Permission page in Settings

CLI Tasks

  • #8488 - Add a skip to option for the digitalobject:regen-derivatives task
  • #8574 - Include CLI task to strip HTML from archival description fields
  • #8708 - Change export:bulk task option to use --single-slug instead of --single-id
  • #8842 - Add ability to limit number of digital objects loaded and add remaining count