Public Interface Documentation (for staff)

Introduction

This documentation is supplementary to the ArchivesSpace PUI Documentation for researchers.  It contains information that is relevant only to staff users of ArchivesSpace, however, since it is focused on explaining how changes made in the staff interface affect the public interface.

Please note that this documentation will use staff-side terminology rather than the default labels used in the Public Interface. For example, this documentation will use the word “Accessions” rather than “Unprocessed Material.”  For a list of the differences between the default terms used in the staff interface vs. the public interface, please see Appendix A.

Features / Explanations

Switch to the Staff Interface from the Public Interface

If you are logged into the Staff interface in the same browser that you are using to access the Public Interface, then you will see a “Staff Only” action button on those pages that you can access directly in the staff interface (including, for instance, resource, archival object, and even top container records, but excluding repository records).  Note that you must have permissions to edit those records in the Staff interface, as well as permissions for that particular repository, otherwise the link will not resolve since you cannot actually edit that record.  Here is an example of what the Staff Only action button looks like, from the context of an archival object page in the public interface:

Simply click the Staff Only button and let the service take care of switching to the correct repository when you are directed to the Staff interface.

Repository logo

Want to add a logo for your repository in the public interface?  This can be done by adding a link to a web-accessible URL in the “Branding Image URL” field for that particular repository record in the staff interface. Previously this field has only been used by ArchivesSpace’s EAD export (XPath: /ead/eadheader/filedesc/publicationstmt/p[@id=’logostmt’/extref/@xlink:href) and EAD-to-PDF transformation process, but starting with version 2.1 it can also be used to include a repository logo in the staff interface. In version 2.1, this logo will appear on the repository landing page as well as alongside the repository record in a search-result screen.

Citation action button and the Preferred Citation note

There are two types of citation notes in the public interface: 1) partially-constructed citation notes, which will use the preferred citation note as entered in the staff interface’s notes module, and 2) fully-constructed citation notes, which will be created dynamically from elements already present in the description.  

Partially-constructed citation notes

If there’s a preferred citation note, then this note will display as the citation, followed by the URI and the current date. If there are multiple preferred citation notes, then these notes will be concatenated together.  Please also note that the preferred citation note can be inherited, if desired, so that it will always be used when the Citation action button is clicked by a user.  In all cases, the preferred citation note that’s been added in the staff interface will *only* appear when a user clicks the Citation action button in the public interface.  By default, this particular note is not repeated anywhere else in the public interface.

Fully-constructed citation notes

If there is no preferred citation note at the archival object level, then the citation will be composed of the Display String, Collection Title, Identifier, Repository Name, URI, and the current date.

If there is no preferred citation note at the resource level, then the citation will be composed of the Resource Title, Repository Name, URI, and the current date.

Since there cannot be a preferred citation note at the digital object level, the citation note here will always be composed of the Digital Object Title, Repository Name, URI, and the current date.

By default, the Citation action button does not appear on Accession pages.  

In all cases, the current date that’s provided in the citation is preceded by the word “Accessed."

Example:

Notebook, Bali and C[hinese] Theatre Notes, 1932. Harold Acton papers, GEN MSS 663. Series III. Yale University Library Special Collections. http://pui.hudmol.com/repositories/3/archival_objects/1280 Accessed July 09, 2017.

In this example:

• “Notebook, Bali and C[hinese] Theatre Notes, 1932” is the Display String, which is constructed from the title of the archival object, concatenated with a comma and the first (but only the first!) date subrecord, if there is a date subrecord, as per the rules in place in the ArchivesSpace staff interface.

• “Harold Acton papers” is the Resource title.

• “GEN MSS 663. Series III.” is the composite identifier for the Archival Object, which is a configurable inheritance option for the new public interface.

• “Yale University Library Special Collections” is the Repository name.

• “http://pui.hudmol.com/repositories/3/archival_objects/1280” is the URI of the Archival Object for which the user has clicked the Citation action button.

• “July 09, 2017” is the date when the Citation action button was clicked.

Language code / Language note

