Connector Pattern Guide
Use this engineering pattern when adding or reviewing a third-party connector node. The full guide, with the Go skeleton and the PR checklist, is tietai-hydra-platform/docs/CONNECTOR_PATTERN_GUIDE.md.
Two patterns
| Pattern | Where | Use when |
|---|---|---|
| A: node handler | pkg/node/handlers/<vendor>_node.go | The vendor has a multi-operation REST, FHIR or GraphQL API. The node has its own operation setting. Almost every EHR connector uses this. |
| B: driver | pkg/connector/<type>/ implementing connector.Driver (Connect, Disconnect, Test, Metadata, Read, Write) | The source is a uniform set of records (S3, GCS, FHIR Bulk Export). The pipeline node is generated automatically and named <driver-type>-connector. |
What a pattern A connector provides
Each connector is a node, so its contract is the node schema (Schema()), which the catalog API returns:
| Schema field | Requirement |
|---|---|
ID, Name, Description | The id is the node type: lowercase, hyphen-separated (for example webdoc-carasent). |
Category | ehr for every vendor-specific connector, including the SAP nodes. Generic standards nodes (FHIR client, FHIR query, FHIR CRUD) are healthcare. |
Inputs, Outputs | Typed ports. Outputs normally use the shared result / metadata / success envelope. |
Config | Every setting, with label, description, group (basic, auth or advanced), default and allowed values. |
Compliance, Capabilities, UseCases, ConfigHighlights, PerformanceTier | Descriptive metadata shown in the catalog and used by the Copilot. |
ErrorCodes | Known error conditions. The guide asks for at least <VENDOR>_AUTH_FAILED and <VENDOR>_REQUEST_FAILED. |
The connector must also be registered in pkg/node/handlers/registry.go and listed in inferCategory() in internal/api/rest/nodecatalog_handlers.go.
Authentication rules
- Declare every token, key or password as a
secret-typed config field. The configuration form renderssecretfields as secret inputs, and run configuration snapshots store them masked. - Authentication styles in use today: HTTP Basic (Acuity, Cliniko), Bearer token (Dentally, EasyPractice, Kaddio, WebDoc, Avon), a vendor header (Semble
x-token, SenseiX-Sensei-Api-Key, EXACTX-API-Key, Muntra Bearer plusX-API-Key), and OAuth2 client credentials (Epic, Cerner, athenahealth, athenaPractice, DIPS, Nextech, Allscripts, Dedalus, EMIS, MAXIMS). See the Connector Directory for the per-connector detail.
Output shape
A generic REST connector returns:
{
"result": "parsed JSON body, or {\"raw\": \"...\"}",
"metadata": { "operation": "...", "status_code": 200, "content_length": 123 },
"success": true
}
success is true only for a 2xx response. Downstream nodes depend on this shape, so build it with the shared helper wrapJSONResponse rather than inventing a new one.
Documentation checklist
When a connector is added or changed, update:
- Connector Directory
- EHR Connector Node Index
- The per-node docs under
tietai-hydra-platform/docs/nodes/ehr/<id>/(design.md,technical.md,usage.md) - The connectors index table in
tietai-hydra-platform/docs/CONNECTOR_PATTERN_GUIDE.md
Something unclear? Send documentation feedback by email.