Create a Collection Relationship in Specify 7

Before you can create a Collection Relationship in Specify, you need to define a CollectionRelType view definition to create a Collection Relationship.

If you are unfamiliar with editing forms, please watch and read our documentation on the subject before proceeding.

Create CollectionRelType Form

First, you will need to either create a new form definition or navigate to an existing one available to your user in App Resources.

Once there, check “Show All Tables” to display all tables in the Specify model. Find “Collection Relationship Type” in the list.

Once selected, click the Create button to make a new view definition for the table.

Rather than choosing one of the default views, click New to create one from scratch.

You will need to leave the name as “CollectionRelType”.

Once the new view definition is created, copy the following XML and replace the contents of the new XML:

<viewdef
            type="form"
            name="CollectionRelType"
            class="edu.ku.brc.specify.datamodel.CollectionRelType"
            gettable="edu.ku.brc.af.ui.forms.DataGetterForObj"
            settable="edu.ku.brc.af.ui.forms.DataSetterForObj">
            <desc><![CDATA[The Collection Relationship Type form]]></desc>

            <columnDef>100px,2px,195px,5px,86px,2px,210px,5px,74px,2px,146px,15px,p:g</columnDef>
            <columnDef os="lnx">115px,2px,195px,5px,125px,2px,210px,5px,125px,2px,131px,15px,p:g</columnDef>
            <columnDef os="mac">130px,2px,215px,5px,138px,2px,260px,5px,138px,2px,155px,15px,p:g</columnDef>
            <columnDef os="exp">p,2px,min(p;220px),5px:g,p,2px,p,5px:g,p,2px,200px,p,p:g</columnDef>
            <rowDef auto="true" cell="p" sep="2dlu"/>

            <rows>
                <row>
                    <cell type="label" labelfor="1"/>
                    <cell type="field" id="1" name="name" uitype="text"/>
                    <cell type="label" labelfor="2"/>
                    <cell type="field" id="2" name="remarks" uitype="text"/>
                </row>
                <row>
                    <cell type="label" labelfor="4"/>
                    <cell type="field" id="4" name="leftSideCollection" uitype="querycbx" initialize="name=CollectionRelationship" isrequired="true" colspan="6"/>
                </row>
                <row>
                    <cell type="label" labelfor="5"/>
                    <cell type="field" id="5" name="rightSideCollection" uitype="querycbx" initialize="name=CollectionRelationship" isrequired="true" colspan="6"/>
                </row>
            </rows>
        </viewdef>

After this, you need to add /specify/view/collectionreltype/new/ to the end of your Specify installation’s base URL (e.g. https://sp7demofish.specifycloud.org/specify/view/collectionreltype/new) and navigate to the new Collection Rel Type form.

Give the CollectionRelType a name

Use the :search_: (search) icon to the right of the Left Side Collection and Right Side Collection query combo boxes to search for the collections you want to make the relationship between.

Note: If the collections are in a different discipline, you will need to set both query combo boxes to use the collection within the current discipline. Then, switch collections, navigate to the Collection Relationship Type record, and set the appropriate “Right Side” or “Left Side” collection.

This is due to the ‘Query Builder’ system being scoped to the current collection.

Once the collections are set, you can click Save to create the relationship.

Form Definition Usage

In the forms, these relationships can be referenced directly in the Collection Relationship form plugins.

CollectionRelOneToManyPlugin

In the XML,

<cell type="label" label="Tissues:" initialize="align=left;"/>
<cell type="field" id="colrel" uitype="plugin" name="this" initialize="name=CollectionRelOneToManyPlugin;relname=Has Tissue;" colspan="9"/>

ColRelTypePlugin

ColRelTypePlugin

In the XML,

<cell type="label" label="Tissues:" initialize="align=right;"/>
<cell type="field" id="colrel" uitype="plugin" name="this" initialize="name=ColRelTypePlugin;relname=Has Tissue;"/>

Building a Query

Now that you can associate records in a Collection Relationship, you will need to modify the Schema Config for the discipline(s) involved in the relationship.

From Collection Relationships:

On a database level, the Collection Object Relationship sides are:

Source: Left Side
Destination: Right Side

To search and find data from objects linked via the CollectionRelOneToManyPlugin (source to destination, e.g. ‘voucher → tissue’), you will need to unhide the relationship field leftSideRels on the collectionobject table in the schema.

Once it is unhidden, you can query across Collection Object --> Left Side Rels --> Right Side --> Collection Object to retrieve data from the linked COs, even if they are in another collection.

In a similar way, to search and find data from objects linked in the ColRelTypePlugin (destination to source, e.g. ‘tissue → voucher’), you will need to unhide the relationship field rightSideRels on the collectionobject table in the schema.

Once it is unhidden, you can query across Collection Object --> Right Side Rels --> Right Side --> Collection Object to retrieve data from the source CO.

Hi Grant:

Seems there is some typo on at the code:

<viewdef>
            type="form"
            name="CollectionRelType"
            class="edu.ku.brc.specify.datamodel.CollectionRelType"
            gettable="edu.ku.brc.af.ui.forms.DataGetterForObj"
            settable="edu.ku.brc.af.ui.forms.DataSetterForObj">

Shold be in this way, isnt it?

<viewdef  type="form"
            name="CollectionRelType"
            class="edu.ku.brc.specify.datamodel.CollectionRelType"
            gettable="edu.ku.brc.af.ui.forms.DataGetterForObj"
            settable="edu.ku.brc.af.ui.forms.DataSetterForObj">

Anyway, after doing this and type any character on Name field ona dockerized 7.9.6.2), it returns en error on api.

Error: Error occurred fetching from https://XXXXXXXXXXXX/api/specify_rows/collectionreltype/?limit=0&domainfilter=true&distinct=true&fields=name
Invalid response code 500.

    This error may indicate a misconfiguration or a bug in Specify. Please
    double check your configuration and report this issue.

HierarchyException at /api/specify_rows/collectionreltype/\nqueryset model Collectionreltype has no hierarchy field\n\nRequest Method: GET…

Doing this at production instance, returns same result so, could you please what that error means and if its needed any further action before/after creating the form view?

Thanks

Hi @miquelmAuupa,

You are right, thank you! I’ve corrected the XML snippet.

The error dialog you see due to the HierarchyException is a known issue (#4989), though it should not prevent you from assigning the collection on either side of the relationship. You can dismiss and safely ignore the error “toast” in the top right of the screen.

You will need to set the collections by clicking on the :search_: (search) icon for the query combo box so that you can use the embedded query builder to assign the appropriate collection!