Upload and manage digital objects¶

Link a single digital object to an archival description¶

A single digital object can be linked directly to an existing archival description in AtoM via the “Link digital object” option. Users can either upload a digital object, or link to an existing resource available on the web. Instructions on how to do both are included below.

To link a single digital object:

1. Navigate to the view page of an existing archival description in AtoM. You can do this by browsing or by searching for a specific archival description - see Access content for more information on navigation in AtoM.
2. Click on the “More” button in the button block; from the menu that appears, select “Link digital object”.

3. AtoM will redirect you to the link digital object edit page. Users can either upload a digital object, or link to an existing digital object available on the internet.

4. To upload a digital object locally, cick the “Choose File” button to navigate to and select a file on your computer or device. Click “Open” once the item has been selected from the window that will appear.
5. To link to an object on the internet, enter the URL to the external object to which you wish to link.

Important

To link to a digital object via the web, you must enter a URL that ends with the file extension of the resource to which you are trying to link - for example, to link to an image, the URL should end with .jpg, .png, etc. You can usually get to this URL by clicking on the resource directly, or by right-clicking and selecting “View image” etc in your browser.

6. Click the “Create” button in the button block. When you return to the view page, the reference display copy will be displayed in the digital object field, above the other fields linked to that archival description.

   Note

   Users can view or play the reference display copy (depending on the type of digital object). Authenticated (i.e. logged-in) users can also download the master digital object.

7. Objects with multiple pages, such as multi-page TIFFs or PDF files, will by default be displayed with single-page reference display copies. To have them viewed with a pager to allow the user to browse through the pages, go to Admin > Settings > Global > Upload multi-page files as multiple descriptions and select “Yes”; this will also cause all pages of a multi- page object to appear individually as child records of the description to which the object was uploaded. (See: settings).

You can upload any file format, but only supported formats can be viewed or played directly in AtoM. For a list of formats, see File formats. Formats that are not supported can still be uploaded: clicking the object will download it to the user’s desktop where (assuming the user has the required software) it can be viewed or played.

See below for more information on making changes to your digital object.

Back to top

Digital object metadata¶

When you link a digital object to an archival description, the “Digital object metadata” section on the archival description view page will include an “Access Copies” subsection.

1. Clicking on the “Access copies” subsection label link will collapse or expand the subsection.

2. The “Access Copies” subsection will include metadata about the “Master file”, “Reference copy”, and “Thumbnail copy” representations of the digital object. Specifically: filename, media type, mime-type, filesize, and uploaded (the timestamp for when the digital object was uploaded to AtoM).

   

3. An administrator user can toggle the display of specific “Digital object metadata” section fields on or off in the Admin > Visible elements > Digital object metadata area section. This only affects display for unauthenticated users. Any authenticated users will see all metadata elements in each section as long as those fields contain a value. For more information, see: Visible elements.

4. If the Reference representation or Thumbnail representation is deleted via the “Edit digital object” page, then the “Reference copy” and/or “Thumbnail copy” metadata is no longer displayed on the archival description view page. Additionaly, the thumbnail is not show on Browse pages and the reference copy is not displayed on view pages.

5. The filename for each representation is either shown as plain text or as a hyperlink. If it is a hyperlink, it indicates that this user has explicit download permission for this representation.

6. The icon underneath the “Master file”, “Reference copy”, and “Thumbnail copy” label is coloured black or grey. If it is grey it indicates that the user does not have access to that representation. Note that in the case of unauthorized users, the default setting is to display the reference copy at the top of the archival description view page. Therefore, the icon is coloured black for reference copies by default. However, an explicit hyperlink is not provided in the digital object metadata section for unauthorized users. This is to respect institutional policies around displaying a copyright access statement for downloaded digital materials. That feature only works for Master file representations. See Add a Copyright statement before allowing access to a master digital object.

   

   Tip

   Access to the “Master file”, “Reference copy”, and “Thumbnail copy” can be configured per user group. The “Access master”, “Access reference”, and/or “Access thumbnail” permission can be set to “Grant” or “Deny” for any user group, including unauthenticated (“anonymous”) users. See: Edit permissions.

