Note: Please read “Configure a lab automation run” for more general information about configuring the lab automation run.

What is an output file config?

An output file is a CSV where each row represents an action performed by a robot. For liquid handlers, each row represents a transfer operation: this means that each output file row specifies a source plate/container, transfer volume, usually a destination plate/container, along with other optional columns.

We map each column of each row of the output file to specific Benchling functions: registration, plate creation, and transfer. The output file ingestion functionality can register new samples, create new plates, and transfer the samples into the plates in the same action. Automation output files can be consumed by runs whose run schemas are configured to consume them.

The output file processor will take an action for each row of the output file. These actions can either be:

  • Liquid handling actions. One or both of the following: Execute a transfer operation (decrement a source container by some volume, and move the contents to a destination container, or fill a destination container with a source entity)Register a new entity (this can be done by itself, or alongside a transfer)

  • Analytical instrument actions. Create results associated with an entity


Entity schema fields may be populated either directly (as when importing to registry from spreadsheet) or from the contents of the source containers. Result schema fields may be populated with data directly from a spreadsheet.

The output file ingestion can be configured to register new entities or transfer existing entities to a new plate/container. When new entity registration is desired, one new entity will be registered for each unique destination container in the spreadsheet. Entity schema fields may be populated either directly (as when importing to registry from spreadsheet) or from the contents of the source containers.

Sources in output files are specified by container barcode, plate barcode and coordinates, both, or none. Source containers must already exist in Benchling Inventory before ingesting the output file.

Destinations may be specified by container barcode, plate barcode and coordinates, or both. A destination must be specified. Destination containers and plates do not need to preexist in Benchling Inventory: they will be created if they do not exist while existing empty containers and plates will be filled.

The containers, plates, and/or entities produced by ingesting the output file will be linked to the run as output samples. These will present as the RunOutputs as shown above.

Configure the output file config

Add an automationOutputFileConfigs to the schema, which is an object with the following properties:

  • entitySchemaInfo: if specified, contains information about the entities to be created and registered. If not present, existing entities will be transferred rather than created

  • resultSchemaInfo: If specified, contains information about results that will be created. If present, entitySchemaInfo may not be present, and no entities or transfers will be created

  • name: the value to display in the UI (“pulling” in the example up top)use the same name in the inputFileConfig and the files will stack (as shown in the example up top)

  • destinationInfo: if specified, contains information about the plates/containers to be created if not present, you must use existing destination plates/containers

  • columnTypes: an array of strings, which are the column types present on the output file from left to right (top to bottom in the config). Exactly one of columnTypes or columnTypesByName must be present.

  • columnTypesByName: a map from column header to column type. In this case the order of columns will not be respected and will instead be looked up by column header. Exactly one of columnTypes or columnTypesByName must be present.

  • volumeUnits: the units of volume to transfer required if a TRANSFER_VOLUME_AMOUNT column is present

  • tableType: controls the presentation of the run output table to be either one row per destination plate or one row per destination sample

  • delimiter: single character, defaulting to (and hidden if set to) “,”. Controls the delimiter for parsing output files and saving processing files (if processing steps exist).

  • fileExtension: a string defaulting to (and hidden if set to) “csv”. Controls the file extension for generated output processing files (if processing steps exist).

Tips for configuring the output file config

  • Determine the columns necessary for the output file prior to configuration

  • Make sure that all of the information in the desired output file can be looked up from the values inputted into the run fields

Did this answer your question?