Welcome to the Specify WorkBench!
Get started by clicking WorkBench 
in the navigation bar.
The WorkBench offers the following features:
-
You can import data from CSV, TSV, TXT, XLS, and XLSX files
-
Create, view, and edit data in a grid view
-
Visualize georeferenced object information in GEOLocate and GeoMap
-
Convert geocoordinates into different formats
-
Export and reimport data sets while retaining the mapping
When clicking on the WorkBench in the navigation menu, you are offered three options:
You can import existing data in compatible formats, create a new mapping and base table and manually enter data, or close the window.
Useful Links
GitHub: Technical breakdown of the WorkBench
Webinar: WorkBench in Specify 7
Note: Dates uploaded using the WorkBench will need to conform to the date format specified in the Remote Preferences file.
Learn more here: Configure Database Date Format
Adding a Data Set
Import file
You can import data from CSV, TSV, TXT, XLS, and XLSX files.
You can get one of these filetypes from your system’s file browser or drag it into Specify.
You will see a preview of your Data Set, along with the option to name the Data Set so you can access it later from Record Sets. Click Import file if everything looks correct.
If this is your first time uploading this file you will have to define an upload plan. Click Create.
You will then be asked to select a base table or choose an existing plan.
If you have uploaded/created data sets in the workbench before then you can select Choose Existing Plan which will give a list of the data sets the user has and it will match those exact mappings.
If you do not have any existing data sets or want to make a new plan then you will select a base table. For this example, I am going to choose Collecting Event as I want to use the Field Number as the primary association in this import.
The WorkBench will read the existing column headings in a Data Set and map them to Specify fields using the ‘Automapper’.
In this example, the Automapper automatically associated many of the imported document’s columns with its field in Specify. The first column is automatically selected, identified by the gray background.
You must match each column with the correct field within Specify. You can use the Map Explorer ribbon at the top of the WorkBench interface or the drop-down menus in each column’s row.
Create New
When creating a new Data Set, first you will be prompted to select a base table. This is the table you will build the Data Set on including all tables within it.
Once you select your base table you will be greeted by an Empty Data Set dialog.
After closing the dialog, click “Add New Column” in the bottom left-hand corner multiple times to add the desired number of columns.
The active/selected column will have a gray background. You can use the Map Explorer or the drop-down menus to assign each column a field.
For example, here is a very simple mapping. Columns 1 and 2 use fields from the Collection Object table, Column 3 uses a field from the Accession table, and Columns 4 and 5 use fields from the Agent table.
Now you can press Validate to ensure the mapping is complete. Press Save and you will be presented with the grid editing view.
WorkBench Mapper Guide
Here are the basic buttons in the WorkBench mapper:
| Button | Description |
|---|---|
 |
Changes the underlying base table. Doing this will undo any previous mappings |
 |
Clears all mappings |
 |
Uses the Automapper to assign column headers a field in Specify. |
 |
Hides the map explorer section of the WorkBench. |
 |
Opens a window allowing you to select which table’s data must match existing records. |
  |
Validates the upload plan to ensure no missing mappings or data fields required by your configuration are unfinished. Turns green when clicked on once the data is ready to be saved. |
 |
Cancels the import or new mapping creation. |
 |
Saves the data set. |
 |
Adds a new column to the Data Set. |
 |
