The Specify 7 WorkBench

Welcome to the 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
  • Link images to existing records
  • 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

For a more technical breakdown of the WorkBench and its functions, see the write up on our Github wiki.

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.

WorkBench Mapper Guide

Here are the functions in the WorkBench editor:

Changes the underlying base table

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 X icon to the left of the column will clear its 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.

The column will suggest which mapping it believes is best above the drop-down mapping tool.

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 have no icon to their left as they 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.

The Map Explorer will follow along with the selections made in the drop-down menus.

Import file

You can import data from CSV, TSV, TXT, XLS, and XLSX files.

You can 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 be asked to select a base table. For this example, I am going to choose Collection Object as I want to use the Catalog 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 ‘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.

You will only see fields that are unhidden in your Specify schema configuration, so make sure that every column you are importing is able to be mapped.

You can toggle the ‘Reveal Hidden Form Fields’ checkbox next to the Add New Column button to reveal most hidden fields. Data mapped to these hidden fields will not appear in Specify unless unhidden in the schema.

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.

Once you close the dialog, click Add New Column in the bottom left-hand corner as many times as you want 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,2,4, and 5 use fields from the Collection Object table while Column 3 uses a field within the Determinations table.

Now you can press Validate to ensure the mapping is complete. Press Save and you will be presented with the grid editing view.

Whenever data is added to the last empty row, another row will be added. This allows users to enter a large amount of data at once.

If you wish to modify your new grid, you can return to the mapping view by clicking Data Mapper.

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 - Guide - Handsontable Documentation

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.

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 row 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.

Using Tools

You can click on to open the WorkBench toolset including GEOMap, GEOLocate, and Coordinate Convertor. You can learn in-depth about each programs features later in this document.

When using these tools, only the selected rows will be pulled into the programs.

When you click on a pin in GEOMap, it will highlight the relevant rows on the grid.

Modify Cells

Cell Context Menus

When you right-click on a neutral cell, you will be presented with several options.

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. You can tell Specify that the new data is the same as the existing information or choose to create a new distinct record.

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

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.

Error Cell Behavior

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

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.

|300.7855157852173x81

|302x169.3673847913742

|270x343.649662733078

WorkBench Grid Editing Guide

Displays the metadata including the name, remarks, number of rows, columns, date created, date modified, who created it, and the import file name.

Expands a hidden menu that includes the following:

Change the data set owner to another user

Export the Data Set as a CSV file

Delete the Data Set permanently, along with its upload plan

The following tools are explained in greater detail in upcoming pages

Opens Latitude/Longitude converter

Open GEOLocate

Open GEOMap

Return to the data mapping interface to add or modify columns

Validates the Data Set to ensure no errors have been introduced. The button turns green when clicked on once the data is clear to be uploaded to the database

Shows the number of potential new records that would be created in each table

After the data is uploaded into the database, you can right-click on any blue cell to open the newly created record.

Upload the Data Set into your database

This option only appears after it has been uploaded successfully

Undo the Data Set upload to the database

If data has been modified, these will appear as interactable.

Undo the most recent modification

Save all changes

WorkBench Grid Editing Navigation Tools

The WorkBench features several navigators to make modifying and understanding your Data Set simple.

Search and Replace & Search Results Navigator

The text you enter in the Search text box will be queried on the Data Set. Click on the icon and you can configure the cursor priority, search options (match case, find entire cells, live search, use regular expression) and the replace options (all matches or next occurrence).

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 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.
Create KML for Google Earth This feature is only available in the query builder. Create a locality query and create a KML file after you run your search. This can be imported into Google Earth, which will plot your locality using a pushpin icon. Latitude1, Longitude1

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.

For Georeferencing United States localities:

Column Data Needed
Locality Name Yes
Country Yes
State Yes
County No, but will improve results(Required when searching waterbody and highway crossings)
Latitude1 No (this is the results column)
Longitude1 No (this is the results column)

For Georeferencing localities outside of the United States:

Column Data Needed
Locality Name Yes
Country Yes
Child Node of Country No, but will improve results
Latitude1 No (this is the results column)
Longitude1 No (this is the results column)

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.

Placing a marker will change your point’s latitude and longitude and move the uncertainty radius around with it.

The green selected marker is the value for the most accurate result. This will be saved when you save this to your application.

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 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.

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.

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.

Create a new Locality query, including all the information you wish to export to Google Earth. Once you have the query pulling your desired results, click Create KML.

Your notifications menu will change to orange. Click on it and you will see a query export completed message. Press Download and now you can upload your KML into Google Earth.

|624x190.32600164413452

Yellow pins will appear at the locality coordinates. You can click on them to recall associated information and each pin links back to the Specify 7 locality.