Collection Relationship Subviews: Linking Objects Within the Same Collection

[bronwyn]

This guide explains how to configure a subview-based layout for Collection Relationships that link Collection Objects within the same collection.

What Are Collection Relationships?

Collection relationships in Specify allow specimens to be associated with either specimens in another collection or with a taxonomic name in another collection. Common examples include tissue-and-voucher, plant-and-pollinator, and host-and-parasite relationships. Specify allows collection objects in two different collections to be related to one another for the purpose of documenting these types of connections. The collections may be in different disciplines, but are required to use the same catalog number format.

Collection relationships consist of two sides:

• Source (Left Side): The primary record. In a single relationship, a source may have many destinations.
• Destination (Right Side): The associated record. A destination may only have one source.

While collection relationships commonly connect records across different collections (such as linking a mammal host to an insect parasite), there are cases where you may want to relate records within the same collection, for example, linking a tissue sample back to the voucher it was derived from, or documenting that one object was found inside or attached to another. This guide covers that same-collection use case using a subview-based layout.

This approach ensures that whether you are viewing the source record or any of its associated destination records, the relationship displays cleanly and shows the correct linked record from both perspectives.

[!info] New to Collection Relationships?
If you are setting up a relationship for the first time, we highly recommend reviewing our foundational guides first:

• Collection Relationships Overview
• Creating a Collection Relationship Type in Specify 7

Understanding the Two Subviews

When viewing a Collection Object record, the two subviews serve distinct purposes:

• Left Subview (leftSideRels): The current record is the source. Use this to add objects that are derived from or descended from the record you are viewing. For example, if you are looking at a voucher specimen, you would add tissue samples here; if you are looking at a host, you would add parasites found on it.
• Right Subview (rightSideRels): The current record is the destination. Use this to add objects that the current record originated from — that is, records that the current object is connected to from the other side of a relationship. For example, if you are looking at a tissue sample, you would add the voucher it came from here; if you are looking at an object found inside another, you would add the containing object here.

Together, these two subviews give you a complete picture of all relationships involving a record, regardless of which side of the relationship it sits on.

Step-by-Step Configuration

1. Define the Collection Relationship Type

First, establish the relationship structure in your system settings.

1. Navigate to your system configuration and create a new Collection Relationship Type.
2. For same-collection relationships, set both the Left Side Collection and the Right Side Collection to point to the same collection. (For cross-collection relationships, select the two different collections instead.)
3. For full context on this step, see Creating a Collection Relationship Type.

2. Create the Pair of Subview Definitions

Next, we will define how these relationships look on the screen. Because a record can be either a source or a destination, we need to create two matching views for the CollectionRelationship table.

1. Go to App Resources and open the desired form definition.

2. If you are creating a new view from scratch, ensure you check the Show all tables option to make the CollectionRelationship table visible.

3. We will add two distinct view definitions: CollectionRelationship (for the Left Side/Source connections) and CollectionRelationship_2 (for the Right Side/Destination connections).

   To prevent circular selections or drop-down confusion for your users, we change the UI Type (uitype) of the current record’s side to a plain text field, while leaving the opposite side as a searchable dropdown (querycbx).

Left Side/Source Relationship Subview (leftSideRels) XML:

<viewdef name="CollectionRelationship" class="edu.ku.brc.specify.datamodel.CollectionRelationship" type="form" gettable="edu.ku.brc.af.ui.forms.DataGetterForObj" settable="edu.ku.brc.af.ui.forms.DataSetterForObj">
	<desc>The CollectionRelationship Table - Left Side View</desc>
	<enableRules/>
	<columnDef>p,p,p,2px,p,2px,p,2px,p,2px,p,2px,p,p,p,p:g</columnDef>
	<rowDef auto="true" cell="p" sep="2px"/>
	<rows>
		<row>
			<cell type="label" labelfor="type"/>
			<cell type="field" uitype="querycbx" id="type" name="collectionRelType" initialize="editBtn=false;viewBtn=false;newBtn=false;" colspan="5"/>
		</row>
		<row>
			<cell type="label" labelfor="ls"/>
			<cell type="field" uitype="text" name="leftside" id="ls" viewname="leftsiderels" colspan="6"/>
			<cell type="label" labelfor="rs"/>
			<cell type="field" uitype="querycbx" name="rightside" id="rs" viewname="rightsiderels" colspan="6"/>
		</row>
		<row/>
	</rows>
</viewdef>

Right Side/Destination Relationship Subview (rightSideRels) XML:

<viewdef name="CollectionRelationship_2" class="edu.ku.brc.specify.datamodel.CollectionRelationship" type="form" gettable="edu.ku.brc.af.ui.forms.DataGetterForObj" settable="edu.ku.brc.af.ui.forms.DataSetterForObj">
	<desc>The CollectionRelationship Table - Right Side View</desc>
	<enableRules/>
	<columnDef>p,p,p,2px,p,2px,p,2px,p,2px,p,2px,p,p,p,p:g</columnDef>
	<rowDef auto="true" cell="p" sep="2px"/>
	<rows>
		<row>
			<cell type="label" labelfor="type"/>
			<cell type="field" uitype="querycbx" id="type" name="collectionRelType" initialize="editBtn=false;viewBtn=false;newBtn=false;" colspan="5"/>
		</row>
		<row>
			<cell type="label" labelfor="ls"/>
			<cell type="field" uitype="querycbx" name="leftside" id="ls" viewname="leftsiderels" colspan="6"/>
			<cell type="label" labelfor="rs"/>
			<cell type="field" uitype="text" name="rightside" id="rs" viewname="rightsiderels" colspan="6"/>
		</row>
		<row/>
	</rows>
</viewdef>

3. Embed the Subviews on the Collection Object Form

Now, we place these two subviews onto your main Collection Object view definition. Placing them side-by-side within a panel and setting defaulttype="table" gives your data entry team a clear spreadsheet-like grid.

Form Layout XML:

<row>
	<cell type="panel" colspan="16">
		<rows>
			<row>
				<cell type="subview" name="leftsiderels" id="lscr" viewname="CollectionRelationship" colspan="7" defaulttype="table"/>
				<cell type="subview" name="rightsiderels" id="rscr" viewname="CollectionRelationship_2" colspan="7" defaulttype="table"/>
			</row>
		</rows>
	</cell>
</row>

[!tip] Conserving Screen Real Estate

If many of your specimens do not use relationships, you can use Conditional Rendering to hide this entire panel until a specific checkbox on the form is selected. Learn how to implement this in our guide on Editing Forms: Conditional Rendering.

4. Once your edits are complete, save by clicking the Save button in the editor.

Finished Experience

The grid on the left tracks all objects derived from or descended from this record such as tissue samples from a voucher, parasites from a host, or objects found inside or attached to the current specimen.

The grid on the right tracks all objects that this record originated from, such as the voucher a tissue came from, the host a parasite was found on, or the containing object an attached specimen was removed from. This provides a fully traceable link back to the source record.

---

Want to add relationships to existing records in-bulk? Check out our guide below:

Create Collection Relationships via the WorkBench

This guide walks through how to upload Collection Relationships through the WorkBench and includes screenshots of the mapping and what the uploaded results would be. Collection relationships in Specify allow the association of specimens with other specimens in different collections. Examples include tissue-voucher, plant-pollinator, and host-parasite relationships. This functionality enables you to document these important connections, even across different disciplines, as long as the …