Settings¶

Application version¶

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.

The second number after the dash represents the database schema version. This can be useful information to include in a support message if you are experiencing unexpected issues with your installation - if a system administrator forgets to run the upgrade task as part of a site upgrade this can lead to missing tables and/or columns in the database, which can cause unexpected errors later when trying to use AtoM.

For more information on installing AtoM and searching for different versions, see:

• Installing AtoM with:
  • Linux Ubuntu
  • Windows
  • Mac OS X
• Upgrading
• Check for updates

Check for updates¶

If yes is selected, authenticated (i.e. logged in) users 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.

This image shows a themed AtoM installation at the City of Vancouver Archives, showing an update notification in orange at the top of the screen. Only authenticated users will see this notification.

For more information on updates, see:

• Search for updates

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. Note that the minimum accepted value is 5 results per page, and the max value is 100.

For more information on navigating in AtoM, see Searching in AtoM and Navigating in AtoM.

Escape special characters from searches¶

This setting allows users to define special characters that should be escaped when performing a search, to avoid errors.

AtoM uses Elasticsearch (ES) as its search index. In ES, certain characters are normally reserved to be used as operators in advanced searching - for more information, see: Advanced search using the AtoM Search box - particularly, Boolean operators. Normally, if you want to perform a search using these special characters without them being interpreted as operators, then you need to manually escape them with a \ leading backslash character. From the ES documentation:

If you need to use any of the characters which function as operators in your query itself (and not as operators), then you should escape them with a leading backslash. For instance, to search for (1+1)=2, you would need to write your query as \(1\+1\)\=2.

The reserved characters are: + - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /

Failing to escape these special characters correctly could lead to a syntax error which prevents your query from running.

Many institutions prefer to use a / slash character as the default Reference code separator. This can lead to errors for users trying to search for full reference code strings. However, with this setting, you can define characters (such as the /) that you wish to be automatically escaped when a search string is submitted as a query.

You can add multiple escape characters to the field by separating them with commas:

Back to top

Sort browser (users)¶

This setting controls the default sort order of records shown on Browse pages in AtoM - specifically, archival description results. Sorting can always be changed by users via the sort button available on related search and browse pages, but an administrator can use this setting to control the default sort when arriving on the page for the first time.

Administrators can configure default sort order for the browse display for both authenticated (i.e. logged in) and unauthenticated (i.e. public) users - this setting controls the default sort of records for logged in users, while the setting described below, Sort browser (anonymous), affects the default sort for public users.

Options available include:

• Title/name: An “alphabetic” A-Z sort (but see the IMPORTANT admonition below) based on the title or authorized form of name
• Date modified: Will sort based on the date the records were created or last modified.
• Identifier: A-Z (but see the IMPORTANT admonition below) based on the unique identifier value added to the record
• Reference code: A-Z (but see the IMPORTANT admonition below) based on the reference code associated with the description. See the related setting, Inherit reference code (information object) for more information.

Important

The Title/name, Identifier, and Reference code sorts are all based on what is sometimes known as ASCII sort - that is, the sort is not a true alphabetic sort as humans think of it, but rather as computers do.

Elasticsearch does not naturally apply alphabetic sort in a human-friendly way (what is often known as “natural sort” in computer science) - instead, it applies what is known as ASCII sort, based on the order of the characters in the ASCII character encoding scheme. Consequently, some results may appear out of order, depending on how the values have been entered. Artefactual hopes to improve sorting in AtoM for future releases. In the meantime, below is an image of an ASCII table - sort order is determined based on this schema - so that a description whose title starts with “A” will be preceded by one starting with a number, which in turn will be preceded by one beginning with a quotation mark, which will be preceded by a description that begins with a space before its first character. If you are concerned about sort order, be sure to consider this when naming your records.

By default in a new installation, 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)¶

This setting controls the default sort order of records shown on Browse pages in AtoM - specifically, archival description results. Sorting can always be changed by users via the sort button available on related search and browse pages, but an administrator can use this setting to control the default sort when arriving on the page for the first time.

