Shareable Apps FAQ

📘

Want to try Shareable Apps?

Contact your Benchling account team or [email protected] to get early access.

Benchling has released a new standard called Shareable Apps (formerly known as Global Apps). Shareable Apps are an improvement over the existing Benchling apps framework, designed to streamline the experience of creating and installing apps. Shareable Apps have identity and configuration details defined independently from the tenant in which they were created, which allows them to be easily shared via an install link and installed to any tenant without the need for manifest uploads.

Shareable Apps are an improvement on the existing Benchling App framework, instead of a net-new feature, which can make it difficult to understand the ways in which Shareable Apps differ from legacy Benchling apps. This resource addresses a number of common questions about Shareable Apps

What are Shareable Apps?

A Shareable App is a Benchling app whose definition is stored globally, in a new tenant-independent apps service. This is in contrast to legacy Benchling apps, whose definition was stored only in the tenant in which it was created.

This new framework gives Shareable Apps a number of advantages:

• App developers can create a single app definition that can be managed and updated in one place
• App developers can share their app easily to any Benchling customer using a single install link
• Tenant admins can easily install an app from a listing page, without needing to work with local manifest files

The shift to Shareable Apps provides users a more intuitive app installation flow that resembles how users are accustomed to installing apps in other systems, and provides a number of advantages to app developers when building, versioning, and distributing Benchling apps.

How are Shareable Apps different from legacy Benchling apps?

There are a few differences in the way Shareable Apps behave compared to legacy Benchling apps:

• Legacy Benchling apps existed entirely in a single tenant, and there was no distinction between “creating” and “installing” a Benchling app. While app framework features like App Manifest and App Configuration existed to improve usability and portability, a distinct copy of the app needed to be created in each new tenant. Maintaining consistency across many tenants required depending on an external app manifest file.
• Shareable Apps exist in a dedicated global service, and have a definition that exists apart from any specific installation. Shareable Apps are created a single time, and can then be installed across multiple tenants. Shareable Apps are fully portable between tenants since they can be installed directly from this definition, automatically ensuring consistency and allowing the app to be managed in one place.

What specific features and functionality is different between Shareable Apps and legacy Benchling apps?

At a more granular level, the shift to Shareable Apps has a number of impacts for folks working with apps:

App Creation

• Previously, there was little distinction between creating and installing a Benchling app. App definitions were created (either directly or via an app manifest) in the same tenant to which they were to be installed, at the same time.
• Now, Shareable Apps are created and installed separately. App definitions are now created and published by app developers in a single tenant; sharing and installing the app is done separately by tenant admins.

App Installation

• Previously, apps were installed when the definition was created in a tenant. Further manual intervention was required based on whether the app was created "from scratch" or "from a manifest." In both cases, additional steps were required to complete the app installation and ensure the app was activated.
• Now, Shareable Apps are installed directly from the app's listing page with a single click. Because the listing page is based on the tenant-independent app definition, installing the app is completely distinct from creating it.

App Versioning

• Previously, apps did not natively support versioning. App developers needed to create a new app manifest file for the new version. Tenant admins needed to upload the new manifest file, essentially creating a new app.
• Now, Shareable Apps natively support versioning. App developers can create, test, and publish new versions of their app in their home tenant. Tenant admins can update their installed apps in-place.

Versioned/Unversioned Data

• Previously, because apps did not support versioning, all data in the app definition was considered “unversioned.” Updating app definition data (e.g. webhook URL, configuration options) required manual intervention by a tenant admin.
• Now, Shareable Apps support both "version" and "unversioned" data in app definitions. Versioned data can only be updated by publishing a new app version, while unversioned data can be updated at-will by the app developer. Versioned data includes data that directly impacts a particular installation, like an app’s configuration options or description. Unversioned data includes data that is tenant-agnostic and managed by the developer, like an app’s webhook URL and public key.

How do I create/manage Shareable Apps?

