Global Apps FAQ

📘

Want to use Global Apps?

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

Benchling has released a new standard called Global Apps. Global Apps are an improvement over the existing Benchling apps framework, designed to streamline the experience of creating and installing apps. Global 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.

Global 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 Global Apps differ from legacy Benchling apps. This resource addresses a number of common questions about Global Apps

What are Global Apps?

A Global 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 Global 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 Global 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 Global Apps different from legacy Benchling apps?

There are a few differences in the way Global 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.
• Global Apps exist in a dedicated global service, and have a definition that exists apart from any specific installation. Global Apps are created a single time, and can then be installed across multiple tenants. Global Apps are fully portable between tenants since they can be installed directly from this global definition, automatically ensuring consistency and allowing the app to be managed in one place.

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

At a more granular level, the shift to Global 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, Global 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, Global 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, Global 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, Global 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 Global Apps?

A key difference between Global 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 Global App definitions publicly available?

No. All Global 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. Global 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 Global Apps in your tenant. Once Global Apps are enabled, you will need to recreate your app as a Global App. After recreating your app as a Global 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 global app now has a single client ID and client secret, instead of a distinct pair for each tenant. This set ofcredentials 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 global credentials.
3. Update your app to deprecate reading credentials from lifecycle webhooks, as this no longer applies to Global Apps. Most apps used a MANUAL lifecycle, in which case no change should be required. Apps that used an AUTOMATIC lifecycle and obtained tenant-specific client credentials via a lifecycle webhook should no longer do so, instead opting to use their global app credentials.

With these steps complete, your app can now be installed to other tenants as a Global 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 global 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 Global App?

Global 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 global 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.”