Managing and Sharing Benchling Apps

The Benchling app framework provides features to make it easy to manage, install, and update apps across tenants. Benchling apps can support multiple versions to allow developers to make updates to their app manifest without causing disruption to existing installs. They can also be shared to multiple tenants to allow a single app to be installed across dev/test/prod environments or, in the case of 3rd party apps, across different tenants entirely. This guide covers these, as well as some other app management features designed to support cross-tenant app management.

📘

Legacy apps

Some of the features described on this page are not available for Legacy Apps. Apps created before July 15, 2024 and all apps on GxP (val cloud) tenants are Legacy Apps. Please refer to this guide for more information about the differences between the two frameworks.

App versioning

Benchling apps are versioned. We recommend following semver best practices for versioning your app.

A version update is required if your app is already shared with at least one other tenant and you want to make an update to the app manifest, such as adding or removing settings, app configurations, features, or subscriptions.

If an app is not already shared, it's possible to upload a new instance of a manifest via the API without creating a new app version. Please note that if your app is already installed on your home tenant, the manifest changes immediately take effect.

Installing an app on the home tenant

By default, any apps created in your tenant are not automatically installed on your tenant. This allows you to iterate on an app's settings, config, features, and event subscriptions without affecting any functionality in your tenant.

To install an app that was developed by a user on your tenant, go to Feature Settings > Developer Console > Apps and click on the app that should be installed. Navigate to Version History, select the version you wish to install, and click "Install", as seen in this screenshot:

On home tenants (i.e. the tenant that owns the app), it's possible to switch between different versions. This means you can go back to an older version of an app, if desired.

Sharing an app

Apps are also shareable to other tenants. This is helpful when promoting your app from a dev to a test tenant and eventually to a production tenant. It also allows 3rd parties to distribute their app more broadly.

It's important to note that an app version becomes immutable once it is shared. Making further changes to an app after it has been shared requires creating a new version of the app.

To share an app, open the app in the Developer Console and navigate to the Version History tab. Click "Share". This opens a modal that allows you to share the app with other tenants:

Entering a valid tenant URL or ID generates an install url that you can copy from the UI. You will need to click "Save" before this url becomes valid.

An admin of the other tenant can then use that url to install that specific version of your app on their tenant:

Apps that are shared with at least one other tenant require a valid webhook url. On Install, Benchling sends a v2.app.installed webhook to the app to inform the developer that their app has been installed. That webhook's payload includes the id of the installing tenant and the app version that has been installed.

Troubleshooting sharing issues

• Sharing is done per app version. Tenants that have access to one version of your app do not automatically have access to newer or older versions of the app. The same steps from above need to be repeated per app version.
• If a tenant has an IP allowlist, sharing via tenant url is not possible. The tenant_id needs to be entered in the share modal instead.
• If the install url appears inaccessible to a user of the installing tenant, please make sure that all of the following is true:
  • The user accessing the page is logged in.
  • The user accessing the page is a (tenant) admin.
  • The user accessing the page has FULL Developer Platform access.
  • At least one app version is shared with that tenant.

Publishing an app

Apps with the Audience set to Public can request for their app to be reviewed by the Benchling team. Apps that have been reviewed and approved may be made fully public. Once an app is fully published, any Benchling customer can install the app, regardless of whether they have been added to the allowlist or not.

3rd party apps that are available to install are listed under Technology Partners here.

Updating an app

Installing tenants do not automatically get access to new versions of an app. A new version needs to be shared with them for the admin to be able to upgrade to the latest version.

Updating an app works the same as installing the app. The same install url will now show an "Upgrade" button instead of an "Install" button if at least one version of the app is already installed on the tenant.

If the "Upgrade" button appears grayed out, there is no newer version of the app available to that tenant.

Currently, it's not possible to select a specific version to install. Installing tenants always get the most recent app version that is available to them (i.e. is shared with them).

App activation

Apps that subscribe to the v2.app.activateRequested webhook show a "Activate" button in the App Workspace.

Developers may decide to add an Activate button to their app if the app requires additional setup inside or outside of Benchling after the initial installation in order for the app to properly function. Clicking "Activate" can then be used to let the developer know - via the webhook that is sent to the app - that the setup has been completed.