8. Access to the “Master file”, “Reference copy”, and “Thumbnail copy” may be overridden by actionable PREMIS rights configured for individual archival descriptions and their digital object. See:

   • Make rights actionable on digital objects
   • Configure Disallowed and Conditional access statements

   For example, if a PREMIS right is added to an archival description where the “Act” is “Disseminate” and the “Restriction” is “Disallow”, then the hyperlinks in the “Digital object metadata” section are no longer active, all the document icons are coloured grey, and the reference copy of the digital object is no longer displayed on the archival description view page. Instead the customizable text of the “Disallow statement” is displayed at the top of the page as well as in a “Permissions” field for each Access copy representation, e.g. “Access to this record is restricted because it contains personal or confidential information. Please contact the Reference Archivist for more information on accessing this record.”.

   

   Note

   If the “Restriction” were to be changed to “Conditional” and the default permission settings are enabled then the “Reference copy” and “Thumbnail copy” become available again on the AtoM template. The customizable text for the “Condition Statement” is displayed in a “Permissions” field for the “Master file” representation, e.g. “This record has not yet been reviewed for personal or confidential information. Please contact the Reference Archivist to request access and initiate an access review.”.

Back to top

Digital object metadata for preservation files¶

If you or another user of a preservation system (e.g. Archivematica) has sent a DIP upload to an archival description slug in AtoM then thumbnails for the digital objects in that Dissemenation Information Package (DIP) will be displayed in the archival description’s digital object carousel.

When selecting one of the digital objects included in the DIP upload, the “Digital object metadata” section on the archival description view page will include a “Preservation Copies” and “Access Copies” subsection.

1. Clicking on either of these subsection label links will collapse or expand the subsection. See the Digital object metadata above for more about the “Access copies” section.
2. The “Preservation Copies” subsection will include metadata about the “Original file” and “Preservation copy” representations that are stored in the preservation system.

3. The “Preservation copy” metadata includes filename, filesize, and a timestamp for when the preservation system normalized (i.e. transcoded) the preservation copy from the original file.

4. The “Original file” metadata may include filename, file format name, file format version, format registry key (the unique key assigned to the file format by a format registry), format registry name (e.g. PRONOM), filesize, and ingested (the timestamp for when the preservation system received the original file).

5. If the preservation action system statement option is enabled, you will also see a “Permissions” field with custom text that is populated by an administrator via Admin > Settings > Permissions > Preservation system access statement (e.g. “Access only provided on research room computer”). For more information, see: Configure a preservation system access statement.

   

6. An administrator user can toggle the display of specific “Digital object metadata” section fields on or off via Admin > Visible elements > Digital object metadata area. This only affects display for unauthenticted users. Any authenticated users will see all metadata elements in each section as long as those fields contain a value. For more information, see: Visible elements.

7. If you are logged in and belong to the “authenticated” group, then you will also see the File UUID and AIP UUID for the Original file. The file UUID is the preservation system’s universally unique identifier for the file and the Archival Information Package (AIP) UUID is the universally unique identifier for the preservation system package which contains the file along with other related files.

8. If the preservation copies came from the Archivematica preservation system and AtoM has enabled the “arStorageServicePlugin” to allow for AIP download, then users that belong to a group with Download AIP permissions (by default Administrators only) will also see a “Download file” and “Download AIP” link next to each UUID. Clicking on them will fetch the file or the full AIP from the preservation system. See Storage service settings.

   

9. If the user has “Download file” and “Download AIP” permissions then the box icon under the “Original file” label will be coloured black. Otherwise it is coloured grey.

Back to top

Link a single digital object to an authority record¶

The process to link a digital object to an authority record is similar:

1. Navigate to the view page of an existing authority record in AtoM. You can do this by browsing or by searching for a specific authority record - see Access content for more information on navigation in AtoM.
2. Click on the “More” button in the button block and select “Link digital object”.

3. AtoM will redirect you to the link digital object edit page. Users can either upload a digital object, or link to an existing digital object available on the internet.
4. To upload a digital object locally, cick the “Choose File” button to navigate to and select a file on your computer or device. Click “Open” once the item has been selected from the window that will appear.
5. To link to an object on the internet, enter the URL to the external object to which you wish to link.

6. Click the “Create” button in the button block. When you return to the view page, the reference display copy will be displayed in the digital object field, above the other fields linked to that authority record.

   

As with archival descriptions, you can upload any file format to authority records, but only supported formats can be viewed or played directly in AtoM. For a list of formats, see File formats. Formats that are not supported can still be uploaded: clicking the object will download it to the user’s desktop where (assuming the user has the required software) it can be viewed or played.

See below for more information on making changes to your digital object.

Back to top