The language code translation value from the staff interface displays in the single-scroll view of a resource record (i.e. the finding-aid overview, that's provided when you click on the second tab of a resource page).  The language code translation value is also added to the new PDF output.  Last, even though this language code is set up to be inherited by default, since it does not display on any pages in the PUI currently, you will not see any evidence of that inheritance. In future releases, this element could be used as an additional facet.

The language note element, however, displays above the accordion section on all resource and archival object level pages.  Just like the other note elements, if this note is repeated, then all of the language notes will display in the public interface in the same order that they are recorded in the staff interface.

The working group's suggestion to handle the language code / language note was to follow the logic that the Language Note should be the element that is displayed to users, whereas the Language Code translation value could be used for facets, but if a Language Note was missing, then the translation value from the Language Code would display in its absence (e.g. if there is no language note, but a language code of "eng" is supplied, a Language Note with the value of "English" would still display to the user). This is not how the PUI works currently, however, but that behavior could be accommodated with a plugin, or in a future release of the new PUI.

Resource / Archival Object badges

Resource and archival object pages are created by the combination of two different elements from the staff interface, only one of which is a required element:

• Level of description
• Analog Instance preview information – a combination of container type(s) and container indicator(s)

For example, a file-level description that's linked to an analog instance of Box 1, Folder 1, would have a badge equal to "File - Box 1; Folder 1".  This badge displays on the landing page of the record as well as on search-result pages.

If there are multiple analog instances attached to that particular level of description, then the text "Multiple Containers" will display in place of any container information.  In those cases, you will need to look in the Physical Storage Information accordion section to see more information about the multiple container groupings.  The group discussed adding a number here to indicate the total number of container groupings, but since some users might have indicators with ranges (e.g. Box 1 -5, and Box 6), we decided to only use the text "Multiple Containers" since we wouldn't want the number to provide misleading information in some cases (e.g. "2 containers" instead of "6 containers").

Digital Object badges

By default, the Digital Object display badge will show up as "Digital Record." If the VRA core option of Collection, Image, or Work is selected in the Staff interface, then that will change the badge display to "Digital Collection", "Digital Image", or "Digital Work", respectively. This will only affect display in the default Public interface.  There are no facets included in the Public interface to differentiate between these four possible display options.

Series-based facets for top containers

For any collection that has top containers linked to it, there will be a new search-resutls page in the Public interface that returns all of the top containers associated with that collection. On this page, one of the two possible facets that can display here are Series titles. Please note that the Series will only appear as a facet if it has an identifier in the staff interface. This limitation could be changed in a future release, but right now it is in place due to how the Top Container information is constructed on the staff-side of the application. 

Internal linking

You can use the EAD “ref” element along with it’s @target attribute in the staff interface to provide internal links within the same finding aid in the public interface.  The advantage of using this is 1) that the link won't change regardless of your public-facing URL structure (e.g. archives.myinstiution.com vs. archives.library.myinstituion.com) and 2) these links will also work in your EAD files outside of the ArchivesSpace Public Interface.

If you want to link to a specific component from the context of the resource record's scope and content note, for example, then all you need to do is grab the reference ID of that archival component and use that as the value of the target attribute in your EAD ref element (see https://www.loc.gov/ead/tglib/elements/ref.html for more information).

Example: Check out the <ref target="b5eb603c1f21d605311e2c0b5b25a796">photographs</ref>!

Digital object links / thumbnails

You can include links to digital objects in other systems by using the File URI subrecord on a digital object.  

Please note that the “make representative” feature that’s in the staff interface is not yet used in the Public interface.   The Digital Object buttons are only included on the archival object pages with the 2.1 release.  These should also be included on the resource and accession pages, but right now the only reference to digital objects on those pages are in the accordion section.

Links between digital object records and accessions, resources, and archival objects

...just a place to note how the full hierarchy is displayed on the digital object pages, where the actual linkable occurs at the level that's bolded.  Should actually move this to the other PUI documentation page.

Agent links

Please note that if you provide a description of a relationship between two agents, the same description will appear on both agent landing pages. This behavior is the same in the staff interface as it is now in the public interface.  You will need to keep this in mind when authoring any descriptive notes for agent relationships, since you cannot have two different descriptions written from different perspectives associated with the same relationship in ArchivesSpace 2.1.  For example, if you were to link an agent record for Vincent Price and his mother, Marguerite Cobb Price, in the staff interface, it would be best to have the note reference both names since the same note will appear on both Vincent’s landing page as well as Marguerite’s, assuming that both agent records are published in the staff interface.

Publishing/unpublishing Agent records

In ArchivesSpace versions 2.0 and earlier, an agent record had to be published AND linked to a material description record (i.e. an accession, resource, digital object, or archival object) in order to appear in the public interface. Now that the new ArchivesSpace Public Interface also displays linked relationships between agent records, that restriction has been relaxed so that any agent record that is published in the staff interface will appear in the public interface. Please note this difference and review your the publication status of your agent records prior to turning on the ArchivesSpace Public Interface version 2.1. Remember, for instance, that every User and Repository record in ArchivesSpace also has an Agent record, so you will not want to publish all of your ArchivesSpace agent records in the staff interface.

Embedded metadata

Metadata about agents (corporate bodies and persons)  and resource level pages is embedded in the PUI by default, using the schema.org vocabulary (and one extension for “archival collections” currently used in OCLC’s WorldCat database). As adoption increases, and the Architypes’ proposed schema.org extension is realized, these metadata mappings should be updated and expanded to other parts of the public interface.

