Standardize data capture with structured tables

Structured tables in Benchling Notebook entries enable teams to capture, analyze, and manage experimental data in a consistent and traceable manner. These tables support various scientific workflows, including entity registration, inventory management, result recording, and more all centralized in the Notebook.

Structured tables in Entries

Structured tables can be added to Notebook entries to facilitate various data management tasks and connect your Notebook to the rest of your Benchling applications.

Benchling supports several types of structured tables, each designed for a specific use case:

• Registration tables: allow you to Register new or existing entities
  • Mixture prep tables: a specific type of Registration table that helps you prepare and register complex mixtures such as media, buffers, etc.
• Inventory tables: allow you to track and record container creation, sample transfers, container fills and updates
• Results tables: allow you to capture experimental or assay results and submit them directly to Benchling's Results infrastructure
• Lookup tables: allow you to surface contextual reference data from other structured tables or linked entities

These table types enable seamless integration between the Notebook and other Benchling applications like Registry, Inventory, and Results, allowing you to enter data once and keep it consistent and traceable across your workspace.

About adding structured tables

1. Open a Notebook entry
2. Click on Insert in the formatting panel
3. Select the desired table type (e.g., Results table, Inventory table, Registration table) from the menu
4. Fill out the table attributes so the table supports the actions you wish to take and click Insert

About using structured tables

Each row in a structured table corresponds to one Benchling object and the columns are defined by both the table type and the fields configured on the table by an admin. 

1. Add entities or containers to the table
   1. Individually – use the Add rows textbox to define how many new rows you’d like to add to the table, then click Add rows to take the action
   2. In bulk – click the + icon at the top of the table, then choose what source you’d like to use to add to the table from (structured table, worklist, spreadsheet)
2. Fill out each row with the information required by the schema
3. Use the gear icon to open a modal to adjust name and registry ID settings and folders if needed before submitting the table
4. Resolve any errors that are flagged in the table, errors may include:
   1. Illegal/required value – Benchling will flag cells and rows with illegal or required values that are not filled out correctly with a red notification
   2. Un-submitted change – Benchling will flag rows with un-submitted additions or modifications with a blue notification
5. Click Submit 

Note: Table limits are 1,000 rows and 255 columns. 

An organization admin can enable the ability to view a summary of table sizes in an entry which will provide a sortable count of the rows and columns for plain and structured tables. 

This summary table will show warnings when the total number of cells exceeds 17,500 and 35,000. Though you will not be blocked from exceeding these cell limits, Benchling will not be able to assist with performance issues beyond this scale.  

In PDF exports, tables exceeding 500 rows will be exported as attached CSV files. In the exported entry, they will display as collapsed tables with the CSV file name visible. 

Actions in structured tables 

Once you’ve submitted a structured table, there are additional icons that become available to you: 

• Re-sync dropdown
  • Refresh lookup columns – all lookup values will be recomputed, this is the only part of the table that will update
  • Re-sync table – all values in the table will update to reflect any values updated outside of the table
• Request dropdown
  • Select the Request template that you would like to create and map a source column from the table to the template. You will then proceed to follow the process for creating a new Request, for more information  on how to do this, see the linked article
• Workflow dropdown
  • Select the Workflow schema that you would like to create and map a source column from the table to the template. You will then proceed to follow the process for creating a new Workflow, for more information on how to do this, see the linked article
• Add items to Worklist dropdown
  • Select the name of the column that you want to add to the Worklist. You will then proceed to follow the process for adding items to a Worklist, for more information on how to do this, see the linked article
• Archive
  • Select the items that you want to archive, provide a reason and Registry action. For more information on archiving, see the linked article
• Add to analysis dropdown
  • Add to new analysis – fill out the attributes for your new Analysis, for more information on creating and using Analysis, see the linked article
  • Add to existing analysis – use the search bar to find the Analysis that you’d like to add a new table to and update the name of the Analysis table if necessary

The sections below provide more information about each type of structured table. 

Create, update, and register entities with Registration tables

Registration tables provide a structured way to register new entities or register existing ones in a Notebook entry. For more about how to use the Registry, see the linked article. 

Insert a Registration table

1. Click on Insert and select Registration table from the menu
2. Define the action the Registration table will take, choose between:
   • Create new entities
   • Register existing entities
3. Use the Schema dropdown and search bar to select the Registry schema
4. Use the name and registry ID settings dropdown to choose the settings you want the table to apply
5. Define the folder location that created items will be associated with, choose between:
   • Entry’s project folder – items will be associated with the folder that the Entry is in
   • None – items will only be associated with the Registry, not a specific folder
   • Choose a folder – select an existing folder that you want items to be associated with
6. Use the preview to verify the table that you are inserting is what you want to use
7. Click Insert

