This section describes how to customize your AtoM application to the specific requirements of your own institution or network.
Below, you will find information on the following information areas:
- Global settings
- Site information
- Default page elements
- Default templates
- User interface labels
- Add/Remove languages
- OAI repository
- Finding aid
- Security panel
- Digital object derivatives
- DIP upload
Each of the settings areas listed above is accessible via a list of links on the left-hand side of the settings page. Click on the appropriate link, and click save after making your changes.
Global settings allow administrators to control certain aspects of how AtoM appears and behaves.
To access the “Settings” menu in AtoM, click on the Admin menu in the main menu located in the header bar and select “Settings” from the drop-down menu. You will be redirected to the “Site Settings”, where a number of information areas, including the “Global” settings, should be opened. If closed, simply click on the “Global” blue menu to open the area and view the fields.
- Application version
- Check for updates
- Maximum image width
- Results per page
- Accession mask
- Accession counter
- Reference code separator
- Inherit reference code (Information object)
- Treeview type
- Sort treeview (information object)
- Sort browser (users)
- Sort browser (anonymous)
- Default repository browse view
- Multiple repositories
- Default archival institution upload limit
- Total space available for uploads
- Upload multi-page files as multiple descriptions
- Show tooltips
- Generate description permalinks from
- Default publication status
- SWORD deposit directory
Hovering over each field will also provide additional information on that field - it will appear in an “information box” below your cursor.
This field shows the current version of the software. The value cannot be edited but is automatically updated when AtoM is upgraded to a newer release.
For more information on installing AtoM and searching for different versions, see:
Check for updates¶
If yes is selected, an administrator will automatically receive a notification if a newer version of the AtoM software has been released and can be installed. This notification will appear in the browser for authenticated (i.e. logged in) users, as an orange bar across the top of the application alerting users to the newest release available.
For more information on updates, see:
Maximum image width (pixels)¶
One of AtoM’s design assumptions is that the display dimensions of files users upload typically will be too large to fit into the view page for an archival description. Therefore, when you upload a file, AtoM creates a reference display copy for displaying in the view page.
AtoM ships with a default setting specifying the maximum width of the reference display copy at 480 pixels. This is the optimized width given AtoM’s field width. Administrators, however, can increase or decrease the maximum reference image width to suit the requirements of their institution or network.
Results per page¶
By default, AtoM lists objects in list pages and search results ten at a time, with a pager at the bottom of the page to allow users to navigate through long lists of objects. Administrators can increase or decrease this default number.
Editing this number to display a large number of results per page may affect page load times.
By default, AtoM creates the accession record identifier as a unique
number compiled from YEAR-MONTH-DAY-Incremental#, expressed as
This mask, or default counter, can be changed by
administrators to suit institutional needs.
For more information on accession records, see Accessions.
AtoM provides you with the number of accessions created. If you delete an accession, it will still be included in the Accession counter total value. If this number is changed by an administrator, the next accession created will receive the next number in sequence.
Reference code separator¶
The reference code separator is the character separating hierarchal elements in a reference code (see Inherit reference code, below). The default reference code separator appears as a dash “-” in AtoM, which can be changed by an administrator to suit institutional practices.
A bug has been found in the 2.3.0 release
related to this setting - see issue
#10276 in our issue
tracker for more information. 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
Follow the link above and download the script. Place it somewhere accessible from the root directory of your AtoM installation.
From AtoM’s root directory, use the
tools:runcommand 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.
Inherit reference code (information object)¶
When this is set to “yes”, the reference code string will be built using the archival description identifier plus the identifier of all its ancestors (parent records), as well as the repository identifier and country code if they have been entered. The string will appear in this order with the applicable elements:
- Country code (derived from the country code of the country entered into the contact information of the related archival institution)
- Repository identifier (derived from the identifier field on the related archival institution)
- Fonds/Collection level identifier
- Series identifier
- Subseries identifier
- File identifier
- Item identifier
When reference code inheritance is enabled, AtoM will also display the full reference code in the edit page for archival descriptions, as contextual information to help orient the user.
Whether reference code inheritance is turned on or not, the sort button option on the archival description browse page will still sort by full inherited reference code, and not by identifier alone. This setting only affects the display. For more information on sorting, see: Sort button.
This setting also determines how the
<unitid> element in the EAD XML is
populated. If the inheritance is turned on, then AtoM will populate all
descendant records in the EAD XML with the full inherited reference code.
If inheritance is turned off, AtoM will only add the identifier for that
record in the
<unitid> on export. This allows users exporting to a
different source system that does not have a reference code inheritance
setting to maintain a full reference code at all levels in the target
system. However, if you are exporting from one AtoM instance to another
(for example, from a local institution to a portal site), you might want to
consider how this will impact your record display in the target system - if
you have reference code inheritance turned on when you export, and the
target AtoM instance also has the setting turned on, you may end up with
duplication in the display!
The Sidebar setting refers to the classic treeview that appears in the left-hand context menu of an archival description. The Full width treeview, introduced in the AtoM 2.3 release, will display below the description title, and above the first information area of the description. The display space of the full-width treeview can be expanded by users by gripping and dragging the bottom bar of the treeview downwards to expand the viewing area.
Other differences include:
- The sidebar version does not indent lower-levels, while indentation is used in the full width treeview
- The Identifier is included in the sidebar treeview nodes, while no identifier is included in those of the full width version
- The results in the sidebar treeview are truncated - the first 5-6 nodes in the hierarchy are displayed by default, after which an approximate count of remaining nodes in the current level is provided, with the option to expand the results to display more. All nodes are shown in the full width treeview.
Below are screenshots of the same fonds, shown with each version of the treeview enabled, for comparison.
Full width treeview
Sort treeview (information object)¶
- Selecting “manual” means the descriptions will appear in the order in which they were entered into AtoM. If manual sort is selected, editors can also drag and drop descriptions within the treeview to re-order.
- Selecting “title” sorts the descriptions by title.
- Selecting “identifier - title” sorts the descriptions by identifier, then by title.
AtoM’s search index is based on Elasticsearch, which sorts characters based on the order of the in the ASCII character encoding scheme. This can result in seemingly wrong orders when sorting by identifier- for example, 1-1 will be followed by 1-10 instead of 1-2. The solution is to use leading zeroes when forumulating identifiers that you wish to sort in a human- readable order, e.g. 1-01, 1-02, etc.
For more information, see Treeview quick search.
Sort browser (users)¶
Administrators can configure default sort order for the browse display as either “alphabetic”, “last updated,” or “identifier” for logged-in users. “Last updated” will display records most recently added or edited at the top of the results, allowing users to explore what has changed. By default, the sort order is set to “Last updated” for authenticated users. However, users have the option to reorder the page while browsing via the sort button located at the top of most browse pages.
Sort browser (anonymous)¶
Administrators can configure default sort order for the browse display as either “alphabetic,” “last updated,” or “identifier” for public users (e.g., not logged-in). “Last updated” will display records most recently added or edited at the top of the results, allowing users to explore what has changed. By default, the sort order is set to “Alphabetic” for anonymous (i.e. public) users. However, users have the option to reorder the page while browsing via the sort button located at the top of most browse pages.
Default repository browse view¶
This setting will determine if the “card view” or the “table view” is the default view for the archival institution browse page, when users first arrive on the page.
Regardless of which setting you choose, any user can easily toggle between the card view and the table view on the archival institution browse page, using the view toggle button that appears to the right of the archival institution search box:
For more information on working with archival institutions, see:
Select “yes” if your AtoM application is acting as a union list or portal for descriptions of materials held at more than one archival institution or repository. The repository will appear as a column on the “Browse archival descriptions” page. The repository will appear as a link in the context menu.
Select “no” if your AtoM application is being used only by a single institution. By selecting “no”, the repository name will be excluded from certain displays because it will be too repetitive and the creator rather than the repository will now appear as a column on the list archival description page.
Default archival institution upload limit (GB)¶
Enter the upload limit in GB allowed for uploading digital objects. Use “-1” as the value for unlimited upload space. This setting can be modified by an authenticated (i.e. logged-in) administrator.
A value of “0” (zero) disables file upload.
For more information, see Upload digital objects.
While this setting is global, an upload limit can also be set by an administrator on a per-repository basis, from the archival institution page. For more information, see: Set digital object upload limit for an archival institution.
Total space available for uploads¶
This field will display the used space for digital objects as well as the total space available.
Upload multi-page files as multiple descriptions¶
Select “yes” if you would like each page of a multi-page file to be attached to a separate child-level description. For example, a PDF file with 10 pages uploaded to a description would result in 10 individual descriptions, one for each page in the file.
Select, “no” if you would like one multi-page file to be attached to a single description.
Tooltips are online text designed to assist users to enter data in edit pages. While adding or editing an archival description, tooltip text is usually derived from the standards on which the edit templates are based (e.g. RAD, ISAD, etc).
Default publication status¶
This setting determines whether new archival descriptions will automatically appear as draft records or published records. Note that this setting also affects imported descriptions. For more information, see Archival Descriptions.
The site title and description will appear in the AtoM header bar, if they are included in the default page elements. See below for an image of where the Title and description appear, and more about setting the visibility of default page elements.
The base URL is used to create absolute URLs included in XML exports (e.g.
MODS and EAD exports). For example, your AtoM site is made up a series of web
pages. Each page has a full Uniform Resource Locator (URL) something like
http://www.your-atom-site.com/your-description. The Base URL is the part of
this URL that does not change - in this example,
Setting this value will ensure that links included in your XML exports will be
properly formed. Do not include a slash
/ at the end of your base URL -
AtoM will automatically add this when building the absolute URLs.
To save any modifications, click the “Save” button located below the “Site Description” field.
Default page elements¶
This section allows administrators to enable or disable certain page elements. Unless they have been overridden by a specific theme, these settings will be used site-wide.
Checked boxes will display the corresponding element and unchecked boxes will hide the element. The logo, site title, site description, and language menu all appear as part of the AtoM header bar:
The Copyright status filter and the General material designation filter appear as filters available in the Advanced search panel. For more information on using this panel, see: Advanced search. The Copyright status filter relates to PREMIS rights added to descriptions - for more information, see: Rights. The General material designation filter is derived from the Canadian Rules for Archival Description (RAD) standard, and is only used on the RAD template.
When unchecked, the above elements will be hidden from display after you save the default page element settings. This can be useful for customization - for example, if you are not translating the content of your website and do not need the language menu, unchecking it here will remove it from the AtoM header bar. Similarly, if you are not using the Canadian RAD standard as your default template, you might want to hide the General material designation filter from the advanced search panel.
AtoM ships with default page templates for viewing and editing archival descriptions, authority records, and archival institutions. For more information on the standards on which these templates are based, see Descriptive standards.
The “Name” column shows the types of entities that are described in AtoM: “Archival descriptions”, “Authority records” and “Archival institutions”. Drop-down menus of descriptive standards for each are provided under the “Value” column. Administrators may select one for each entity using the drop-down menus.
Once changes have been saved, records on the site will be able to be edited and viewed in the templates that have been selected.
User interface labels¶
AtoM is flexible enough to support descriptions a variety of cultural materials such as archival, library, museum, and art gallery collections. The code, therefore, uses generic terms for entities. Administrators can specify how they want these terms to appear in the user interface labels to suit the institution’s collections. The default labels that ship with AtoM are terms typically used by archival institutions.
The “Name” column shows the generic entity name and the “Value” column shows AtoM’s default user interface labels. The following is a list of the generic terms and their AtoM user interface labels. Click on each label below to see glossary definitions and descriptions of how the terms are used in AtoM.
- informationobject: archival description
- actor: Authority record
- creator: Creator
- repository: Archival institution
- function: Function
- term: Term
- subject: Subject
- collection: Fonds
- holdings: Holdings
- place: Place
- name: Name
- digitalobject: Digital object
- physicalobject: Physical storage
- mediatype: Media type
- materialtype: Material type (general material designations used in the Canadian Rules for Archival Description).
- facetstitle: facets title
- genre: Term for the Genre access point taxonomy, currently only available on the RAD template. It appears as a facet filter in the archival description browse and search pages - this label will change the display in the facet headers.
User interface labels can be changed by administrators by entering a new label(s) into the field(s) under the “Value” column. Changes will only be saved once the “Save” button is clicked. Changing the label will change its appearance throughout AtoM for both authenticated (logged-in) and public users.
Changing the user interface labels will not automatically change the corresponding labels in the navigation menus. To change these menus, go to Admin > Menus. See the Manage menus page for more information.
AtoM relies on volunteer translators from the community to support new language options. The translations are managed using Transifex and community members can learn more about contibuting translations here.
The language menu will display the languages that are currently available in your AtoM application.
To add a language:
- Select a language from the drop-down menu located under “Language code”.
- Click the “Add” button.
- AtoM adds the language and refreshes the page; the added language will now appear in the “Add/remove language” section in “Settings”, as well as in the drop-down menu of the language navigation menu located at the top right corner of the header bar.
If you are adding a new language to the AtoM user interface, you must re-index your site for the new language to work as expected after adding it via the settings page. Using the command-line, a system administrator will need to run the following command from the root directory of your AtoM installation:
php symfony search:populate
See: Populate search index for more information.
Many languages appear in the “Add/remove language” section in “Settings”, but the translations for all languages are not completed. If a language is selected from the Language menu in the header bar, content that has not yet been translated will remain in English.
To continue adding languages, repeat these steps as required.
If a user selects a language that is not currently supported (i.e., where the content has not yet been translated through Transifex), AtoM will refresh the settings screen without implementing any changes.
To remove a language:
- Click the delete located in the third (blank) column next to the language.
- AtoM will delete the language and refresh the page; the deleted language will no longer appear in the “Add/remove language” section in “Settings”, nor in the drop-down menu of the language navigation menu located at the top right corner of the header bar.
To continue removing languages, repeat these steps as required.
Open Archives Initiative, or OAI, is a protocol for metadata harvesting that allows automatic data harvesting and crawling within other systems that support OAI harvesters.
Comprehensive documentation on each field in the OAI repository settings is included in the OAI repository documentation, here:
To use the OAI repository functionality in AtoM, you must first make sure that the arOAIPlugin is turned on. For more information, see:
If the arOAIPlugin is not turned on, then you won’t see the OAI repository tab on the settings page menu!
These settings configure how AtoM generates finding aids from archival descriptions. For more information, see Print finding aids; specifically, Finding aid settings includes a description of each settings field.
Limit administrator functionality by IP address
This feature allows administrators to limit administrator functionality to one or more IP addresses or IP ranges. Separate multiple IP address or ranges by semicolons, and use a dash to indicate an IP range. For example:
- 192.168.0.1 (single IP address)
- 192.168.0.1;192.168.0.255 (multiple unique IP addresses)
- 192.168.0.1-192.168.0.255 (IP range)
Require SSL for all administrator functionality
This feature allows administrators the option to enable the Hypertext Transfer Protocol Secure (HTTPS), which is a protocol for security over a computer network. It works by layering the Hypertext Transfer Protocol (HTTP) with the SSL/TLS protocol (Secure Sockets Layer/Transport Layer Security).
Select yes to require all HTTP requests to be redirected to the HTTPS server, changing the URI scheme from “http” to “https.”
This will only apply to users who are authenticated (logged-in) or visiting the login page.
Require strong passwords
This feature allows administrators to enhance login validation by requiring the use of strong passwords. Strong passwords use least 8 characters, and contain characters from 3 of the following classes:
- Upper case letters
- Lower case letters
- Special characters
Choose “yes” to require authenticated (logged-in) users to have strong passwords.
Permissions settings are used by administrators to make PREMIS rights records in archival descriptions actionable on attached digital objects. See Rights for more information on working with rights in AtoM.
The permissions settings page is divided into 3 sections - PREMIS access permissions, PREMIS access statements, and the Copyright statement.
For information on configuring the PEMIS access permissions, see: Make rights actionable on digital objects (and for an example use case, see: Example: Configuring copyright permissions). For information on configuring the PREMIS access statements, see: Configure Disallowed and Conditional access statements. For information on configuring and using the Copyright statement, see: Add a Copyright statement before allowing access to a master digital object.
The Inventory list allows an administrator to make a page of lower- level descriptions contained within a parent record available on a separate inventory page formatted as a table with sortable columns. For more information, screenshots, and instructions for end users, see: Using the Inventory list.
The selections an administrator makes in this section of the settings will determine what levels of description are included in the inventory list when accessed by users.
To multi-select multiple levels of description for inclusion in the inventory list, hold down the CTRL key (or the Command key on a Mac) while clicking the target levels.
Any level not selected will not appear in the inventory list results when a user clicks the inventory link.
Because level of description terms are included in a taxonomy that can be configured by users with the appropriate permissions, a hyperlink to the Levels of description taxonomy is also provided - an administrator can customize available terms by adding new ones, removing unused ones, or editing existing terms (for more information, see: Terms). Any new term added to the Levels of description taxonomy will show up in the Inventory settings page the next time an administrator returns to the settings page.
When you have selected the levels of description you want included in the Inventory list, remember to click the “Save” button located in the button block at the bottom of the page.
Configuring the Inventory settings in a multilingual environment
If you have multilingual content in your AtoM instance, or you expect users to be browsing in different cultures (using the Language menu), you will need to configure the Inventory settings for each target culture. For example, to configure the settings for English, French, and Spanish:
- Make sure the user interface is set to “English” using the language menu - see Language menu for more information.
- Configure the inventory settings as described above for English, and save.
- Using the language menu, flip the user interface to French.
- Repeat steps 1-2.
- Using the language menu, flip the user interface to Spanish, and repeat steps 1-2 again.
Digital object derivatives¶
This setting will affect the digital object derivatives generated by AtoM when uploading multi-page content, such as a PDF.
Whenever a digital object is linked to an archival description, AtoM will generate two derivative copies from the master digital object (e.g. the original) - a reference display copy, used on the archival description view page, and a thumbnail, used in search and browse results, and in the digital object carousel. By default, AtoM will use the first page of multi-page content (such as a PDF) when generating the derivative images.
However, with multi-page content such as PDFs, the first page may not be useful to users browsing the content - it may be an institutional cover page used on all digitized content, a blank cover page, etc.
This setting will allow users to set a page number that should be used when generating the derivative copies. It will work for both locally uploaded content, and for PDFs linked via URL. If a system administrator runs the derivatives regeneration task, AtoM will use the setting value when regenerating PDF derivatives.
If you enter a page number that does not exist for one or more of your derivatives (for example, entering 99 as the value, when your PDF only has 9 pages), AtoM will use the closest available value (in this example, page 9) when generating the derivatives.
If you make changes, remember to click the “Save” button in the button block.
This setting is for users who are uploading content from a linked Archivematica instance. Archivematica is an open-source digital preservation system developed by Artefactual Systems, the same creators of AtoM. For more information, see: https://www.archivematica.org
For information on DIP upload from Archivematica to AtoM, see the following page in the Archivematica documentation:
Archivematica can be used to manage and prepare digital content for long-term preservation, and can generate a Dissemination Information Package (DIP) with access-copy derivatives of your master digital object files processed in Archivematica, for upload into AtoM.
If no additional metadata is provided with the content during preparation,
then when uploaded to AtoM, AtoM will use the file names as the default titles
for the associated information objects (a.k.a.
descriptions) generated, to which the digital
objects in the DIP will be attached. However, this might produce descriptions
with titles like
When this setting is set to “Yes,” AtoM will automatically strip the file
extensions from the information object names automatically generated during
the DIP upload process - from the examples above, this setting would lead to
information object titles such as
my.document. Users can
still edit the description title after DIP upload to customize them as
Note that the setting will not retroactively affect existing uploads/information objects, only new information objects created during the DIP upload process from Archivematica. Similarly, the uploaded file itself is not affected (the extension is not stripped from the digital object) - only the title of the description generated so the digital object can be attached and uploaded.