A key difference between Shareable Apps and legacy Benchling apps is that the app definition is distinct from a particular installation. An app developer creates an app definition in a single tenant, referred to as the app’s home tenant. From this home tenant, an app developer can publish new app versions and update unversioned app data, among other things. Admins looking to use the app can install it from this definition to their tenant(s); a tenant that has installed an app is referred to as an installing tenant.

Managing the app definition in an app’s home tenant does not directly impact the app’s installation in an installing tenant; unversioned data does not interact with installing tenants and can be updated at-will, while publishing new app versions will prompt installed tenant admins to update the app to the most recent version.

Are all Shareable App definitions publicly available?

No. All Shareable app definitions are stored in a global service and have the potential to be installed across any number of tenants, but access to the app definition is managed by both Benchling and the app developer. Shareable Apps can be configured with three levels of availability:

• Private - A private app is intended to be installed by a single customer, though not necessarily a single tenant. A private app will never be published or distributed by Benchling outside of this context.
• Limited availability - A limited availability app is intended to be installed by some number of customers, but not made available for broad distribution. A limited availability app will not be published or distributed by Benchling, but can be made available to a set of tenants based on an allowlist defined by the app developer.
• Public - A public app is intended to be installed by many customers and distributed broadly. A public app can be published and distributed by Benchling, pending review, and is made available to all tenants.

What do I have to do to migrate my apps as an app developer?

Reach out to your Benchling representative to enable Shareable Apps in your tenant. Once Shareable Apps are enabled, you will need to recreate your app as a Shareable App. After recreating your app as a Shareable App, you will likely need to make some modifications to your app code:

1. Update your app to use a single set of credentials, instead of a separate set of credentials per installed tenant. A shareable app now has a single client ID and client secret, instead of a distinct pair for each tenant. This set of credentials is used to generate tenant-specific access tokens for each installing tenant (see below)
2. Update your app to use the /token endpoint to create tenant-specific access tokens, if it doesn’t already. Most apps should already depend on the /token endpoint, in which case no change should be required. Note that the client_id and client_secret values provided to this endpoint are no longer tenant-specific; instead, they are the app’s only set of credentials.
3. Update your app to deprecate reading credentials from lifecycle webhooks, as this no longer applies to Shareable Apps. Most apps use a MANUAL lifecycle, in which case no change should be required. Apps that use an AUTOMATIC lifecycle and obtained tenant-specific client credentials via a lifecycle webhook should no longer do so, instead opting to use their app-specific credentials.

With these steps complete, your app can now be installed to other tenants as a Shareable App. Tenants with legacy installs (i.e. installs of the old legacy version of your app) should uninstall the old app version, and install the new shareable version of the app.

What do I have to do to migrate my apps as tenant admin with installed apps?

No immediate action is required to keep existing apps functioning. Migrating existing legacy apps depends on who created them:

1. If you have installed Benchling apps where you or another user in your tenant is the app developer, follow the steps above under What do I have to do to migrate my apps as an app developer?
2. If you have installed Benchling apps where Benchling is the app developer, your apps are likely already in the process of being migrated. If you have not been contacted already, reach out to your Benchling representitive for more information.
3. If you have installed Benchling apps where a third party is the app developer, contact the third party for more details on when and how they will migrate the app.

How do I install a Shareable App?

Shareable Apps have a listing URL from which they can be installed. From the app’s homepage in the app workspace of the home tenant, you will find the App Listing button:

Clicking will bring you to the app’s listing page, where the app definition lives in Benchling. The URL will have the following format:
https://<tenant_subdomain>.benchling.com/app-catalog/apps/<definition_id>/install

This URL is the mechanism by which the app can be installed to other tenants. The definition_id parameter is the app definition ID, and remains constant. The tenant_subdomain parameter is a particular tenant’s subdomain, and varies based on the specific tenant to which the app should be installed.

A tenant admin looking to install the app must navigate to this URL using their tenant subdomain and the app’s definition ID, whereby they will see the listing page in their own tenant and can click “Install.”