Register entities

1. Enter information into the rows of the Registration table
   • Add rows using the Add rows button at the bottom of the table
   • Use the + icon to add from a structured table, worklist, or spreadsheet
2. Click Submit to add entities to the Registry

Entities added to a table via structured tables, worklists, or spreadsheets are added to the first empty cell in the destination column. Entities added to different columns will fill the same rows, if those cells don’t yet have values. 

Note: when importing entities in bulk, the order they are created may not follow the order of your spreadsheet. This is due to Benchling’s performance optimizations that may parallelize the creation process. For consistent naming, consider asking your admin to use a naming template with renaming options upon Registration.

Modifications can be made after registration by updating fields and re-submitting. You can both register new entities (in new rows) and update entities (in existing rows) at the same time.

Mixture prep tables

Mixture prep tables allow you to create mixture preparations directly in your Notebook entry. In order to insert a mixture prep table, your local admin needs to configure a mixture schema type that allows measured ingredients and has a parent link mixture field. 

Insert a mixture prep table

1. Click on Insert and select Mixture prep table from the menu
2. Use the Schema dropdown and search bar to select the mixture schema
3. Use the name and registry ID settings dropdown to choose the settings you want the table to apply
4. Click Insert

Register a mixture prep

1. Use the textbox to enter the name of the mixture in the Entity Name field
2. Use the Main Component search box to search for the Entity that is the main component of the mixture
3. Fill out the target amount and use the dropdown to define the units for that amount
4. Add rows to add the necessary ingredients, and fill the relevant schema fields
5. Click Submit to register the mixture prep

Modifications can be made after registration by updating fields and re-submitting. 

Create and update Inventory objects with Inventory tables

Inventory tables provide a structured way to create and fill new containers, fill existing containers or plates, and update container or plate well attributes in a Notebook entry. Each Inventory table can only transfer into or update a single specified container schema. 

For more about how to use the Inventory, see the linked article. 

Add an Inventory table

1. Click on Insert and select Inventory table from the menu
2. Specify the desired action:
   • Create and fill new containers
   • Fill existing containers
   • Update container or plate well attributes
3. Use the source dropdown to define if the source is an entity, container, or plate
4. Use the destination dropdown to define the destination object
5. Use the schema dropdown and search bar to select the inventory schema
6. Certain schema types will also ask you to provide additional information by toggling features on and off including
   • If you’d like to use custom or autogenerated barcodes
   • If you’d like to enable sample control roles
7. Click Insert

Each action that an Inventory table can take has specific columns, these columns are listed for each action in the lists below. 

Creating/filling containers

• Source container (if the sample is being taken from another container)
• Source entity
• Destination location, box, or plate (depending on the destination specified when inserting the table)
• Destination position (location of the new container within a box or plate)
• Destination container (automatically populated after clicking Transfer to fill the containers)
• Quantity
• Concentration
• Container fields specific to the selected container schema
• Restriction status (if selected)
• Restricted sample users (if selected)
• Sample owners (if selected) 

Updating container attributes

• Container
• Contents (automatically filled after you select a container)
• Location (automatically filled after you select a container)
• Position (automatically filled after you select a container)
• Quantity (automatically filled after you select a container)
• Units (automatically filled after you select a container)
• Add/Deduct by (this will change the quantity of the container)
• Concentration (automatically filled after you select the container and can update the value)
• Concentration units (automatically filled after you select the container and can update the value)
• Container fields specific to the selected container schema

Use an Inventory table

Each row of an Inventory table corresponds to a transfer or container update, and a transfer may simultaneously transfer a sample to multiple containers. 

1. Enter information into the rows of the Inventory table
   • Add rows using the Add rows button at the bottom of the table
   • Use the + icon to add from a structured table, worklist, or spreadsheet
2. Click Submit to add objects to the Inventory

Once you submit an Inventory table, the Inventory actions button allows you to take the following actions on your containers: 

• Reserve
• Check out
• Check in
• Move
• Print labels
• Archive 

Result tables

Result tables provide a structured way to capture experimental data in a Notebook entry. For more about using Results, see the linked article.  

Insert a Result table

1. Click on Insert and select Result table from the menu
2. Use the Schema dropdown and search bar to select the Result schema
3. Click Insert

Save results

1. Enter experimental data into the rows of the Result table
   • Add rows using the Add rows button at the bottom of the table
   • Use the + icon and add from a structured table, worklist, or spreadsheet
2. Click Submit to capture the data  

Submitted results will appear in the Results tab of the corresponding entity in the Registry. 

Reference and view sample information with lookup columns and tables

Lookup columns and tables are two methods you can use to reference structured data that has been captured elsewhere. Both methods allow you to view information about your sample while running an experiment, without having to leave your entry. 

