Batch Edit :batchedit_:

Specify makes it simple to edit a batch of records directly through the Specify WorkBench interface. The Batch Editing tool is a powerful way to augment or modify existing records—potentially affecting thousands of records with just a few mouse clicks. Use Batch Editing to:

  • Add new information to or correct multiple records at once
  • Standardize or correct grammatical and spelling errors
  • Update fields to comply with Darwin Core standards

Below is an overview of Batch Editing, including images of the interface, setup guidelines, and step-by-step instructions.

[!note] Known Limitations

  • Note: This tool is in beta, meaning we will be making iterative improvements and adjustments as we gather feedback!

    • ‎ Roll Back support is experimental and must be enabled via User Preferences.
    • Backups of the database should be made before making any edits.
  • Batch Edit is disabled for system tables and scoping hierarchy tables (e.g. specifyuser, division, collection, etc.).

  • Latitude1 and Longitude1 are not editable at this time, meaning some tools like GEOLocate or Convert Coordinates are not available until a later release.

  • Data cannot be ‘imported’ in Batch Edit at this time, though you can copy and paste the contents from an external spreadsheet into the editor. If you use this approach, take great caution and make sure to copy unique identifiers (preferably GUIDs) to make sure you do not update the wrong row erroneously.


Before You Begin

Before launching a Batch Edit session, please take the following precautions:

  1. Make a fresh, full backup of your database.
  2. Ensure that you understand the relationships represented by the fields and tables you wish to change before using the Batch Editor.
  3. When creating queries to choose the data that will be displayed in the Batch Editor, create the query from the primary table and include fields and tables related to the specific data you wish to edit.
  4. After a batch edit is completed, view the updated query results to confirm that your changes did not inadvertently affect related fields and tables. Remember, once any of the updated data is edited, it cannot be rolled back.

Permissions for Batch Edit

Batch Edit adds a new permission category under the same name. Please refer to the Security and Accounts documentation to learn more about how to grant these permissions to users in a Specify database.

Institution Admin users have all permissions already.

Permission Description
Create Can create new records in Batch Edit.
Update Can modify existing records.
Delete Can delete base records.
Commit Can upload (commit) the changes back to the database.
Rollback Can roll back a Batch Edit data set (experimental).
Validate Can validate the pending changes before committing.
Transfer Can transfer records between collections.
Create Recordset Can save the results of a Batch Edit as a new Record Set.
Delete Dependents Controls whether dependent records can be deleted in Batch Edit.
Edit Multiple Tables Controls whether related tables (relationships) are editable in Batch Edit. This preference only applies if “Edit Multiple Tables” permission is set.

Delete Dependents

  • If granted, Batch Edit will delete dependents when you clear all visible fields (subject to “visible fields for empty record check”).
  • If not granted, clearing visible fields leaves dependent records in place (fields become empty). If a required field is emptied, validation will fail.
  • Deleting dependents requires extra integrity checks; this permission acts as a barrier and must be explicitly requested from the Collection Manager.
  • Note: Even with this permission, a dependent will not be deleted if it has its own dependents. For example, deleting a Determination will not succeed if there is a linked Determiner record; likewise, deleting an embedded CE will not succeed if it has an associated CEA.

Edit Multiple Tables

  • If not granted, all relationship columns in the grid appear read-only.
  • This is completely independent of the Enable relationships preference in Batch Edit → General—enabling that preference has no effect unless the Edit Multiple Tables permission is also granted.

Expected Behavior

Dependent vs. Independent Relationships


Interface Overview

[!info]
Batch Edit and the WorkBench use the same grid editing interface. To learn about the full suite of tools available in the grid editor, please review the WorkBench documentation:
WorkBench Grid Editing Documentation

Grid Navigation

The Validate button works similarly to that in the WorkBench. In addition, Batch Edit displays cell highlights for specific actions:

  1. Updated Cells
    Cells with newly changed values are highlighted light blue.
    Updated Cells

  2. Deleted Cells
    Cells where records are deleted and dependent cells are empty are highlighted orange.
    Deleted Cells

  3. Matched and Changed Cells
    Cells where a to-one independent record is matched to a different record than the current one are highlighted blue.
    Matched and Changed Cells