Upload multiple digital objects to archival descriptions¶

In AtoM, there is a 1:1 relationship between archival descriptions and digital objects - that is, only one digital object may be associated with an archival description, and all digital objects require an associated description. However, to enable a rapid workflow where users can upload multiple digital objects without first having to create associated descriptions, AtoM includes an option to upload multiple digital objects at once, as children of a selected archival description. Users can choose what level of description is used when the placeholder descriptions are created; a title can also be added to each uploaded digital object, which will then be used as the title for the related description.

To upload multiple digital objects in AtoM:

1. Navigate to the view page of an existing archival description in AtoM. You can do this by browsing or by searching for a specific archival description - see Access content for more information on navigation in AtoM.
2. Click on the “More” button in the button block; from the menu that appears, select “Import digital objects”.

3. Select a default title for the objects - this will be used as the title for the associated archival description that will be created for each object uploaded. Each object will also have its own title field that can be customized later in the process, but if you do not wish to individually name each object’s associated description, an automated title can be added to all objects using the title field at the top of the upload page. The %dd% in the default title provided represents an incrementing 2-digit number - that is to say, the default will use image 01, image 02, etc. However, this can be customized as needed:

4. Choose a default level of description. Unlike the Link a single digital object to an archival description option, which attaches the digital object directly to the archival description at that level, the “Import multiple objects” option requires the user to designate a level of description (e.g.: Fonds, Subfonds, Collection, Series, Subseries, File, Item, Record group, Part, etc). This level of description will be used for the new children that are generated as part of the upload.

5. Add your digital objects. You can drag and drop a selection onto the pane provided (as shown in the image below), or you can click the “browse” link and use your computer’s file explorer to find and select the digital objects you would like to load.

6. Once selected, the page will show previews of all the objects. If you like, you can edit the title for each description that will be created, by clicking the pencil icon under to the preview. However, once we click the “Upload” button, a separate page dedicated to customizing the description titles will be provided (see step 9 below). Remember, the title you enter here will be the title used for the associated archival description that will be created for each digital object uploaded.

7. If necessary, you can click the black “X” icon on the top right of the thumbnail generated to remove an object from the upload. You can also add additional objects either by dragging them in, or by using the “Add more” link provived in the top right corner of the upload area.

8. You can quit the upload process at any time by clicking the “Cancel” button in the button block; any digital objects already uploaded will not be saved. Note that simply navigating away from the page by any other means, without first clicking “Upload” will also result in no new digital objects being uploaded.
9. Click the “Upload” button in the button block when you are satisfied with your changes. AtoM will upload the images using the default description titles provided, but will immediately redirect you to a page where you can individually customize those default titles if desired:

10. When you are satisfied with the associated description titles, click the “Save” button in the button block at the bottom of the page. When you return to the view page, you will see that the objects have all been attached to the archival description as child records of that description. If the digital object Carousel is enabled (see Default page elements for instructions on enabling or disabling the carousel), you will also see the thumbnails of your uploaded digital objects in the carousel.

Back to top

Upload PDF¶

A user can link a single PDF and import multiple PDFs into AtoM. A full-text search of the content of the PDF is available through the main search box. PDFs that have a text layer will work, including all OCR PDFs and born-digital PDFs that include a text layer (e.g., exported Word documents) will work. Search results will refer users to the PDF that contains the search term(s), but will not reveal the location of the term(s) within the PDF.

Currently, AtoM 2.x truncates PDF text after the first 65,535 bytes.

As mentioned above, it is possible to upload multi-page TIFFs or PDF files to be displayed with a page viewer and to upload each page as a child object of the parent. To enable this feature, see settings.

Otherwise, the process for uploading PDFs is the same as described above.

Back to top

Edit digital objects¶

Any digital object that has been uploaded and linked to an archival description or authority record can be edited at any time by an authenticated (i.e. logged-in) user. Accessing the digital object edit page is the same for all of the following options:

1. Navigate to the view page of an existing archival description or authority record that has an associated digital object.
2. Click on the “More” button in the button block; from the menu that appears, select “Edit digital object”.
3. You will be redirected to the digital object’s edit page. On this page, all representations (i.e. master representation, reference representation and thumbnail representation) of the digital object will be listed, along with information on their Filename, Filesize, Media Type, and other options.

From this edit page, you can perform the following actions:

Jump to

• Edit the digital object metadata
• Edit reference and thumbnail representations
• Add subtitle, caption, and/or chapter files to audio and video
• Save your changes

Edit the digital object metadata¶

The top part of the digital object edit page will include basic metadata about the original digital object in the “Master” information area. Basic technical metadata such as Filename and Filesize are display only, and cannot be edited. However, you can change other metadata elements such as the Media type, Alt text, and latitude/longitude values associated with the digital object.

The Media type is used by the Media type facet in the search/browse pages - in some cases, AtoM might not properly detect the media type, and you can adjust it here for better results. Values include: Audio, Image, Video, Text, and Other. For more information on filter facets in AtoM, see: Facet filters.

In the “Alt text” field, you can add alternative text to display if the image cannot be displayed in your browser. This text will also be used by accessibility supports such as screen readers.

You can also add latitude and longitude values to the Master digital object’s metadata for basic geolocation support. This can configured to display a dynamic Google map in AtoM - for more information, see below:

• Add dynamic maps to your digital object metadata

Edit reference and thumbnail representations¶

Below the Master information area on the digital object edit page, you will also find sections for the various derivatives created upon upload - the reference display copy and the thumbnail. While these derivatives are typically automatically created by AtoM during digital object upload, you can delete them, and either re-generate them or upload your own versions. Since thumbnails are used in search and browse results and the reference copy is displayed on the related archival description view page, this can be a useful way to customize the display of your digital objects.

If you wish to use a different image as the thumbnail or reference, first click the “Delete” link in the relevant area.

AtoM will ask you to confirm that you would like to delete the derivative. After confirming, the Edit digital object screen will then give you the option to upload a new derivative by clicking Browse and selecting a file from your local computer, or else auto-generate a new representation from the master image.

Tip

Somewhat confusingly, the digital object edit page will use the thumbnail to provide a preview of both the thumbnail and reference derivatives, and the reference copy to provide a preview of the master digital object.

Because of this, don’t be alarmed if, for example, you are trying to replace the thumbnail and after confirming the deletion of the current version, you see the preview of the reference copy missing! The original reference copy will remain unchanged until you edit it, even if the preview shown in this page is no longer correct once your derivatives have been customized.

Add subtitle, caption, and/or chapter files to audio and video¶

AtoM also supports the ability to upload WebVTT (.vtt) or SubRip Text (.srt) files to audio and video digital objects as a means of adding chapter markers, captions, or subtitles to your content. Captions and subtitles can also be added in multiple languages.

Files used should be in .vtt or .srt format, and should use UTF-8 character encoding.

Click the “Choose file” button to open a local file explorer, and select the file you wish to upload from your device. If you’re adding Caption or Subtitle files, be sure to select the correct language from the Language drop-down menu before uploading.

Important

Currently, the largest file size supported for these file uploads is 64 MiB.

Once you have saved your changes, you will be re-directed to the view page of the related archival description or authority record.

When captions or subtitles are correctly added, they will appear under the “CC” icon on the media player:

When chapters are correctly added, they will appear under the menu icon on the media player:

You can re-enter edit mode to make further changes as needed, or to add additional subtitles or captions in other languages. Basic metadata about the files will be shown, including the file name and size, as well as an option to delete the current uploads. Note that you can only have one chapter file per digital object, but multiple subtitle or caption files for multilingual support:

Add dynamic maps to your digital object metadata¶

To support basic geolocation, AtoM has the ability to associate latitude and longitude coordinates with a digital object. If desired, you can also display a dynamic Google map in the digital object metadata area showing the location of the coordinates. To do so, an administrator will first need to configure certain settings so the map can be visible.

Enabling the display of digital object maps

Two separate settings must be changed to enable the display of the digital object maps in AtoM. First, in Admin > Settings > Global, an API key must be added to the Google Maps Javascript API key setting.

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

Additionally, in Admin > Settings > Default page elements, the “Digital obect map” setting checkbox must be checked. Remember to save your changes in the Settings area!

For more information, see:

• Google Maps Javascript API key setting
• Default page elements

Adding latitude and longitude values to a digital object

Once the above settings are configured, then any time a digital object has latitude and longitude values added to it, it will display a dynamic, zoomable map in the Digital object metadata area. To add your latitude and longitude values to an existing digital object (Examples show this process for archival description - the instructions are the same for authority record):

1. Navigate to the archival description or authority record linked to the digital object you want to edit. You can do this by searching or browsing - for more information on navigation in AtoM, see: Access content.

