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
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
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)
- 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
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:
Proxy Setting Check
Check for proxy settings on the PC where the gateway will be installed. Proxy settings can be checked by:
- Open “Proxy Settings”
- 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.
- 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
- The proxy info will be used and defined during the gateway installation
Supported platform for Benchling Gateway:
- 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.
- Double-click the BenchlingGateway*.msi file to begin the installation. Click next to continue.
- Accept the terms of the License Agreement and click Next to continue.
- Accept or change the install path (default: C:\Program Files\Benchling Gateway\) and click Next to continue.
- Enter the name of the gateway (e.g. the name of your instrument server that you can readily identify), and click Next to continue.
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.
- 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.
- Click “Installer” to complete the Gateway installation.
- The installation process will take approximately a minute:
- While installing on the PC, back on your tenant, you will see the pending gateway installation.
- When the installation is complete, click Finish.
- 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.
- Double-click the BenchlingGateway*.msi file downloaded from the installation step to begin the uninstallation. Click next to continue.
- Click the "Remove" option to remove the existing Benchling Gateway. Click next to continue.
- Click the "Remove" button to continue.
- Review the *.msi that will be removed from the computer. Click the "Yes" button to continue.
- 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
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:
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
- 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:
⏺️ 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:
- Allotrope conversion type(s) are .CSV files converted from the raw instrument output files