Manage connections

A connection is how Meridian reaches an external system: its URL, its authentication, and the parameters its type declares. Plugins contribute the connection types (fhir-r4 of @posos/fhir, posos-api of @posos/posos, hermes of @posos/snomed); the instance declares the connections. An adapter, an event source or a node that requires a connection receives the one designated for it, or the default connection of its type.

Connections come from two places, which share one identifier space:

Nothing is copied from one to the other.

Before you start

• The plugin that contributes the connection type is loaded. The console's Plugins page lists the types under Connection types, with their parameters and the authentication schemes they accept.
• For a connection created in the console with a secret: MERIDIAN_SECRET_KEYS is set on the proxy and the endpoint, with the same key ring (see Manage credentials). The endpoint does not open the database: it reads the store's connections from the proxy, secrets sealed, and opens them with its own key.

1. Declare a connection in the manifest

connections:
  entrepot:
    type: fhir-r4
    label: Entrepôt FHIR du CHU
    baseUrl: https://fhir.chu.example/r4
    auth:
      scheme: oauth2-client-credentials
      tokenUrl: https://sso.chu.example/token
      clientId: meridian
      clientSecret: env:FHIR_CLIENT_SECRET
  posos:
    type: posos-api
    baseUrl: https://api.posos.co
    audience: "<client OAuth de la passerelle IAP>"
    auth: { scheme: ambient }
connectionDefaults:
  fhir-r4: entrepot
  posos-api: posos

• Keys other than type, label, baseUrl, timeoutMs, headers and auth are the type's parameters (audience, region for posos-api).
• A secret field of auth is written env:NAME; a literal secret makes the connection unusable. The variable must be set on every process that uses the connection: the proxy (event sources, terminology) and the endpoint (ports, nodes).
• The schemes and their fields are listed in Instance manifest.

Restart the proxy and the endpoint. A connection that fails its checks is logged at boot (connexion « <id> » du manifeste inutilisable : …) and shown with its issues in the console.

2. Create a connection in the console

Connections → Connexions sortantes → Nouvelle connexion:

1. Choose the type. The form shows its parameters and the schemes it accepts.
2. Enter an identifier (lowercase letters, digits and dashes), a label, the base URL and the parameters.
3. Choose the scheme. A scheme that needs a secret lists the credentials of the matching kind (basic, header, token, oauth2-client); Nouveau credential creates one in place.
4. Tick Connexion par défaut de ce type to make it the default.

A change applies to the next call: the endpoint reads the store's connections from the proxy at most every 10 seconds. The console refuses an identifier already used in the manifest, a scheme the type does not accept, and a credential of the wrong kind.

Deleting a connection is refused while it is the default of its type, is named by the manifest (ports.*.connection, terminology.*.connection, the connection parameter of a pulled inbound connection, sources.*.connection, connectionDefaults), or is designated by a node of a published workflow.

A connection type that is not reached over HTTP declares its URL schemes (for example smtp://relais.chu.local:25); a type whose plugin reads the secret itself (an SMTP client) is flagged in the connection form.

Inbound connections

An inbound connection receives messages of a format (HL7 v2, PN13…) through a transport (http, directory, mllp…). Create it in Connexions → Connexions entrantes (see Connect an EAI), or declare it in the manifest with format:

connections:
  bus-chu: { type: mllp, format: hl7v2, port: 2575, bindings: [hl7v2-adt-admission] }

The fields are listed in Instance manifest. A workflow's receiving trigger designates it by its identifier (connectionId).

An inbound connection whose type is an event source (fhir-poll, adsb-poll) is pulled: its source polls the external system with the connection's parameters, and the bindings enabled on the connection project the records it reads. It has no format:

connections:
  fhir-poll: { type: fhir-poll, connection: entrepot, intervalSeconds: 15, bindings: [fhir-creatinine] }

See Connect an event source and Instance manifest.

3. Designate the connection of a port, a source or a node

Without designation, a consumer uses the default connection of its type:

ports:
  patient:      { adapter: fhir }                    # default fhir-r4 connection
  prescription: { adapter: fhir, connection: autre-entrepot }
connections:
  fhir-poll:    { type: fhir-poll, connection: entrepot, intervalSeconds: 15 }

A source designates its connection through the connection parameter of its pulled inbound connection. In the console, that parameter lists the outbound connections of the type the source requires; Connexion par défaut du type leaves it empty.

A node that requires a connection designates it in the workflow (nodes.<id>.connection, the Connexion list of the node in the editor); without designation it uses the default connection of its type (the posos.* nodes). A node that requires a port, such as notify.send (port notification), accepts any connection whose type an adapter of the port requires, and without designation uses the port bound by the instance (ports.notification). GET /api/connections/types lists, for each type, the ports its connections serve (ports). See Workflow DSL — connection.

Verify

• GET /api/connections lists the connections of both directions (direction: inbound | outbound), the outbound ones of both origins (origin: instance | store) with their issues, and the defaults; GET /api/connections/types lists the outbound types.
• fhir-poll logs polling par la connexion fhir-r4 … at start (component sources, field connection: the pulled connection's identifier).
• Each request goes through a span connection.fetch with the attributes connection.id, connection.type and connection.revision.

Troubleshooting

• Connexions en conflit : connexion « <id> » définie dans le manifeste d'instance et en base. … at boot: the proxy does not start. Rename the connection in the manifest, or delete the store's one from a proxy still running on the previous manifest, then redeploy. The same applies to a default set on both sides.
• Aucune connexion par défaut pour le type « <type> ». …: set a default in the console or under connectionDefaults.
• Connexion « <id> » inutilisable : …: the issues name the cause (variable absent, credential missing or of the wrong kind, parameter missing).
• Credential « <name> » illisible : MERIDIAN_SECRET_KEYS absent sur l'endpoint. or … non chiffré : définir MERIDIAN_SECRET_KEYS sur le proxy.: set the same key ring on both processes.
• [fhir] config.baseUrl est déprécié …, [posos] POSOS_API_URL, POSOS_AUDIENCE et POSOS_REGION sont dépréciés …: the instance still uses the previous configuration, read for one version. Declare a connection of the type and remove the old keys.

Related

• Instance manifest — the connections and connectionDefaults fields.
• Manage credentials — credential kinds and encryption at rest.
• Connect a FHIR warehouse — the fhir-r4 connection in practice.
• Plugin manifest — how a plugin contributes a connection type.