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]
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
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
Notifications
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).