If selected, you will be able to map columns to hidden fields in your Specify configuration’s schema. These will not appear on your forms unless modified. |
A column is selected when it has a gray background behind it.
The gear icon to the right of the column allows you to modify its matching behavior.
The button on the far left of the column mapping will clear the column’s mapping.
A column’s mapping can be selected with either the drop-down menu in each column or the map explorer at the top of the WorkBench.
When selected, the AutoMapper will automatically recommend a particular mapping based on the field name and spreadsheet column heading.
Mapping Options
Map Explorer
The Map Explorer allows you to visualize the process of mapping each column in a data set.
The fields presented under each table that have no icon to their left are children of their parent table that appears at the top.
When you see an icon such as 
to the left of a field, it means that it is a table. Upon clicking on that item, you will see another list appear allowing you to either choose a field from it or go into another sub-table.
Once you have reached the final field you wish to map, you can double-click on the item to map it or click on Map and move on to the next column.
Drop-down Menu Mapping
In addition to the Map Explorer, you can map items with the drop-down menus in each column’s row. This works the same as the Map explorer, except it does not preserve the field navigation. You will have to go through all the sub-tables and fields to find the field you wish to map.
The drop-down menu will show you the Automapper’s suggestions for your column’s mapping. You can click on a suggestion to have it autocomplete the mapping.
The Automapper suggest mapping the Locality Name column to its correct location.
Sometimes there will be multiple suggested mappings and you will have to choose which is the correct one or if none of them are correct then you’ll have to map it yourself.
The Map Explorer at the top will also follow along with the selections made in the drop-down menus.
Matching Behavior
The mapping options allow you to chose on a field basis if a cell needs to match a record that already exists in the database or if a new record can be created within that field.
Ignore when Blank
This is the default matching behavior for a given column. This means that blank values are considered “null”. This means no value in the cell indicates to the WorkBench that it can be ignored for matching purposes when looking for existing records, but if any value is present, it will not be ignored.
Always Ignore
You can set a column to “Always Ignore” so that the value is never be considered for matching purposes, only for uploading.
If the “Author” value differs slightly from an existing Taxon record in your database but matches other mapped fields like “Name,” it won’t stop it from matching existing records during the WorkBench upload. This helps avoid unnecessary duplication!
When importing new taxonomy data or collection object records, it’s advisable to skip non-essential matching fields with potentially slightly different non-essential data (think Taxon authors or common names) to prevent duplication.
Never Ignore
This will force the WorkBench to never ignore the value of the field, so even if it is blank, it will require that records matched to it also have a blank value in that column.
Allow Null Values
This checkbox allows you to configure whether empty values are considered “errors” or not when validating. If unchecked, all empty cells in this column will be considered errors after validation completes.
Use Default Value
You can establish a default value for all entries in a column if no conflicting value exists in the imported spreadsheet or data set entered by the user.
WorkBench Grid Editing
Grid editing enables Data Sets to be modified like a spreadsheet. It is not intended to be a replacement for traditional spreadsheet applications (Microsoft Excel, Apple Numbers, or Google Sheets). Grid editing provides many specialized tools that are specific to collections management data.
Navigating the Grid
You can interact with any cell, column, or row by selecting it. You can navigate the grid with your mouse or use keyboard navigation with the arrow keys.
The entire WorkBench is navigable with only a keyboard. You can use documentation from Handsontable to learn about the specifics of keyboard navigation in Specify.
Learn more here: Keyboard shortcuts - JavaScript Data Grid | Handsontable
Modifying the Grid
By clicking and dragging on a column header, you can rearrange the table’s column order in seconds.
Resize Columns
Place your mouse between two column headers. You can drag and resize the width of each column.
Rearrange Columns
Click and hold on a column header, then begin to drag it to another part in the grid. A shadow will begin following your cursor representing the column moving to a new location. When hovering between two columns, a thick line will appear. This is where the column will drop once you release the click.
Sort Columns by Ascending and Descending
You can click on the column header text once to sort the grid ascending, twice to sort descending, and three times to reset it to neutral sorting.
Click once to sort in ascending order
Click twice to sort in descending order
Click three times to return to the default neutral sorting
You can set the sorting priority of multiple columns by pressing Alt while selecting the column headers. A number (such as 
) will appear on the right of the column header showing the order of sorting operation.
Select Entire Rows or Columns
To select an entire row, just click on the row number.
To select an entire column, click on the column header.
To select multiple columns, click on the first column head and click while pressing Ctrl on the other columns. Press Shift to select subsequent in-between columns all at once.
Modify Cells
Auto-incrementing formatters
In order to automatically create new catalog numbers (or new values in other auto-incremented fields) you need to insert the format for the field into the cell.
For example, if your catalog number is formatted as a 9-digit number you need to insert
#########
If you are using one of these example formatters, you would enter the following in the cell:
Formatter Cell Value AccessionNumber 2023-AA-### AccessionNumberByYear 2023-AA-AAA AccessionStringFormatter AAAAAAAAAA CatalogNumber 2023-###### CatalogNumberAlphaNumByYear 2023-###### CatalogNumberNumeric ######### DeaccessionNumber 2023-AA-### GiftNumber 2023-### InfoRequestNumber 2023-### LoanNumber 2023-### NumericBigDecimal ############### NumericByte ### NumericDouble ########## NumericFloat ########## NumericInteger ########## NumericLong ########## NumericShort #####
Editing Cell Values
To begin editing a cell, you just need to click it or select it with your keyboard and begin typing.
Pick Lists
Cells that are mapped to fields formatted as pick lists are available as pick lists in the WorkBench.
While you can enter text into the field, it will only be valid if new pick list items can be added. Click on the 
symbol to expand the drop-down menu.
Cell Context Menus
When you right-click on a neutral cell, you will be presented with several options.
| Name | Description |
|---|---|
| Insert row above | Inserts a row above the selected cell. |
| Insert row below | Inserts a row below the selected cell. |
| Remove row | Removes the entire row containing the selected cell. |
| Disambiguate | Allows you to solve ambiguity errors that result when new data has identical records matching information already in the database. |
| Fill down | Takes the top row of selected cells and fills it down the grid. |
| Fill up | Takes the bottom row of selected cells and fills it up the grid. |
| Undo | Undoes the previous modification. |
| Redo | Redoes the previously undid modification. |
Error Cell Behavior
After a data set has been validated there might be some errors.
In most cases, error cells will notify you with a potential solution or explanation for why there is an error. A tooltip will appear when hovering over an errored cell.
In some cases, you will have to manually edit to solve the error (for example, you must choose a value that matches the numeric formatter).
Another error is ambiguity errors related to duplications in the database. When a disambiguation error appears, you can right-click and disambiguate the value to solve the issue.
Now you can choose if you want this correction to apply to all matching cells or only the first selected one.
New Cell Behavior
After uploading the Data Set into the database, the new cell’s right-click context menu will link to the record that was created from the cell.
WorkBench Grid Editing Guide
| Button Name | Description | Requirements |
|---|---|---|
| Meta Data | Displays the metadata including the name, remarks, number of rows, columns, date created, date modified, whether it has been uploaded or not, and who created it. | None |
| Tools | Expands a hidden menu that includes the following 6 buttons | None |
| Change Owner | Change the data set owner to another user. This is especially useful for users who can import and validate data sets but need to send it to admin user who can upload it. | Transfer permission |
| Upload Plan | Provides a .json file of the workbench mappings. | None |
| Export | Export the Data Set as a CSV file. | None |
| Convert Coordinates | Opens Latitude/Longitude converter. | Latitude1, Longitude1 |
| GEOLocate | Open GEOLocate. | Latitude1, Longitude1 |
| GeoMap | Open GEOMap. | Latitude1, Longitude1 |
| Data Mapper | Return to the data mapping interface to add or modify columns. | None |
| Validate | Validates the Data Set to ensure no errors have been introduced. After clicking it will start to validate and once it is done there will be one of two dialogs either: completed with errors or completed with no errors | Validate Permission |
| Results | Shows the number of potential new records that would be created in each table. After the data set has been uploaded, at the bottom there is a Create Record Set button | None |
| Create Record Set | This will create a record set with all the records from the data set. | Create Record Set Permission |
| Upload | Uploads the Data Set into your database. After the data is uploaded into the database, you can right-click on any blue cell to open the newly created record. | Upload Permission |
| Roll Back | After uploading you can undo (or roll back) the Data Set upload in the database. | This only works if no changes have been made to any of the uploaded records. |
| Revert | Undo the most recent modification. | Revert Permssion |
| Save | Save all changes. | Update Permission |
WorkBench Grid Navigation Tools
The WorkBench features several navigators to make modifying and understanding your Data Set simple.
Search Results Navigator
The text you enter in the Search text box will be queried on the Data Set. This can be used either as a regular search funtion or to replace what was searched with something else. Click on the 
icon and you can configure:
| Options | Description |
|---|---|
| Cursor Priority | When navigating the search results: column first means that it will move up/down the column and then move to the next row whereas row first means it will move across the row before moving up/down the columns. |
| Find entire cells only | If the search result needs to match the entire cell then this needs to be checked but if it can just be a part of a cell then this should be unchecked. |
| Match case | With this checked the search will be case sensitive, with it unchecked it will be case insensitive. |
| Use regular expression | Regular expression is supported when searching and when using find and replace. |
| Live search | With this checked it will search as you are typing, if it is unchecked it will only search after enter is pressed. |
| Replace mode | When using the find and replace feature: replace all matches will replace every instance of the searched term with the replaced term, replace next occurence will just replace the selected search term with the replaced term. |
Every cell that matches the entire text in the search field will be highlighted green. This behavior can be modified.
Modified Cells Navigator
Every cell you modify before saving will be highlighted yellow.
New Cells Navigator
Every cell that is new to your database before uploading will be highlighted purple.
Error Cells Navigator
Every error cell will be highlighted in red and must be modified before proceeding.
WorkBench Grid Locality Tools
| Button | Tool | Description | Column Requirements |
|---|---|---|---|
 |
GeoLocate | The WorkBench processes all the selected rows and caches the information, and then the results can be stepped through one row at a time. The appropriate Latitude/ Longitude can be selected, or skipped. | Latitude 1, Longitude 1 |
 |
GeoMap | GeoMap plots all the points in your selection on the map. It uses OpenStreetMap, ESRI, Géoportail, USGS, and NASA maps to give a multitude of viewing options. | Latitude1, Longitude1 |
 |
Latitude/Longitude Converter | The Latitude/Longitude Converter tool converts numerous georeference formats within the Latitude1 and Longitude1 columns of a Data Set into decimal degrees (DD.DDDD),degrees decimal minutes(DD MM.MM), degrees minutes seconds (DD MM SS.SS), decimal degrees with cardinal direction (DD.DDDD N/S/E/W) and degrees minutes seconds with cardinal direction (DD MM SS.SS N/S/E/W). | Latitude1, Longitude1. Lat1text and Long1text can be added to preserve a copy of the original Lat1 and Long1 values. |
Each of these tools can be scoped to a specific row and the convert coordinates and GeoMap tools can be scoped to multiple rows at once.
GEOLocate
The GEOLocate project has created software and services for translating textual locality descriptions associated with biodiversity collections data into geographic coordinates. It uses a description of a Locality and geography fields, such as County, State and Country, to find Latitude and Longitude coordinate values. This is referred to as georeferencing. The Specify and GEOLocate teams have collaborated to create a GEOLocate module inside Specify.
GEOLocate will show you any possible locations it can find based on the information in your columns. You can zoom, scroll, and navigate the GEOLocate web application within Specify. You can edit the uncertainty, add pins, and draw polygons.
You can view and modify the locality, country, state, and county from the GEOLocate window. Click 
to search the modified query.
GEOLocate Definitions
- Position represents the Latitude and Longitude of the GEOLocate result, visually depicted on the map as a green marker. These results can be edited.
- Markers represents the Latitude and Longitude of a GEOLocate point, visually depicted on the map as a red marker. These will be become a green marker if it is the selected position.
- Uncertainty Radius represents the error due to the uncertainty of the locality information provided. It is shown as a grey circle around the green point marker on the map. The Uncertainty Radius can also be edited.
- Latitude represents the latitude to the hundredth degree.
- Longitude represents the longitude to the hundredth degree.
- Pattern, or pattern identifier, is a text description of the pattern or keyword used to determine a GEOLocate result. Single locality strings often include multiple patterns, producing multiple GEOLocate results.
- Precision is an indication of the quality of locality information. Each GEOLocate result is given a score between 0 and 100 which represents the probability of it being a match. That score is then placed within a ‘low’, ‘medium’ and ‘high’ ranking to indicate precision. Results are then ordered according to their probability number, which allows results within the same rank to include the most accurate matches first.
- Error Polygon is a polygon which encompasses the entire area of uncertainty.
- Uncertainty represents the error due to the uncertainty of the locality information provided.
Placing a marker will change your point’s latitude and longitude and move the uncertainty radius around with it.
Measuring allows you to click anywhere on the map, move your mouse to measure a distance, and double click to finish the measurement. It will display in kilometers and miles.
This text box shows the Lat1, Long1, Uncertainty radius in meters, and the coordinates of your polygon’s points.
Draw a polygon by clicking on map for each point in your polygon. Once you are finished creating it, double click the mouse. You can clear your polygon by pressing the Clear Polygon button to draw a new one.
You can save the information created on GEOLocate to Specify if you have the correct columns in your Data Set. The information will be fed directly to the WorkBench once you click the 
button at the bottom of the window.
Under the Workbench tab in GEOLocate’s interface, you can click 
to configure the georeferencing options.
• Match Water Body - When enabled, GEOLocate will search the locality string for bridge crossing information and attempt to pinpoint the locality at the intersection of the river and highway. This feature only works for U.S. localities and requires county data.
• Detect Hwy/River Crossing - When enabled, GEOLocate will search the locality string for the names of rivers and streams. If one is found, GEOLocate will snap the calculated points to the nearest point on the waterbody. This feature only works for U.S. localities and requires county data.
• Do Uncertainty - When enabled GEOLocate will calculate and return the uncertainty radius if one exists.
• Do Error Polygon - When enabled GEOLocate will calculate and return the error polygon.
• Displace Polygon - When enabled GEOLocate will use any distance value referred to in the Locality Description to displace the GEOLocate Error Polygon value (if one exists). If 10 miles North of Lawrence is in the Locality Description, but the Error Polygon in GEOLocate is a 30-mile radius around the center of Lawrence, GEOLocate will move the 30-mile radius 10 miles North of the center of Lawrence.
• Restrict to Lowest Adm. Unit - When enabled limits results found by GEOLocate to points within the lowest administrative unit in the locality description.
• Language - Tells GEOLocate what language to use for the Locality interpretation.
Specify uses the embedded client from GEOLocate. For more documentation, visit their website https://www.geo-locate.org/.
All Specify interactions are managed by the Specify Software.
GeoMap
GeoMap plots all the points in your selection on the map. It uses OpenStreetMap, ESRI, Géoportail, USGS, and NASA maps to give a multitude of viewing options.
| Icon | Use |
|---|---|
 |
Toggle the full screen view |
 |
Zoom in and out on the map |
 |
Change the map type as well as enable or disable labels, boundaries, pins, polygons, polygon boundaries, and error radiuses |
 |
Click to view all details about the pin |
 |
When full screen view is enabled, this allows the user to print the current map view, including pin details if activated |
Google Earth
In Specify 7, the Google Earth functionality has been moved to the Query builder.
See Query Builder for more information