Administrators can configure default sort order for the browse display for both authenticated (i.e. logged in) and unauthenticated (i.e. public) users - this setting controls the default sort of records for public (i.e. anonymous; unauthenticated) users, while the setting described above, Sort browser (users), affects the default sort for logged in users.

Options available include:

• Title/name: An “alphabetic” A-Z sort (but see the IMPORTANT admonition below) based on the title or authorized form of name
• Date modified: Will sort based on the date the records were created or last modified.
• Identifier: A-Z (but see the IMPORTANT admonition below) based on the unique identifier value added to the record
• Reference code: A-Z (but see the IMPORTANT admonition below) based on the reference code associated with the description. See the related setting, Inherit reference code (information object) for more information.

Important

The Title/name, Identifier, and Reference code sorts are all based on what is sometimes known as ASCII sort - that is, the sort is not a true alphabetic sort as humans think of it, but rather as computers do.

Elasticsearch does not naturally apply alphabetic sort in a human-friendly way (what is often known as “natural sort” in computer science) - instead, it applies what is known as ASCII sort, based on the order of the characters in the ASCII character encoding scheme. Consequently, some results may appear out of order, depending on how the values have been entered. Artefactual hopes to improve sorting in AtoM for future releases. In the meantime, below is an image of an ASCII table - sort order is determined based on this schema - so that a description whose title starts with “A” will be preceded by one starting with a number, which in turn will be preceded by one beginning with a quotation mark, which will be preceded by a description that begins with a space before its first character. If you are concerned about sort order, be sure to consider this when naming your records.

By default in a new installation, the sort order is set to “Alphabetic” for 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. By default in a new installation, this setting is set to “card.”

Tip

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:

• Browse archival institutions
• Search archival institutions
• Archival Institutions

Default archival description browse view¶

Similar to the Default repository browse view setting, this setting will determine if the “card view” (used by default on the Digital object browse page) or the “results stub view” (the default description search/browse view in new AtoM installations - called “table” in the related setting) is used when users first arrive on the archival description search/browse page. By default in a new installation, this setting is set to “table” - aka the results stub view.

Note that this setting will not affect the use of the card view on the Digital object browse page - however, an administrator could change this by altering the path in the related node of the browse menu - for more information on editing menus, see: Manage Menus.

Additionally, even once set, any user can easily toggle between the results stub view and the card view, by using the view toggle button that appears above archival description and digital object results:

For more information on working with archival descriptions, see: Archival Descriptions. For information on searching, browsing, and navigating in AtoM, see:

• Search
• Browse archival descriptions
• Navigation in AtoM
• Advanced search

Multiple repositories¶

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 facet filter on the “Browse archival descriptions” page. Once a specific description linked to an archival institution, or a repository record has been visited, AtoM will also provide the option to filter searches in the global search box to the most recent repository - for more information, see: Institutional search box delimiters

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. Other changes include:

• Hiding the repository facet filter from archival description search and browse result pages
• Hiding the repository filter in the advanced search panel
• Hiding the Institutional search box delimiters in the global search box
• Hiding the related repository name in search/browse result stubs

Enable institutional scoping¶

Institutional scoping adds additional visual cues and user interface elements to better support searching and browsing within the holdings of one archival institution when used in a multi-repository system. We strongly recommend that the setting above, Multiple repositories, is set to “Yes” when using this setting.

When enabled (i.e. set to “Yes”), this setting will add an institution block to the repository view page, consisting of the repository logo, as well a dedicated search box and browse menu that will both return results linked to the current archival institution.

Similarly, when an archival description search or browse page is filtered (or “scoped”) to a particular repository, the institution block will appear, and (if applied) the custom background color of the institution will also be displayed behind the scoped search results.

Additionally, the Institutional search box delimiters are disabled when Institutional scoping is enabled - the global search box in the AtoM header bar will only return results from all repositories, while the dedicated search box inside the institution block can be used to search the holdings of the scoped repository. As such, the institution block offers users a method of remaining “scoped” to one institution’s holdings - users can still search and browse across all repositories using the global search box and browse menu found in the AtoM header bar, but the institution block provides a method of better limiting results to one institution as a user explores.

