Benchling Connect Installation Guide

Purpose

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

Please contact Benchling support for Access Provisioning and Data connectors 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

• •  
• 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”

2. 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.

3. The proxy info will be used and defined during the gateway installation 

Supported platform for Benchling Gateway:

• Architecture:
  • x86_64 (also known as x64)
• 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 Multi-Tenant 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.

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

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

Note: On this page, if the chosen directory already exists, or if the benchgw_user user already exists, a warning will appear. (this may occur if either the directory or the user was leftover accidentally from a previous uninstallation)

4. Select which tenant(s) you want to install.

Due to limitations in the Windows Installer software, the “Will be installed on local hard drive” and “Entire feature will be installed on local hard drive” options are identical. 

“Entire feature will be unavailable” means that gateway will not be installed, or it will be uninstalled if it previously existed.

5. If your network requires the user of a proxy server, you can enter these settings here. Contact your network administrator if you need assistance. The installer will automatically try to verify that it can access benchling.com through the given settings.

   A couple of notes:

   • A checkbox with the following message will appear - “Network connection successfully verified”. When you see this message, click Next to continue.
   • Make sure that the URL starts with http:// (particularly if you see an error along the lines of “scheme not supported”)
   • Even if no username or password is required for the proxy, you may find that it still requires something to be set in both fields to succeed. Any text can be entered in both fields, as long as they are not empty

6. On the instrument gateways page, for each gateway being installed, go to the tenant associated with each gateway and download an installer token.

• • 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:

• • Now, upload the installer token: 

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

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

8. The installation process will take approximately a minute: 

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

10. When the installation is complete, click Finish.

11. 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.

Upgrading from the v1.0 Installer

If there is already a gateway on the machine that was installed using the initial v1.0 installer, the v1.1 installer will walk the user through the process to migrate that gateway to the new installer.

1. If an existing gateway is detected, this page will appear:

2. As per the instructions, please choose exactly one tenant to designate the originally-installed gateway to.

   

   • • If the user accidentally doesn’t select only one tenant, this error will appear:

3. The installation will proceed as before.

Adding (or Removing) New Gateways

1. To add or remove additional gateways after the initial install (or the upgrade flow described above), go to the “Add or Remove Programs” page in Control Panel, find “Benchling Gateway” and click “Modify”, and then click the Change button:
   

2. On this page, now select or unselect all desired tenants. 

   For any tenant which already has a gateway present, it will be shown as “installed” – mark it as “unavailable” to uninstall it. 

   
3. On the next page, any existing gateways will have their names displayed, along with the tenant they came from. If there was a gateway that was migrated from the v1.0 installer, we are unable to display this metadata at this time; instead, it will say “Migrated from single-tenant installation”.
4. The installation will proceed as before.

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. 

Note on Uninstalling a v1.0 Gateway

After upgrading a v1.0 gateway to v1.1, if the user then wants to uninstall that gateway, they should first run the uninstall process for v1.0, before running the uninstaller for v1.1. These can be uninstalled through the “Add (or remove) programs” section. 

If this is accidentally done in the reverse order, the user may encounter issues with future installs. To fix this, full cleanup can be performed by downloading this official troubleshooting tool from Microsoft, opening the tool, and uninstalling any remaining Benchling Gateway program(s) that are present.

Common Errors

Another Installation is in progress

You may occasionally encounter this error:

If this happens, open Task Manager, find the Windows installer main task, right click and choose End task. Then, run the installer again as before.

At this point, the gateway will have already been created in Benchling. Make sure to archive the gateway on the Instrument Gateways page to avoid confusion.

Troubleshooting

Folder Structure

Upon installation, these are the folders and files that should appear in the designated directory. The gws folder contains the gateways themselves, the jdk folder contains the JDK we install, and the installation.manifest contains important metadata, and should not be modified.

Inside of the gws folder are the individual gateways, one folder per gateway.

If an upgrade was performed from a v1.0 gateway to a v1.1 one, there will instead be a primary folder for that gateway, and a primary.manifest file that indicates which type of tenant (production, development, or test) the v1.0 gateway has been mapped to.

For additional troubleshooting of unexpected gateway behavior, please go to the logs directory inside the folder for the gateway in question. The default-adapter and greengrass log files will be most helpful in particular if consulting with the Benchling team. 

Data Connector Specific Guides

• For the instrument specific data connectors 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 data connector(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 data connectors 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: