Questions about implementing Archon classifications as taxonomy terms in AtoM
117 views
Skip to first unread message
Krista Gray
May 6, 2024, 3:21:09 PMMay 6
to AtoM Users
Dan Gillean
May 7, 2024, 8:32:53 AMMay 7
to ica-ato...@googlegroups.com
Hi Krista,
The short answer is that for maintenance reasons going forward, I would suspect that adding a new taxonomy and all the required pieces to get what you want from that (e.g. integration with the EAD import/export, the CSV import export, the taxonomy browse pages, etc) will be easier to maintain in a separate plugin than an attempt to bend an existing taxonomy to this new purpose. Either way, this sounds like a lot of development, and I suspect that not all of it will be changes you can easily keep isolated in a plugin - meaning that no matter what, doing this much custom work will make future upgrades difficult, requiring developers to manually reapply a lot of customizations, and even rewrite parts where the base code may have changed.
There are still more alternatives you might consider. First, without any development, here are some more browsing options you may not have come across:
There's a treeview option that exists for the entire holdings that can be turned on or off - here is the example from our demo site:
You can expand top-level records with descendants, and it will show all the immediate levels below, and so forth all the way down. The second you click on any record in the tree, you go to that view page, where you then have a treeview just for that archival unit. A user browsing from here could easily go here from Record Group to the Subgroups, to the Series, etc.
There's also a configurable Inventory List, as a way of browsing lower level records in an archival unit - here is an example from the demo site again:
- https://demo.accesstomemory.org/kantokoski-koski-koivula-korpela-family-3/informationobject/inventory
- docs: https://www.accesstomemory.org/docs/latest/user-manual/access-content/browse/#using-the-inventory-list
Administrators can configure what levels are included in the Inventory list. By default, the Inventory list will be available in the right-hand context menu (i.e. the sidebar) of an archival description view page if the levels below it include records that would appear in the inventory list.
Finally, to set up my suggestions below, I will also point out that if you use Record Group as your top descriptive levels, then these will be available for browsing by users on the archival description browse page. AtoM includes a number of facets, filters, and sort options, as well as an advanced search panel. See:
As for an alternative suggestion:
If you customize the levels of description in AtoM (i.e. so you have Record Group, Subgroup, Series, etc - all the levels you currently use as levels in AtoM), and you look at the facets on AtoM's search / browse page, you will see that you can facet results by level of description. If you navigate to the View page of a fonds / collection / record group in AtoM and look in the right-hand context menu, you'll see a "Browse as list" link, which will take you to a search/browse page already filtered to just the records of the current archival unit. All of AtoM's search / browse criteria are passed via URL - i.e. when you view a browse page for a particular record group, and then further filter it to just series-level records in that record group, looking at the page URL you will see that an ID for the collection / record group and and ID for the level of description are both part of the URL. Each description's view page will also have a treeview if it is part of an archival hierarchy, giving users another way to explore the structure of the record group. Given these facts:
What if you added some custom code that would use JavaScript to insert some special browse buttons wherever you'd like on the view page of your Record Group descriptions? Using the URL parameters, a little JS widget could generate and insert links to browse pages that are pre-filtered to just the subgroup records, or just the series, etc. The advantage of something like this would be that:
- If it uses JavaScript inserts on page load, then it could sit alongside AtoM, and the only code changes you would need directly in AtoM would probably be a small amount of modifications to the view page, to inject the buttons. Otherwise, it could query the AtoM database for the relevant IDs, and then use existing search/browse URLs filtered by those IDs (to the current Record Group, to the Subgroup level, etc...) for the link used by the inserted button. This means that the level of changes you need to make in AtoM directly are greatly reduced, making future upgrades much easier.
- If you're otherwise using the existing functionality, then you don't need to mess around with import/export mapping for EAD and CSV support, for example.
- If a JavaScript sidecar application doesn't work for this approach, this level of changes could probably be done in a custom plugin - again helping with ongoing maintenance. You would just need overrides for the description view templates, to add your custom buttons.
Your custom theme could also make some of the existing view page browse options (like the Inventory list, the "Browse as list" and "Browse digital objects" sidebar links, even the Finding aid download button, etc) more prominent as well, if desired. Given that you can upload your own custom finding aids (docs here), that is yet one more way you could be providing users with customized exploration tools without development.
Anyway, just trying to think of some less intensive ways to achieve similar outcomes.
One word of warning: the AtoM Maintainers are working on a significant upgrade of AtoM's dependencies for the 2.9 release. Most importantly will be changes to the search index. As you may know, Elasticsearch (the library we use for search) changed their license after one of their 7.x release s, to something that we at Artefactual (and many others in the open source development community) consider potentially a risk for the ongoing use of ES in an open source application like AtoM. This is one of the reasons we have not upgraded ES in some time. Two community forks appeared almost immediately, and new rival projects popped up. The Maintainers have been observing this for some time, running tests, and deciding how to move forward with AtoM - either replace Elasticsearch with something new, move to one of the community forks, or upgrade to the last open ES version and delay any final decisions for another major release. I do not know what they will decide.
All this to say: it's a challenging time to do significant AtoM development customization, because the underlying code is likely to change significantly in the next major release! At minimum, be sure to develop against our qa/2.x development branch, update your local environments frequently, and keep your custom code abstracted and separated as much as possible.
If you are committed to the approach you've outlined, then I would recommend using previous commits and pull requests in AtoM's GitHub history as guides - searching for PRs etc related to the Genre taxonomy, the addition of the DACS template, etc. Here is the most recent PR I could find that includes the addition of a new taxonomy:
Good luck!
he / him
--
You received this message because you are subscribed to the Google Groups "AtoM Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to ica-atom-user...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/ica-atom-users/80f60c55-cfa5-4e5e-b057-4a7431146b6en%40googlegroups.com.
Krista Gray
May 7, 2024, 11:00:46 AMMay 7
to AtoM Users
Thanks, Dan! I appreciate the thought you have given this for us, and also the insight into the development impact considerations. That is all very good to know.
The hierarchy approach was what we first experimented with. However, we ran into a lot of significant issues, unfortunately. Some key ones:
First, the hierarchy page quickly became essentially unusable since we were combining 4 repositories into one system, all with different approaches to their identifiers and classifications. We could not determine how it was sorting, or how to limit by repository. But even with a fraction of our records imported into a test site, it became completely unusable as a navigation tool.
Second, the system interpreted the record groups as the top level records when set up in the manner you are describing (if I am understanding your idea correctly). This had the following impacts:
- Unable to attach pdf finding aids for individual record series (if you try to attach the pdf finding aid at the record series level, it would apply to the entire record group that the record series was a part of)
- Unable to browse individual record series from the repository page (it would default to top level records only, meaning you only saw the record groups)
- Unable to find record series with the default search (because, again, the system couldn't see the record series as top level records, only the record groups)
- Unable to browse digital objects by individual record series from the collection record (similar issue to the PDF attachment problem, I think)
To make sure we are on the same page, this is the kind of nested structure we attempted in the archival description record that caused the above issues:
Record group 1
> Record subgroup 1-1
>> Record series 1-1-1
>> Record series 1-1-2
>> Record series 1-1-3
> Record subgroup 1-2
>> Record series 1-2-1
>> Record series 1-2-2
>> Record series 1-2-3
>> Record series 1-2-4
> Record subgroup 1-3
>> Record series 1-3-1
>> Record series 1-3-2
I'm not quite sure I am following your javascript idea, but that could be because I am not sure how it would address the problems we encountered with the nested record approach. Do you have any sense of whether these issues would be easier or harder to resolve?
Thanks,
Krista
Dan Gillean
May 8, 2024, 9:15:14 AMMay 8
to ica-ato...@googlegroups.com
Hi Krista,
A few responses:
I'm not quite sure I am following your javascript idea, but that could be because I am not sure how it would address the problems we encountered with the nested record approach. Do you have any sense of whether these issues would be easier or harder to resolve?
Using my browser tools I've quickly made you a super-fast, super-ugly mockup of what I mean, though the buttons could go anywhere else, be styled very differently, etc:
Notice the added "Browse by Subgroup" and "Browse by Series" buttons I have added next to the Other languages drop-down, below the treeview and above the image carousel. The idea being that:
- You can either add these in a custom plugin by directly modifying the information object view page templates, or if you want to alter AtoM as little as possible, then you would use JavaScript to inject the code for these dynamically at page load time. I have seen some other examples of developers modifying AtoM this way in the past, and it can be a good way to build alongside AtoM while modifying as little of the application as possible - hence the suggestion
- You could likely borrow some of the logic from the existing sidebar "Browse as list" "Browse digital object" links for the lookups
- Users would use the default Browse page to browse record groups. When selecting one, they would arrive at a page like this, where the treeview would immediately show them the available Subgroups / Series, and your links would provide an immediate path to a browse page for those subgroups or series
As for the things you wanted to try but were unable to do:
There are always going to be some tradeoffs when moving to a different application. Given that AtoM also has some technical debt, I am sure that you are not only considering this migration because Archon is old, right? I can offer some suggested workarounds or alternatives for some of these points, but some of them are just how AtoM works - either featues it doesn't have, or deliberate differences in implementation. With that in mind:
Unable to attach pdf finding aids for individual record series (if you try to attach the pdf finding aid at the record series level, it would apply to the entire record group that the record series was a part of)
Yes, that's how AtoM's finding aids currently work - at present you can add only one per archival unit. Some workaround options would be:
- Just make your finding aids really well organized, with hyperlinked ToCs etc, so users can easily see the overall arrangement and jump to relevant Subgroup and Series descriptions. If the flow from Record group to Series is meaningful to your users and you expect them to enter by browsing from Record groups, this might not be as much of a barrier as you think?
- If Record Groups are NOT meaningful to your end users but are to the organization, then perhaps you make Series your top level of description, and consider using taxonomy tags as classifications to add relevant Record group / Subgroup membership - sort of reversing your previous idea to take advantage of what AtoM can offer users that Archon didn't have much of (namely, browsing with filters and facets). This would also allow you to upload finding aids to each series
- Put the series level finding aids elsewhere on your site and link to them in the descriptions. Alternatively, put them in a folder on the AtoM installation server, and link to them directly. AtoM description templates support Markdown so you can style your links without breaking CSV and EAD exports, etc.
- At each series-level, attach the series-level finding aid as a digital object, rather than as a finding aid. Bit of a hack, but since a Series is an abstract intellectual entity, you're unlikely to have digital objects from the holdings at that level that would conflict(they'd be files or items)
Unable to browse individual record series from the repository page (it would default to top level records only, meaning you only saw the record groups)
First, because all of AtoM's search and browse criteria are passed via URL, and because AtoM's menus are customizable via the user interface, you could add a link to the AtoM browse menu that will take users to a browse page already filtered to series-level descriptions. This would be across ALL record groups however - to be able to select a record group then browse by series from there, you'd need to do either my suggestion above, or another workaround. To do this:
- Navigate to Browse > Archival descriptions
- Remove the "top level descriptions" filter
- Using the Levels of description facet, limit the results to Series-level descriptions
- We are going to use the unique part of the URL from those results - it should look something like this:
- informationobject/browse?levels=2004225&topLod=0&sort=alphabetic&sortDir=asc
- Open a different browser, and navigate to Admin > Menus
- Click on Add new
- Give it a name in camelCase, like browseSeries
- Give it the label you want to display in the Browse menu (e.g. "Browse by Record series" or similar)
- Under the "Parent" drop-down, select -browse
- In the path, copy the unique part of the browse page URL shown above, and put it here
- The description is for your internal use only - add something or don't. Save.
Now the AtoM browse menu will include a direct link to a browse page pre-filtered to Record Series.
With that workaround in mind for the global experience, here's a way you can recreate this manually on your repository page:
First, option 1 is to enable the Institutional Scoping setting. This is useful for multi-repository sites, keeping search and browse pages bettter scoped to a particular institution after visiting its repository page, as well as adding some additional customizable elements to the related repository view page. One of those is an editable drop-down menu to explore the institution's holdings. Archeion, the Ontario provincial archival portal site using AtoM, has this setting enabled if you'd like to see an example - see the "Browse our holdings" drop-down under the repository logo and search box:
Docs for the feature:
Now we can add our custom Series-level browse links per repository to this menu, following the same approach:
- The repository page already gives you a link to a browse page limited to the current repository
- Facet by series, copy the URL; In menus add a new one
- We can look at one of the existing default links there to see how it filters to the repository:
- informationobject/browse?repos=%currentRealm%
- Now we can use that, combined with the URL for our series faceting, to create a series level browse page filtered by repository - something like:
- informationobject/browse?repos=%currentRealm%&levels=2004225&topLod=0&sort=alphabetic&sortDir=asc
Repeat as needed for Subgroup, etc.
Other options:
- The Edit theme options in the user interface for customizing a repository page include an area that will accept HTML and in-line CSS. You can use these to create your won links, style them as buttons or however you want, and have them appear above the archival institution details on the view page of the repository
- Once again, you could use Markdown to add links directly to the body of the description if you want
- You can create and style static pages using either HTML or Markdown. You could create one per Record group with more links, or one per Repository with more links, etc. Then use any of the options above (the menus, markdown, the editable HTML areas) to link to these pages as landing pages for a guided entry to a particular subset of holdings, like a record group. Some examples of how others use static pages:
- As landing pages to explore content, combined with taxonomy terms - see the Beaton Institute:
- As a tour of how the catalog works and how to use archival holdings - see the Mills Archives:
- As help resources for researchers - see the Borthwick Institute for Archives:
Unable to find record series with the default search (because, again, the system couldn't see the record series as top level records, only the record groups)
First, while Browsing will default to showing top-level descriptions, searches in AtoM from the global search box default to search all levels of description. Users can then easily use the facets to limit the results by Series (or by sub group, etc). The result stubs include a level of description, and will say "Part of __" with a link to the related top-level description. Additionally, there is a "Part of" facet (that you could relabel however you want - e.g. "limit to Record Group.". It's certainly not identical to how the Archon search works, but hopefully the other browse suggestions might help offset this.
If that's not enough, you will need to do some exploration on your own for the next part, but: these slides include a sample code snippet for creating your own custom search box on an AtoM static page (around slide 31 or 32):
You can see examples of this in use, both of which have been customized to return results limited to certain types of digital objects, on the Mills homepage:
I tried adding this code block to our demo site, and it appears that something has changed recently in newer versions of AtoM (or we have additional HTML filters on in the demo site), as it didn't immediately work. Nevertheless, I am sure it COULD if properly configured - and you can then apply the same tips and suggestions as above (i.e. use the search parameters to customize how the search box will filter results to Series; add this custom search box to the editable HTML area of a repo page and further scope it by repository, or add it to a static page designed as an overview of a particular Record Group, etc).
Unable to browse digital objects by individual record series from the collection record (similar issue to the PDF attachment problem, I think)
First, this functionality is not exactly easy to find on the Illinois Archon site. AtoM's isn't much better, but it is also there: when you are on the view page for a Series, if there are digital objects in lower levels, then AtoM will:
- Provide users with a carousel showing the first X results (determined by the global "Results per page" setting; default 10)
- Provide a link to a browse page that will be automatically filtered to digital objects below the current level
Meaning that we can already get to such a page, though it takes a few clicks. Here is an example link from our demo site:
- A "Photographs" series in a fonds - see the carousel, with the "See all" button below it:
- Click that See all button and go to the browse page, limited to the "Photographs" series and lower levels with digital objects:
From the URL, we can see that if we know the object ID of a description, then we can pass it as a parent-level filter using ancestor= in a search/browse request. Meaning that you can potentially use any combination of the suggestions above to create your own links to browse digital objects pre-filtered to a particular series.
If you need to know the object ID of a specific record, we have example SQL queries in the docs that can return that (as it is not easily shown in the UI), using the slug as input:
Anyway, hopefully this might give you some additional ideas that don't all require development. As I started with, AtoM is not Archon - it was developed with some very different starting places in terms of archival arrangement and description. Nevertheless, it's a pretty flexible platform, and I hope this might help you strike a balance between recreating old functionality and finding new ways to provide your users with access to your holdings.
Good luck!
he / him
To view this discussion on the web visit https://groups.google.com/d/msgid/ica-atom-users/e5982253-304e-4b66-afeb-b95c9015deffn%40googlegroups.com.
Krista Gray
May 8, 2024, 6:22:03 PMMay 8
to AtoM Users
Hi Dan,
Thanks for sending us all these detailed ideas! A number of these (for example, how to add elements to the institutional scoping menu on the repository page) are features that would definitely help us improve the navigation of AtoM for our staff and user community, which is much appreciated.
I had a couple follow-up questions for some of your ideas:
If Record Groups are NOT meaningful to your end users but are to the
organization, then perhaps you make Series your top level of
description, and consider using taxonomy tags as classifications to add
relevant Record group / Subgroup membership - sort of reversing your
previous idea to take advantage of what AtoM can offer users that Archon
didn't have much of (namely, browsing with filters and facets). This
would also allow you to upload finding aids to each series.
If we took this approach with taxonomy tags, how would you recommend implementing it? We are indeed thinking it will be best to have the record series as the top level of description, and the record group membership is more informational in many cases rather than being a navigational feature (as you suspected, the navigational element of it is used more by archives reference staff). Also, what do you mean by "taxonomy tags"? Is this a type of taxonomy term?
Put the series level finding aids elsewhere on your site and link to
them in the descriptions. Alternatively, put them in a folder on the
AtoM installation server, and link to them directly. AtoM
description templates support Markdown so you can style your links
without breaking CSV and EAD exports, etc.
In some ways, we might prefer this approach for our PDF finding aids (rather than attaching them to the archival description record) since it would allow us to retain our existing file names. However, is there a way for these to be indexed in AtoM's search if we take this approach? The ability to index and search PDFs within the same system as the collection descriptions is a big draw for us with potentially migrating to AtoM.
Thank you again for your help.
Best,
Krista
Dan Gillean
May 9, 2024, 8:24:20 AMMay 9
to ica-ato...@googlegroups.com
Hi again Krista,
I'm glad to hear that some of my workaround might help. Regarding your questions:
If we took this approach with taxonomy tags, how would you recommend implementing it? We are indeed thinking it will be best to have the record series as the top level of description, and the record group membership is more informational in many cases rather than being a navigational feature (as you suspected, the navigational element of it is used more by archives reference staff).
I would say that this depends on how much development you want to do. If you want to do none, then the simplest approach would be to create a top-level taxonomy term called something like "Record Classifications" in one of the existing taxonomies (like the Subjects taxonomy), and then nest terms for the Record Groups and subgroups under it. Users could then use the taxonomy browse results page to explore by Record Group when viewing all descriptions that appear under the top-level "Record Classifications" term. You would still be able to use the Subjects taxonomy for actual subject-based classification and access points so long as you didn't mind sharing the source taxonomy. If desired, you could even have a separate top-level term for "Subject access points" and nest all other terms under it, to keep each set of uses in separate hierarchies
Another option if the record groups truly are only meaningful to your staff: you could pick something like the RAD General Material Designation taxonomy. It doesn't have a browse page (as I think you previously noted), and if you are using DACS, then staff would need to flip to the RAD template, add the relevant classification, then flip back to DACS - but since the RAD GMD has a filter in the Advanced search, staff at least would be able to easily limit records by record group. Further, you can look at how filtering that way structures the URL, and then use those link IDs to implement some of the other suggestions I made.
Finally, there are the options you had originally considered - either fully repurposing an existing taxonomy and modifying it via development to suit your need, or else using development to add a new custom taxonomy to AtoM.
Also, what do you mean by "taxonomy tags"? Is this a type of taxonomy term?
Sorry, that was off the cuff; I should have been more precise in my language choice. I simply meant controlled vocabulary taxonomy terms used as access points in that moment.
In some ways, we might prefer this approach for our PDF finding aids (rather than attaching them to the archival description record) since it would allow us to retain our existing file names. However, is there a way for these to be indexed in AtoM's search if we take this approach? The ability to index and search PDFs within the same system as the collection descriptions is a big draw for us with potentially migrating to AtoM.
Out of the box - no, unfortunately. There MIGHT be a way for a developer to programmatically inject additional content into an existing search index, but it would likely be onerous, and something you'd need to remember to do manually any time you added, modified, or removed one of these finding aids. Similarly, there MIGHT be some way described in the Elasticsearch documentation to have ES index an additional location - but if there is, I am not familiar with it and it's not something our team has tried before. Plus, I believe that AtoM is first using other tools like the CLI utility pdftotext to scrape the text layer from the digital objects to the database, and the index is using that populate (rather than parsing the text layer of the PDFs themselves) - although on this I am not actually sure. If it's important to know how that works, I can follow up with a developer - let me know.
Otherwise, in terms of workarounds? My only thoughts would be that:
- If you are still making the Record Group your top level, then what if the PDF you upload there is for the FULL record group (so everything gets indexed), but you ALSO make external Series-level finding aids available via links, for a better end user experience?
- If you are going to make the Series the top level of description, then... I believe this issue is avoided? You can now upload 1 finding aid per series, and those will be indexed.
Hope that helps. Good luck! I hope you find a solution that will work for your needs.
Cheers,
he / him
To view this discussion on the web visit https://groups.google.com/d/msgid/ica-atom-users/a34bfc39-010c-4c2c-8e8d-42e0ba0877efn%40googlegroups.com.
Reply all
Reply to author
Forward
0 new messages