Finally, the institution block will also appear on the view page of a related archival description, but only if the description is arrived at via one of the scoped elements - i.e. the holdings list on the repository view page, or from a scoped search or browse page. If a user arrives at the archival description via a global search or browse page, the institution block will not appear.

An administrator can customize the search box header text via Admin > User interface labels, using the institutionSearchHoldings field - for more information on changing these settings, see: User interface labels. At installation, the default text label is “Search our collection.”

The institution block’s dedicted browse menu can also be customized via Admin > Manage menus, under the browseInstitution menu - for more information on working with menus, see: Manage Menus.

Back to top

Enable description change logging¶

This setting will enable a basic audit log for archival descriptions in AtoM. When enabled, the log will capture basic information on creation and modification events related to archival descriptions, including date, type (creation or modification), username, and/or related description title, depending on where the information is viewed. Note that the contents of specific changes made are not currently captured as part of the modification history’s audit trail.

Once enabled, authenticated (i.e. logged in) users with sufficient permissions can view the modification history for a description by opening the “More” menu in the button block at the bottom of the description’s view page, and selecting “View modification history.” For more details, see:

• View the modification history of an archival description

Users can see their own description modification history by navigating to their user profile. An administrator can view the description modification history for any user. Fore more details, see:

• View a user’s description modification history

Additionally, an administrator can filter archival description results in the Description updates module by a specific username. For more information on using the Description updates module, see:

• Description Updates

Show tooltips¶

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).

Administrators can select “yes” to to have tooltips appear in edit pages as the user enters data. Selecting “no” will disable tooltips.

Generate description permalinks from¶

This setting allows an administrator to determine if the slug (or permalink) generated from an archival description when it is saved is derived from the title, or from the reference code of the description (for more information on how reference codes are constructed in AtoM, see above: Inherit reference code (information object)). By default, AtoM will derive the slug from the title of a description - the title will be sanitized by removing capitalization, spaces, and special characters; it will also be truncated if it exceeds a certain length. Administrators can now choose, via this setting, if they prefer that the slug is derived from the identifier or the reference code (with or without the country and repository code included) instead.

Note that this setting does not apply retro-actively to descriptions already created. It will only apply to new descriptions created after changing the setting.

For further context on slugs in AtoM, see: Notes on slugs in AtoM

Use any valid URI path segment and uppercase character in slugs¶

This setting will affect how AtoM generates permalinks, or slugs for new records. In new installations, this setting is set to “No” by default.

When set to “No,” generated slugs will only allow digits, letters, and dashes. Sequences of unaccepted characters (e.g. accented or special characters, etc.) are replaced with valid characters such as English alphabet equivalents or dashes. When set to to “Yes,” AtoM will allow upper case characters, any valid unicode characters as specified in RFC 3987 including accented characters, and some special characters such as: , - _ ~ : = * @. For further details, see:

• Notes on slugs in AtoM

The command-line task to generate slugs, and AtoM’s Rename module (which will allow users to edit the slug associated with an archival description) will both respect and enforce the setting going forward. However, changing this setting will not automatically alter existing slugs. For more information, see:

• Generate slugs
• Rename the title or slug of an archival description

Default publication status¶

This setting determines whether new archival descriptions will automatically appear as draft records or published records. By default, public users (i.e. those who are not logged into AtoM) cannot see draft descriptions.

Note that this setting also affects imported descriptions. For more information, see Archival Descriptions - specifically, see:

• Publish an archival description

Show available drafts notification upon user login¶

This setting, when enabled, will display a notification with a count of the number of draft archival descriptions currently available in AtoM. A link to the Description updates page is also provided if users wish to review the current available draft records - for more information on working with the Description updates page, see: Description Updates.

This notification, when enabled, will be visible to all authenticated (i.e. logged in) users.

SWORD deposit directory¶

