App Workspace & Configuration
App Workspace & Configuration
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.
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 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:
- App Manifest: A
yamlfile that serves as the environment-independent definition of the app. The manifest is stored externally, usually alongside the app code.
- 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:
- The app developer sends a tenant admin the following:
- The app’s
- The app’s recommended permissions (see Granting an app access for more info)
- The app’s
- Using this information, the tenant admin can then install the app by:
- Creating new app from the manifest in the developer console
- Granting the app the relevant permissions
- Filling out the configuration fields
- Generating a new client secret
- 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
- 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
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
Updated 20 days ago