Create, Edit and Publish Automation Templates [Limited Availability]

Automation templates let you save a repeatable analysis workflow and apply it across Benchling. You can create a template directly as a draft, edit it in place using the same interface as an analysis, review where it can be applied, and publish it when it's ready for others to use. This replaces the previous approach of building a throwaway analysis just to save it as a template.

Automation templates require the Benchling Automation SKU. Contact your Benchling representative for more information.

Note: This feature is in limited availability (LA) and is not enabled by default. For more about what it means for features to be in LA, see our article that describes the Benchling release stages.

Create a draft template

New templates are created as drafts. A draft is fully editable and isn't available for use until you publish it. You can start a draft from Template Collections or from global create.

To create a template from global create:

1. Click the + icon in the left navigation
2. Type Automation template in the search field
3. Select Automation template from the results
4. Enter a name in the Name field
5. Select a collection from the Template Collection dropdown
6. Click Create

Add source steps

Source steps define the data your template works with. A template can pull data from a dataset supplied at run time, a fixed dataset you select during configuration, files already uploaded to Benchling, custom variables, or a live query that refreshes on every run.

1. Click Add data to open the Add source step right side-panel
2. Select a step from the list, or search for it by name
3. Click Next
4. Configure the step and confirm

Available source steps are grouped by category:

• Code — Custom code
• Combine tables — Join tables, Union tables
• Create file — Import files from data catalog
• Create table — Create table from dataset, Create table from SQL query, Create table from template variables
• Look up — Look up

Add a dataset

Use Create table from dataset to bring tabular data into the template. Datasets can be variable, meaning the user supplies one each time the template is applied, or static, meaning the template always uses the dataset you select. Both types use a reference dataset so Benchling knows the expected shape of the data.

Search for an existing dataset, or upload a new one directly from this step. Uploading here replaces the separate Create table from Uploaded CSV entry point.

Configure column mapping

When you add a variable dataset, you decide whether users map columns themselves or whether the template maps them automatically. Configuring mapping in the template removes that work from the people applying it.

1. When adding the variable dataset, locate the Require user to map columns when applying template checkbox
2. Select the checkbox if you want users to map columns each time — the required columns come from the reference dataset you selected
3. Leave the checkbox cleared if you want to define the mapping yourself
4. If you cleared the checkbox, configure the expected column mappings by position, by name, or by regular expression

Add custom template variables

Use Create table from template variables to collect values from the user at run time and reference them throughout the template -- such as a boolean flag, a plate identifier, or a text value.

1. Add a Create table from template variables step to the flowchart
2. Select the variable type (Boolean, Text, Integer, Decimal or Benchling Type)
   • Benchling Types supported:
     • AA sequence
     • Container
     • Custom Entity
     • DNA sequence
     • Mixture
     • Molecule
     • Plate
     • RNA sequence
     • User
3. Provide an example value — this value is used during prototype execution and is replaced with the actual value each time the template runs

Note: Variable types in Create table from template variables don't map 1:1 to run schema field types. For example, a multi-select text variable becomes a single-select text field in the auto-generated run schema. Review the generated run schema fields after saving the template to confirm the mapping is as expected.

Add files from the data catalog

Use Import files from data catalog to add files already uploaded to Benchling through a Connection or through global create. This is useful for workflows that process instrument output files. To upload a new file, use global create first. See article for How to use Files.

Add a refreshable SQL query (Beta)

Create table from SQL query queries the Warehouse directly and re-runs every time the template is applied, so the template always works with current data and the user doesn't need to supply anything.

1. Add a Create table from SQL query step
2. Enter a name in the Table name field
3. Enter your query in the SQL query editor
4. Save the step

See enablement section below for enabling this feature with Automation templates.

Edit a template

Templates and analyses share the same editing interface, so building a template works the same way as building an analysis. Add, configure, and remove steps from the flowchart, and expand any step to review its inputs, outputs, and configuration in one place rather than inferring what it does from its name.

To rename or move a template, click the More options icon and select View metadata.

Add output steps

Output steps define what the template does as actions in Benchling — sending data to an entry or worksheet, saving to results, or writing back to the registry. You can configure output steps in a draft template without those actions firing, so nothing is written to your tenant while you build. A step that would create outputs displays a halted status explaining that it can't be run during configuration.

To add outputs, click Send output and select the outputs you want to configure. Output steps can also be deleted from the template.

Register entities and Update entities steps are added directly from the flowchart and configured in place. For an Update entities step, select a Schema, choose a Folder or leave the folder unchanged, and complete the Column Mapping by pairing each field with a column from your data. These steps are in beta and require an additional flag to be flipped. Contact Benchling support to enable this. 

Check template compatibility

Where a template can be applied depends on the input variables it uses. Check compatibility shows which areas of Benchling your template supports, so you can confirm it works for its intended entry point before you publish.

1. Click the More options icon () in the header
2. Select Check compatibility
3. Open the Input variables tab to review the template's table, file, and field variables
4. Open the Compatibility tab to see which entry points the template supports
5. Adjust the template's variables if a needed entry point isn't supported
6. Click Close

The Compatibility tab evaluates the template against these entry points: Apply template in analysis, Run schema, Run schema output file, Assay unit operation, and Recipe unit operation. Each entry point lists its variable requirements, with a marker showing whether your template meets each one.

Publish a template

Publishing moves a template from draft to published. Draft templates are excluded from apply listings and from configuration migration, so a template must be published before others can use it or before it can move between tenants.

1. Click the Draft dropdown in the header
2. Select Publish template

The status changes to Published and a confirmation message appears. A banner at the top of the template confirms that editing is disabled on published templates.

Published templates are immutable and cannot be edited. To change a published template, duplicate it into a new draft.

Note: Published Automation templates do not currently have controlled version numbers and have not reached parity with entry template versioning. Support currently covers the draft to published transition only, with versioning planned for a future release.

Duplicate a template

Duplicating creates a new draft you can edit freely. Use it to revise a published template, or to branch from an existing draft.

1. Open the template you want to copy
2. Click the More options ()
3. Select Duplicate

Duplicating a published template creates a draft copy of that published template. Duplicating a draft creates a copy of the original draft.

Note: If the original template was not created as an editable template, you may need to select new reference datasets in the duplicate.

Enablement

Editable and publishable Automation templates are controlled by configuration flags. Contact Benchling Support to enable them for your tenant.

Two capabilities described in this article are in beta and require additional enablement:

• Create table from SQL query source steps require Insights Labs
• Register entities and Update entities output steps 

Understand template permissions

Automation templates follow the same permissions model as existing Automation templates. Access is granted through the template collection that contains the template, so a user's ability to create, edit, or apply a template depends on their access to that collection.

Frequently asked questions

1. Can I add standalone Export to Dataset or Save to Results steps to a template?
   Not currently. Use Send output to configure these outputs.

2. Can I test whether an output step will succeed before publishing?
   No. Output steps are halted during template configuration rather than executed against preview data.

3. Can I create, configure, publish, or apply Automation templates through the API?
   Not currently. V3 API support is not available for Automation templates.

4. Are published Automation templates versioned?
   No. Published templates do not have controlled version numbers.

5. Can I edit a published template?
   No. Published templates are immutable. Duplicate the template to create an editable draft.

6. Can I use Create table from Registry schema or Create table from Plate schema steps?
   These steps are not supported in Automation templates. Use Look up steps or a refreshable Create table from SQL query step instead.