The SWORD deposit directory is currently being used to support packages deposited by Archivematica into AtoM. If you do not know the name of your deposit directory, consult with your system administrator. The default is /tmp.

AtoM 2.7 has added a new feature that deletes the DIP directory from the SWORD deposit after uploading the DIP to AtoM. In order for AtoM to delete this directory, the AtoM user (www-data or nginx by default) must have write permissions to this directory in order to delete it. The easiest way is to use the setfacl command.

Using the default SWORD deposit (`/tmp`) will not work and setfacl should not be used on the `/tmp` directory as it could cause security issues when setting new permissions.

If you are using the archivematica user to rsync from Archivematoca to AtoM, you can create a new SWORD deposit directory on `/home/archivematica`.

First, install the acl package on Ubuntu or CentOS:

sudo apt-get install acl # Ubuntu
sudo yum install acl  # CentOS

Create a new SWORD deposit directory:

sudo mkdir /home/archivematica/atom_sword_deposit
sudo chown archivematica:www-data /home/archivematica/atom_sword_deposit
sudo chmod 770 /home/archivematica/atom_sword_deposit

Set the ACL on new directory:

sudo setfacl -d -m u:www-data:rwX /home/archivematica/atom_sword_deposit

The ACL sets rw- permissions for files and rwx permissions for directories for the nginx user and then the www-data (or nginx) user can delete the temporay DIP directory.

Almost all the *NIX filesystems support ACL. NFSv4 can support ACLs but still requires the server to support ACLs. Anyways you can force the uid and gid for new files when mounting cifs or nfs on /etc/fstab.

Google Maps Javascript API key setting¶

This setting allows you to store and use a Google Maps API key - AtoM relies on this setting to be able to add dynamic Google maps to the view page of a repository, and to the Metadata area of a digital object, when latitude and longitude values are provided. For more information on these features, see:

• Add a Google map to an archival institution
• Add dynamic maps to your digital object metadata

You can request a Google Maps API key free of charge - all you need is a Google account. For more information, see:

• https://developers.google.com/maps/documentation/javascript/get-api-key

Generate archival description reports as public user¶

This setting relates to the creation of file and item-level reports for archival descriptions, as well as finding aids - for more information, see:

• File and item list reports and printing
• Generate, upload, download, and print finding aids

This setting determines whether or not draft records and retrieval information is included in the reports generated or not - that is, physical storage information such as location, container type, and name.

When this setting is set to “Yes”, then reports generated will not include draft descriptions. Additionally, if physical storage information is hidden via the Visible elements settings, then physical storage information will also be excluded from finding aids. When set to “No”, then the reports and finding aids will include drafts and physical storage information.

Cache description XML exports upon creation/modification¶

AtoM includes several options for exporting archival description metadata in XML format - for more information, see: Export XML.

Additionally, users can enable the OAI plugin to allow harvesters to collect archival description metadata via the OAI-PMH protocol, in EAD 2002 or Dublin Core XML - for more information, see: OAI Repository.

Normally, when exporting or exposing archival description metadata, the XML is generated synchronously - that is, on request via the web browser. However, many web browsers have a built-in timeout limit of approximately 1 minute, to prevent long-running tasks and requests from exhausting system resources. Because of this, attempts to export or harvest EAD 2002 XML for large descriptive hierarchies can fail, as the browser times out before the document can be fully generated and served to the end user.

To avoid this, AtoM includes this setting, which allows users to pre-generate XML exports via AtoM’s job scheduler, and then cache them in the downloads directory. This way, when users attempt to download large XML files, they can be served directly, instead of having to generate before the browser timeout limit is reached.

When this setting is set to “Yes,” then anytime an archival description is created or modified via the user interface, this will automatically trigger a background job that will generate and cache EAD 2002 XML and DC XML for the related resource. With any new description or edit, two jobs are initiated - one to generate the EAD 2002 XML, and the other to generate the Dublin Core XML.

Highlighted in red is an example of the 2 jobs triggered by an edit to an archival description when the Cache XML setting is turned on - one job to generate an updated version of the cached EAD 2002 XML, and another job to generate an updated version of the cached DC XML.

