Benchling Connect Installation Guide

Achala
Achala
  • Updated

Audience

✔  External

✔ Partners

✔ Internal

 

Purpose

This guide outlines the steps required to install a Benchling gateway on a Window Server with an example of a generic file-watcher adapter on your tenant.

Please contact Benchling support for Access Provisioning and Adapters enablement.

 

Verify Instrument Server & Network Setting

Port

If your network settings only allows traffic through particular ports, check id the traffic is being allowed via port 443. 

This can be verified by running the following command in PowerShell:

Test-NetConnection -Port 443 -ComputerName benchling.com -InformationLevel Detailed

Endpoints

If your network settings only allows traffic through particular endpoints, explicitly add these endpoints outlined in the screenshot below (see this AWS documentation for more details):

region in these endpoints should match the AWS region of the tenant (e.g. us-west-2)

  • *-ats.iot.region.amazonaws.com
  • *.credentials.iot.region.amazonaws.com
    • These two correspond to correspond to iotDataEndpoint and iotCredEndpoint as found in the EffectiveConfig.yaml  under “C:\benchgw\v1\config” folder (see below) – if more restricted network settings, these can be added instead of the above two endpoints

effectiveConfig-yaml.png

    •  
  • greengrass-ats.iot.region.amazonaws.com
  • *.s3.amazonaws.com
  • *.s3.region.amazonaws.com

Executable Permissions

If the above settings (for ports or endpoints) need to be changed on a per-application basis (e.g. if they use a service like Netskope), the applications that need to be granted permissions are:

  • greengrass.exe
  • java.exe
  • Python.exe

Proxy Setting Check

Check for proxy settings on the PC where the gateway will be installed. Proxy settings can be checked by:

  1. Open “Proxy Settings”

  1. Within the Proxy view below, check if there is any proxy info:

    • If there is a script in the Script address box (something like http://some-internal-url/wpad.dat), and you can put the address in a browser URL box and it will download the config file
      • In the downloaded config file there are probably a lot of different proxy addresses, you should pick the one that corresponds to the lab PC's location as best as possible
    • If there is nothing within this proxy setting view,  you may be using some other type of network security software.
      • If none, skip to the next step of downloading the gateway.
  1. The proxy info will be used and defined during the gateway installation 

 

Supported platform for Benchling Gateway:

  • Architecture:
    • X84_64
  • Versions:
    • Windows 10
    • Windows 11
    • Windows Server 2019
    • Windows Server 2022

 

Gateway Installation with Windows Installer

Benchling Tenant Setup:

Gateways are created in Benchling and provide installers for the Windows system attached to your instrument. There is one gateway per instrument PC. 

Navigate to “Feature Settings” → “Run Schema” → “Instrument Gateways”.  

In the upper right corner, click the Download Gateway”  dropdown button:

 

Clicking "Download Gateway" will download the installer file ("BenchlingGateway.*-signed.msi") and prompt the following messages.

Clock "Generate New Token" to download the token file ("Installer_token_file.json") then click the “Done” button:

 

 

Benchling Gateway Setup:

These steps are performed on the PC which will host the instrument files. 

  1. Double-click the BenchlingGateway*.msi file to begin the installation. Click next to continue.

  1. Accept the terms of the License Agreement and click Next to continue.

  1. Accept or change the install path (default: C:\Program Files\Benchling Gateway\) and click Next to continue.

  1. Enter the name of the gateway (e.g. the name of your instrument server that you can readily identify), and click Next to continue.

  1. If your network requires the user of a proxy server, you can enter these settings here. Contact your network administrator if you need assistance. 
    • A checkbox with the following message will appear - “Network connection successfully verified”. When you see this message, click Next to continue.

  1. Click the “Open…” button  and choose the installer json file that you downloaded from your tenant. After selecting the installer JSON file, the token will be verified. The processing time can take approximately 5 seconds. 

    • This token file contains authentication and expires after an hour. Suppose you’re installing after the token has expired. In that case, you can download a new one from your tenant by going back to the Instrument Gateways page, clicking on the down arrow ( 🔽) next to the Download button, and generating a new token:

    • When the token is verified, you’ll see a screen like the one below. Click the “Next” button to continue. 

  1. Click “Installer” to complete the Gateway installation.

  1. The installation process will take approximately a minute: 

  1. While installing on the PC, back on your tenant, you will see the pending gateway installation.

  1. When the installation is complete, click Finish.

  1. When you return to your tenant, the gateway status should appear as Open.

    • If the status does not show up as open, please wait a minute and refresh the page. If it still does not show as Open within a few minutes, please get in touch with Benchling Support.

 

 

Gateway Uninstallation with Windows Installer

These steps are performed on the PC which will host the instrument files. 

  1. Double-click the BenchlingGateway*.msi file downloaded from the installation step to begin the uninstallation. Click next to continue.
  2. Click the "Remove" option to remove the existing Benchling Gateway. Click next to continue.
  3. Click the "Remove" button to continue.
  4.  Review the *.msi that will be removed from the computer. Click the "Yes" button to continue.
  5. When the uninstallation is complete, click Finish. 

 

Adapter Specific Guides

  • For the instrument specific adapters please see this section of the Help Center                 
  • For the Benchling File Watcher Adapter please see the setup steps below

 

Schema Setup

Connections

You can now create a Connection from the Instrument Gateway.

Browse to the Connections application and choose Connections. At the top, click the [+] to create a new File Watcher Adapter connection. 

The list of adapter(s) in the dropdown are managed via Adapter Allowlist 

Give the connection a meaningful name like instrument name/type, select the Instrument Gateway you created in the previous step.

Set the Directory and Input Directory to be the directory in the Windows PC

 

Ensure that benchgw_user has access to your directory by:

  • Right-click [Your Directory] Security (tab) Click "Edit" Button Click "Add" Button Add benchgw_user Apply the permission below
      • Read (for Directory - output file monitoring purposes)
      • Write (for Input Directory - send an input file from Benchling)
  • Note: benchgw_user is a local user account that Benchling creates upon the installation of the gateway via Windows Installer. This account will be used to run the gateway service

 

Once this is created, the Instrument Service will push down the file adapters to the PC and install it. This takes a few minutes. You will be able to see the installation activity in:

  • c:\benchgw\v1\logs\greengrass.log 
  • c:\benchgw\v1\logs\file-watcher-adapter.log

 

Run

A Lab Auto Run schema can now be configured with the Connection Schema:

 

 

Results within a Run

  • You can use the existing Result schema or create a new Result schema from the associated Connect instrument data
  • Set a default Allotrope conversion type as a part of the Run schema configuration. Setting this default will eliminate the second-step to choose a Allotrope conversion type within the “Retrieve Data” modal in a run. 
    • Allotrope conversion type(s) are .CSV files converted from the raw instrument output files
      • For example with plate readers, it is expected that the Allotrope file could result in the creation of up to 3 canonical Allotrope typed .CSVs:
        • Measurement - values provided directly from the instrument
        • Processed data - values derived from measurement, dependent upon user-defined parameter
        • Well data - each row corresponds to a plate well and contains the corresponding measurements and processed data that can be rendered on a single line
    • ⏺️ See the walkthrough video and learn how to default the conversion type as a part of the Run schema 
      • If the default is set as “None” in a run schema config, the "Retrieve Data" modal in a run will display the two-step for users to select the conversion type at the time of run execution, as shown in the example below:

 

 

Was this article helpful?

Have more questions? Submit a request