Skip to main content

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​

PatternWhereUse when
A: node handlerpkg/node/handlers/<vendor>_node.goThe vendor has a multi-operation REST, FHIR or GraphQL API. The node has its own operation setting. Almost every EHR connector uses this.
B: driverpkg/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 fieldRequirement
ID, Name, DescriptionThe id is the node type: lowercase, hyphen-separated (for example webdoc-carasent).
Categoryehr for every vendor-specific connector, including the SAP nodes. Generic standards nodes (FHIR client, FHIR query, FHIR CRUD) are healthcare.
Inputs, OutputsTyped ports. Outputs normally use the shared result / metadata / success envelope.
ConfigEvery setting, with label, description, group (basic, auth or advanced), default and allowed values.
Compliance, Capabilities, UseCases, ConfigHighlights, PerformanceTierDescriptive metadata shown in the catalog and used by the Copilot.
ErrorCodesKnown 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 renders secret fields 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, Sensei X-Sensei-Api-Key, EXACT X-API-Key, Muntra Bearer plus X-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:

  1. Connector Directory
  2. EHR Connector Node Index
  3. The per-node docs under tietai-hydra-platform/docs/nodes/ehr/<id>/ (design.md, technical.md, usage.md)
  4. The connectors index table in tietai-hydra-platform/docs/CONNECTOR_PATTERN_GUIDE.md

Something unclear? Send documentation feedback by email.