The XML generated will be cached in AtoM’s downloads directory - 2 subdirectories named ead and dc will automatically be created, and the XML will be stored by type in these two subdirectories.

When users attempt to download XML from the view page of an archival description, AtoM will check if there is a cached copy of the requested XML and if so, it will serve it. If there is no cached version available, then AtoM will fall back to the default behavior of generating the XML on request.

In an OAI-PMH request, if a cached version of the EAD 2002 XML is available, AtoM will serve it in response to oai_ead requests - if there is not a cached version, then AtoM will return a “Metadata format unavailable” reponse. In contrast, if no cached DC XML exists, the OAI Repository module will generate DC XML on the fly to respond to the request. For further information, see: OAI Repository.

By default, cached XML files are generated for public users, meaning that draft descriptions are not included in the XML.

There is also a command-line task available that will generate cached EAD 2002 and DC XML for all existing descriptions. See:

• Generate and cache XML for all archival descriptions

If you are making many edits to your AtoM site, you may want to disable this setting until your edits are complete and then run the command-line task, to avoid constantly triggering many jobs.

Back to top

Saved clipboard maximum age¶

Both public and authenticated (i.e. logged in) users have the option to save results pinned to AtoM’s clipboard, and load them at a later date - for more information, see:

• Saving your clipboard for another session
• Loading a saved clipboard

To avoid having AtoM’s database grow indefinitely when the clipboard is used heavily, saved clipboards are not stored indefinitely. Instead, an administrator can configure how many days saved clipboards are stored before being purged from the database.

The setting takes a numeric value that represents the number of days a saved clipboard should be stored before it is eligible for automatic deletion from the database.

Note that AtoM also has a command-line task that can be used by a system administrator to manage and delete saved clipboards. For more information, see:

• Delete temporary data (saved clipboards, access log, and downloads)

Clipboard sending¶

These settings can be configured to integrate the clipboard with a third-party site or application, for use in reference requests, loans, or other similar cases. When configured, it will allow results on the clipboard to be sent to a specified URL as a JSON array of slugs. Data can be sent using either HTTP POST or GET methods.

When a user adds items to the clipboard and these settings are enabled, an additional button will display on the clipboard’s view page. The button text can be customized, along with the text shown to the user while the results are being sent. When clicked, AtoM will send a JSON array of the clipboard results to the target URL, and then will redirect the user to that URL for further action.

In new installations, this functionality is disabled by default, but can be configured and enabled via the settings described below.

Enable digital object export functionality¶

In AtoM 2.7 and higher, an administrator can enable users to include digital objects with archival description XML and CSV exports from the clipboard. By default, this setting is set to “No” in new installations.

When set to Yes, the clipboard export options screen will include an “Include digital objects” checkbox. If the user checks that checkbox, any digital objects attached to the archival descriptions being exported will be included in the ZIP package the user downloads. Administrators should ensure that the server on which the AtoM instance is installed has enough processing power, memory and storage space to create and temporarily store zipped packages of the digital objects selected for download.

Note that if the user checks the “Include digital objects” checkbox in the export options screen, it is no longer possible to include descendants in the export, and the “Include descendents” checkbox will be greyed out. This is a safeguard designed to prevent users from deliberately or inadvertently exporting large descriptive hierarchies with hundreds or thousands of digital objects attached at descendant levels of description.

For more information on using this feature, see:

• Including digital objects with an XML clipboard export
• Including digital objects in a clipboard CSV export

Back to top

PDF page number for image derivative¶

This setting will affect the digital object derivatives generated by AtoM when uploading multi-page content, such as a PDF.

By default, AtoM will use the first page of multi-page content (such as a PDF) when generating the reference display copy and thumbnail 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 make changes, remember to click the “Save” button in the button block.

Maximum length on longest edge (pixels)¶

This setting determines the maximum size of the reference display copy derivative created from a master digital object during digital object upload. It is measured in pixels, and will be applied either to height or width - whichever side reaches the pixel limit first.

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 or height 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 size to suit the requirements of their institution or network.