Background Information

  • The default number of records selected from a query is 5000. This can be changed in Preferences, though larger data sets will take longer to validate and commit.

  • Batch Editing is available only to users with Admin, Manager, or Full Access status who have access to both the Query Builder and WorkBench tools.

  • Fields that are read-only in the schema (e.g., GUID or Timestamp Created) can only be viewed.

  • When you bring data into Batch Edit, you are essentially “checking it out” from the database to later validate and apply changes. If other users are editing the same records, discrepancies may occur during validation. In this case, Specify will not commit the changes and will alert you via a dialog window.

  • If more than one collection resides in a single database, any changes made in shared tables will affect all collections within the same Discipline.

Useful Links:


Choosing Records to Edit

To select records for batch editing, create a query by clicking on the appropriate table in the Create Query section or use an existing one.

Add all the fields you want to edit or view, ensuring you include related data to determine the uniqueness of each record. Once you finish, you can save the query by clicking the Save Query button in the top right and naming your query.


Batch Editing Process

Once your query is ready, click the Batch Edit button above the query results.

Note: If you haven’t saved the query, you’ll receive a warning and you will have to close out and save the query before continuing.

The query results will then display in a spreadsheet format, and you can access the Batch Edit tool via the Batch Edit option in the navigation bar.

A demonstration video is available:

The Batch Edit interface resembles the WorkBench grid editor, offering functionalities such as copy, paste, sort, fill up, fill down, etc. For more details, see the Workbench documentation.

Note: Columns with non-editable fields appear grayed out.
To revert back to the original data during editing, click the Revert button at the top right of the screen. Once you are satisfied with your changes, click the Validate button in the top-right area of the Workspace screen.


Viewing Results

Click the Results button to see the total number of records that will be updated in each affected table. If these numbers do not match your expectations, review your edits before committing changes.

It may be helpful to load and edit a small subset of records first, then create queries on the modified records to analyze the impact on related fields and tables. Once satisfied, proceed to apply the changes to all records.

After verifying that there are no validation errors, click the Commit button.


Commit and Record Set Management

After committing a Batch Edit, the records can be saved in a new Record Set. By default, the Record Set is named BE commit of “(query name)”, but you can modify the name for clarity. If you opt not to save initially, you can always return to the Results button and click Create Record Set later.


Roll Back (Experimental)

Roll Back in Batch Edit is highly experimental. We strongly recommend doing a full database backup before using the Roll Back feature.

  • Limitations:
  • Roll Back only works for simple fields; you cannot Roll Back relationships.
  • Depending on User Preferences, relationships can either be editable but non-Roll Backable, or relationships can be disabled (read-only) but still Roll Backable.
  • Preferences Impacting Roll Back:
  • Enable relationships (global): If enabled, Roll Back is disabled.
  • Show Roll Back button: Controls visibility of the Roll Back button.
  • Once you Roll Back a data set, it can no longer be edited—rerun the query if you want to try again.

To perform a Roll Back:

  1. Query the updated records.
  2. Return to the Batch Edit data set and click Roll Back.
  3. Confirm to revert all values to their state prior to the batch edit.

Batch Edit Preferences

Batch Edit offers two preferences at the data set level:

Use only visible fields for match (default: true)

You only need some fields to match an existing record. For example, if matching catalogers by first and last name, you can match just those fields instead of all agent fields.

When checked, only the fields in the data set are used for matching. If unchecked, every field must be in the data set to match to another record.

Use only visible fields for empty record check (default: false)

This setting controls deletion logic. If unchecked, all fields must be mapped to delete a record. If checked, you can delete records by mapping only the fields you want to remove.


User Preferences

At the bottom of User Preferences there is a Batch Edit tab containing three options:

Number of records selected from the query

Default is 5000 but can be adjusted to any number (larger data sets take longer to validate and commit).

Enable relationships (default: true)

Allows batch editing of relationships to the base table; Roll Back will be disabled if enabled. This is a global setting applied before data set creation.

Relationships enabled:

Relationships disabled:

Show Roll Back button (default: true)

If unchecked, the Roll Back button will not be visible even if relationships are disabled.


Batch Edit for Trees

There are two main approaches to batch editing trees: using the tree as the base table or editing via a relationship. Choose based on your editing goals:

  • Tree as the Base Table: Best for updating tree-specific data (e.g., authorship).
  • Edit via a Relationship: Best for matching tree nodes and updating linked records.

