Benchling's Result schemas define the structure of data captured in Result tables within Notebook entries. They ensure standardized, searchable, and compliant data collection across experiments and assays. This guide provides comprehensive instructions on creating, configuring, editing, and archiving Result schemas to support your team's data management needs.

Result schemas are configured by organization-level admins or teams with admin privileges to meet your team’s specific needs based on the types of experiments and assays you perform.

As of October 2021, we replaced this legacy Results functionality with an updated version. If you are looking for current information on configuring Results or using Results, see the linked articles. 

Create Result schemas 

Configure a legacy Result schema

1. Click on your Avatar and navigate to the Feature settings menu and select Result schemas from the menu
2. In the Result schemas menu, click Create at the top right to initialize new schema creation
3. Define schema attributes, such as schema name and select the organization that is the owner of the schema, and the primary samples using the dropdowns
4. Click Create 

This will bring you to the JSON editor for the Result schema. 

Add and edit fields to a legacy Result schema 

For each field that you want to add to the schema, you’ll add a column to the Result table. 

1. At the bottom of the JSON editor, click Configure Result Table which will open the Result table configurator
2. To add a new column, right click on the column header named Untitled and choose to insert a column left or right
3. To rename the column, right click on the header of the new column and click Rename column, enter a column name in the textbox and click Ok
4. To edit the data type of a field, right click on the header of the column you want to edit and click Edit type, use the dropdown to set column type
5. When you have added all the fields you need, click Publish
6. When you are finished, click Update to save the edits that you’ve made 

When you are editing the field type, here’s a list of available data types: 

• Datetime: Allows you to select a specific time in a clock interface
• Entry Link: Link to a Notebook entry
• Blob Link: Allows you to upload an external file into the designated field
• Storable Link: Link to a container, box, or inventory location
• Result Links: Used in integrations. Please contact Benchling directly for more information

There are a few other things that you can edit in the JSON editor, the sections below walk you through them. 

Add minimum and maximum thresholds to number fields

If your schema field has Integer or Decimal selected as the data type, you can add minimum and maximum value thresholds.

To add thresholds in the JSON editor, add the following, replacing minimum and maximum with your numbers:

{"min": MINIMUM,
"max": MAXIMUM}

For example, add a minimum and maximum to the Viability (%) field of a Cell Viability Result table:

{ "id": "tsf_IHrUby3IzF",
"displayName": "Viability (%)",
"name": "viability",
"type": "float",
"isRequired": false,
"isMulti": false,
"isSnapshot": false,
"unitApiIdentifier": "unit_61QKnMCW",
"min": 70,
"max": 100
}

Configure decimal field placement

If your schema field has Decimal selected as the data type, you can configure the display precision. For example, a display precision of 3 would record submitted results to the thousandths position (0.000).

To specify display precision, add the following in the JSON editor, replacing number with the number of places after the decimal:

{"displayPrecision": NUMBER}

For example, add display precision 2 to the Viability (%) field of a Cell Viability Result table:

{ "id": "tsf_IHrUby3IzF",
"displayName": "Viability (%)",
"name": "viability",
"type": "float",
"isRequired": false,
"isMulti": false,
"isSnapshot": false,
"unitApiIdentifier": "unit_61QKnMCW",
"displayPrecision": 2
}

Configure text dropdown options in decimal fields

You can configure decimal (float) fields to accept text. If a user enters text values that are not configured in the field, it will be flagged as illegal to preserve data integrity. For example, a number field can be configured to accept ULOQ and LLOQ to represent the upper and lower limits of quantification, which can be useful for analytics assays.

To configure text drop-down options in a schema, first ensure the dropdown exists. You will need to input the dropdown ID in your JSON script.

To find the dropdown ID and configure your JSON script:

1. Select Dropdowns in the left-side panel, then click the dropdown
2. Copy the end of the URL containing the dropdown ID. This begins with sfs_
3. Replace sfs_ExampleID in the script below with the dropdown ID you just copied, then paste the script into the JSON editor

{ "legalTextDropdownId": "sfs_ExampleID"}

When a number field has text options configured, Benchling automatically generates an additional text column for that field in the data warehouse. Since columns can only contain one type of information, the original column holds the numeric value and the text column holds the text value, depending on the entry’s selected value. The new column is titled {field_name}$text.

Archive fields in a Result schema

Archiving fields removes them from active use while preserving historical data.

1. Click on your Avatar and navigate to the Feature Settings and select Result schemas from the menu
2. In the Result schemas menu, click on the name of the schema that you want to edit
3. In the JSON spec editor, scroll to find the field that you wish to archive and add a new property called “archiveRecord” with the reason for archival
4. Click Update to save the changes that you’ve made 

 Note: you can leave ”archiveRecord” : {} brackets empty to default to the reason of “other.”

Use Result tables in the Notebook

Custom columns in Result tables 

If you right click on a Result Table, you may notice that you can insert columns in the result table and, when you do, your newly inserted column will have a "*" in the column name.  These are custom columns.

Custom Columns allow you to insert formulas, text, lookups, and lookupfields to enhance usability of your result table for your experiment. You can type formulas in a cell in custom columns just like you would a cell in a regular table or in Excel.  

When would I use a custom column?

Some common use cases for custom columns are:

• Using a formula to convert units from a standard in your result table to another
• Calculating a concentration or density (given other parameters in your result table - such as volume or mass)
• Calculating Molarity (using a lookupfield to retrieve the Molecular Weight of your sample)

Note: Custom Columns are designed for your reference only and data that is stored in them is not stored in the Data Warehouse, the Results Tab of your registered entities, or anywhere outside of your entry.

Marking Results as Invalid

Marking results as invalid helps maintain data integrity by flagging erroneous entries.

1. Open the Notebook entry containing the Results table
2. Highlight the cell, row, or column to mark as invalid
3. Click Set validation (located to the left of the gear icon in the table toolbar)
4. The selected area will display a yellow flag indicating invalidation
5. To revert if the results is later determined to be valid, click Set validation again, changing the flag to blue
6. Click the flag to view the full history of validation changes

Frequently asked questions

Q: Can I change the data type of a field after data has been entered?
A: No. Once data has been recorded, the field type cannot be changed. To modify the field type, archive the existing field and create a new one with the desired type.

Q: How do I add a dropdown to an existing Results schema?
A: Dropdowns must be added via the JSON editor. Obtain the dropdown ID from the Dropdowns section under Registry Settings and include it in the field's JSON configuration.

Q: What happens when I archive a field in a Results schema?
A: Archived fields are removed from new entries but remain visible in existing data. They are hidden from the Results tabs of linked entities and are excluded from non-$raw Warehouse tables.

Q: Are custom columns stored in the Data Warehouse?
A: No. Data in custom columns is for reference within the Notebook entry and is not stored in the Data Warehouse or linked to registered entities.

Q: How can I mark a result as invalid?
A: Highlight the desired cell, row, or column in the Results table, click Set validation, and the area will be flagged as invalid. Click the flag to view the validation history.