Back to top

Enable accession mask¶

This setting controls whether or not the Accession mask (described in the section below) is enabled or not.

When this setting is set to “yes,” then when a user creates a new accession record, the Accession number field will be prepopulated with the next unique value based upon the Accession mask settings - users can still manually edit the pre-populated value provided by the mask, so long as a unique number is used.

When this setting is set to “no,” then the accession mask will not be used, and when creating a new accession record, the accession number field will be blank.

See:

• Add a new accession record
• Accession mask

Accession mask¶

When working with an accession record, AtoM requires that a unique Accession number be added - for more information, see: Add a new accession record. To help ensure that accession record numbers are created in a consistent and unique manner, AtoM includes an accession mask, which can define a pattern by which the next unique accession number is generated. Turning the mask on or off is controlled by the setting described above, Enable accession mask.

On installation, the accession mask is enabled by default, and prepopulated with a suggested value that will generate unique accession numbers. Expressed in the mask setting as %Y-%m-%d/#i, this value will generate a unique accession number for every new accession record compiled from the following elements: YEAR-MONTH-DAY/Incremental#. So for example with the default mask setting, the first accession you create, if it was generated on January 01, 2018, would have an accession number of 2018-01-01/1.

This mask, or default counter, can be changed by an administrator to suit institutional needs, using text strings and PHP strftime parameters. To add leading zeroes to the unique incrementing number for example, you can add more i characters to the mask setting - so for example %Y-%m-%d/#iii would lead to incremental numbers like 001, 002, 003, etc.

The value of the incremental number is based on the Accession counter value, described below. An administrator can choose to manually change or reset the counter number if desired.

For more information on accession records, see Accessions.

Accession counter¶

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. The value of this counter is used to inform the incremental value used in the Accession mask, described above.

Enable identifier mask¶

This setting controls whether or not the Identifier mask (described in the section below) is enabled or not.

When this setting is set to “yes,” then when a user creates a new archival description, the Identifier field will be prepopulated with the next unique value based upon the Identifier mask settings - users can still manually edit the pre-populated value provided by the mask. AtoM does not enforce the uniqueness of archival description identifier values.

When this setting is set to “no,” then the identifier mask will not be used to pre-populate identifier values, and when creating a new archival description, the identifier field will be blank. However, a Generate identifier option will still be provided below the field - if clicked, then the settings defined in the Identifier mask will be used to populate the field.

See:

• Add a new archival description
• Identifier mask

Identifier mask¶

The Identifier mask can be used to manage the creation of unique archival description identifier values when creating new descriptins. By enabling the identifier mask, all descriptions created through the user interface will be assigned an identifier based on a pre-defined pattern.

On installation, the identifier mask is disabled by default - to change this, use the Enable identifier mask setting described above.

The identifier mask is prepopulated with a suggested value that will generate unique identifiers. Expressed in the mask setting as %Y-%m-%d/#i, this value will generate a unique identifiers for every new archival description created, comprised of the following elements: YEAR-MONTH-DAY/Incremental#. So for example with the default mask setting, the first description you create, if it was created on January 01, 2018, would have an identifier of 2018-01-01/1. The value of the parameter, #i, represents the Identifier counter value.

This mask, can be changed by an administrator to suit institutional needs, using text strings and PHP strftime parameters. To add leading zeroes to the unique incrementing number for example, you can add more i characters to the mask setting - so for example %Y-%m-%d/#iii would lead to incremental numbers like 001, 002, 003, etc.

The value of the incremental number is based on the Identifier counter value, described below. An administrator can choose to manually change or reset the counter number if desired.

It is also possible to replace an existing archival description identifier with one based on the identifier mask by editing a description and selecting Generate identifier below the identifier field.

For more information on creating archival descriptions, see:

• Add a new archival description

Identifier counter¶

The identifier counter defines incremental integer at the end of a generated identifier, represented in the identifier mask as #i. AtoM provides you with a count of the number of archival description records created via the user interface. This value is then used as part of the Identifier mask as the incrementing number value.

