Configure the Output File Processor to Create New Entities

Benchling has the ability to create and register entities using the Connect output file processor. The functionality is convenient for use cases that require large numbers of entities to be registered  in one action.

Populated run and new entity

Process overview

1. Create the entity schema you want to use in the Benchling Registry if it doesn’t already exist.
2. Create a Run schema to process an output file and create the new entities.
3. Create an output file with entity field information, one row for each new entity.
4. Insert the run object into a Benchling notebook entry and create a new run.
5. Upload the output file to the run and click Process. New entities will be created and shown as an output  on the run.

Example output file

Output files should be comma separated UTF-8 plain text format. Each row represents the schema field information for one new entity.

Step-by-Step Guide for Benchling UI

Step 1: Configuring the Display Name

Navigate to the 'Output File Configurations' and begin by setting a display name for your output file, which will act as a section header in the run.

Step 2: Setting Up the Output Table

Choose the action to 'Register and/or update entities' in the 'Configure output table' section. This instructs Benchling to prepare for the creation of new entities.

Step 3:  Configuring Entity Schema

Apply any necessary transformations to ensure your output file is in the correct format for Benchling to process. These can include operations like removing extra headers or merging columns.

• If you're using an existing entity schema, you can select it directly.

• To create a new entity schema from the Run schema, navigate to the 'Configure entity schema' option.

Step 4: Mapping Columns

through the 'Configure column mapping' section, tell Benchling how to interpret each column. You can map them by column order or by column name, depending on the structure of your output file.

Step 5: Setting the Delimiter

Choose the appropriate delimiter for your output files. The default is a comma (","), but this can be changed if your file uses a different delimiter.

Example JSON configuration

Note: fields from the run schema can be accessed with a lookupConfig and used to populate fields of the new entities that are created.

{
	"fields": [
		{
			"isMulti": false,
			"type": "text",
			"displayName": "Run field",
			"name": "run_field",
			"isRequired": false
		}
	],
	"automationOutputFileConfigs": [
		{
			"entitySchemaInfo": {
				"fields": {
					"Date": {
						"columnName": "Date",
						"type": "DIRECT"
					},
					"Info": {
						"columnName": "Info",
						"type": "DIRECT"
					},
					"Run field": {
						"lookupConfig": {
							"isMulti": 
								false,
						"lookupSteps": [
						{
						"type": "SCHEMA_FIELD",
						"schemaField": "run_field"
						}
						]
						},
						"type": "LOOKUP"
					}
				},
				"shouldReplaceExisting": false,
				"schema": "ts_78oiNs0j",
				"labelingStrategy": "DELETE_NAMES"
			},
			"name": "Entity creation",
			"columnTypesByName": {
				"Date": "SCHEMA_FIELD",
				"Info": "SCHEMA_FIELD"
			},
			"delimiter": ",",
			"fileExtension": "csv",
			"tableType": "SAMPLE",
                        "spreadsheetProcessingLocale": "en-US"
		}
	]
}

For runs processing >=100k cells of entity creation information, File Queuing can be enabled to improve the convenience of uploading very large files into Benchling.

Benchling supports ingestion of localized numbers and dates. You can configure the Locale in your user settings. To learn more, visit Updating user locale.