Note: if your Entry has been created from a Fill-in Entry template, you will be unable to modify or add new lookup columns to ensure the data referenced is not changed. 

Add a lookup column

Lookup columns can be added to any new structured table. 

1. In your structured table, click the dropdown on the column header
2. Select one of the insert lookup column options from the menu
3. In the modal that opens, configure the lookup path by using the dropdown to specify the base column
   • Optionally specify the entity in column (if it is not already indicated)
   • Optionally add filters for any lookups if you need to constrain the result
4. Add any additional lookup steps that are needed, then click Continue
5. Select the attribute you want to populate into the lookup column. These options are based on the schema fields of the lookup object you specified
6. Once you’ve finished configuring the lookup, click Insert 

Note: you can specify a maximum of 5 lookup steps. 

Add a lookup table

Lookup tables allow you to bring in additional information about entities or containers that are not present in other structured tables and allow you to consolidate a lookup into one place. 

1. Click on Insert and select Lookup table from the menu
2. Specify if you want to lookup the Registry or Inventory
3. Use the schema dropdown and search bar to select the starting schema
4. The table will insert into the Entry, then click the column header to add lookup columns as needed

Table Mapping

Table mapping automates the flow of data between structured tables allowing you to move information from upstream structured tables into other tables without having to copy and paste.

You can use table mapping in the following structured tables: 

• Result
• Registration
• Inventory
• Box creation
• Plate creation
• Lookup
• Workflow task (source only)
• Workflow output (destination only)

Configure table mapping

Table mapping can be added to any structured table in an Entry or an Entry template. 

1. In the destination table, click the dropdown on the column header
2. Select Add table mapping from the menu
3. This will open a modal where you will need to define which source columns to pull data from
4. Use the textbox to define the number of replicates for the table mapping
5. Click Save

Note: multiple sources can be selected, however only one column per table can be mapped

After submitting the source table, designated data will appear in the destination table. Existing data in the destination table will not update if the source data is edited, but new rows added to the source will be mapped accordingly. 

Re-syncing Tables

When data in a structured table becomes outdated because it was updated outside of the table, the table will not update. Instead, both the corresponding row and the cell will be labeled with purple indicators. 

To update the values in a table:

1. Click the refresh button at the top of the table
2. From the menu, choose what parts of the table you’d like to update (lookup values only or the entire table)
3. Confirm that you want to proceed with re-syncing the table by clicking Yes, continue to finish the update

This will resync all submitted rows in your table, not just the values flagged as outdated. 

Note: Unsubmitted changes or formulas will be lost during a table re-sync. Benchling will warn you before completing the action. 

Units in tables 

Unit-aware fields allow data to be stored with associated units to enhance consistency in experimental data recording. 

Unit-aware fields are supported in structured tables like Registry, Inventory, and Result tables where quantitative data is commonly recorded. When a unit has been defined on a schema field as the default unit, and the value is entered in a different but compatible unit, the cell will offer a converted value for you to confirm. 

Frequently asked questions

Q: What is the maximum number of rows allowed in a structured table?

A: Structured tables support up to 1,000 rows 

Q: Can I modify data after submitting a structured table?

A: Yes, you can update fields and re-submit to reflect changes. 

Q: Can I edit any entity in a Registration table? 

A: You can only edit entities that were registered in the table. You cannot add an existing, registered entity to a Registration table to perform edits. If you wish to make edits to entities outside of the Registration table, do so on the entity metadata tab or through the spreadsheet import option found in the Registry application as one of the options for updating entities. 

Q: How do I add the current datetime to a Results table?

A: Click on the desired cell in the Results table and then click the clock icon to insert the current time. 

Q: Can rows automatically be added to a table from another table? 

A: Yes, you can populate tables by adding from a structured table.

Q: Can I use a Registration table to look up information about existing, registered entities? 

A: No, you cannot add existing, registered entities to a Registration table. 

Q: Can multiple users use the same Registration table to register new entities?

A: Yes, as long as the users have the correct permissions to edit the Notebook entry that contains the Registration table. 

Q: Can I tell if an entity was registered in a Notebook versus using the global create button? 

A: Yes, by using the registration_origin table in a SQL query in Insights. Entities registered in a Notebook will have an origin_entry_id, while entities registered via global create will have a null in that field.

Q: Will changes in source tables automatically update mapped data in destination tables?

A: No, existing data in destination tables will not update if the source data is edited. However, new rows added to the source table will be mapped accordingly. 

Q: What happens if I re-sync a table with unsubmitted changes?

A: Unsubmitted changes or formulas will be lost during a table re-sync. Benchling will warn you before completing the action.