Introduction

FerroFED is a pure-Rust openEHR federation gateway, one of the FerroHEALTH family. It sits in front of several openEHR CDRs as a transparent ITS-REST intermediary. A client sends it an ordinary AQL query with no federation syntax, and gets back an ordinary ITS-REST result set whose meta.federation names each node with its status. The gateway resolves the patient first, outside the query, through an identifier cross-reference service. It then sends each node standard AQL scoped to that node’s own ehr_id, so no request the gateway composes for a node carries a directly identifying patient identifier, and it merges the answers with each node’s provenance. It holds no clinical data of its own.

FerroFED implements the openEHR Federation Working Group’s Federation Tier with AQL specification, release 1.0.1, and reaches every node over openEHR ITS-REST 1.1.0.

This book covers FerroFED alone. What every FerroHEALTH product shares is in the family book: how the products fit together, the manufacturer, Cadasto B.V., with its security policy and the Cyber Resilience Act from the manufacturer’s side, and licensing and trademarks.

See how it works: the gateway in diagrams.

What it does today

The latest release ships the ferrofed binary for Linux and the image ghcr.io/ferrohealth/ferrofed, both signed, and a compose.yaml that runs the gateway alone in front of your own CDRs (The gateway from a release). The quickstart runs it beside four member CDRs. This book describes the gateway as it is built on main, and the changelog says which release first shipped each part. Over the members of a registry, the gateway:

• answers the federated query, POST {base}/v1/query/aql and its GET form, with one ITS-REST RESULT_SET and a meta.federation report that names every member with its status;
• resolves the patient through an IHE PIXm PIX Manager (ITI-83), after an IHE PDQm query (ITI-78 or ITI-119) where the client names the patient by an identifier the cross-reference does not know, and refuses any query that would carry the patient identifier to a node;
• can ask only the members that may hold the patient, localized through IHE XCPD (ITI-55), the Dutch NVI or the PIX Manager, can leave out the members a consent pre-filter such as the Dutch Mitz denies, and can read its members from an IHE mCSD care services directory;
• authenticates to each node as itself, with an OAuth 2.0 token, by client credentials or token exchange and optionally bound with DPoP, a token of the Dutch Nuts or FAPI 2.0 track, or a static credential, and tells each node who is asking in a token it signs for that node;
• audits every IHE transaction it makes or receives to an ATNA Audit Record Repository;
• fails a query when a node it asked does not answer, unless you ask for a partial answer, and shapes the merged rows as one CDR would: ORDER BY with LIMIT, bounded OFFSET pages, DISTINCT, recombined aggregates and opt-in de-duplication of copied versions;
• lets you direct a query at named nodes, in the AQL or in a header;
• routes the EHR resources under a path ehr_id to the one node that holds that EHR, and a versioned write only to the CDR that controls the version;
• sends a template or another definition request to the node you name, and can fan a template upload out to several;
• holds stored queries itself, as immutable versions it runs by name, and can distribute them to the members;
• describes itself at OPTIONS {base}/;
• gives you, the operator, a check to run before you admit a node, a registry reload on SIGHUP, health probes, metrics for Prometheus or an OpenTelemetry collector, and traces over OTLP.

Every client authenticates with an access token from an issuer you trust (Client authentication). Each page says what is built, and the claims page lists the limitations to know before you deploy it.

How this book is organised

The four parts follow what you came to do.

• Evaluate: whether FerroFED fits your problem. How the gateway works, one question per page, what the Federation Tier is, what FerroFED claims, the conformance matrix and the obligations checklist, the version pins and the licence.
• Integrate: what a client sends and what it gets back.
• Operate: installing, configuring and running the gateway, what it needs around it, and what each release added.
• Contribute: how the work is tracked and which checks a change has to pass.

The tracker is the scope. Open issues are the worklist, milestones are releases, and the milestones page is the public view of both.