See this JIRA ticket for the mappings used in ArchivesSpace 2.1 (but note that the Repository mappings have not yet been put into place): https://archivesspace.atlassian.net/browse/AR-1484

You can test out these new features by going to Google’s Structured Data Testing Tool, https://search.google.com/structured-data/testing-tool, and pasting in a URI from the public interface for a resource or person/corporate body agent record.

Customizable Features

Archival Inheritance

With the new version of the Public Interface, all elements of description can be inherited. This is especially important since the PUI displays each level of description as its own webpage.  

Each element of description can be inherited either directly or indirectly.  When an element is inherited directly, it will appear as if that element was attached directly to that archival object in the staff interface.  When an element is inherited indirectly, it will appear on the lower-level of description in the public interface, but the inherited element will be preceded with a note indicating the level of the ancestor from which the note is inherited (e.g. From the Collection, or From the Sub-Series).  In both cases, the element will only be inherited if it is missing from the archival object.  Additionally, the element of description will only be inherited from the closest ancestor.  In other words, if a top-level collection record has an access restrictions note, and a child-level series record has an an access restrictions note, but the sub-series child of that series record lacks an access restrictions note, then the sub-series record will inherit only the access restrictions note from its parent series record.

Additionally, the identifier element in ArchivesSpace, which is better known as the Reference Code in ISAD-G and DACS, can be inherited in a composite manner.  When inherited in a composite manner, the inherited elements will be concatenated together.  In other words, an identifier at the item level could look like this:  MSS 1. Series A. Item 1.  Though the archival object has an identifier of “Item 1”, a composite identifier is displayed since the series-level record to which the item belongs has an identifier of "Series A”, which in turn also belongs to a collection-level record that has an identifier of “MSS 1”.

By default, the following elements are turned on for inheritance:

• Title (direct inheritance)

• Identifier (indirect inheritance, but by default the identifier inherits from ancestor archival objects only; it does NOT include the resource identifier.

  also it is advised to inherit this element in a composite fashion once it is determined whether the level of description should or should not display as part of the identifier, which will depend upon local data-entry practices)

• Language code (direct inheritance, but it does NOT display anywhere in the interface currently; eventually, this could be used for faceting)

• Dates (direct inheritance)

• Extents (indirect inheritance)

• Creator (indirect inheritance)

• Access restrictions note (direct inheritance)

• Scope and contents note (indirect inheritance)

• Language of Materials note (indirect inheritance, but there seems to be a bug right now so that the Language notes always show up as being directly inherited. See AR-XXXX)

See https://github.com/archivesspace/archivesspace/blob/master/common/config/config-defaults.rb#L296-L396 for more information and examples.

Also, a video overview of this feature, which was recorded before development was finished, is available online: https://vimeo.com/195457286

Composite Identifier Inheritance

If you add the following three lines to your configuration file, re-start ArchivesSpace, and then let the indexer re-index your records, you can gain the benefit of composite identifiers:

AppConfig[:record_inheritance][:archival_object][:composite_identifiers] = {
:include_level => true,
:identifier_delimiter => '. '
}

When you set include_level to true, that means that the archival object level will be included in identifier so that you don't have to repeat that data.  For example, if the level of description is "Series" and the archival object identifier is "1", and the parent resource identifier is "MSS 1", then the composite identifier would display as "MSS 1. Series 1" at the series 1 level, and any descendant record.  If you set include_eve to false, then the display would be "MSS 1. 1"

Request action button

By default, this action button is turned off.  This feature has been configured in the Test Corpus, however, so that a Gmail email account is used to 1) email users with information about their request, and 2) to email staff detailed information about the user’s request.  The information that is included in a request is detailed in the following JIRA ticket:  https://archivesspace.atlassian.net/browse/AR-1660

See https://github.com/archivesspace/archivesspace/blob/master/common/config/config-defaults.rb#L493-L524 for more information about how to configure this option.

Additional Customizations

Search the configuration file, https://github.com/archivesspace/archivesspace/blob/master/common/config/config-defaults.rb, for “pui” and “public” for other options that can be configured easily.

The labels used in the PUI may also be configured in whichever YML file is used: https://github.com/archivesspace/archivesspace/tree/master/public/config/locales

Known Bugs

...hopefully none to report, but will likely have a few

(e.g. when container type is missing, the text "Container " plus the container indicator are displayed in the badge on the landing page of an Accession record, but the text Container is missing from the badge on a search-result page).

and the fact that if you suppress some archival objects that have top containers attached, then you need to edit those top containers, as well, in order for those top containers not to show up in the container inventory view of the PUI. 

...

...

Appendices

Appendix A