How to use Runs

Runs in Benchling are tools that allow you to automate and perform various Benchling actions at scale. They allow the structured capture and execution of lab workflows driving automation or standardized file-based processes. Runs help your team track inputs, outputs, metadata, and associated files in one place, enabling reproducibility, integration, and automation.

Whether you're working with instruments files, processing results, or need to archive runs, this guide walks you through the core features available to users working with Runs in Benchling.

Understanding Runs

A Benchling Run is an action performed through an assay instrument, robot, or software analysis pipeline. For example, runs can be used to model NGS sequencing runs, flow cytometry experiments, or liquid handling methods. Runs are used in Notebook entries to allow a seamless flow of structured data throughout an experiment. Additionally, a run may be used to improve the user experience by automating or increasing throughput of certain tasks.

Similar to how Registry, Inventory, Results and Workflows use schemas for structured data capture, Connect uses Run schemas. A Run schema defines the metadata that will be tracked on a Run. This metadata may include fields for attaching raw instrument output files, or other parameters to instruct the instrument. Run schemas can be created by registry admins.

Each Run:

• Is associated with a specific Run schema
• Stores uploaded files, metadata, and results
• Link to downstream Results tables, Datasets, Inventory, or other Benchling records

Runs are essential for automated instrument-driven work and keeping data tightly integrated with your Benchling environment.

Create a Run

To use a Connect Run in Benchling:

1. Navigate to the section in your Notebook entry where you need to add the Run
2. Click on Run, Insert from the action bar on the top of the Notebook Entry
3. Select the desired Run, select the run schema (these are configured by admins), and click Insert
4. Fill any relevant run metadata fields (e.g., selecting the Connection, linking sample plates, etc)
5. Click Create Run

Once created, you can use the run to generate input files, and process instruments output files.

In some workflows, Runs may be automatically created through integrations (e.g., using APIs). In those cases, you would not need to manually initiate a Run, but you can still interact with it, view parsed results, and complete downstream tasks. 

Add and process files in a Run

Runs allow you to add and process files, create structured data outputs, and perform various Benchling actions based on the files content. These files can be automatically parsed to populate results tables, update metadata, or initiate downstream workflows. Supported file formats typically include .csv, .txt, and .xlsx, depending on how your Run schema is configured. Be sure to confirm the expected format with your Benchling admin. 

If the file cannot be parsed, Benchling will show an error message within the Run record. Parsing must succeed before results are created or displayed. 

Adding files two runs can be done by two methods: 1) Uploading a local file or 2) adding a File from a Connection. Please note that each run is configured to support only one of these options.

Upload a local file to a Run

1. Navigate to the Run you inserted.
2. Click Upload Files (or drag and drop into the upload area).
3. Select the relevant file(s) from your local system.
4. Once uploaded, click on “Process all” to process the data files.

If the file is not processed as expected, Benchling will raise an error. Ensure that:

• The file matches the configured format (e.g., data format and layout, headers match the runs expectation, you are using the correct file type)
• It’s linked to the correct schema and parser

Upload a local file to a Run

1. Select the Connection to be used
2. Click on Retrieve data
3. A pop-up window will appear, select the file(s) to be processed
4. Click Process

View and interact with Run data

Once your files have been uploaded and parsed, you can view the results directly within the run record. This is where you’ll inspect experimental outputs, validate parsing accuracy, and review associated metadata. Interacting with the data lets you confirm that results align with expectations, verify links to entities, and explore how the run integrates into broader workflows. Depending on the Run schema, this may include:

• Result tables
• Linked entities
• Metadata fields
• Inventory information
• Dataset outputs

You can also:

• View and download the original file
• View and download the result table as csv
• Click on Benchling links (e,g., entities or inventory) directly in the run to navigate to those objects.

Archive and and Unarchive processed Results

Archiving ensures that data in Benchling is not mistakenly deleted, when data is archived, it is hidden from the working view. To archive results:  

1. Once an output file has been processed, the file will appear above its associated Result table
2. Next to the downloadable file will be the Archive option
3. The next modal will allow you to provide a reason for why the Results are being archived
4. Once the reason is confirmed, select Archive

Note: This will archive all the rows of the results created by the file.

To Unarchive Results, click the Unarchive icon in the Run.

Archive and Unarchive Runs

Over time, your list of active runs can become crowded, especially if you're working in a high-throughput environment. Archiving runs allows you to reduce clutter in your active workspace while preserving historical data for traceability and reporting. Unarchiving brings old records back into view when they’re needed again, such as during audits or reanalysis.

Archiving runs allows you to clean up active views while preserving historical records. while preserving historical records. Archived runs are hidden from default views but still searchable and reportable.

To archive a Run

1. Navigate to the Run you want to archive in your Notebook entry
2. Click the three-dot menu in the upper-right corner
3. Select Archive Run
4. Confirm the archive action

To unarchive a Run

Using Global Search:

1. Use global search or schema filters to locate the archived Run.
2. Open the Run.
3. Select Unarchive Run from the top right corner.

In Notebook Entries:

1. Click on the “+” icon in the top right hand corner of your Run and select Insert from inbox.
2. In the subsequent window, filter for Archived Runs.
3. Select the Run you’d like to unarchive and change the filter back to Not archived.
4. Select your Run again and select Insert run.

Note: You must have appropriate permissions to archive or unarchive runs.

Frequently Asked Questions

Q: Can I edit a Run after it’s been created?

If the schema allows, you can update metadata fields or re-upload files. However, some data may be locked depending on schema configuration. Editing parsed results typically requires archiving the undesired data, creating a new Run, and processing the correct data/file.

Q: Can I track who uploaded a file and when?

Yes. Each uploaded file includes metadata that records the uploader and timestamp. This can be viewed in the entry activity history.

Q: Can I upload multiple files to a single Run?
Yes. Runs can support multiple file uploads, and each file will be parsed or stored according to schema configuration.

Q: What happens if my file doesn’t parse correctly?
Benchling will raise an error, and flag the reason why the file was not processed. Ensure the file format matches the expected structure. Common issues include header mismatches or missing required fields. Contact your Benchling admin if you need help reviewing the parser.

Q: Can I delete a Run?
Runs cannot be permanently deleted by default. You can archive a run to remove it from active views.

Q: Where are Runs used in Benchling?
Runs are primarily used in automation workflows and data ingestion processes. They’re commonly configured for high-throughput assays, QC workflows, and integrations with lab equipment. Users usually interact with Runs using the Notebook Entries.

Q: Can Runs be used to process Results and Register entities?
Yes. The same Run can be configured to create results directly, register entities, and link results to entities.