App Workspace & Configuration

Introduction

The Benchling Apps Workspace is a configurable “home base” for a Benchling Apps. By default, all Benchling Apps have a unique homepage where users can view information about the app. Additionally, app developers are able to leverage App Configuration to allow users to make changes to an app's configuration options and assess the app’s access to Benchling data.

App Configuration allows app developers to include configuration options that enable Benchling users to customize their app experience. Configuration options can include Benchling dependencies like schemas, folders, and projects, as well as generic types like text, integers, and checkboxes. Configuration options can empower Benchling users to get an app up and running, or customize how the app functions without requiring work from the app developer.

Key Concepts

App Workspace

The App Workspace is the public face of an app in Benchling. It can be accessed through the sidebar menu under Connections > Apps.

The App Workspace is where users will be directed anytime they click on the app in other parts of Benchling.

The Configuration and Access tabs are where admins of the app can control the app’s configuration and assess the app’s access to data in Benchling.

All apps have a homepage once created on a Benchling tenant, but only apps that have included a Manifest will have a configuration page.

App Configuration

App Configuration includes the configuration options an app developer provides that enable Benchling users to customize their app experience. This configuration is powered by the App Manifest and the App Installation:

1. App Manifest: A yaml file that serves as the environment-independent definition of the app. The manifest is stored externally, usually alongside the app code.
2. App Installation: The credentials, configuration values, and general app presence on a specific Benchling tenant. These tenant-specific installation details are stored in Benchling.

The app manifest defines the configuration options available to users. In Benchling, App Configuration appears to users in the App Workspace under an app's "Configuration" tab:

When To Create a Manifest

Developing a working Benchling app doesn’t technically require a manifest. Following our Getting Started with Benchling Apps guide or Building your first App guide, you can complete the process of building a Benchling App end to end without defining any App Configuration.

Often, determining the configuration details that an app requires to function properly is done after the app has been created in Benchling. When there are known configuration requirements, the next step is to start building your app’s manifest. This will allow you to define the configuration options required to power your app.

Defining an app manifest and configuration is especially useful when you want to install a single app on multiple Benchling tenants. For example, you might want to use the same app on your dev, test, and production environments, or you may want to distribute your app to other Benchling customers.

Distributing an App

App developers building a Benchling App to distribute to multiple customers or across multiple tenants should work with tenant admins to help them install their app. Developers should avoid having user accounts created and directly accessing the tenant(s) in question. Instead, the following process allows tenant admins to complete the installation themselves:

1. The app developer sends a tenant admin the following:
   1. The app’s manifest.yaml file
   2. The app’s recommended permissions (see Granting an app access for more info)
2. Using this information, the tenant admin can then install the app by:
   1. Creating new app from the manifest in the developer console
   2. Granting the app the relevant permissions
   3. Filling out the configuration fields
   4. Generating a new client secret
3. The tenant admin then sends the app ID, client ID, client secret, and tenant URL back to the app developer over a secure messaging system
4. The app developer stores these app details in a secure credential store accessible by the app

While the specific implementation of these steps will vary depending on your infrastructure, it’s critical that application sensitive details are kept secure in transit and at rest. For receiving the app details from the tenant admin, consider a shared vault solution like 1Password. For storing the app details in a secure credential store, consider something like AWS Secret Manager or similar functionality supported by your hosting provider.

With these steps complete, the app is fully installed and ready to run. To see an example of implementing an app manifest with an existing app, check out our guide to Building your first app with App Configuration

Manifest Reference

The full list of all supported config types can be found in the Benchling reference documentation; click the “Schema” view to see details on the config field types:

For convenience, here is an example manifest including every possible currently available config option:

manifestVersion: 1

info:
  name: My App Name
  description: A user understandable description of what the app does, 
  and support contact info.

configuration:
  # Benchling Schemas and Configuration
  - name: AA Sequence Schema
    type: entity_schema
    description: config option description
    fieldDefinitions:
      - name: Message
        description: field level description
      - name: Dropdown
  - name: DNA Sequence Schema
    type: entity_schema
  - name: Custom Entity Schema
    type: entity_schema
  - name: Container Schema
    type: container_schema
  - name: Plate Schema
    type: plate_schema
  - name: Box Schema
    type: box_schema
  - name: Location Schema
    type: location_schema
  - name: Result Schema
    type: result_schema
    fieldDefinitions:
      - name: entity
  - name: Run Automation Schema
    type: run_schema
  - name: Request Schema
    type: request_schema
  - name: Entry Schema
    type: entry_schema
  - name: Workflow Task Schema
    type: workflow_task_schema
    fieldDefinitions:
      - name: Task Input
        description: Workflow tasks can have input fields
    output:
      fieldDefinitions:
        - name: Task Output
          description: Workflow tasks can also have output fields
  - name: Dropdown
    type: dropdown
    options:
      - name: Option 1
      - name: Option 2
  - name: Workflow Task Status
  - type: workflow_task_status
  
  # Individual Benchling Objects
  - name: AA Sequence
    type: aa_sequence
  - name: Box
    type: box
  - name: Container
    type: container
  - name: Custom Entity
    type: custom_entity
  - name: DNA Oligo
    type: dna_oligo
  - name: DNA Sequence
    type: dna_sequence
  - name: Mixture
    type: mixture
  - name: Entry
    type: entry
  - name: Folder
    type: folder
  - name: Location 
    type: location
  - name: Plate
    type: plate
  - name: Project
    type: project
  - name: Registry
    type: registry
    
  # Custom Configs
  - name: Text Field
    type: text
  - name: Float Field
    type: float
  - name: Integer Field
    type: integer
  - name: Boolean Field
    type: boolean
  - name: Date Field
    type: date
  - name: Datetime Field
    type: datetime
  - name: Secure Text
    type: secure_text