Generate, download, and print finding aids¶
AtoM allows logged-in users to generate printer-friendly finding aids in either PDF or RTF format. The format and some other parameters can be set by administrators in the finding aid settings. Once the finding aid is generated, it can be downloaded from the top parent description level of an archival description by any user, via a link provided in the right-hand context menu.
Finding aids in AtoM are generated asynchronously in the background using
Gearman, AtoM’s job manager. You will need to make sure
that Gearman is properly configured during installation to be able to generate
finding aids - for more information, see: Asynchronous jobs and worker management.
Additional information about the status of any Finding aid generation job
can also be seen via 
Manage > Jobs - for more information on the Job
management page in AtoM, see: Manage jobs.
Important
At this time, the finding aids being generated have only been formatted to use the Canadian Rules for Archival Description (RAD) template. If you are using another template, you can still generate finding aids - but they will be formatted according to the RAD standard. We hope to be able to add further options in the future. For more information on the RAD standard, see: Rules for Archival Description. For an overview of all data entry templates in AtoM, see: Data entry / templates and Descriptive standards.
Below you’ll find information on how to configure the finding aid settings, generate a finding aid, view information on the status of your finding aid generation request, and how users can view the finding aid after it has been successfully generated.
Jump to:
Finding aid settings¶
Before generating your finding aids, you will want to carefully review the
settings for finding-aid generation. These can be accessed by an
administrator by navigating to 
Admin > Settings, and
clicking on “Finding aid” in the settings menu on the left side of the page.
Finding aid format: AtoM can generate finding aids in either Portable Document Format (PDF), or in Rich Text Format (RTF). Choose whether you would like finding aids generated in PDF or RTF - essentially, if you would like users to have the ability to easily edit your finding aids locally after download, choose RTF, and users should be able to open the finding aid with any common document editor such as LibreOffice or Microsoft Word. If you prefer that the finding aids remain static and cannot be as easily edited by users, PDF will be a better choice. Note that most modern browsers include a PDF reader (meaning that once a user clicks the download button for a PDF-formatted finding aid, the finding aid will usually open in a new tab and be visible immediately to the user), while RTF finding aids will require local download to access, and will need to be opened in a separate application.
Warning
At present, you can only have 1 format of finding aid used for download throughout AtoM. If you have previously generated a bunch of PDF finding aids, and then you switch this setting to RTF, it will make the previous finding aids inaccessible, and you will need to re-generate new finding aids in the new target format. If you switch the setting back, your PDFs will be available again - the file is still there, but this setting also determines what format the download link will look for, so unless you generate all your finding aids in both formats, be careful when switching settings!
Finding aid model: At present, this setting will change how lower-level descriptions (e.g. children, such as files and items) are presented in the finding aid. You can choose between “Full details” and “Inventory summary.” Hover your cursor over the Finding aid model field label to see a brief tooltip:
The “Inventory summary” option is best used when your lower-level descriptions do not include a lot of detail - it includes lower-level descriptions (such as files and items) in a summary table beneath each parent record, such as a series, sub-series, subfonds, etc. When lower-level descriptions include more detail, such as a scope and content description, you may want to include this information in the finding aid - choose “Full details,” and each level of description will display all fields available. A comparison image is included below, with the Inventory summary on the left, and a sample item description with full details on the right:
Generate Finding Aid as public user: This setting determines whether or not Draft records are included in the PDF generated, as well as physical storage information, depending on your Visible elements settings for physical storage.
When set to “Yes,” draft descriptions are excluded from the finding aids generated. If you have hidden physical storage information via the Visible elements module, it will also be excluded from new finding aids generated.
For more information on the publication status and setting records as draft or public, see: Publish an archival description. For more information on using the Visible elements module, see: Visible elements.
Important
At this time, no other Visible elements settings are affected by this finding aid setting - only physical storage information. This means that even with the public setting engaged, any other fields you have hidden via the Visible elements module will still be included in your finding aid! Be sure to review your finding aids carefully.
Tip
If you have the “Generate Finding Aid as public user” setting set to “Yes,” the option to generate a finding aid will not appear on any draft descriptions in AtoM. You will have to publish the description before you can generate a finding aid.
Generate finding aid¶
Once you have configured the finding aid settings, you can now begin to generate finding aids for your archival descriptions. While the settings can only be configured by an administrator, at present any authenticated user can generate a finding aid for a description they have permission to view. An administrator can review all finding aid generation requests via the Jobs page - for more information on managing jobs in AtoM, see: Manage jobs.
To generate a finding aid:
- Navigate to the archival description for which you would like to generate a finding aid. You can do this by browsing or searching for the archival description - see Access content for more information on navigation in AtoM.
Note
You can only generate a finding aid for a top-level description - e.g. a parent record such as a fonds, collection, or perhaps a series (depending on local practice). The level of description in AtoM does not determine if it is a top-level description or not (in AtoM, even an item-level description could be considered a top-level description if it has no parent) - instead, a description is considered top-level if it is not the child of any other descriptions in a hierarchy.
In the right-hand context menu, you will see a section titled “Finding aid”. For logged-in users, this menu will include status information, and if a finding aid has already been generated, a download link for the current finding aid. Status messages are never shown to public users - the finding aid section will only appear in the context menu if a finding aid has been successfully generated.
Finding aid statuses and their meanings
- Unknown: No finding aid has previously been generated for this description.
- File missing: Finding aid was previously generated, but the Finding aid settings for have sinced changed. Generate a new finding aid to resolve.
- Error: Something went wrong with the finding aid generation. See the Troubleshooting finding aid issues section below, and try generating a new finding aid.
- Generating: The job is underway and the finding aid is generating. Refresh the page for an updated status, and/or visit the Jobs page - see: Manage jobs
Tip
Don’t see the Finding aid section in the right-hand context menu? It could be because your archival description is still in draft status, and your Finding aid settings are set to “Generate Finding Aid as public user.” AtoM will hide the link to generate finding aids from any draft descriptions when this setting is engaged. You can either change your settings (see above), or you can publish the description - see: Publish an archival description.
- To generate a new finding aid, click the “Generate” link in the Finding aid section of the right-hand context menu. AtoM will reload the page, and the Finding aid section will display a status message of “Generating”.
- To update the status and determine if your finding aid was successfully generated, wait a moment for the process to execute, and then refresh the browser. Alternately, you can navigate to the jobs page for more details about the status of a job - see: Manage jobs for more information.
- If the finding aid has failed to generate, you will see an “Error” status
message in the right-hand context menu. You can also navigate to
Manage > Jobs to see if further details on the cause of the error are
available. See the troubleshooting section
below for suggestions on how to resolve
errors.
- If the finding aid has generated successfully, you will see a Download link when you refresh the page. Click on this link to view your finding aid. Public users will now be able to see this Download link as well.
- You can re-generate a new finding aid at any time by following steps 1-5 above. This can be useful if you make edits to your archival description or its children, or if you change the format of the finding aid in the settings.
Finding aid layout¶
AtoM’s finding aid generation includes a simple cover page, a table of contents, and some basic styling to separate areas of the finding aid.
The cover page includes the name of the archival institution linked to the description, the title of the archival unit (e.g.title of the fonds, collection, etc), The date the finding aid was generated, the language of the description, the address of the archival institution, and the URL from which the source description originates in AtoM. An example cover is pictured below:
The table of contents will be automatically generated, and includes hyperlinks to the related section. In a PDF, this means that bookmarks to each main section of the finding aid are included by default.
Note
The numbering of the table of contents has been known to display occasional problems when generated in RTF and then viewed in Microsoft Word. This is a problem with Word’s display of RTF rather than a problem with the file. The table of contents displays in other document viewers correctly, such as OpenOffice and LibreOffice.
Each page includes a simple header and footer. The header includes the title of the archival unit, and the identifier. The footer includes the name of the related archival institution, and a page number.
At present, AtoM has two primary layout options for the printable finding aids: “Full details,” and “Inventory summary.” These options are managed via the Finding aid settings - see: Finding aid settings.
The Inventory summary option is best used when there has been minimal description added to lower levels, such as file and item-level records. AtoM will display these lower levels in a summary table beneath each parent series (or sub-series, etc). The Full details will treat each lower-level record similar to the higher-level ones, and all fields will be displayed. A sample first few pages of each, minus the cover page, has been included in an image below for comparison.
Troubleshooting finding aid issues¶
Below are a few common questions and problems users might encounter in generating finding aids, and some suggestions on how to address them.
Before proceeding, make sure that you have followed all the installation requirements for job scheduling in AtoM - for more information, see: Asynchronous jobs and worker management.
The AtoM Jobs page can possibly supply you with more information on any errors encountered, as finding aid generation is a job handled asynchronously in AtoM. For more information on the Jobs page, see: Manage jobs.
Jump to:
- Physical storage information is not included in my finding aid
- I don’t want to display physical storage information in my finding aid
- Draft descriptions are being shown in my finding aid
- There’s no option in the context menu to generate a finding aid
- My finding aid link says “Status: File missing”
- My scope and content is not included for file and item level descriptions
- Finding aid generation error; the jobs page says that “Exporting EAD has failed”
Physical storage information is not included in my finding aid¶
Physical storage information is excluded from the Finding aid if:
- The “Generate Finding Aid as public user” setting is set to YES, and
- The Visible elements module for your template is set to hide physical storage information from public users (e.g. the box is unchecked).
If you have included physical storage information with your descriptions via
AtoM’s Physical storage module, and would like it included in your finding aids,
you will also need to display it in the public view pages for
your descriptions. To do so, navigate to Admin > Visible elements and
make sure that the Physical storage option is 
checked.
Now you can re-generate your finding aids, following the steps above, Generate finding aid.
I don’t want to display physical storage information in my finding aid¶
Physical storage information is excluded from the Finding aid if:
- The “Generate Finding Aid as public user” setting is set to YES, and
- The Visible elements module for your template is set to hide physical storage information from public users (e.g. the box is unchecked).
If you have included physical storage information with your descriptions via
AtoM’s Physical storage module, and do not want it included in your finding aids,
you will also need to hide it in the public view pages for
your descriptions via AtoM’s Visible elements module. To do so, navigate to
Admin > Visible elements and make sure that the Physical storage
option is 
unchecked.
You will then need to check the finding aid settings, and make sure that the “Generate Finding Aid as public user” option is set to “yes”. See above for more details on the finding aid settings.
Now you can re-generate your finding aids, following the steps above, Generate finding aid.
Draft descriptions are being shown in my finding aid¶
If you don’t want draft descriptions shown in your finding aid, navigate to
Admin > Settings, and click the “Finding aid” section in the menu
on the left. AtoM will load the finding aid settings, described in detail
above.
Make sure that the “Generate Finding Aid as public user” option is set to “yes”, and remember to click the “Save” button in the button block if you make any changes.
Now you can re-generate your finding aids, following the steps above, Generate finding aid.
My finding aid link says “Status: File missing”¶
This could be because you changed the finding aid format in the Finding aid settings.
At present, AtoM can only offer one type of finding aid download at a time to users - there is no option for a public user to pick the format even if both a PDF and an RTF finding aid have been generated. This means that the “Finding aid format” setting is actually setting 2 things - the format for future finding aid generation, AND the default download format for finding aids.
If you have generated a bunch of finding aids in PDF format, and then you change the format setting to RTF, your previous descriptions with PDF finding aids will now display a “Status: missing” message, and the download link will be hidden from public users. This is because AtoM is now looking for an RTF finding aid, and not finding it. You can either generate a new finding aid in RTF format, or you can change the setting back - your PDF finding aids have not been lost. Once the Format setting is restored to PDF, any previous finding aids generated in PDF format will be available again via the Download link.
See also
My scope and content is not included for file and item level descriptions¶
This could be because you have selected the “Inventory summary” option in the “Finding aid model” settings. AtoM has two different stylesheets for finding aids. One includes only an inventory table with minimal details for lower-level descriptions such as files and items (the “Inventory summary” option); the other includes full details at all levels of description. A comparison image is included below, with the Inventory summary on the left, and a sample item description with full details on the right:
If you want all fields present in your lower-level descriptions to be available in the finding aid you generate, we suggest changing this setting to “Full details.” Remember to save your changes after making settings changes.
Now you can re-generate your finding aids, following the steps above, Generate finding aid.
See also
Finding aid generation error; the jobs page says that “Exporting EAD has failed”¶
AtoM generates its PDF finding aids by first exporting the archival description as EAD XML, and then transforming that EAD XML using an XSLT into the desired format (PDF or RFT).
For this process to work, the EAD XML must first be able to export - which means it must first be valid XML.
This means your EAD may fail to export properly if:
- You’ve used unescaped special characters, such as ampersands
& - You’ve used inline HTML elements to style the display of some fields in AtoM -
for example, using
<em>or<i>elements for emphasis or italics. - You’ve cut and pasted non UTF-8 encoded characters into AtoM - a common example
would be the curvy quotation marks used in many word processing applications like
Microsoft Word, instead of the standard UTF-8
straight quotes
"
We suggest you try reviewing your description(s) in edit mode and look
for some of these common errors that can affect EAD export. Remove any HTML you
have added inside AtoM’s edit fields. Make sure that you replace any non-standard
punctuation cut and pasted from common word processor applications. You can also
escape special characters using HTML character escapes - for example, &,
when written in an edit page field in AtoM and saved, will render in the
view page as &.
Other useful character escapes:
| Character | Character escape |
|---|---|
< |
< |
> |
< |
& |
& |
" |
" |
' |
' |
Now you can re-generate your finding aids, following the steps above, Generate finding aid.