Skip to content

Latest commit

 

History

History
181 lines (132 loc) · 6.95 KB

Install.md

File metadata and controls

181 lines (132 loc) · 6.95 KB
Raw

benchling-packager

The Benchling Packager automatically creates a dedicated Quilt package for every Benchling notebook, to help ensure all your experiment data is:

  • Findable
  • Linkable
  • Accessible
  • Interoperable
  • Reusable

within your AWS private cloud.

How it works

Benchling Packager is an example CloudFormation template for Benchling-Quilt integration. The template creates an AWS Lambda function that is triggered by Benchling EventBridge events.

The lambda will create or update a Quilt packages on the following Benchling EventBridge events:

  • v2.entry.created
  • v2.entry.updated.fields

If the notebook has an appropriate schema, the lambda will also back-update the Benchling notebook entry with the following fields:

  • Quilt+ URI
  • Quilt Revise URL
  • Quilt Catalog URL

Installation

You will need access to both the AWS Console and Benchling Admin Console to complete the configuration. You will also need:

  • Your Benchling tenant domain (e.g., <YOUR_TENANT> from <YOUR_TENANT>.benchling.com)
  • Your AWS Account ID (e.g. 12345689123)
  • The AWS Region (e.g., us-west-2) you want to process events in
  • An Event Bus Name (e.g., quilt-integration)

1. Create an event subscription in your Benchling tenant

From your Benchling tenant, use that event bus name and your AWS account ID to subscribe to Benchling events

  1. Go to https://<YOUR_TENANT>.benchling.com/event-subscriptions, or go navigate to the settings menu > Feature settings > Developer Console, which takes you to the Events page

  2. Click the “+” button, which should open the following modal: Create subscription modal

  3. Fill in the:

    1. AWS Account ID
    2. AWS Region
    3. Event Bus Name
    4. Event Types: v2.entry.created and v2.entry.updated.fields

  4. Click “Create"

This will also create a Partner Event Source in your AWS account.

2. Create a custom event bus in AWS

As soon as you create a new event subscription in Benchling, you should immediately create a corresponding event bus in AWS. Otherwise, the source may be automatically deleted, which would require a support ticket to restore.

  1. Go to the Partner Event Sources for your region.
  2. Click the name of the Partner Event Source created in the previous step, e.g. aws.partner/benchling.com/<YOUR_TENANT>/quilt-integration
  3. Click Associate with event bus
  4. Click Associate.

This will create a new event bus in your AWS account with the exact same name as the Partner Event Source. You will need this name when you create the CloudFormation stack.

Don't worry about creating an "Events Rule" in AWS. That will be handled via CloudFormation.

3. Setup Benchling app

It is best to run each stack using its own credentials.

3.1 Create a new Benchling app

You get these credentials by creating a Benchling app and giving it access to your tenant:

  1. In the Benchling Developer Console, click "Apps" (in the left sidebar, right above "Events)
  2. Click Create app -> From scratch
  3. Enter the App Name (and optional Description)
  4. Select "Manual" for Lifecycle Management
  5. Click Create

3.2 Create a new Benchling app secret

This takes you to the app settings page.

  1. Click Generate secret to create the Client Secret value.
  2. Use the "copy" icon on the right to copy the Client ID and Client Secret values for use later.

NOTE: You do NOT need to explicitly add the app to your tenant, since it was already created there.

3.3 Add App to the Organization

Admins can add apps in the organization page in the “APPS” tab:

  1. Profile -> Tenant Admin Console -> Organizations
  2. Select the organization you want to add the app to
  3. Click “Apps” tab
  4. Type the name of your app in "Search for an app"
  5. Click “Add App”
  6. Select the app you want to add

4. Create CloudFormation stack

  1. Download CloudFormation template here
  2. Go to the CloudFormation service.
  3. Select the region used in step 1.
  4. Click Create stack -> With new resources (standard)
  5. Under Specify template select Upload a template file
  6. Click Choose file and select benchling_packager.yaml which you downloaded earlier.
  7. Click Next and enter a stack name, e.g. benchling-packager
  8. Under Parameters:
    1. Enter the name of the event bus created at step 1 as BenchlingEventBusName.
    2. Enter the client ID from settings of app created at step 2 as BenchlingClientId.
    3. Enter the your Benchling tenant name (i.e. $BenchlingTenant in https://$BenchlingTenant.benchling.com) as BenchlingTenant.
    4. Enter the name of the S3 bucket to use for storing packages as DestinationBucket.
    5. Optional: change the PackageNamePrefix used when creating new packages (default: benchling/).
    6. Specify the hostname of your Quilt Catalog as QuiltWebHost
  9. Click Next, then click Next again
  10. Check I acknowledge that AWS CloudFormation might create IAM resources.
  11. Click Submit

4.1 Set app secret in CloudFormation stack

  1. Under Resources tab of CloudFormation stack find BenchlingClientSecret and click on its Physical ID.
  2. Click Retrieve secret value
  3. Click Set secret value (or "Edit" if it is already set)
  4. Enter as "Plaintext" the Client Secret ("cs_XXX") from the app generated at step 2

5. Create/update Entry schema

In order for the lambda to update Benchling with the package information, the notebook must have a schema containing exactly the following fields:

Name Required Multi-select Definition
Quilt+ URI Text
Quilt Revise URL Text
Quilt Catalog URL Text
Sentinel Integer

You can either create a brand-new schema, or add these fields to an existing schema. Each new notebook will need to have this schema applied to it. You can either do this manually, or by adding the schema to a template.

See Benchling docs for more information.

6. Test

Create new Benchling entry with schema created at the step 5, or set this schema for existing entry.

Within minutes the package will be created and the entry fields will be updated with links to this package.

To refresh Quilt package from entry again you have to update Sentinel field with a different value.