How to launch from your notebook
Use this guide when you have just finished a notebook entry and want it checked against the effective SOP
without leaving the ELN. You start in the notebook entry with the Trovensa canvas visible; you end in a
console thread pinned to that entry, with a check bound to an SOP version and its findings sent to QA.
Launching needs program.threads.use on the program the connection belongs to; the check itself runs under
review.agents.use.
Nothing runs before a person is authenticated. The click in the notebook only mints a one-time launch id with a 10-minute expiry; the check starts after you sign in to Trovensa and the plan card is approved. Trovensa writes nothing into the notebook: you fix the entry yourself.
Prerequisites
- The program has an ELN connection in status
connectedwhose app has the canvas feature, and the entry belongs to a project inscope_rules.project_ids. - Your Trovensa account; where the organisation has mapped notebook users to Trovensa users by e-mail, the same person must click and sign in.
Click the canvas button in the entry
In the notebook entry the Trovensa canvas (rendered when the app handled v2.canvas.initialized) shows
“Check this entry against the effective SOP”. Click it. The ELN posts a signed canvas interaction to
POST /api/v1/hooks/benchling/{connection_id}; the gateway verifies the signature before parsing, writes a
webhook_deliveries row, mints a launch_ids row (context = {object_type: entry, external_id, payload_hash, vendor_user_id}, expires_at = now + 10 min), renders Open in Trovensa into the canvas
and answers 202 within the ELN’s 3-second window.
Open Trovensa
Click Open in Trovensa. The browser lands on /launch?id=<launch id>, which stores the id in
sessionStorage, signs you in through the identity provider if needed, and calls GET /api/v1/launch/{launch_id}.
The API checks expiry and single use, resolves the connection to its program, requires program.threads.use
there, compares vendor_user_id with your account where a mapping exists (otherwise the thread header names
who launched it), creates a thread with launch_context pinned to the entry, and audits launch.consume
with both ids. You arrive at /p/<slug>/console/<thread id> with the composer pre-filled.
Approve the plan
The plan card reads, for example: “Check entry EXP-0417 (content hash 9f3a…, modified 2026-09-11) against
SOP-BA-012 v3.1. Bound to v3.1 (effective 2026-05-02, inferred from first observation); change the binding
if the work was done under another version.” The version is chosen by the automatic rule (effective at the
entry’s last modification). If the work was done under another version, choose Change binding, pick the
version and give a reason; the check then carries binding_rule = manual and your binding_reason. Press
Enter to approve.
Read the deviation table
The run streams a deviation_table artifact onto the canvas: each row is a review finding with its
requirement code, severity, the cited clause (page and paragraph of the SOP text) and the cited passage of the
entry. The run rail shows “Bound to SOP-BA-012 v3.1 (effective 2026-05-02, inferred from first observation)”
and the model configuration record.
Fix the entry and send to QA
Correct the entry in the notebook yourself; the review state Trovensa shows for it is labelled “recorded in
the notebook”. Then press . on the check and choose Send to QA. Holders of review.findings.approve
receive an approval_requested notification and decide each finding (accepted, dismissed or resolved)
from the e-mail deep link; their decisions are audited with actor_kind = human.
What the records look like
A checks row with target_type = eln_entry, target_id pointing at the connector_objects row,
target_ref = benchling:entry:<id>@<hash prefix>, sop_version_id, binding_rule, requirements_hash,
check_logic_version, agent_version_id and target_reference_at; review_findings with chunk_refs; a
thread whose launch_context names the entry. If the entry changes afterwards, a new check against the new
content hash carries supersedes_check_id.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| “This launch link has expired” | more than 10 minutes passed, or the id was already used | click the canvas button again |
| “You are not the person who launched this” | the mapped notebook user differs from your account | sign in as that person, or ask an administrator to fix the user mapping |
403 with program.threads.use | your persona cannot start threads in that program | viewer reads only; ask for scientist or a direct assignment |
| The canvas shows no button | the app lacks the canvas feature or the project is out of scope | see How to connect an ELN |