Incorporate feedback on collection nesting documentation

Explore how to add the following to Collection Nesting FAQ...

The following was recommended by @laritakr:

A few additional details which might be helpful to have documented somewhere.. (or may be too much detail, I don’t know)

In the Model

Nesting is added to Hyrax via the inclusion of Hyrax::CollectionNesting in the Collection and Work models.

Configuring Nested Collections

Hyrax contains a config file (hyrax/config/initializers/samvera-nesting_indexer_initializer.rb) specifically for setting up the nesting depth and solr field names used for indexing. An additional indexed field for storing the field name for deepest nested depth is defined in the nesting_index_adapter.

In Fedora and Solr

(Note: I’m not sure how this should be worded, but I thought it might be informative to some people to know what to expect to see in Solr and Fedora)

In Hyrax, a child is stored as a member of a parent. The relationship is stored in Fedora as ldp container “member_of_collections” with a memberOf relationship. It is indexed in solr in "member_of_collection_ids_ssim" and “member_of_collections_ssim” as part of the standard to_solr method. Additional fields are added to Solr via an after_update_index callback.

Indexing

In Hyrax, ActiveSupport::Concern is extended by Hyrax::CollectionNesting to add an after_update callback. This calls the Samvera::NestingIndexer via the Hyrax’s nesting_index_adapter to add additional indexed fields to both collections and works, based on the object's "member_of_collections" attribute stored in ActiveFedora. The field names are specified in config variables and in the nesting_index_adapter.

The nesting indexer updates the solr document for collections and contained works with additional fields which are used for displaying the nested collections and validating which collections are valid for new creating nested relationships. A call to the indexer reindexes the object itself, as well as all of its descendant collections and works.

The additional fields added to the solr document are:

ancestors: an array of the pathnames to each ancestral node of the given node (e.g. pathname to my parent, pathname to my grandparent)
parent_ids: the ids for of the parents of the given document
pathnames: an array of each path to traverse from a root document to the given document
deepest_nested_depth: the count of ids in this document's longest pathname

These fields are more fully explained in the Samvera::NestingIndexer gem's documentation.

How does this relate to nested works?

A nested work can be added to a nested collection. However, nested works are implemented separately from and indexed differently than nested collections. Adding one nested work to a collection does not affect the indexing of its contained works, as they will not contain the member_of_collections attribute unless they are also independently added to the collection.

Re-Indexing

In Hyrax, ActiveFedora::Indexing.reindex_everything is overridden to actually call Samvera::NestingIndexer.reindex_all!. ActiveFedora reindexes using only to_solr, which will remove the indexed fields from collections and works that were added by Samvera::NestingIndexer.

The Samvera::NestingIndexer method reindex_all! uses the each_perservation_document_id_and_parent_ids method defined in Hyrax's nesting_index_adapter to process each object in the repository. It uses ActiveFedora to retrieve the repository objects with priority models first, and then branches the indexing between the nesting indexer and to_solr, depending on whether or not the model includes the "CollectionNesting" module.

Abilities

In order to nest a collection within another collection, you must have deposit permission on the parent collection, and read permission on the child collection. Abilities are defined in Hyrax::Ability::CollectionAbility and Hyrax::Collections::PermissionService.

samvera / samvera.github.io