Querying Trees

When creating the query to edit ranks, each rank must be mapped to “name.” If a rank is mapped to “full name,” its column will be read-only. Querying on a given rank automatically includes all lower ranks in the data set. If any lower rank is missing, a dialog will list missing ranks or allow you to add them manually.

  • Higher ranks need not be added.
  • For better column order, add all needed ranks before launching Batch Edit.

Multiple Taxon Trees

To batch edit across multiple taxon trees:

  1. Create a query with either the Taxon table or a related table (e.g., Collection Object, Determinations) as the base.
  2. Select the ranks you want. If multiple trees share ranks, include those; if no overlaps, include at least one rank per tree.
  3. Click Batch Edit.
    • If all ranks are mapped, the data set includes all trees and ranks.
    • If any rank is missing, a dialog will show missing ranks per tree and let you select which trees to include. If you continue without selecting, all trees will be added.

For more detailed guidance, refer to the WorkBench and Query Builder documentation links above.
To perform a roll back:

  1. Query the updated records.
  2. Return to the Batch Edit data set and click Roll Back.
  3. Confirm to revert all values to their state prior to the batch edit.

Batch Edit Preferences

Batch Edit offers two preferences at the data set level:

Use only visible fields for match (default: true)

You only need some fields to match an existing record. For example, if matching catalogers by first and last name, you can match just those fields instead of all agent fields.

When checked, only the fields in the data set are used for matching. If unchecked, every field must be in the data set to match to another record.

Use only visible fields for empty record check (default: false)

This setting controls deletion logic. If unchecked, all fields must be mapped to delete a record. If checked, you can delete records by mapping only the fields you want to remove.


User Preferences

At the bottom of User Preferences there is a Batch Edit tab containing three options:

Number of records selected from the query

Default is 5000 but can be adjusted to any number (larger data sets take longer to validate and commit).

Enable relationships (default: true)

Allows batch editing of relationships to the base table; rollback will be disabled if enabled. This is a global setting applied before data set creation.

Relationships enabled:

Relationships disabled:

Show rollback button (default: true)

If unchecked, the Roll Back button will not be visible even if relationships are disabled.


Batch Edit for Trees

There are two main approaches to batch editing trees: using the tree as the base table or editing via a relationship. Choose based on your editing goals:

  • Tree as the Base Table: Best for updating tree-specific data (e.g., authorship).
  • Edit via a Relationship: Best for matching tree nodes and updating linked records.

Querying Trees

When creating the query to edit ranks, each rank must be mapped to “name.” If a rank is mapped to “full name,” its column will be read-only. Querying on a given rank automatically includes all lower ranks in the data set. If any lower rank is missing, a dialog will list missing ranks or allow you to add them manually.

  • Higher ranks need not be added.
  • For better column order, add all needed ranks before launching Batch Edit.

Multiple Taxon Trees

To batch edit across multiple taxon trees:

  1. Create a query with either the Taxon table or a related table (e.g., Collection Object, Determinations) as the base.
  2. Select the ranks you want. If multiple trees share ranks, include those; if no overlaps, include at least one rank per tree.
  3. Click ‎ Batch Edit‎ .
    • If all ranks are mapped, the data set includes all trees and ranks.
    • If any rank is missing, a dialog will show missing ranks per tree and let you select which trees to include. If you continue without selecting, all trees will be added.

For more detailed guidance, refer to the WorkBench and Query Builder documentation links above.

2 Likes

Question for the roll back feature – is it limited in the same way that roll backs of workbench uploads are (i.e., that rollback cannot be done after a record in the set has been edited?)

Hi @nfshoobs,

As you mentioned, there are some cases (such as when you add a new Determination to a Collection Object uploaded through the WorkBench) that prevent a roll back after uploading data in the WorkBench.

Our developers do not anticipate anything that would prevent a roll back as of the latest version of Specify due to Batch Edit supporting only simple fields at this time. In future releases, we expect the limitations to be largely the same as the WorkBench as they are built on the same foundation, so edits can prevent roll backs from taking place.

Note that roll back is considered experimental for Batch Edit, so we strongly recommend performing a complete database backup before making any changes with this tool.

1 Like