How to configure Runs

Lab Automation Runs in Benchling streamline the integration of laboratory instruments with digital workflows. Runs are capable of producing files that can be used on instrument software. Additionally, Runs can ingest files into Benchling to capture Results or Datasets, register new samples or track transfers between Inventory items. Ultimately, Runs support seamless and accurate tracking of samples and data in bulk. 

This guide provides step-by-step instructions for setting up and managing Lab Automation Runs on your Benchling tenant.

Understanding Lab Automation Runs

Lab Automation Runs in Benchling consist of three main components:

• Run Fields: User-defined fields that capture metadata or parameters for the run.
• Input File Configurations: Define how input files are generated to instruct laboratory instruments.
• Output File Configurations: Specify how output files from instruments are processed and mapped back into Benchling.

These components work together to automate laboratory workflows, ensuring data integrity and efficiency. Understanding how each component fits into the broader automation strategy will help ensure that your team’s Run configurations are accurate, repeatable, and tailored to your processes.

Configuring Run Fields

Run fields capture essential information required for the automation process. These fields define variables that may influence file generation, sample routing, or downstream analysis. Examples of a Run field include, but are not limited to, a Plate Link, which defines the plate the actions are being taken on or a Dropdown field which defines the method that was used for the instrument.  Setting them up correctly ensures that all necessary inputs are accounted for before initiating the Run.

Steps to Configure Run Fields:

1. Navigate to the desired Run schema in Benchling.
2. Click ➕ next to Run fields.
3. Enter the Field Name.
4. Select the Field Type from the dropdown menu (e.g., Text, Number, Date, Boolean, Entity Link, Inventory Link, Dropdown, Attachment).
5. Optionally, check Required and/or Multi-select based on your needs.
6. Click Save to apply the changes.

Note: Run fields must be saved before configuring Input or Output File Configurations.

Note: Once a Run is used once, a field may not be changed from unrequired to required. If you want to make this change, use the “Duplicate schema” option to create a new schema. If for some reason, a new schema is not feasible for your use case, reach out to Benchling Support for assistance.

Setting Up Input File Configurations

Input File Configurations define how Benchling generates files to instruct laboratory instruments. These files serve as instructions to the instrument, guiding actions like liquid transfers, thermal cycling, or plate processing. Properly configuring input files ensures the correct data is passed to the instrument in the format it expects. All of the data that you want to be present in the input file has to be accessible either directly or via lookups in the Run schema field metadata.

Configuring Sources

Sources are used to populate values in the file. They can pull from user-entered run fields, count entities to determine repetitions, or insert constants. Establishing sources is essential for dynamically populating data in your input files.

Note: The number of rows in the resulting file will be determined by the number of values found in the lookups for all Sources.

1. In the Run schema, click ➕ next to Sources within the Input File Configuration section.
2. Choose the source type:
   • Run Schema Field: Use data from existing run fields.
   • Counting Entities: Specify the number of entities in a schema field.
   • Constant Value: Use a fixed value for all rows.
3. Define any necessary lookup steps to retrieve related data.

Configuring Destinations (optional)

Destinations are used to define the destination of a transfer. It is only required to define your destination if you will use one of the “Plate Layout” options to generate a transfer file that matches a pre-defined method for your plating operation such as “Stamp” or “Interleave”.

Note: To use the “Plate Layout” option for defining your Input File, both the Source and Destination must be defined as a plate.

1. In the Run schema, click ➕ next to Destinations within the Input File Configuration section.
2. Give the Destination a label
3. Define the lookup steps to return your destination location

Note: The “Placeholder Plates” and “Placeholder Boxes” option for the destination will autogenerate a new and unique output plate or box barcode in the cases where the barcode is not specified by a user.

Configuring Input Table (File Columns)

The Input Table represents the structure of the file and defines what data is included in each row. Defining columns and how they are populated helps ensure your instrument reads and executes the run correctly.

1. Within the Input File Configuration, navigate to “Configure columns for the input file” section.
2. Create a new column, by right clicking on an existing column and inserting a new column
3. For each new column:
   • Enter the Column Name.
   • Define the Lookup Steps to determine the data populating the column.
   • Choose whether or not to “Consolidate results into a single row”.

Note: Choosing to consolidate results into a single row will take the value(s) that are returned by the lookup step and insert them into every row of the file. For example, if your lookup steps return a single plate and you choose to consolidate into a single row, the plate barcode value will be present in every row of the file. The amount of rows in the file is defined by the number of values returned from the Source and choosing this option will create a single row for each row in the Source.

Note: It is important that all columns will return the same number of rows as the defined Source. If a column’s lookup returns a non-equal number of rows to the Source, the user will experience an error when attempting to use the Run.