2. When you are on the view page of the related description, scroll down the button block at the bottom of the page, and in the “More” menu, select “Edit digital object”

3. AtoM will redirect you to the edit page for the digital object. In the information area for the master digital object, add your latitude and longitude values to the fields provided.

4. When you save the record, AtoM will return you to the archival description’s view page. In the Digital object metadata area, you should now see a Google map showing your coordinates with a pin. You can zoom, pan, change the map type, and clik to view a full Google map in a new tab.

Tip

Not sure how to find out the coordinates of a location? You can use Google maps!

Find your location on a map - zoom in to make it as precise as possible. If you right-click and select the “What’s here?” option that will appear in the context menu that appears, Google Maps will display the latitude and longitude values, along with any addtional information it has:

You can then use this information in AtoM following the steps described above!

Back to top

Edit the filename of a digital object linked to an archival description¶

For locally uploaded digital objects, you can edit the file name of the digital object after it has already been uploaded, using the “Rename” module. Once edited, AtoM will automatically update all related file paths to ensure that the link between the digital object and the associated archival description is maintained.

Note: this is not available for digital objects linked to authority records.

The Rename module used to edit the linked digital object filename can also be used to edit the title of the associated archival description, and its slug - detailed instructions on how to use it for these other purposes are included on the Archival Descriptions documentation page - see: Rename the title or slug of an archival description.

To change the filename of a linked digital object:

1. Navigate to the view page of an existing archival description with a linked digital object in AtoM. You can do this by browsing or by searching for a specific archival description - see Access content for more information on navigation in AtoM.
2. Scroll down to the button block at the bottom of the page, and click on the “More” button - a menu will open with further options. Click on “Rename” to open the Rename module.

3. AtoM will redirect you to the Rename module page. You will see 3 fields - one for the title of the description, one for the slug; the third field is for the filename of the digital object linked to the description.

4. To the right of the edit fields, there is a checkbox corresponding to each field. By default, the title and slug checkboxes will be checked, and the filename field will be unchecked. The checkbox associated with a field must be checked to enable editing. You can uncheck these fields at any time to disable them - doing so will undo any changes made and prevent the field from updating when the “Update” button is clicked. To edit the filename of the linked digital object, check the “Update filename” box. You also might wish to uncheck the Title and Slug boxes, to prevent any accidental edits.
5. Place your cursor in the filename field and make changes as necessary. For reference, the original value before your changes is displayed below the field.

6. If you do not wish to save your changes, you can click the “Cancel” button in the button block at the bottom of the Rename module page. Note that navigating away from the Rename page will also result in no changes being saved.
7. When you are finished making your edits, save your changes by clicking the “Update” button located in the button block at the bottom of the Rename module page. AtoM will redirect you to the view page for the related archival description. A notification banner at the top of the page will let you know that the description has been updated.

8. You can see the updated filename in the Digital object metadata area at the bottom of the record. If you are unhappy with the results, you can repeat steps 1-7 as necessary.

Back to top

Delete digital objects¶

To delete a digital object that has been uploaded and linked to an archival description or authority record:

1. Navigate to the view page of an existing archival description or authority record that has an existing digital object.
2. Click on the “More” button in the button block; from the menu that appears, select “Edit digital object”. You will be redirected to the digital object’s edit page.
3. Scroll to the bottom of the page and click “Delete”. You will be prompted to confirm that you wish to “Delete” the digital object; click “Delete” once again. You will be redirected to the archival description’s view page.

Back to top

Adding a watermark to reference images¶

A system administator can place a watermark file in AtoM’s root directory, so a digital watermark is overlayed over all reference display copy images generated when a digital object is uploaded.

For more information, see the Administrator’s manual:

• Watermarking

Back to top

Digital object storage¶

In AtoM, administrators can track digital object storage per repository. Storage limits may be placed on individual repositories by in-house server capacity or on hosted server agreements.

If you are utilizing a multi-institutional / portal instance of AtoM, you will need to check with the site administrator to learn the digital object storage limitations.

For more information, see Managing digital object storage.

Files formats¶

A number of file formats are supported as digital objects in AtoM. Files in other formats can still be uploaded to AtoM; they just cannot be directly accessed or streamed within AtoM itself. In these cases the user must download the file from AtoM to his or her desktop and (assuming the user has the requisite software) access the content there.

The table below shows image, audio and video formats which can be viewed in AtoM:

Back to top