How to connect a source
Use this guide when a program needs evidence from an external system (literature search, an electronic
lab notebook, a document library) or a source you cite by hand. You start with a program that has no
connection; you end with a connection record, a sync run recorded as skipped, and a source record in
Evidence. The steps need program.connections.manage, program.connections.sync and
evidence.sources.manage; reading needs the matching .read permissions.
Every provider is designed. A new connection starts as pending and a manual
sync finishes as skipped with a NotImplemented error entry, because the adapters
do not fetch data yet. The steps below record what the product is designed to do.
Prerequisites
- A program you can open (the program appears in your switcher).
- The permissions named in each step, for example through the
program_leadorprogram_ownerpersona.
Open Setup › Connections
In the rail choose Setup, then Connections in the panel (/p/<slug>/setup/connections). The page
lists the program’s connections with provider, status, health, enabled flag and last sync. The header
summarises the four providers and their release status. Needs program.connections.read.
Add a connection
Choose Add connection (needs program.connections.manage). In the dialog pick a Provider from
literature_search (“Literature search”), eln (“Electronic lab notebook”), document_library
(“Document library”) or analysis_tools (“Analytical and design tools”), give it a Name, optionally
pick a Stage (the program’s current stage is the default) and submit. The form calls
POST /programs/{program_id}/connections; the record appears with status pending until an operator
configures the provider secret. Secret values are never stored in the database: secret_refs hold
references only.
Trigger a sync run
Select the connection, then Sync now (needs program.connections.sync). This calls
POST /programs/{program_id}/connections/{connection_id}/sync and queues a sync run with trigger
manual. The run list under the connection (GET .../connections/{connection_id}/runs) shows it move
from queued to skipped once the worker claims it.
Register a source by hand
In the rail choose Evidence, then Sources in the panel (/p/<slug>/evidence/sources). Choose
Add source (needs evidence.sources.manage), pick a Kind (publication, eln_entry, protocol,
report, dataset or other), enter a Title, optionally a Citation, an External reference
(a DOI, URL or record id in the connected system) and a Summary, and submit. The source is created
with status pending and a “Saved” confirmation.
Link the source to a question
Open the source and link it to a question, finding or hypothesis (needs evidence.sources.link, route
POST /programs/{program_id}/evidence/sources/{source_id}/links with target_type in question,
finding or hypothesis). Findings that cite the source keep the link in source_ids.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Add connection is not shown | You lack program.connections.manage | Ask a program owner for the program_lead persona or a direct assignment |
The sync run stays queued | No worker process is running | Run make worker in api/ |
The sync run finishes skipped | Expected: every provider is designed | Nothing to fix; the error entry says NotImplemented |
403 with permission in the body | The route needs a permission you do not hold | The problem document names the missing key |
Related
- Products and the provider list on the API reference.
- How to run an evidence comparison.