Using Plate Layouts (optional)

Plate layouts ensure that well-level data is interpreted correctly. When your run involves microplates with defined plating operations, this step ensures instructions account for layout-specific formatting like row and column identifiers.

1. Ensure both Source and Destination are set to plates.
2. Specify the Plate Layout to maintain correct well positions.
3. Configure columns to map source and destination containers appropriately.

Apply Transforms to the Input File

Transforms can be applied to the input file to generate additional columns, filter data, or otherwise change the shape of the file after all of the lookups have been complete:

1. Click “Set Transforms”
2. Select the type of transform you want to perform on the file and follow the prompts to define your transform

Configure the file format

The file format can be customized to give the file an informative name and file type. Users can use the Run schema fields, other Run properties, or constant text values to give their files a name template. Additionally, the Run can be configured to support .csv, .txt, or .tsv file creation. 

1. Click the pencil icon on the File name section
2. Define the file name properties and drag and drop them to create the final file name formate
3. Use the file format and delimiter sections to further define the file format

Defining Output File Configurations

Output File Configurations process data files generated by laboratory instruments, translating them into actions within Benchling. This is how results, datasets and/or updates to volumes from instruments are brought back into the system for further tracking, reporting, or decision-making.

Configuring Output Files

1. In the Run schema, click ➕ next to Output File Configurations.
2. Set the Display Name for the output file section.
3. Choose the Benchling Action(s):
   • Transfer Samples: Move samples between containers.
   • Register and/or Update Entities: Create new entities in Benchling.
   • Record Results: Capture analytical results.
   • Record Datasets: Capture instrument data as a dataset.
4. Configure the necessary schema information:
   • Entity Schema: For registering entities.
   • Inventory Schema: For transferring samples.
   • Result Schema: For recording results.
5. Apply transforms to the if it needs to be altered before ingestion
6. Define Column Mappings to interpret the data correctly.
7. Set the appropriate Delimiter (default is a comma).

Output File Actions (Benchling action)

Creating New Entities

This option allows Benchling to automatically create new entities based on the output of your instrument. This can be helpful for processes like automated construct assembly or sample derivation.

1. Ensure the desired Entity Schema exists in Benchling.
   • If the schema does not exist, you can create a new one directly in the “Configure entity schema” modal
2. Configure the Output File to Register and/or Update Entities.
3. Map columns from the output file to the corresponding schema fields.

Note: The “replace entities in existing containers” button in the Entity Schema configuration modal can be used to if you want to create new entities in a destination plate which may have previously already had entities. For example, if you had a plate that already had cell lines, but performed a process to transfect the cell lines in the same plate, you may want to now replace the contents in that plate with a new schema type of entity.

Capturing Results

Result capture links instrument output back to the entities in your system, enabling data review, analysis, and decision-making directly in Benchling.

1. Ensure the desired Result Schema exists in Benchling.
   • If the schema does not exist, you can create a new one in the “Configure result schema” modal
2. Configure the Output File to Record Results.
3. Map columns from the output file to the corresponding result fields.

Transfer Samples

The transfer samples option allows you to use the output files from your instruments to track the physical volume of material that is being moved between containers during your process.

1. Ensure the Container/Plate Schemas to be used exist in Benchling.
2. Configure the Output File to Transfer Samples.
3. In the Inventory Schema section choose one of the following options:
   • The “use existing destinations” option will assume that the destination container/plates already exist. The run will error if a barcode in the output file has not already been created in Benchling.
   • The “create new destinations” option will assume that the destination container/plate barcodes do not exist in Benchling yet. Therefore, this option will open a modal to allow you to customize the properties of the newly created container/plates
4. Map columns from the output file to corresponding transfer properties, such as the Source and Destination containers or plate coordinates and the quantities to be transferred.

Note: Output File configurations can be configured to do multiple of the above actions at once. It is important that for each of the actions, a column in the output file can be mapped to all of the required fields for the specified action.

Applying Transforms to Output Files

Instrument data from lab instruments is not always in a neat, row by column format that is easy to ingest into your Benchling schemas. Oftentimes, additional transformations need to be performed before the file is parsed. 

These can include transformations such as removing header information from the file, or melting our pivoting data to get the datapoints you care about in a single column. Output file transforms can be used in sequence to transform the file before it is ingested. 

When you are creating the output file transforms, you can load an example file into the “Preview” section in order to see what the final state of your file will be as you create the transforms.

Archiving Run or Result Schema Fields

Archiving a schema field hides it from user input while preserving historical data. This is useful when fields are no longer needed in future runs but should remain in the system for audit or reference purposes.

In order to archive a required field, the user will first have to mark it as unrequired before archiving it.