Deleting an archival description will not affect the counter - it simply adds the next integer, rather than looking for unused integers. 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.

Inherit reference code (information object)¶

In AtoM, a reference code is a unique identifier string associated with an archival description, created through the combination of inherited identifiers from other related entities. While an individual description identifier is rarely globally unique (and is often not unique even in the same AtoM instance), by combining additional elements such as a the country code, repository code, and any parent identifiers, a unique reference code can be created, which facilitates international discovery and exchange.

When this setting 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
• etc.

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.

Inherit reference code (DC XML)¶

This setting controls whether an individual archival description’s identifier or its full inherited reference code is used when a description is exported as Dublin Core XML (including when exposed via AtoM’s OAI Repository module.

When set to “No,” only the current description’s identifier will be included in DC XML exports. When set to “Yes,” AtoM will use the reference code inheritance model described above in Inherit reference code (information object), meaning in addition to the description’s local identifier, the <dc:identifer> will also include:

• The country code of any related archival institution (derived from the country added in the address section of the related repository record)
• The repository identifier of any related archival institution
• Identifiers of any parent descriptions, separated by the default separator defined in the Reference code separator setting

By default, this setting is set to “No” in new installations.

Back to top

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. Any attempts to log in without using proper HTTPS will redirect to the home 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:

1. Upper case letters
2. Lower case letters
3. Numbers
4. Special characters

Choose “yes” to require authenticated (logged-in) users to have strong passwords.

Back to top

Treeview type¶

This setting allows administrators to choose between two different display formats for the treeview. For more information about the treeview in AtoM, see: Treeview.

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. With the full-width treeview, users can configure which elements are included in each node - for more information, see below: Full-width treeview settings.
• 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.

Sidebar treeview

Full width treeview

For more information on each treeview type, see:

• Sidebar treeview
• Full-width treeview

With the 2.5 release, administrators can also choose to show a browse hierarchy option on the archival descriptions browse page. This new feature will provide users with an additional way of browsing records held in AtoM - via a full-page version of the full-width treeview that contains all descriptions.

This new browsing mode will be disabled by default in new installations. To offer that option to users, an administrator can enable this feature by choosing ‘Yes’ to ‘Show browse hierarchy page’ in the treeview settings. When enabled, a new link will appear on the archival description search/browse page, labelled “Browse by hierarchy.”

For more information on browsing with this option, see:

• Browse

Make full width treeview collapsible on description pages¶

This setting affects the default display of the full width treeview when users first arrive on the view page of an archival description. See Treeview type above for more information on the different treeview types available in AtoM.

By default in new AtoM installations, this setting will be disabled (i.e. set to “no”). When this setting is enabled (i.e. set to “yes”), the full-width treeview will be wrapped in a collapsible section, similar to The Advanced search panel on archival description search and browse pages.

Once the setting is enabled, the treeview collapsible section will be closed when users first arrive on a view page, but users can click to expand it, and it will maintain its open state as users navigate to different descriptions in the hierarchy via the treeview nodes.

Users can click the container heading again at any time to collapse or expand the treeview. Navigating elsewhere or triggering a full page refresh will result in the treeview widget returning to its default collapsed state.

An administrator can also customize the labels used on the widget - the default text included during installation reads “Show hierarchy” when collapsed, and “Hide hierarchy” when expanded. To customize these default labels, see:

• User interface labels

Show browse hierarchy page¶

The hierarchy browser is a user interface element that can be enabled or disabled by an administrator. When enabled, it provides end users with a full-width treeview of all of AtoM’s archival description holdings. Users can expand and collapse individual nodes in the treeview to explore the hierarchical arrangement of a specific archival unit; however, clicking any node in the hierarchy browser will redirect the user to the related description’s view page. For more information on using the hierarchy browser, see: Using the Hierarchy browser.

When “Show browse hierarchy page” is set to yes, a new option will be added to the archival description browse page, above the results:

This option will be available to all users, including unauthenticated (i.e. public, or not logged in) users. When clicked, users will be taken to a full-page, full-width treeview containing all top-level descriptions in AtoM, which can be used for high-level browsing:

See the related browse documentation for further information on the hierarchy browser’s behavior and use.

When the setting is set to no, the hierarchy browser will not be created, and the link on the browse page will not be shown.

Sidebar treeview settings¶

Settings in this area relate only to the sidebar treeview. They will not affect the behavior of the full-width treeview.

Full-width treeview settings¶

Settings in this area relate to the functionality and display of the full-width treeview. They do not affect the behavior of the sidebar treeview.

Currently all elements in this section relate to what information is displayed in the treeview for each node. Users can configure whether the identifier/reference code, level of description, and/or dates of creation are included in each node’s display.

When all elements are displayed, the ordering of the metadata elements is as follows:

[Level] ID - Title of description, dates

So for a Series level description with an identifier of 004 called “Photographs” and created in 1959, the display with all elements would be:

[Series] 004 - Photographs, 1959

Each configurable element is described further below.

Items per page¶

This setting controls how many immediate child descriptions are loaded below the top-level description when users first visit a hierarchical description’s view page. It also controls the number of top-level descriptions that are added to the hierarchy browser on first load

Like the sidebar treeview, for performance reasons AtoM may not load all available descriptions at once in the full-width treeview, when there are many immediate children below the top-level description in the archival unit. The default value for this behavior is 50 - meaning, if there are more than 50 immediate children below the parent description, AtoM will add a count of the number of remaining records not immediately displayed to a button in the top right corner.

Clicking on that button will load the next set of records, using this “items per page” setting value to determine how many to load at once. If there are still more records not displayed, the number of remaining records will be shown and the user can choose to see the next set, or return to the beginning by choosing “reset”.

To allow for more records to be loaded initially, and with each subsequent click of the “More” button, an administrator can adjust this “Items per page” value. The minimum value is 10, and the maximum value that can be set via the user interface is 10,000.

Tip

If your site has very large hierarchies and you need to set the initial page load value higher than 10,000 records, a system administrator can modify this max value in the configuration file found at config/app.yml. Look for the following line in the file:

treeview_items_per_page_max: 10000

After the change, you will need to clear the application cache, and restart PHP-FPM. For more information, see:

• Manage AtoM configuration files
• Clear cache
• Restarting PHP-FPM

The behavior is similar for the hierarchy browser, though instead of affecting the number of children loaded below the top-level archival description, here the setting will determine how many top-level descriptions are loaded in the initial view. See Using the Hierarchy browser for more information.

Back to top

Total space available for uploads¶

This field will display the used space for digital objects as well as the total space available. The space available is determined by a configurable setting that a system administrator can modify in one of AtoM’s configuration files - see:

• config/app.yml

Archival institution upload limits¶

In addition to setting a global limit on the total space available for digital object uploads, an administrator can also set individual upload limits per archival institution, which can be useful when AtoM is used as a multi-repository system. There is also a setting for configuring what the default upload limit is per repository - see below:

• Default archival institution upload limit (GB)

This setting controls whether or not the configurable per-repository upload limit widget is enabled and displayed. When set to “Enabled”, an administrator can further customize the upload limit per archival institution using the widget displayed to authenticated (i.e. logged in) users on the related repository view page. However, disabling this widget can sometimes be useful for improving page load performance, particularly in large installations.

For more information on using the per-repository upload limit widget, see:

• Set digital object upload limit for an archival institution

Default archival institution upload limit (GB)¶

In addition to setting a global limit on the total space available for digital object uploads, it’s also possible to set a default limit per archival institution when using AtoM as a multi-repository system. When set, this will be applied as the new default upload limit per institution.

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 and manage digital objects.

Upload multi-page files as multiple descriptions¶

Normally, a multi-page file such as a PDF is uploaded as a single digital object, linked to a single target archival description. However, it is possible to break up each page into its own digital object, and attach these to new child 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.

Back to top