Expected Behavior in Batch Edit

[Grant]

Batch Edit in Specify is a powerful tool for modifying, augmenting, or correcting large numbers of records in bulk. The way records are created, updated, deleted, matched, or unlinked depends on the type of relationship, the fields mapped, and user preferences set in the Data Mapper. This section summarizes what happens when you edit, clear, or otherwise change relationship records in Batch Edit.

[!info]
Before you begin working with Batch Edit, first become familiar with the difference between dependent and independent relationships as this has a major impact on how the edits you make will be reflected in the database.

---

Relationship Types and Batch Edit Actions

To-One Dependent Relationships

(e.g., Collection Object → Collection Object Attribute)

• Update: Editing mapped fields directly updates the related record.
• Create: If the related record does not exist and you enter non-empty values, a new record is created.
• Delete: If all mapped fields are cleared (i.e., made empty), Batch Edit will attempt to delete the related record only if:
  1. All fields in the database for that record are empty (excluding system fields), according to the “empty record” preference.
  2. The record has no dependents of its own.
     • Even if the user has permission and the “use only visible fields for empty record check” preference is enabled, a dependent record will not be deleted if it has any child dependent records (e.g., a Determination with a Determiner, or a Collecting Event with a Collection Event Attribute).
• Batch Edit data set preference:
  • Use only visible fields for empty record check
    • If enabled, only visible (mapped) fields must be empty to trigger deletion.
    • If disabled (default), all fields (except system fields) must be empty for deletion.

To-Many Dependent Relationships

(e.g., Collection Object → Determinations, Collection Object → Preparations)

• Update: Changes in mapped fields directly update the related records.
• Create: If a related record does not exist and you enter data, it is created.
• Delete: If all mapped fields are cleared, Batch Edit will attempt to delete the related record only if:

1. All fields in the database for that record are empty (excluding system fields), as per the preference.
2. The record has no further dependents.
   • A Determination with a linked Determiner (for example) will not be deleted even if the Determination’s own fields are cleared.

To-One Independent Relationships

(e.g., Collection Object → Cataloger, Preparation → Storage)

• Match: If you enter values that match an existing record (according to matching preferences), the relationship is updated to link to the matched record.
• Clone: If no match is found, a new record is created by cloning the existing related record and applying your changes. Any mapped dependents are also cloned; unmapped dependents remain unchanged.
• Unlink:
• Clearing all mapped fields removes the relationship from the base record, but does not delete the related record.
• The original related record remains in the system.
• Preferences: Matching can use only visible fields or all fields, depending on the Batch Edit preference.

To-Many Independent Relationships

(e.g., Collecting Event → Collection Objects, Locality → Collecting Events)

• Update: Changes are applied to the related records.
• Create: If a related record does not exist and you enter data, it is created.
• No Deletion or Unlinking: Clearing all fields does not delete the related record nor unlink the relationship.

Trees (Taxonomic/Hierarchical Data)

• Update/Clone: When editing tree paths (e.g., via a tree as base table), records are cloned for changes, not updated directly.
• (Any rank) Columns: Read-only unless the base table is a tree.
• Deletion: Deletion of tree nodes is not performed via clearing fields; such columns are not editable as relationships.

---

Special Notes

• No Change Principle:
  If you make no change to a record, Batch Edit will not create, modify, or delete anything in the database.
• System/Read-only Fields:
  Fields such as GUID, TimestampCreated, TimestampModified, and other system columns are never editable or considered for deletion checks.
• Parent‐Child Dependency Protection:
  Dependent records with their own dependents are protected from deletion, regardless of user permission or “empty record” preference. This prevents orphaned child records.

---

Visual Feedback

• Updated Cell: Highlighted when a simple field is changed.
• Deleted Cell: Highlighted orange when a dependent record is deleted due to all relevant fields being empty and it has no child dependents.
• Matched and Changed: Highlighted when a to-one independent is matched to a different record.
• New Cell: Highlighted when a new record is created due to entry of data where no related record existed.

---

Preferences

User Preferences

The Batch Edit User Preferences modify the look and behavior of Batch Edit for their associated user.

• Number of records selected from the query
  • Determines the number of rows to pull from the Query Results when creating the data set
  • Default: 5,000
• Enable relationships
  • When unchecked, any columns for relationships from the base table of the query will be read-only in the resulting Batch Edit data set
  • If checked, relationships can be edited but the data set cannot be rolled back
  • Default: Checked / True
• Show rollback button
  • Controls visibility of rollback option in Batch Edit.
  • Requires both permission to rollback and Enable relationships unchecked
  • Default: Checked / True

Default user preferences can be overridden at the collection, discipline, or institution level. See Setting Default User Preferences.

Data Set Preferences

Batch Edit data set preferences can differ across each data set.

• Use only visible fields for empty record check
  • Controls whether deletion is based on mapped fields only or all fields
  • Default: Checked / True
• Use only visible fields for match
  • Controls whether matching for to-one independents uses just mapped fields or all fields
  • Default: Checked / True

---

Deletion and Empty Record Checks

• All Fields vs. Visible Fields:
  The preference “Use only visible fields for empty record check” controls how aggressively deletion is triggered:

  • Enabled: A dependent record is deleted if mapped fields are empty and it has no child dependents.
  • Disabled: All non-system fields in the record must be empty and it must have no child dependents.

• Risk of Accidental Deletion:
  If not all fields are mapped, unmapped data may prevent deletion under the default setting. To delete based on visible fields only, enable the preference—but note that deletion will still be blocked if the record has dependents.

---

Summary Table

Relationship Type	Editing Mapped Fields	Clearing All Mapped Fields	Result / Action
To-one dependent	Updates existing record	All fields empty	Deletes related record only if no child dependents (and per preference)
To-many dependent	Updates existing related record(s)	All fields empty	Deletes related record only if no child dependents (and per preference)
To-one independent	Matches or clones record	All fields empty	Unlinks relationship; related record is not deleted
To-many independent	Updates or creates related record(s)	All fields empty	No deletion or unlinking; record remains
Tree (as base table)	Clones node for changes	Not applicable	Records are cloned; no direct deletion

---

Examples

• Updating a Dependent Record:
  • Edit a mapped field for a Collection Object Attribute; the attribute is updated.
• Creating a Dependent Record:
  • If no Collection Object Attribute exists and you enter data, a new attribute record is created.
• Deleting a Dependent Record:
  • Clear all mapped fields for a Collection Object Attribute. It is deleted only if it has no child dependents and meets the empty-fields criteria.
• Matching or Cloning an Independent Record:
  • Change Cataloger fields to match another Agent; the relationship updates to that Agent. If no match, a new Agent is cloned and linked.
• Unlinking an Independent Record:
  • Clear all mapped fields for a Cataloger (to-one independent); the Agent remains but is no longer referenced.
• No Change:
  • If you make no edits, Batch Edit will not modify or delete any records, regardless of empty fields in the UI.