Locality Update Tool

Update Locality Tool

The Update Locality Tool allows users to batch update fields relating to georeferencing on locality records by using a delimiter-separated (like the csv format) file.

This feature is extraordinarily helpful if georeferencing for existing records in Specify takes place through an external georeferencing source (such as with CoGe, MaNIS, HerpNet, FishNet, ORNIS, or some other source) and the data is to be brought back into Specify.

The tool is visible and usable to Specify 7 Administrators.

Before Using the Tool

The Locality Update Tool utilizes any delimiter-separated file format (CSV, TSV, PSV) containing the desired georeferenced locality data.

The column headers of the file must match the database names of the fields in Specify (case-insensitive).

Required Columns

  • GUID

The file must contain a column which represents the globally unique identifier (guid) of the Locality records within Specify. The Locality Update tool will use the GUID to identify and match the record in Specify.

Updatable Locality Fields

  • Datum
  • Latitude1
  • Longitude1

If the Data Set file contains rows with values in any of these columns, the matched Locality record in Specify will have its corresponding values in the field replaced with the values in the Data Set file.

The Locality Update tool will only overwrite the values in these fields if there is a corresponding value in the column of the Data Set. Otherwise, the field will remain untouched and retain its previous value.

Usable GeoCoordDetail Fields

Any non-relationship field on the GeoCoordDetail table can be used. These fields are listed below

  • ErrorPolygon
  • GeoRefAccuracy
  • GeoRefAccuracyUnits
  • GeoRefCompiledDate
  • GeoRefDetDate
  • GeoRefDetRef
  • GeoRefRemarks
  • GeoRefVerificationStatus
  • Integer[1-5]
  • MaxUncertaintyEst
  • MaxUncertaintyEstUnit
  • NamedPlaceExtent
  • NoGeoRefBecause
  • Number[1-5]
  • OriginalCoordSystem
  • Protocol
  • Source
  • Text[1-5]
  • TimestampCreated
  • TimestampModified
  • UncertaintyPolygon
  • Validation
  • Version
  • YesNo[1-5]

:warning: If a row in the the Data Set file contains any non-empty values for these fields, any previously existing GeoCoordDetail record associated with the Locality will be deleted and a new one created with the values in the columns (fields) in the Data Set

Create a backup or export of the GeoCoordDetail records if there are values in GeoCoordDetail records which should be kept and will be removed through use of the Locality Update Tool

If there are no values in a row for columns which represent a Usable GeoCoordDetail Field, the Locality Update Tool will leave the GeoCoordDetail associated with the Locality untouched.

Unknown/Unrecognized Columns

Any other columns besides the ones specified in Required Columns, Updatable Locality Fields, and Usable GeoCoordDetail Fields will be ignored.

Using the Locality Update Tool

The Locality Update Tool is accessible to Specify 7 Administrators in the User Tools Menu

A file can then be selected using the interface, and a preview of the file will be displayed along with the options to change the character encoding used to parse the file and the delimiter of the file.

The following table represents our externally georeferenced data processed in a format which the Locality Update Tool accepts ( the Locality_Update_Data_Set.csv as pictured above)

Example Data Set

LocalityName GUID Latitude1 Longitude1 Datum Source georefdetdate maxuncertaintyest maxuncertaintyestunit
Test Locality bf337172-c60f-4ea2-b79b-338bacb7d498 38.971583 -95.162442 WGS84 SomeExternalSource 06/19/2024 103 m
Cedar Bluff Reservoir 6a6bfdee-15a7-42c9-ad0a-1c74549d0d98 38.787023 -99.733689 WGS84
Near Oaxaca 72fc97f4-2926-4f35-aad3-0306b382483c 17.04327 -96.67932 WGS84 52 m

Upon clicking the Import File button, a warning dialog is displayed if there are any unknown or unrecognized columns.
In this example, LocalityName is an unrecognized column.

Parsing the Data Set

Upon proceeding with the Update (or if the Data Set does not contain any invalid columns), the Data Set will be checked for errors and the total progress of the process will be shown as a Progress Bar.

If all of the values in the Data Set conform to values acceptable by Specify, a dialog will appear stating how many Locality records were identified and matched, as well as how many GeoCoordDetail records will be deleted and subsequently created.

Otherwise if there are values in the Data Set which do not conform to the database schema, a dialog will be shown which contains information regarding the errors. For each error, the row number in the Data Set is provided, as well as the associated Field/Column and an Error Message which can be used to diagnose and fix the error

The parsing failure results is available to download as a CSV containing the same information as the dialog.

Performing the Update

Once the Data Set has been successfully parsed, the Import button can be pressed to initiate the Update Process.

Once the Update process completes, a Record Set will be automatically created containing the Locality records which were matched from the Data Set.

If an error occurs at any point during the Locality Update process, a dialog will be shown indicating the status and allowing an Error Message to be downloaded

:bulb: The Locality Update Tool utilizes an ATOMIC SQL transaction and will only ever change records in the database if the process succeeds completely. Any changes will be ignored and rollbacked if an error occurs or the process is cancelled


The status and state of the Locality Update processes can be reviewed via Notifications sent to the User which initiated the process.

The Notifications are a way to view (or review) the outcome and results of the Locality Update process (at any step in the process).

The below video demonstrates using the Notification system to review the results of a Locality Update task which had Parsing-related errors.

Similar interactive notifications are sent for when the process Fails (which enables downloading the crash report), and when the Locality Update succeeds (which enables viewing the automatically created Record Set or if the Record Set is deleted, viewing the matched Locality records via forms from which a new Record Set can be created).