Add support for adding a generic automatic relationship record during data entry

[grantfitzsimmons]

Problem Statement

When entering new records in Specify, users often must create related records, such as Determinations, Preparations, Collection Object Attributes, Collection Object Properties, Collectors, or Locality Details, to fill in all necessary details about a record. These are linked to the primary record being entered in the data model via 'Relationship Fields'. For example:

• collectionobject -> determinations
• collectionobject -> collectionObjectAttribute
• collectionobject -> preparations

Currently, Specify supports automatic creation of only three dependent tables (Collection Object Attribute, Determination, Preparation) via remote preferences settings (CO_CREATE_COA, CO_CREATE_DET, CO_CREATE_PREP). Extending this behavior to other relationships (e.g., Collector, Locality Detail) is not currently possible. This leads to extra clicks, risk of missing required fields, and inconsistent data entry workflows between users.

What we need is a generic, configurable mechanism to declare which relationship records should be auto-created, and under what circumstances, would streamline data entry, reduce errors, and provide a consistent framework for future tables. It should support (for example):

• locality -> localityDetails
• preparation -> preparationAttribute
• collectingevent -> collectors
• determination -> determiners

Functional Requirements

A migration from the current Remote Prefs implementation would be preferred if at all possible.

• Newly created subview records must appear automatically in the data-entry form.
• This should only be done for the first record added for that relationship.
  • For example, if there is a Determination automatically created and the record is saved, a new Determination should not be added automatically after a reload.
  • If the user is using 'Carry Forward' or 'Clone', a new record should only be created in the case that a record in the configured relationship table (e.g. Determination) does not yet exist.
• This should support any relationship field that is a one-to-one or one-to-many that is rendered as a subview (including when shown as a button (see Automatically created Preparation in a button not assigned a PrepTypeID #3094))
• This new record should enforce any required fields (from either the schema or forms) and block saving if those requirements are not met

---

Proposed Solution

We could introduce a unified “auto-create” framework that can be applied to any relationship subview via:

View Definition:
Add a new attribute autocreate to <cell type="subview"> definitions in the view layout XML. For example:

<cell
  type="subview"
  viewname="Collector"
  id="12"
  name="collectors"
  colspan="12"
  rows="3"
  autocreate="true" />

Acceptance Criteria

1. Configurable via ViewDef
   Any <cell type="subview" … autocreate="true"> in a view layout XML must trigger automatic creation of exactly one related record the first time the parent record is saved. The default when the attribute is omitted or set to "false" is no auto-creation.

2. First-Only Behavior
   Once the initial dependent record has been created and saved, subsequent reloads, “Carry Forward,” or “Clone” operations must not spawn an additional record if any existing child record is present. Only if the subview is entirely empty (zero linked records) should a new record be created under "autocreate".

3. One-to-One and One-to-Many Support
   The framework must work for any relationship rendered as a subview—whether one-to-one or one-to-many, including subviews exposed via a button (initialize="btn=true).

4. Enforce Required Fields
   Auto-created records must honor all schema-level and form-level “required” constraints. If mandatory fields in the new child record lack values, the parent save operation is blocked and inline validation messages appear in the subview header.

---

Alternatives Considered

Extending the existing remote preferences approach by adding CO_CREATE_COLLECTOR, CO_CREATE_LOCALITYDETAIL, etc. This would require code changes for each new table, complicating maintenance and forcing a software release for every new auto-creation need.

---

Source and Stakeholders

• Philippe Verley (IRD) via Speciforum: request for automatic Collector creation on CE creation.
• Alexis Beck (NHM Geneva): auto-create LocalityDetail when creating a Locality.
• Nate Shoobs (OSU): auto-create preparation attribute

Discussed in #5993

^{Originally posted by grantfitzsimmons October 31, 2024}
Requested by: Philippe Verley at IRD on the Speciforum

The title purposefully mimics Automatically create a new Preparation, Determination, or Collection Object Attribute upon CO creation and says it all.

The Embedded Collecting Event option and the three remote preferences CO_CREATE_COA, CO_CREATE_DET & CO_CREATE_PREP proved very useful for easing up and securing new CO entry. Number of clicks is decreased and mandatory fields are clearly identified.

A Collecting Event does not make sense without a Collector in CAY herbarium. When I set up the CO_CREATE preps, my colleagues immediately asked whether a new Collector could be automatically created as well, since it is mandatory in our data entry process.

☝️ Can one automatically creates a new Collector upon CE creation ?

A quick look at CollectionObject initialization and CollectionObject Resources initialization seems to indicate that presently answer is no and that it may not be straightforward to implement.

🤔 I'm also wondering why you decided to implement COA, DET & PRE creation through Remote Preferences ? (genuine question) Have you thought of a generalized approach in viewdef resources, with for instance and XML attribute that would control the underlying resource creation ?

<!-- COA subview with 'create' attribute -->
<cell type="subview" viewname="CollectionObjectAttribute" id="10" name="collectionobjectattribute" colspan="14" initialize="" create="onDataEntry"/>
<!-- Collector subview with 'create' attribute -->
<cell type="subview" viewname="Collector" id="12" name="collectors" colspan="12" rows="3" create="onDataEntry" />

The create attribute could accept several values:

• never (default)
• onDataEntry : create the underlying object on new data entry only
• ifEmpty : create the underlying object on new data entry or on data edition if empty
• ?

Feel free to split the last bit to a separate thread "Generalizing automatic object creation on Data Entry" if the thought interferes with my 1st question on collector creation.

[specifysoftware]

This issue has been mentioned on Specify Community Forum. There might be relevant details there:

https://discourse.specifysoftware.org/t/automatically-create-a-new-collector-upon-ce-creation/2051/3