Managing Permissions

To manage the users who have access to configure Run schemas, use the radio button labeled “Team members can create automation, result, request and workflow schemas; team members can update request and workflow schemas” to grant access. 

Permissions for who can create Runs from the schema are controlled in the Access Policies section of the Run Schema. For more information on Schema Access Policies, view this article.

Advanced Configuration Topics

Using Lookup Configuration Options

Benchling allows advanced control over how data is retrieved using lookup steps in both input and output file configurations. This is useful when building complex logic that relies on related data.

• Enable "Consolidate results into single row" to collapse multiple results into one.
• Use "Do not preserve relationship between lookup steps" to simplify dependencies.
• Use nested lookups to fetch data across linked entities.

Output File Processor Requirements

For Creating New Entities

• Each row in the output file must represent a unique entity being created.
• Fields can be populated from the output file or by referencing a related container or entity.
• Data must conform to the entity schema structure to ensure successful creation.

For Capturing Results

• The result schema must exist and support the fields being captured.
• Benchling supports referencing the Primary sample for cases where only a container is provided.
• Users must have write access to the result schema to process result files.

Snapshot Fields in Result Schemas

Computed fields automatically populate based on data from linked entities (e.g., registered constructs, samples). These fields:

• Are not editable in the UI.
• Snapshot the value at the time of result creation.
• Help reduce data entry and enforce consistency.

Computed fields must be configured in the result schema using the schema designer or schema JSON.

Advanced Plate Layouts

Beyond basic layouts, Benchling supports:

• Column Interleave
• Interleave
• Reverse Column Interleave
• Reverse Interleave
• Reverse Stamp to Quadrants
• Stamp
• Stamp to Quadrants

These layouts are critical for automation hardware with specific loading patterns or pooling requirements.

Troubleshooting and Error Handling

If your run fails during input or output processing:

• Check that all required fields are filled and correctly mapped.
• Confirm that file headers match configured column names.
• Review any lookup errors or unresolved entities.
• If failing on Input File generation, ensure that each column lookup returns the same number of rows as the defined Source
• Consult the run’s audit trail and error logs for diagnostic messages.

Common errors include:

• Misaligned row counts
• Ambiguous or missing lookup values
• Invalid field values (e.g., wrong units or formats)

API-Based Automation

Benchling supports the use of REST APIs for automating:

• Creating runs
• Generating and uploading input/output files
• Processing runs and retrieving results

This is particularly useful for integrating Benchling with external scheduling systems, LIMS, or instrument control software. Refer to the Benchling API documentation for implementation examples.

Instrument-Specific Configuration

Some instruments require unique formatting or behavior. Benchling provides tailored guides for integrating specific platforms, such as:

• Unchained Labs Lunatic
• Agilent Gen5
• PerkinElmer Janus

These guides explain how to configure files, transforms, and mappings based on vendor requirements. Refer to Benchling Help Center or your Solutions Consultant for access.

Frequently Asked Questions

Q1: Can I configure multiple input and output files in a single run?
Yes, Benchling allows multiple input and output file configurations within a single run to accommodate complex workflows. However, a file can only be processed through a single output file processor at once.

Q2: How do I handle different delimiters in my files?
You can specify the delimiter (e.g., comma, tab) during the configuration of input or output files to match your file format.

Q3: Is it possible to preview transformed data before processing?
During configuration of the run schema, the transformed data can be previewed when configuring your transforms. When ingesting the data, no preview is available before ingestion but an output .csv file is produced for every transformation step.

Q4: What happens if a field is archived?
Archived fields are no longer active in the schema but remain in the system for historical reference and data integrity.

Q5: Can I use plate layouts for both input and output configurations?
Plate layouts are primarily used in input configurations to maintain correct well positions during sample transfers.

Q6: Can I use the API to automate run creation or processing?
Yes, Benchling offers API endpoints for creating runs, uploading files, and triggering processing actions.

Q7: How do I resolve an error when my run fails to process?
Check for common issues like unmatched lookup values, incorrect file formatting, or missing schema access. Use the audit trail for more information.

Q8: Are there templates or help for specific instruments?
Yes, Benchling provides configuration guides for certain devices. Ask your Benchling contact or visit the Help Center for instrument-specific materials.

Q9: How do I configure complex plate layouts like reverse stamping or quadrants?
Use the advanced layout options in the Plate Layout configuration section and test them with simulated data before launching production runs. Benchling provides tailored guides for integrating specific platforms, such as:

• Unchained Labs Lunatic
• Agilent Gen5
• PerkinElmer Janus

These guides explain how to configure files, transforms, and mappings based on vendor requirements. Refer to Benchling Help Center or Benchling Support for access.