How to connect an ELN
Use this guide when a program’s notebook entries should be readable by the Review and Plans agents and
launchable from the notebook. You start with a program and a partner administrator who can create an app in
the ELN tenant; you end with a connection in status connected, entries mirrored as connector_objects
and customer_internal documents, and the canvas button live in the notebook. Creating the connection needs
program.connections.manage; syncing needs program.connections.sync; reading needs
program.connections.read. The provider id is benchling, category eln, write policy read_only.
The connector is designed until the R1 gates pass, and no public developer tenant exists for this ELN:
until the partner’s sandbox tenant and app credentials arrive, the connection talks to the fake server
api/scripts/fake_benchling.py (port 8190) and everything it returns is labelled “Illustrative”.
Prerequisites
- A program you can open and the permissions above (the
program_leadorprogram_ownerpersona). - A partner administrator in the ELN tenant who can create an app from a manifest and scope it to the notebook projects this program may read.
- The order below matters: the app manifest needs the webhook URL, and the URL is issued when the connection is created.
Create the connection and copy the hook URL
In the rail choose Setup, then Connections (/p/<slug>/setup/connections), then Add connection
(needs program.connections.manage). Pick the provider ELN connector (benchling), give it a name and
set scope_rules.project_ids to the notebook projects the program may read. The form calls
POST /programs/{program_id}/connections; the record appears as pending with a
hook_url of the form https://api.trovensa.com/api/v1/hooks/benchling/<connection id>,
credential_class = service, write_policy = read_only and api_version = v2. Copy the hook URL.
Ask the partner administrator to create the app
The administrator creates the app from the manifest in the ELN’s developer console with the canvas
feature enabled, sets the webhook URL to the hook_url you copied, and scopes the app’s project access to
the same projects. The app issues client credentials (client id and secret). Every read in Trovensa runs
under this app identity, so its profile should be minimal: read-only access to the mapped projects only.
Store the credentials
Back on the connection choose Configure credentials and enter the client id and secret. They are written
to the secret store under <org_id>/connections/<connection_id>/<key>; the database keeps references only
(secret_refs). The worker caches the 15-minute token in memory and refreshes it at 12 minutes.
Run the health check and the first sync
Choose Check health: the adapter fetches the app’s signing keys, verifies the token and the project
scope, and writes connection.health. Then Sync now (needs program.connections.sync) queues a
sync_run with trigger manual. When it finishes the connection reads connected
and Setup › Connections › Objects lists entries as connector_objects with
external_version = <payload hash>@<modifiedAt>, external_modified_at and the review state in state.
Verify the webhook path
Ask the administrator to open a notebook entry in a scoped project: the canvas initialises through a signed
v2.canvas.initialized event to your hook URL, the gateway verifies the signature before parsing, writes a
webhook_deliveries row with signature_ok = true and outcome = enqueued, and the canvas shows “Check
this entry against the effective SOP”. Unsigned or replayed deliveries are stored as rejected without
payload.
What the entries become
Entry text and table notes are flattened into documents with licence_code = customer_internal and the
days structure kept in content_json; attachment metadata is synced and bytes fetched on demand under
25 MB; registry entities are linked by id only. Each entry maps to a sources row of kind eln_entry, and
experiments can reference it through eln_source_id. The notebook stays the scientific record: agents never
write into it, and the review state shown in Trovensa is labelled “recorded in the notebook”.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Health check reports a signature-key error | the app was created without the webhook URL, or with a different one | correct the URL in the app manifest; the connection’s hook_url never changes |
Deliveries appear as rejected | signature or timestamp outside the 5-minute window | check the tenant’s clock and the app’s signing keys; rejected rows carry no payload |
The sync finishes skipped | credentials not configured, or the connection points at the fake server without FAKE_BENCHLING_URL set | store the credentials, or start the fake server locally |
| Entries from another project appear | scope_rules.project_ids too wide | narrow the rule; Trovensa enforces it even when the app token is tenant-wide |
Related
- How to launch from your notebook.
- Connectors for the adapter, budgets and versioning rules.
- Partner onboarding runbook for the operator side.