This guide briefly explains the purpose of WorkBench mappings, how to import and export mapping files, and details how to copy a mapping from one data set to another.
Every WorkBench data set that has been mapped has a “mapping” (also referred to as an “upload plan”), which matches external column names from a spreadsheet to fields in Specify. This mapping is stored in JSON.
WorkBench mappings can be created and viewed using the Data Mapper interface, but they can also be copied to other data sets within Specify or exported and imported, allowing them to be shared and reused by multiple users importing documents with the same (or similar) column headings.
This guide assumes you have access to an existing WorkBench mapping that is ready to import. To learn how to create your own mapping using the Data Mapper interface, and for general information about the WorkBench, please read:
Import Mapping
1. Open WorkBench
To create a WorkBench data set and import a mapping file, click on 
WorkBench in the navigation bar.
You will see the dialog below.
If you would like to import a data spreadsheet, click Import File .
To import attachment files, click Import Attachments .
To create an empty data set, click Create New.
2. Bypass Base Table Selection
Next, you will be prompted to select a base table.
Click Close to dismiss this Select a Base Table dialog.
[!note] Note
The base table set by the mapping file you’re about to import will override the selection made in the dialog. If you do select a base table from the dialog, you will then see an Empty Data Set dialog:
Click Close to dismiss this then skip to step 4.
3. Bypass “No Data Set Mapping is Defined” Warning
The following dialog will remind you that no mapping has been defined.
Click Close.
You will then be taken to the Data Editor interface. If you chose to import a spreadsheet, you’ll see that data reflected on this page.
4. Open Mapping Import/Export Tool
In the top left corner of the Data Editor, reveal tool options by clicking Tools.
From the options shown, click Import/Export Mapping.
6. Upload Mapping File
From the Import/Export Mapping dialog, click Import to open file selection.
Find and select the .json mapping file from its location on your device. Once added, you’ll return to the Import/Export Mapping dialog where you should now see JSON in the text editor box, beginning with something like:
{
"baseTableName": "collectionobject",
"uploadable": {
Once the mapping is imported and you can see the JSON in the text box, click Save.
After importing the file, you can view and edit the mapping by navigating to the Data Mapper.
[!caution] Important
Importing a mapping to an existing data set will overwrite the data set’s current mapping while preserving the columns and data. Column headers that match the headers defined in the mapping will be mapped to the corresponding field, and columns that do not match any headers in the mapping will be unmapped. If a field in the mapping does not match any columns in the data set, a new column will be created and mapped to the corresponding field.
Copy a mapping from an existing data set
If you have an existing data set, you can copy its mapping to another data set in the same collection without exporting and importing a mapping file.
Copy to a New Data Set
To create a new data set using a mapping from an existing data set, first import a data spreadsheet or create an empty data set.
A dialog will prompt you to choose a base table. Instead of selecting a base table, click Choose Existing Mapping.
A menu will appear containing a list of your existing data sets in the current collection. Select the data set from which you want to copy the mapping.
The new mapping should then appear in the Data Mapper.
Copy to an existing data set
To copy a mapping from one existing data set into another, open a data set and navigate to the Data Mapper.
In the Data Mapper, click Base table.
A dialog will prompt you to choose a base table. Instead of selecting a base table, click Choose Existing Mapping.
A menu will appear containing a list of your existing data sets in the current collection. Select the data set from which you want to copy the mapping.
Export a mapping file
-
Open a WorkBench data set.
-
In the top left corner of the Data Editor, click Tools.
-
From the options that appear, click Import/Export Mapping.
- From the Import/Export Mapping dialog, click Export. The
.jsonfile will download automatically.