1 Introduction

Perfuse moves clinical messages between systems that were never designed to talk to each other. A laboratory sends results in HL7 v2; the practice management system expects them with different field positions, a different patient identifier and an acknowledgement within five seconds. Something has to sit in the middle, and that something is an integration engine.

This manual describes what Perfuse does, every option it accepts, and — where a decision is not obvious — why it works the way it does.

1.1 What Perfuse is for

A single interface between two clinical systems is commonly costed in the tens of thousands, with fifteen to twenty per cent of that again every year in maintenance. Much of that cost is not the work; it is that the work requires somebody who has done HL7 before, and most practices do not employ one.

Perfuse is built on the assumption that the person configuring it has a problem to solve and no prior HL7 experience. That assumption shows up in specific places:

• Everything is configurable from the web interface. A feature reachable only from a terminal or a hand-edited file is treated as a defect, not a design choice.
• Messages can be traced one transformation at a time, showing what each step read, what it changed, and what it skipped and why.
• Test traffic can be generated that matches the shape of a real feed without containing any of its data.
• A channel can be proposed from a single sample message, with an explicit statement of what the sample cannot tell you.
• Before replacing an existing engine, its output and Perfuse's can be compared message by message, with the differences grouped by field.

1.2 What is in it

Everything below is in the one binary. Each line names the chapter that covers it.

• Formats. HL7 v2, FHIR R4, R4B and R5, DICOM, X12 (837, 835, 270/271, 276/277, 834, 278, 275), C-CDA and CDA, HL7 v3,

NCPDP Telecommunication and SCRIPT, SMART Health Links and Cards, delimited and raw. See message formats.

• Connectors. 28 source types and 32 destination types, among them MLLP, files, SFTP, databases, DICOM, Kafka, AMQP 1.0,

MQTT, IBM MQ, and AWS, Azure and Google Cloud storage and messaging. See the source reference and the destination reference.

• Changing messages. Filters, eleven declarative transformation steps, JavaScript (Mirth's dialect included) and Lua, shared

mapping tables and code sets, and mapping suggestions. See filtering and transformation.

• Delivering them. A durable, ordered queue per destination, retries, dead letters that keep the message, and acknowledgements

sent after delivery. See delivery and acknowledgements.

• Watching it run. Dashboards, team dashboards, a flow map, eleven kinds of alert, metrics, tracing, and a message store that

finds a patient's messages across formats. See alerting, the message store and debugging.

• Changing a live interface safely. Shadow mode, feed contracts, channel tests and engine comparison. See testing.
• Leaving Mirth. Mirth, Open Integration Engine and BridgeLink channels explained, translated and exported back. See

migration.

• Payers and public health. The four CMS-0057 APIs, Da Vinci CRD, DTR, PAS, PDex and Plan-Net, CARIN Blue Button, an optional

decision service, eCR and ELR. Da Vinci CRD, DTR and PAS answer both their 2.2.x and their 2.1.0 releases. See CMS-0057.

• Who may do what. SAML, OpenID Connect, LDAP, passkeys, SCIM, mutual TLS, six roles, channel groups with a role in each,

tenants, a SMART authorization server, TEFCA and UDAP, and an audit log. See security.

• Running it. One static binary for Linux, macOS and Windows, as a service, with a fleet view of several servers. See

operations, the web interface, the command line and server options.

1.3 Standards and versions

Which release of each standard Perfuse implements, and how that was checked. "Checked" names the outside tool or reference that judged the result; where nothing outside has judged it, it says so. Results are from test data, not from a production site.

1.3.1 Messaging and documents

1.3.2 FHIR implementation guides

1.3.3 National and European profiles

Checked by converting published or invented HL7 v2 messages and validating every resource; the full results and the reasons for each failure are in the repository's conformance/national folder.

None of this is a certification. Perfuse has not been certified by ONC, CMS, gematik, Nictiz, NHS England or anyone else.

1.4 What it replaces

Perfuse covers the ground held by Mirth Connect, and can import Mirth channel exports directly. The chapter on migration describes what translates cleanly, what needs a decision, and how to prove the result matches before cutting over.

The differences that matter in daily use are debugging and silence. In Mirth, seeing what a transformer did to a message generally means redeploying the channel with logging added. In Perfuse, any recorded message can be replayed through the current configuration and inspected step by step, without touching the running channel. And where a Mirth alert on "no traffic" is a fixed threshold that is useless on any feed that is quiet at night, Perfuse learns what each feed's normal week looks like and alerts against that.

1.5 How to read this manual

The first chapters are conceptual and are worth reading in order: channels, message flow, then transformation. Everything after that can be read as needed.

The reference chapters near the end list every configuration key, its type, whether it is required and its default. Those chapters are generated from the source, so they cannot describe an option that does not exist or omit one that does. If a key appears in a configuration file and not in the index, it is not a Perfuse key.

1.6 Conventions

Configuration is YAML. Most keys are snake_case on the wire — max_message_size, idle_timeout — and this manual always gives the wire form, because that is what you type. There is one long-standing exception, dataType on a channel, which is camelCase; it is documented that way in the channel reference and accepted only in that spelling.

Field references in HL7 use the usual notation: PID-5 is the fifth field of the PID segment, PID-5.1 its first component, and PID-3(2) the second repetition of the third field. A path written without a repetition addresses every repetition (see paths).

Durations are written as a number and a unit — 30s, 5m, 2h. A bare number is not a duration and will be refused rather than guessed at.

2 Getting Started

Perfuse is a single binary with an embedded web interface. There is no application server to install, no database to provision and no separate administration console.

2.1 Running it

perfuse serve -channels ./channels -db ./perfuse.db -addr 0.0.0.0:8443 \
  -tls-cert ./cert.pem -tls-key ./key.pem

-channels is a directory of YAML files, one per channel. -db is a SQLite file holding recorded messages, users and audit history; it is created if it does not exist.

On first start with no users configured, an administrator account is created and its password written to the log once. That password is not recoverable afterwards.

2.2 The first channel

A channel needs a name, a source and at least one destination. The smallest useful one receives HL7 over MLLP and writes each message to a file:

name: first-feed
dataType: hl7
source:
  type: mllp
  listen: "0.0.0.0:6661"
destinations:
  - name: to-disk
    type: file
    file:
      root: /var/spool/perfuse
      dir: incoming

Save that as channels/first-feed.yaml and it is picked up without a restart.

Three things about that file are worth noticing, because they are the shape of every channel:

• The source block is flat for MLLP. listen sits directly on source, not inside a source.mllp block. Transports that need more than an address — HTTP, SOAP, DICOM — do have their own sub-block, and those are listed in the source reference.
• A file destination needs both root and dir. root is the boundary that paths are resolved against and cannot escape; dir is where messages land within it.
• There is no transformation and no filter. Both are optional, and a channel with neither simply passes messages through.

2.3 Building a channel from the interface

Everything above can be done from the web interface instead, and for a first channel that is the better route because the form will not let you produce a file that does not load.

The builder offers three ways in:

1. From a message somebody sent you. Paste the sample the lab or vendor emailed. Perfuse reads it and proposes a channel, along with three separate lists: what the sample shows, what has been guessed, and what no sample can tell you. This is described in testing.
2. From something that already works. A set of complete channels that need only their addresses filled in.
3. From nothing. A blank form. Available, but it is the slowest of the three and the easiest to get wrong.

2.4 Verifying it works before connecting anything

Two things can be done before the sending system exists.

Send a message by hand from the interface — the message sender accepts pasted text and reports what happened to it, including which destinations accepted it and what each transformation did.

Or generate test traffic. If the channel has handled any messages at all, Perfuse can learn their shape and produce more messages like them, in the same proportions, with none of the original content. See testing.

2.5 What to do next

• Channels explains what a channel is and how its parts fit together.
• Message flow follows one message from arrival to delivery, which is the fastest way to understand where to put a change.
• Alerting is worth setting up before a feed goes live rather than after the first incident.

3 The Web Interface

Perfuse is built on the assumption that everything is doable from the browser, and a feature that can only be reached by editing a file is treated as a defect. This chapter is a tour of what is behind each part of the navigation, organised the way the interface is: by the question you are asking.

The bar carries Dashboard and Channels directly, because those are where most sessions start and end. Everything else is grouped, and the groups are named after questions rather than after subsystems — you do not go to "the audit subsystem", you go and find out who changed something.

3.1 Reading the header

Five things in the header are easy to miss.

Every view has an address. The address bar follows the view — #/channels, #/messages, #/settings — so a reload returns to it, a bookmark opens it, a link sent to a colleague lands them on it, and the back button moves between views rather than leaving the console. An address naming a view above your role opens the dashboard instead.

Search, or ⌘K. It searches across channels, settings, messages and the manual, which means it is usually faster than navigating — particularly for a setting whose name you half remember.

Theme. Three of them: Midnight, Dark, and Light. Midnight is near-black and is what a wall display in a server room usually wants; Dark is a softer neutral grey; Light is for a laptop next to a window. The choice is stored in the browser rather than against the account, because a theme is a property of where somebody is sitting, not of who they are — the same operator wants Midnight on the wall and Light on a train. A machine's own preference is consulted once, to pick a sensible default the first time.

Language. The console in English (UK or US date order), German, French, Dutch, Spanish, Italian, Portuguese, Polish, Swedish, Danish, Norwegian or Finnish, with dates and numbers written the way that locale writes them. The choice is kept in the browser, and the browser's own language is used until one is made. The translations were made by machine and have not yet been reviewed by native speakers; English is the reference, and the picker says so. Code, messages, payloads, channel names and anything typed are never translated. The manual is published in the same languages at https://perfuse.health/manual/<language>/ (this server's own Manual is the English one).

Manual. The document you are reading, served by the running server. It is the same file the binary can write to disk, so it always describes the version in front of you rather than the latest release.

3.2 Monitor — whether it is working, and what happened

3.2.1 Dashboard

The state of every channel, throughput, and anything currently wrong. This is the screen to leave open.

3.2.2 Messages

Every message that arrived, what it was transformed into, per destination, and what happened to it. Searchable, including by a filter expression, so "show me the ones from this sender that were rejected" is a query rather than an afternoon.

A message can be replayed from here, and reprocessed through the *current* configuration rather than the one that was live at the time — which is how you confirm a fix works against the traffic that broke it. See the message store for what is kept and for how long.

3.2.3 Queue

What is waiting to be delivered, and why. A queue that is not draining is the single most useful early warning an integration engine produces, and it is worth pairing with an alert rule so nobody has to be watching. See delivery.

3.2.4 Alerts

What has fired and what the rules are. Rules are edited here rather than in a file. See alerting.

3.2.5 Metrics

Throughput, latency and error rates over time. Useful for capacity questions and, more often, for board packs — which is why the site's own logo appears on it if one has been uploaded.

3.2.6 SQL on FHIR

SQL on FHIR views: pick an example or a saved view, or write one, run it over this server's FHIR store (all patients or one) or over resources pasted in, see the rows with their types, and download CSV, NDJSON or Parquet. Save keeps it for the FHIR endpoint's $sql-run. See message formats.

3.2.7 Quality measures

Digital quality measures: pick an example or a Measure in the FHIR store, or write one with FHIRPath criteria. Choose a measurement period and a report (summary, summary with patient lists, or one patient) and evaluate it over the FHIR store or pasted resources. The screen shows each population's count and patients, the score, and the strata. Download MeasureReport saves the FHIR result, and Save to the FHIR store keeps the Measure for Measure/$evaluate-measure. Measures in CQL are refused: Perfuse has no CQL engine. See digital quality measures.

3.2.8 Flow map

A picture of how messages actually move: which sources feed which channels, and which destinations they reach.

Its value is not decoration. Every estate accumulates a channel nobody remembers commissioning and a destination nobody realised was still receiving, and both are visible here in a way they are not in a list of channel files.

3.2.9 Team dashboards

A dashboard for each kind of person who watches the interfaces: Operations, Connections, Interface analyst, Prior authorization, Imaging, Revenue cycle, Laboratory, Privacy and security, and a plain-words Department summary. Tiles show counts, states and times, never a message or a patient, so a dashboard can go to a manager or a wall screen without widening who sees patient data.

Each person opens on the dashboard their directory group or role is given. -dashboards dashboards.yaml maps them:

groups: {PACS-Admins: imaging, Network-Team: connections}
roles: {viewer: manager}

A group wins over a role, and anyone unmatched opens on Operations. Arrange tiles hides and reorders tiles, the channel picker filters them, and Save as my view keeps that as your own dashboard until Reset.

Export to Grafana downloads the dashboard as Grafana JSON over /metrics, with a data source variable and a channel filter, for anyone who needs more than light configuration. Tiles with no metric behind them are left out, and the export's description names them.

The Connections tile checks every networked destination in layers. It looks the name up, opens a TCP connection, completes TLS where it is used, and reads the destination's last delivery and failure from real traffic. Each failure says what it means, for example "refused: the partner's engine is probably stopped", "timed out: a firewall or a VPN tunnel that is down", or "a certificate from an authority this server does not trust". Nothing is sent to the partner, with one exception: an immunization registry that has had no traffic for seven days is asked its CDC connectivityTest, which submits nothing. With -vpn tunnels.yaml the VPN tunnels tile beside it reads each partner tunnel's state from AWS Site-to-Site VPN, an Azure VPN Gateway connection or strongSwan on this host, so a time-out can be told apart from a tunnel that is down. It also compares both sides' IKE and IPsec settings, as the cloud reports ours and the file lists theirs, and says where they cannot agree. Connection sheet downloads a partner's settings side by side as Markdown to send them; it never holds a pre-shared key. Figures a dashboard needs that are not recorded yet are listed under Not measured yet instead of being drawn as empty tiles.

The department dashboards compute their own figures on the server, and each one says what window and source it covers:

• Prior authorization: PAS requests decided within CMS-0057's 72 hours (expedited) or 7 days (standard), decided late, waiting,

and overdue now, with the median time to decide. Also how the services asked for were answered (approved, modified, denied, pended), as each stands now, over 30 days.

• Imaging: objects received by C-STORE per modality, and those not delivered on. Also the routing delay per channel (the median

and the 95th percentile), C-FIND queries and failures per query channel, and imaging reports (an ORU whose OBR-24 is an imaging section, or an MDM) that did not reach every destination.

• Revenue cycle: 999 transaction sets accepted, accepted with errors and rejected, and 277CA claims accepted and rejected

(A3, A4, A6, A7, A8). Also 835 claims matched by patient account number to 837s sent through this server, and the commonest rejection reasons.

• Laboratory: result delivery time, from receipt to the last destination's acknowledgement, and critical results (OBX-8 HH, LL,

AA, > or <) that did not reach every destination.

• Privacy and security: who opened messages, searched for patients or read prior authorizations in the console over 7 days, from

the audit log (opening a message is audited as message.read). Also each live API token and when it was last used; a token unused for 90 days is flagged.

3.2.10 Sharing what a feed actually contains

Profile this feed reports what is really arriving: which trigger events, which fields are populated and how often, what shapes the values take, and which codes a sender actually uses. That last one is usually the most useful single fact in it.

A profile can be downloaded and sent to somebody else. It needs a name and — required — which system produced the feed, because the question a stranger asks of a shared profile is whether it describes their system, and an optional field would make "Unknown" the commonest answer in any shared collection.

It carries no patient data, and that is checked rather than assumed. A profile is statistical: counts, rates, lengths, shapes. Values are kept only for fields the standard defines as code tables, because a code table value is not identifying. Identifier values are never listed.

Two things follow from that being a promise rather than a hope. The server rebuilds the profile from the stored messages when you export it, rather than sending the one on your screen — so what leaves the building was assembled by the profiler, which has a test proving this property, not by a browser. And the export refuses outright if a profile ever does list values for a field that is not a code table, naming the field but not the values.

A profile that arrives from elsewhere is checked the same way on the way in, for a different reason: it was produced by somebody whose care is unknown, and showing their patients' identifiers would be this server's disclosure. Importing one changes nothing — a profile describes a feed, and what to do about it is a separate decision.

3.3 Build — change what a channel does, and try it before it is live

3.3.1 Channels

The channel builder. Sources, destinations, filters, transformations, scripts and tests, with the generated YAML shown beside the form as you work — so the file is never a mystery, and anybody who prefers the file can read along.

See channels for what the parts are, and transformation for what the steps do.

3.3.2 Scripts

A workbench for scripts, separate from the builder because writing a script and wiring a script are different activities.

All seven slots are offered — filter, transformer, preprocessor, postprocessor, writer, lifecycle and reader — and choosing the right one matters, because the slot decides what the script receives and what it is expected to return. Checking a script as the wrong kind is not a workaround; it compiles a different thing.

JavaScript, Lua and WebAssembly are all available. See transformation.

3.3.3 Contracts

Expectations about what a feed must look like, created and checked here as well as from perfuse contract. See the command line.

3.3.4 Tables

Lookup tables and code sets: the mappings that turn one system's codes into another's. Editable here so that adding a code is not a deployment.

3.3.5 AI Mapper

Proposes field mappings with a confidence score for each, and abstains rather than guessing. Despite the name it uses no language model and makes no network call: the suggestions come from rules, field names and the sample's contents, on this server. It also proposes a channel from a single sample message, and states explicitly what the sample cannot tell it. That second half is the part that makes it trustworthy — a proposal that looked complete would invite you to believe things the message never said.

3.3.6 Playground

A scratchpad for messages and transformations. Paste a message, apply steps, see the result.

Nothing is sent anywhere once the page has loaded, which is the reason it exists in this form: it is safe to paste something real into, on the understanding that it stays in the browser.

3.3.7 Shadow

Runs traffic through a candidate configuration alongside the live one and reports the differences, so a change can be evidenced before it is trusted. The same idea as perfuse compare, applied to a change rather than to a migration. See testing.

3.4 Exchange — the standards this server speaks to other organisations

3.4.1 FHIR lab

Convert HL7 v2 to FHIR, validate a resource, and inspect the result. The samples cover admissions, lab results, appointments, clinical notes, immunizations and a reportable visit. The validation includes US Core, which is the profile American regulation is written against, so this answers "is what they sent us actually conformant" without adopting anything.

Public health case report builds the eCR eICR a case reporting destination would send for the message. It shows which trigger code made the visit reportable, what the report had to mark as missing, and the document itself. A message with nothing reportable gets the reason instead. Nothing is sent from here.

3.4.2 Subscriptions

FHIR subscriptions and whether their notifications are arriving: events, accepted, waiting, and the last reason one was refused. Subscriptions are created by FHIR clients through the FHIR API, not from this page, and the credentials they gave the server are never shown. See message formats.

3.4.3 Documents

Clinical documents — CDA and the printable form of a document. Useful when the thing being exchanged is a discharge summary rather than a message.

3.4.4 Document sharing

The IHE XDS.b registry and repository started with -xds: how many documents, patients and submission sets it holds and how many were replaced; the addresses of the repository, registry, XCA gateway and MHD; a search for a patient's documents in this registry or another community's (an ITI-18 registry or an ITI-38 gateway, with a token for it); and publishing a CDA document by hand, with the facility type and practice setting a document does not say. See message formats.

3.4.5 Direct

Direct secure messaging. This server's Direct addresses lists every address a channel sends or receives as, with its certificate, when it expires, the anchors it trusts, and anything wrong (a missing file, an expired certificate). The Address book keeps correspondents and the certificates their mail is encrypted to: paste one from their HISP, or Save with the certificate from DNS; a certificate that is not for the address or its domain is refused. Find a certificate in DNS asks without saving. See message formats.

3.4.6 Health links

SMART Health Links and Cards, for CMS's *Kill the Clipboard*. Receive a SMART Health Link reads the link or QR code a patient shows at check-in, verifies the health cards inside and sends it on to a channel. Share a visit record makes a link this server hosts, optionally with a passcode, and a QR code for the patient; Use their patient summary fills it with the patient's International Patient Summary from this server's FHIR store. Links this server hosts lists them with how often each was fetched, when it expires and the passcode tries left, and revokes one. Verify a SMART Health Card checks a card's signature and issuer on its own. See CMS-0057 for the server options it needs.

3.4.7 Imaging

The archive this server keeps when it runs with -dicomweb-archive: counts of studies, series, instances and space used, the DICOMweb address and the data-source block for an OHIF viewer, and a study search by patient name, ID, accession and date made with the same QIDO-RS request a viewer makes. A study opens to its series and instances, and an instance downloads as a DICOM file. Nothing is rendered: Perfuse moves images and a viewer displays them. Without an archive the screen says how to turn one on. See DICOMweb.

3.4.8 TEFCA

The audit trail for exchange through a Qualified Health Information Network, and the purpose-of-use rules that govern it.

Two transports, at genuinely different stages, and the screen says which is which. One flag covering both would be wrong in whichever direction it was rounded.

Facilitated FHIR is implemented, and has never spoken to a real QHIN. It follows the Sequoia Project Standard Operating Procedure effective 8 March 2026: discover the partner's UDAP metadata, verify it, register dynamically, obtain an access token carrying the purpose of use, and query. UDAP is a public key infrastructure over OAuth 2.0 — a trust community issues X.509 certificates to its members, and a member authenticates by signing JWTs with the private key and attaching the certificate chain.

The security layer is verified against somebody else's implementation, which is the only verification worth anything here. A registration signed by this build was sent to a live third-party reference server and refused with unapproved_software_statement — Untrusted: Certificate is not a member of community. To produce that answer the server decoded the request, parsed the software statement as a JWT, checked its signature, walked the certificate chain, and reached a decision about membership. It is the difference between being turned away at the door and being handed back an illegible letter.

What remains cannot be done from here. The certificate that proves community membership comes out of QHIN onboarding and is not something software produces. Until one exists, no exchange with a real partner completes.

How a channel asks. A destination of type tefca asks the Facilitated FHIR partner set in Settings, TEFCA (tefca.partnerFHIRBase) for each message's patient: by identifier when the message has one (PID-3, or a FHIR Patient's identifier), otherwise by family name with date of birth, and never by a name alone, because a wrong match on a name returns somebody else's record without an error. The destination sets the purpose of use (treatment, payment, operations, public health, individual access); a purpose the participant does not declare is refused before anything is sent. Purposes go as the TEFCA Exchange Purpose codes (T-TRTMNT, T-PYMNT, T-HCO, T-PH, T-IAS, system urn:oid:2.16.840.1.113883.3.7204.1.5.2.1), or with tefca.purposeCodes: hl7 as HL7 purpose-of-use codes for communities that use those. The Bundle found is the destination's reply and can be handed to another channel with results_to. Every query, refused ones included, is in the trail on this screen, which names the partner.

The whole path, from discovery to a token the partner's FHIR server accepts, is tested against the udap-dotnet reference server (see verification).

The older QHIN-to-QHIN exchange built on the IHE profiles is not implemented. An attempt is refused with an error saying so, and the refusal is audited as a failure. That is deliberate rather than pending a tidy-up: a stubbed exchange reporting success would put entries in the audit trail for exchanges that never happened, and a trail that disagrees with what happened is worse than none, because the trail is what gets believed.

Throughout, the endpoints used for exchange come from the signed part of a partner's metadata, never the document body. Verifying a signature and then reading the endpoints from the unsigned copy would be an elaborate way of trusting the network: an attacker able to rewrite the response leaves the signed element alone, points the token endpoint at their own server, and collects client assertions from everybody who checked the signature and then ignored what it covered.

A trust anchor bundle is required and its absence is refused at startup. Checking a partner's signed metadata against the certificate that arrived inside it proves only that one party made both — a mistake this codebase has made before, in SAML, where the verifier preferred the embedded certificate and authenticated an attacker as an administrator while every test passed. Include the intermediates in the bundle: a UDAP server need only send its leaf certificate, and the public reference server does exactly that.

3.5 Payers — claims, prior authorization, drugs and the CMS payer rules

3.5.1 Claims & auth

Build an X12 275 claims attachment in the 006020 form CMS-0053-F adopts, from a pasted C-CDA or an uploaded PDF, TIFF or JPEG, and see it read back. Read a 275 and download the document inside. Convert an X12 278 decision into a Da Vinci PAS ClaimResponse. Nothing on this page is stored or sent. See message formats for what the 275 is built from and what it does not do.

3.5.2 Drugs

The drug formulary loaded with -formulary, and the two NCPDP standards answered from it. Formulary lists the plans and the drugs with their tier and requirements, and where the public Da Vinci US Drug Formulary API and the NCPDP endpoints are. Price check (RTPB) prices a drug for a member as a prescriber's Real-Time Prescription Benefit request would: the coverage status, the restrictions in words with their codes, the member's share and the plan's, and the cheaper alternatives. Prior authorization (ePA) sends a SCRIPT initiation to this server's own endpoint, shows the question set as a form, sends the answers and shows the decision; below, every case with where it stands and whether the prescriber has been told, the case's answers, a button to send an unsent decision again, and the drug figures CMS-0062-P proposes. See CMS-0057.

3.5.3 CMS-0057

The payer side of the CMS Interoperability and Prior Authorization rule, as five tools:

• The four APIs: whether Patient Access, Provider Access, Payer-to-Payer and Prior Authorization are ready on this instance,

and what each still needs.

• Reviewer queue: the PAS requests waiting for a person, soonest due first, with the documents sent for each; approve, deny or

certify fewer units. See the reviewer queue.

• Claims to CARIN BB: an 837 and its 835 converted to CARIN Blue Button bundles.
• Prior auth to PDex: a PAS response converted to a PDex prior authorization.
• Prior auth metrics: the yearly public prior authorization metrics page, previewed from a CSV of decisions.

The conversions store nothing and send nothing.

3.5.4 CMS Aligned Network

Readiness for the CMS Interoperability Framework: each of its 26 criteria, grouped as CMS groups them, with what Perfuse provides, whether it is on here, the setting that turns it on, and what is the organisation's to do. The counts at the top filter the list. See CMS-0057.

3.6 Administer — who can do what, and how this server is set up

3.6.1 Users

Accounts, roles (monitor, viewer, operator, editor, admin) and channel groups. Each person's channel groups are edited in place in the list; empty means every channel, and lab=editor, adt gives a different role in one group. An administrator limited to some groups sees only the people of those groups. The header shows your own groups beside your role when you have any. See security.

Machine credentials are also here. A token is for a machine rather than a person: it does not expire and is not affected by anybody signing out, which is what a server polling its neighbour needs. Only a hash is stored, so a token is shown once when it is created and cannot be recovered — a stolen database yields no usable token. Give one the lowest role that does the job.

With MCP on, the section also shows the address an AI agent connects to, a client configuration to copy and each tool with the role it needs; issuing a token with Let an AI agent act with it gives it the mcp:write scope. See security.

3.6.2 Tenants

On a shared server, the platform operator's list of organisations: each one's channel count and stored size beside its limits (channels, messages a minute, storage), which are set in place. Shown only to the platform role. See security for what each limit does.

3.6.3 Certificates

The TLS certificates in use and when they expire. The expiry dates are the point: a certificate that lapsed on a Sunday is a class of outage that is entirely preventable and routinely is not prevented.

3.6.4 Activity

Who changed what, and when. Every configuration change is recorded, which is what makes "it started failing on Tuesday" answerable.

3.6.5 Data protection

A person's requests under the GDPR and the UK GDPR, legal holds, the erasure ledger, retention and the record of processing activities; administrators only. See data protection.

3.6.6 Fleet

Every Perfuse instance on one page.

Mirth sells this as a separate product; here it is a configuration file and a read-only token. The reason it is worth having is narrow and important: a dead server does not look like a quiet one. A single instance's dashboard cannot tell you that a second site stopped reporting, and a fleet view can.

3.6.7 Migrate

Drop in a Mirth or OIE channel export and see how many of your channels would run here unchanged. The same analysis as perfuse explain and perfuse translate, without needing a terminal. See migration.

3.6.8 Settings

Every setting the server has, with a control for each — including the ones that would traditionally live only in a file. Each says whether it takes effect at once or needs a restart, and whether it has been set explicitly or is sitting at its default.

The settings cover every perfuse serve option that turns on a feature: the FHIR endpoint and its version, the payer APIs, PAS and the CRD rules, the X12 278 bridge, eCR, the SMART authorization server, TLS and signing, metrics, fleet and VPN. They are grouped as FHIR, Payers, Public health, SMART, Security and so on. Each is also shown with the flag it corresponds to.

Restarting from the console. A setting marked *Needs a restart* is saved at once but read only when the server starts. While any are waiting, a banner at the top of Settings lists them with a Restart the server button (the sign-on editor and the settings files offer the same button after a save). It asks first, because every channel stops for a few seconds: each finishes the message it is handling, as it does when the service is stopped, and senders resend whatever arrives meanwhile. The console then waits for the server to answer again and reads the settings afresh. Only an administrator can restart, and each restart is recorded in the activity log as server.restart.

On Linux and macOS the process replaces itself with a fresh copy of the same program and arguments, keeping its process id, so systemd, launchd or a container runtime sees nothing happen. On Windows the server starts again inside the same process, which keeps a Windows service under the service manager. If the server has not answered after two minutes, the console says so; the reason is in the server's log.

Flags and the settings file. The first time the server starts, the flags it was given are written into the settings file. From then on the file wins over the flags, so changing a setting is done in the console (or the file), not by editing the service's command line. A flag the file does not yet mention is recorded when the server starts with it. Removing a flag from the command line later does not turn its feature off: turn it off in Settings.

SNMP has a panel below the settings: whether the agent is answering and on which address, the networks it answers, how many alert traps were sent or failed, and Download the MIB for the base OID in use. The values are set under Monitoring, SNMP.

Branding is here too: a site can set the product name, a tagline, an accent colour, and upload a logo. The logo then appears in the header, on the sign-in page, on the dashboard and on the reporting screens. If none is uploaded, nothing is substituted — an unbranded installation stays unbranded rather than acquiring decoration.

3.7 What the colours mean

Four registers, and each says something different. The distinction is worth stating because it is the difference between a screen you can read at a glance and one where everything competes for attention.

Plain text is a fact about how Perfuse works. Most of the interface. Nothing is coloured to tell you it is important.

Green means something succeeded just now, because of something you did. It appears after an action and does not persist.

Amber is a caution: worth knowing before you act, and not a fault. A feature that is not switched on, a setting whose changes are audited, a conversion that approximates rather than reproduces, a transport Perfuse handles but cannot fully verify. Amber is the colour of "read this before you continue".

Red means something is wrong at this moment. A value that was rejected, a request that failed, a certificate that has expired, a critical alert that is firing. Nothing else uses it.

That last rule is why a screen does not open red. Red is the only colour that carries an instruction — stop, and it may be something you did — and a screen that spends it on decoration has nothing left to say when the input really is wrong. This was not always true: the users screen used to open with "the server sent a response that could not be read" on every installation that had not configured passkeys, and the settings screen marked audited values in the same colour as a rejected one. A test in web/src/RedMeansWrong.test.ts now fails if a phrase describing something absent or approximate is given a red style.

Inside a code box the vocabulary is different. There, red is a token type — an HL7 segment name, an XML element — and carries no judgement at all.

4 Channels

A channel is one flow of messages: somewhere they come from, optional changes, and one or more places they go. It is the unit of configuration, the unit of monitoring and the unit of deployment. Everything else in Perfuse exists to serve channels.

4.1 Anatomy

A channel file has these parts, in the order they take effect:

Plus several that apply across the whole channel: scripts, shadow, contract, tables, attachments, group and enabled. Each is in the channel reference.

4.2 One source, many destinations

This asymmetry is deliberate and it is worth understanding early, because it is the single most common source of confusion when coming from a different engine.

A channel has exactly one source. If messages arrive from two places, that is two channels. Trying to express it as one channel produces a configuration where a failure in either transport looks the same from outside, and where the two feeds' traffic is mixed together in the statistics — so a drop in one is hidden by the other.

A channel has any number of destinations, and they are independent. One failing does not stop the others, and each has its own queue, its own retry policy and its own delivery record. A message that reached three of four destinations is recorded as exactly that, not as a success or a failure.

4.3 Destinations are not a chain

Each destination receives the message as it stood after the channel's transformations. A destination does not receive the output of the destination before it.

This matters when a destination has its own transformations, which it may. Those apply to that destination's copy only. A common mistake is to put a change on the first destination and expect the second to see it.

If you genuinely need a chain — the output of one flow feeding into another — use a channel destination, which sends to another channel by name. That is explicit, appears in the message history as two channels, and can be monitored as two things, which a hidden chain cannot.

4.4 Naming

The name is the channel's identity everywhere: in the file, in the message store, in alerts, in the audit log and in the URL. Changing it is not a rename; it is a new channel, and the old one's history stays under the old name.

group is separate and exists for organising the interface. A group has no effect on behaviour, and grouping channels does not make them share anything.

4.5 Enabling and disabling

enabled: false stops a channel starting without deleting it. Its configuration, history and statistics stay.

A disabled channel is not a paused one. Its source is not listening, so a sender attempting to connect gets a refused connection rather than a hung one. For MLLP that is the right behaviour — the sender will queue and retry — but it does mean the sender's own error log will fill up, so a disabled channel is not a substitute for arranging an outage with whoever is sending.

4.6 Where channels live

One YAML file per channel, in the directory given by -channels. The filename is not the channel name; the name key is. Keeping them the same is strongly advised and nothing enforces it.

Files are re-read without a restart. A file that does not parse is reported and the previously loaded version keeps running, so a syntax error cannot take a working feed off the air.

4.7 Encrypting a channel's own listener

A channel that listens on a port is its own server, and its TLS is separate from the TLS on Perfuse's web interface. Setting one does not set the other. For an HTTP source the settings are under TLS and limits on the source.

Switching TLS on asks for a certificate and a private key. Requiring a client certificate turns it into mutual TLS: the sender must present one signed by an authority you name, which is authentication, so a listener with it on does not also need a shared token — though having both is not wrong.

The authority is asked for only once a client certificate is demanded, and is left out of the file until then. A channel naming an authority that is never consulted reads as though senders are being verified when they are not.

An MLLP listener has the same settings under Encrypt this listener, with one difference worth stating: on MLLP a client certificate is the only authentication available. There is no token and no header, so a listener without one accepts messages from any host that can reach the port.

Two limits sit alongside it. Give up reading after a duration, because a sender that opens a connection and stops writing otherwise holds it open. And largest message accepted, in bytes, because zero means no limit and the limit is then memory — a sender that posts a gigabyte is refused rather than absorbed.

4.8 Validation

A channel is checked when it loads, and the checks are refusals rather than warnings where the alternative would be a channel that runs and does the wrong thing.

Examples of things refused outright: a destination with no type, a transformation addressing a path that cannot exist in the declared data type, an acknowledgement mode that the source transport cannot deliver, and a Schedule II prescription with refills.

The distinction Perfuse tries to hold to is that anything which would produce a plausible-looking wrong result is refused, and anything which is merely unusual is allowed and reported. A channel that cannot be wrong is more valuable than a channel that starts.

5 Message Flow

This chapter follows one message from the moment it arrives to the moment it is delivered or given up on. Knowing this order is the fastest way to work out where a change belongs, and why something is not happening.

5.1 The order of events

1. Arrival. The source accepts the bytes. For a stream transport this includes de-framing — finding where one message ends and the next begins.
2. Parse. The bytes become a tree according to the channel's dataType. A message that cannot be parsed stops here and is recorded as a parse failure.
3. Record. The message is written to the message store as received, before anything modifies it. This is what makes replay and reprocessing possible.
4. Filter. If the channel has a filter, it decides whether to accept the message. A rejected message is recorded as filtered, which is a normal outcome and not an error.
5. Transform. The channel's transformations run in order, each against the result of the last.
6. Fan out. Each destination gets a copy of the transformed message, applies its own transformations if it has any, and delivers.
7. Record the outcome. Per destination: delivered, queued, failed, or filtered.
8. Acknowledge. If the source expects an acknowledgement, it is generated and sent. By default this happens here, after delivery — see below.

5.2 When the acknowledgement is sent

This is the most consequential setting in a channel, because it decides what the sender is being promised. It is ack.when, and it has two values.

on_delivery is the default. The acknowledgement is sent only after every enabled destination has accepted the message. A positive acknowledgement therefore means the data actually arrived somewhere, which is the strongest claim an engine in the middle can honestly make.

on_receipt acknowledges as soon as the message is parsed and queued, before any destination has been written.

Perfuse defaults to on_delivery because promising delivery and then losing the message is worse than being slow. Under on_receipt, a message that has been acknowledged can still be lost if the process dies with work queued — the sender believes it is delivered, nothing upstream will resend it, and the only record that it existed is in Perfuse's own store.

5.3 When to choose on_receipt

The case for it is real, and it is timeouts. An MLLP sender that does not get an acknowledgement within a few seconds will typically resend, so a slow destination under on_delivery produces duplicates rather than delay. If one destination is a slow archive or a system that is regularly unavailable, on_delivery couples the sender's timeout to that destination's worst case.

The trade is explicit: on_receipt moves the risk from duplicates to loss. Choosing it means accepting that an acknowledged message can be lost in a crash, and it is worth pairing with queue-depth alerting so that a queue which has stopped draining is noticed. See alerting.

5.4 Where the message is recorded

Before the filter, and therefore before any transformation. Three consequences:

• A message the filter rejected is still in the store. You can see what arrived and confirm the filter was right.
• Replay and reprocessing always start from what actually arrived, not from a partially transformed version.
• A change to the transformations can be tested against real historical traffic, because the original is still there. See testing.

The transformed form is also recorded, per destination, alongside the outcome. So the store holds what arrived, what was sent, and what happened — which is what an investigation needs.

5.5 Failure at each stage

The important asymmetry: a parse failure is permanent and a delivery failure usually is not. Retrying an unparseable message will never help, so it is not retried. Retrying an unreachable destination usually will, so it is.

5.6 Ordering

Within one destination, messages are delivered in the order they arrived, and a message that fails and enters the queue holds its place — later messages wait behind it rather than overtaking.

This is the right default for clinical data, where an admission followed by a discharge delivered in the wrong order is worse than both being late. It also means one poisoned message can hold up a queue, which is why queue depth is worth alerting on.

Across destinations there is no ordering guarantee, because they are independent. Two destinations will not necessarily receive the same message at the same time, and a fast one may be several messages ahead of a slow one.

5.7 Concurrency

A source may handle several connections at once, bounded by max_connections. Messages from different connections are processed concurrently.

This means the arrival order of two messages sent simultaneously down two connections is not defined, and cannot be — they genuinely arrived at the same time. A sender that needs ordering has to use one connection, which is what almost all of them do.

6 Transformation

Transformations change a message. They are a list, they run in order, and each one sees the result of the one before it.

Perfuse's transformations are declarative: each step names an operation and the field it applies to. There is no scripting language in the ordinary path. This is a deliberate limitation and the reasoning is in why not a script below.

6.1 The steps

Every step also accepts description, which appears in the trace and in the interface, and when, which makes the step conditional.

A step is written as the operation name with its own block:

transformations:
  - description: Our record number, not theirs
    set:
      path: PID-3.4
      value: RIVERSIDE
  - copy:
      from: PID-19
      to: PID-3.1
      default: UNKNOWN
  - map:
      path: PID-8
      table:
        M: Male
        F: Female

6.2 Clear, remove and the difference

clear leaves the field present and empty. remove takes it out altogether.

For HL7 this distinction is real and it reaches the receiver. An empty field says "I have this field and it has no value". An absent field says nothing at all. Some receiving systems treat the first as an instruction to blank their stored value and the second as an instruction to leave it alone — which is the difference between deleting a patient's recorded allergy and not mentioning it.

If you do not know which the receiver wants, ask. Guessing has a fifty per cent chance of silently destroying data on the far side.

6.3 Conditions

when takes an expression and the step runs only if it is true:

  - when: MSH-9.2 == "A08"
    set:
      path: EVN-1
      value: A08

A step whose condition is false is recorded as skipped, and this is reported separately from a step that ran and changed nothing. That distinction is the point of the step-through debugger and it is covered in debugging: a false condition and an absent field look identical from outside and mean opposite things.

6.4 Paths

A path addresses a field: PID-5 is the fifth field of PID, PID-5.1 its first component, PID-3(2) the second repetition of PID-3 and OBX(3)-5 the fifth field of the third OBX segment.

Two behaviours worth knowing:

• set creates whatever path it addresses, including intervening structure. This is convenient, and it means set can never demonstrate that a field was absent — after the step it exists. To test what happens when a field is missing, use copy from a path that is not there.
• A path without an index addresses every repetition and every occurrence, as it does in a filter (where PID-3.5 == "SS" is true when any repetition is). On a message with five OBX segments, set on OBX-5 changes all five, and set on PID-3.4 relabels every identifier in PID-3, the national number's included. To change one, give its index: PID-3(1).4, OBX(2)-5.

6.5 Errors

Most steps have nothing to fail at. Setting a value, clearing a field or copying from an absent path with a default are all defined for every input.

date is the exception, because a value that is not a date it recognises has no correct conversion. It takes on_error:

• fail — the default. The message stops and is recorded as a transformation failure.
• keep — leave the original value alone.
• clear — empty the field.

The default is fail because a timestamp that silently did not convert is worse than a message that did not arrive. A date in the wrong format usually still looks like a date, so it passes the receiver's validation and lands in the record as the wrong day.

keep is legitimate when the receiver tolerates either format, and when used the trace marks the change as deliberate so it does not read as a step that failed quietly.

6.6 Order matters, and the trace shows it

Each step sees the previous step's output. Two consequences that catch people:

• A map after a case sees the case-converted value, so its table keys must match the converted form. A table of M/F after a lower-case step matches nothing, silently, because a value not in the table is left alone.
• A copy from a field that a later step removes still works, because it ran first. The reverse does not.

Both are visible in the step-through view, which shows the whole message after each step rather than only the change. See debugging.

6.7 Suggesting mappings, and what to do with a suggestion

The AI Mapper proposes mappings between a set of source fields and a set of targets. Its defining behaviour is that it declines: below its confidence threshold it abstains rather than guessing, because a confident wrong mapping in a clinical system is worse than no mapping at all.

6.7.1 Give it something to be confident about

A name on its own is weak evidence, even when it matches exactly. PatientMRN against PatientMRN scores 68, which abstains at the default threshold of 70.

The engine knows what an HL7 path means — it will tell you PID-7 is Date/Time of Birth and score your field name against that rather than against the string PID-7, which shares no characters with anything. A locally defined Z segment means whatever your site decided, so nothing is claimed about it.

That gets a mapping most of the way. To finish it, supply both halves:

• Example values for a source field, after an equals sign: ZPI-1 = MRN00412, MRN00998
• The kind of value a target holds, the same way: PID-3.1 = mrn. The kinds are mrn, npi, ssn, phone, date and email.

With those, the engine can see that the values agree with the target's kind, and a suggestion rests on more than a name.

6.7.2 Approval is one mapping at a time

Each suggestion has its own approval box. There is no "accept everything above 80%", deliberately: the engine has already used the confidence to decide whether to offer the mapping, and what remains is a judgement about this field in this feed. A number is not that judgement.

An abstention cannot be approved at all. It has no box, not a disabled one, and the screen says the engine does not know. If you know the answer, map it by hand — that is a different act from agreeing with a suggestion.

A suggestion below your threshold is shown without a box too, marked as below it. Worth reading — a near miss is often the mapping you wanted, and hiding it would leave you wondering whether the engine considered it — but not approvable, because your threshold is the line you drew.

6.7.3 Two things to do with what you approved

Add them to a channel turns each mapping into a copy step. This only works where the source is a path in the message, such as ZPI-1, because a step copies from one place in a message to another. The steps go into the channel file and take effect when it next loads — nothing changes in the traffic until then. Each step's description records the confidence it was suggested at and that a person approved it, which is what makes it accountable six months later.

Download as a recipe is the right answer for the commoner case: a mapping from a column name, a JSON key or a vendor's own field name. Those are real mappings, and a channel cannot read such a field directly, so a step cannot express them. The recipe records them as approved and can be shared.

6.8 Why not a script

Mirth puts a JavaScript transformer at the centre of every channel, and it is the most flexible design available. Perfuse offers scripting — see the scripts key in the channel reference — but does not make it the ordinary path, for three reasons that come from what goes wrong in practice.

A declarative step can be inspected. Perfuse can tell you that a step reads PID-5 and writes PID-8, before running it, and can therefore show a field-level trace, warn that a step addresses a path the declared data type cannot contain, and generate a per-step replay. None of that is possible for arbitrary code.

A declarative step can be reasoned about by the interface. The builder can offer the fields that exist in this channel's traffic, and a change to a step can be checked against real historical messages before it is saved.

And a declarative step cannot do something unrelated to the message. A script can call out to the network, read the filesystem, or depend on the time of day. When a channel that worked for two years starts producing wrong output, the cause being outside the message is the hardest case to diagnose, and removing the possibility is worth more than the flexibility it costs.

Where a genuine transformation cannot be expressed declaratively, use a script and accept that the trace will show it as one opaque step.

6.9 What a script is allowed to do

A script is refused anything outside the message unless it is granted, and the grants are on the Scripts section of the builder. This is deliberately unlike Mirth, which gives every script all of them — so there, a transformer can quietly start reading the filesystem after a copy-paste.

There are three.

Read and write files requires you to name the directories it may use, and a channel granting file access without them is refused at load. That requirement is the whole difference between file access and unrestricted file access: granting it without directories once reached the entire filesystem, including Perfuse's own database, which holds password hashes, the LDAP service account password and the OIDC client secret. Creating a channel needs only the editor role, so the escalation completed the moment an administrator started the channel.

Query a database uses the connections configured on the channel. A script with this can read anything those credentials can.

Route messages to other channels lets a script send a message into another channel, which is how a loop between two channels becomes possible.

Granting a capability to a channel with no scripts does nothing, and the generated file omits the whole block in that case.

6.10 Handling a date that does not match its format

A date step converts from one format to another, and the interesting question is what happens when a value does not match the format it claims.

The default is to stop the message, and it is the right default: a timestamp that silently did not convert is accepted downstream and then misread, which is worse than a message that failed loudly and is sitting where somebody can see it.

Leave the value as it is passes it through in its original format. Downstream then sees two formats in one field, which is the failure the step existed to prevent — but it is the right choice where the field is optional and a partner sends it inconsistently.

Empty the field is honest and better than a wrong format, but a receiver that requires the field then rejects the message instead.

6.11 The scripting languages

Three are accepted, and which one to pick depends mostly on whether you are migrating. The value goes in a script's language key:

JavaScript is the default, and an unmarked script is treated as JavaScript. It is here as a compatibility obligation rather than a preference: Mirth's scripts are JavaScript and a site moving across has thousands of lines of it. That includes support for E4X, a long-dead extension to the language that Mirth scripts use for XML and that has to be translated before anything will parse it.

Lua (lua) is the better choice for anyone not migrating. A smaller runtime, no prototype chain to misuse, and integer-indexed tables that match segment and field addressing more naturally than JavaScript's do. Its standard library is small enough to enumerate, which is what makes its sandbox easier to be confident about.

WebAssembly (wasm) is not a language but a compiled module, and the field wants the bytes of a .wasm file rather than source. Use it when the transformation already exists in a compiled language, or when it is heavy enough that the runtime cost matters.

Its contract is deliberately the simplest one available: a module reads the message on standard input and writes its result to standard output. Bytes in, bytes out — which is what every toolchain already does, and what somebody testing a module on their own command line already has. The alternative was an exported function over linear memory, which is faster and requires every module author to agree about allocation, string encoding and who frees what; for something that runs once per message, that trade is not worth it.

Anything a module writes to standard error becomes log lines, so it can explain itself the way a script calling logger can.

6.11.1 What the output means

The rules are the same for all three languages rather than new ones per runtime, so a script's observable behaviour — what it can see, what it may do, how long it may take, what a filter verdict means — is defined once.

For a transformer, preprocessor or writer, empty output means the message is unchanged. Falling off the end of a script leaves the message alone; treating no output as "the message is now empty" would discard traffic on a technicality.

WebAssembly modules are compiled when the channel loads, not on the first message. Compiling is not free — a module built from a language that brings its own runtime can take hundreds of milliseconds — and paying that at load time means the first message through a channel is not mysteriously slower than the rest.

6.12 Shared mapping tables

The other half of the same problem: a site's sex codes and patient classes get translated identically in every channel that touches them, and a table inside a channel is a table only that channel can use.

# codes.codeset.yaml
tables:
  - name: sex-to-lab
    describes: the hospital's sex codes into the numeric codes the lab expects
    decided_by: Dave, during the 2019 migration
    decided_on: 2019-04-11
    source: the lab's interface specification, version 3
    entries:
      - from: M
        to: "1"
      - from: U
        to: "9"
        why: the lab has no 'unknown', and 9 is its 'not stated'

# in the channel
tables:
  - codes.codeset.yaml
transformations:
  - map:
      path: PID-8
      use: sex-to-lab

The provenance is the point. Most of what makes an interface hard to maintain is that nobody knows *why* a mapping is the way it is, and the person who knew has left. A mapping with a reason can be argued with; one without becomes something nobody dares change and nobody dares delete.

Tables are made and changed on Build → Tables as well as in the file. Saving a table that is in force restarts the running channels that load its file, so the next message uses it; a draft restarts nothing.

6.12.1 Versions and effective dates

A table may keep several editions under one name, each with its own version. The edition a message uses is chosen when the message arrives: of the approved editions whose dates cover that day (UTC), the one that started latest. So a code change agreed for the first of next month is entered now and takes over on its own.

tables:
  - name: sex-to-lab
    version: "3"
    effective_from: 2026-11-01   # optional; empty means from the start
    effective_until: 2027-10-31  # optional; the last day it applies
    source_system: urn:local:hospital-sex
    target_system: http://terminology.hl7.org/CodeSystem/v2-0001
    entries: [...]

• status is approved (the default), draft (used by nothing) or retired

(kept for the record, used by nothing).

• Two editions of one name with the same version, or two approved editions

starting the same day, are refused when the file loads.

• Saving a new version with no start date while another is approved dates it

from today, so it replaces the one in force. One that had itself only started today is retired, since two editions starting the same day leave no rule.

• A map step's own default and strict are used when the step sets them;

otherwise the table's.

• On the Tables screen, Show versions lists every edition with its status,

who saved and who approved it, and Compare with the version in force shows what an edition adds, removes and changes.

6.12.2 Sign-off

With Settings → Data → Mapping tables "Changes to a mapping table need a second person's approval" (data.tableApproval) on, every save is a draft, and the person who saved it cannot approve it: somebody else does, optionally giving the day it comes into force. An approved edition cannot be edited in place; New version from this copies it into the next version. Approving, retiring and deleting a draft are written to the audit log, and approving restarts the running channels that load the file.

6.12.3 Values no table maps

Every value a map step looked for and did not find is counted, per table, with the channels it came through and when it was first and last seen. The Tables screen lists them, most frequent first. Map it opens the table with that value already added as a row; Dismiss removes it until it is seen again. Values longer than 64 characters are not recorded (they are not codes), and the list keeps what was seen within the message retention period. The list is kept in terminology.db beside the main database.

6.12.4 Code systems

Published code systems can be imported from their publishers' own files, under Code systems on the Tables screen (admins) or with POST /api/terminology/import?format=… and the file as the body:

None ships with Perfuse: LOINC, SNOMED CT, RxNorm and CPT each have their own licence, and the screen asks the importer to confirm the organisation holds it (recorded with the import). Imported codes are used three ways:

• a table naming source_system or target_system has its entries checked when

saved, and codes that are not in the system are listed on the edition;

• Find a code searches by code or by words in the name;
• the FHIR server answers CodeSystem/$lookup and CodeSystem/$validate-code

for them (see the FHIR server options). ICD-10-CM codes are accepted with or without the dot.

National editions and classifications. A SNOMED CT edition is imported from its whole RF2 package: concepts with their real status, every active description, and the language reference sets. The edition is found from the package (the national module with the most concepts; edition names it instead) and becomes the version URI. language chooses whose preferred term is each concept's display (sv, da, nl, de, fr, en-GB, en-US ...; English otherwise), and every language's preferred term and fully specified name are kept as designations: $lookup returns them, and its displayLanguage picks one (de-CH falls back to de). The editions Perfuse names (International, UK, Germany, Netherlands, Sweden, Denmark, Belgium, Ireland, Norway, Switzerland, Estonia, Spain) are listed by GET /api/terminology/editions, the module IDs not checked against a published source marked as such; any other edition imports too, named by its module.

ClaML files are read in UTF-8, ISO-8859-1, ISO-8859-15 or Windows-1252, as their XML declaration says. Each category's title is its preferred rubric (nested terms included); a modifier (a fifth character for the site of a fracture, say) makes the codes it adds, with the modifier's title after the category's, unless the category excludes it; blocks=true imports chapters and blocks as well. The ICD-11 tabulation's columns are found by name, since their order has changed between releases, and the dashes that show depth are removed from titles. A delimited file takes delimiter (, ; | or tab), encoding (utf-8, iso-8859-1, iso-8859-15, windows-1252) and noHeader=true, with columns then numbered from 1. The console offers settings for the UK ICD-10 5th Edition and OPCS-4 files (TRUD), France's CIM-10 FR table of labels (ATIH) and an ICD-10-BE export; their publishers do not all document their columns, so check them against the file's header.

Effective dates. effective=YYYY-MM-DD imports a version now and uses it from that day (ICD-10-GM, say, each 1 January): until then a lookup that names no version is answered by the version already in force, and the screen shows the date.

ICD-11 from the WHO. With a client registered at icd.who.int (Settings → Data → Code systems, serve -icd11-client-id and -icd11-client-secret; -icd11-release, 2025-01 by default), ICD-11 codes that are not imported are looked up in the WHO ICD API (codeinfo, then the entity's title) and kept for a day. A postcoordinated code (NC72.2&XK9K) is checked whole, so a combination ICD-11 does not allow is refused, and its display names every part ("Fracture of neck of femur (Right)").

ICD-11 without sending codes out. The WHO publishes the same API as a container (whoicd/icd-api, free, Intel and Arm). Run it on your own network and give its address (serve -icd11-url http://icd-api.local, or ICD API address in the same settings); no client is needed and no code leaves your network. Tested against that container (version 2.6.0, release 2025-01 in English and French).

7 Filtering

A filter decides which messages a channel accepts. It is one expression on the channel, evaluated after the message has been parsed and recorded, before any transformation.

filter: MSH-9.1 == "ADT" && MSH-9.2 in ("A01", "A03", "A08")

A message the filter rejects is recorded with the outcome filtered. That is a normal result, not an error, and it does not raise an alert or produce a negative acknowledgement.

7.1 Filtered is not failed

This distinction is worth being firm about because conflating them is how a real problem gets hidden.

A filtered message was correctly declined: it was not for this channel. A failed message was one this channel should have handled and could not. If both were recorded the same way, a channel that starts failing every message would look exactly like a channel that is filtering most of its traffic, which is the normal state of many channels.

So the statistics count them separately, the alert rules treat them differently, and the interface shows them in different colours. A rise in filtered messages might mean the sender has started sending something new; a rise in failures means something is broken.

7.2 What a filter can read

Any field in the parsed message, by the same paths transformations use. The filter runs before transformations, so it sees the message as it arrived — not as it will be sent.

That ordering is deliberate. A filter that read post-transformation values would be deciding whether to accept a message based on changes made on the assumption it was accepted, which is circular and produces channels whose behaviour depends on the order of two things that look independent.

7.3 Expressions

Comparisons: ==, !=, and for numbers <, <=, >, >=.

Membership: in ("A01", "A03"), which is clearer than a chain of || and is the form the builder produces.

Combination: &&, ||, and parentheses. Negation with !.

Absence: a path that is not present compares unequal to any value, including the empty string. To test for absence explicitly, compare against absent. This matters because an absent field and an empty field are different, as described in transformation, and a filter that treats them the same will accept messages it was written to exclude.

7.4 An error in the filter is a refusal

If the filter itself fails to evaluate — a malformed expression that got past validation, or a comparison that cannot be made — the message is refused and the error is recorded against it.

Refusing rather than accepting is the safer of the two, but neither is good, and the outcome is recorded distinctly from an ordinary filter refusal so it can be alerted on. A filter that is erroring on every message is silently dropping the entire feed, and it must not look like a filter that is working.

7.5 Filter at the source where you can

A filter runs after the message has crossed the network and been parsed. Some sources can filter earlier and more cheaply:

• A broker source takes a selector, which filters at the broker. Messages this channel does not want never cross the network at all. On a shared queue that is the difference between reading a hundred messages a day and a hundred thousand.
• A database source's query decides what it returns.
• A file source's pattern decides which files it picks up.

Filtering at the source is a performance decision, not a correctness one, and it has one cost: a message filtered at the broker is never recorded by Perfuse, so it does not appear in the message store and cannot be inspected later. If you need to be able to prove what the sender sent, filter here rather than there.

7.6 Testing a filter

A filter can be checked against real historical traffic before it is saved. The interface reports how many of the last N recorded messages the filter would accept, reject, and error on — which is the fastest way to find out that an expression which looks right accepts nothing.

The trace also shows, per message, which fields the filter read and what values it found. A filter that unexpectedly rejects everything is usually reading a path that does not exist in this feed, and the trace names it.

8 Message Formats

A channel's dataType decides how bytes become a message. It affects parsing, what paths mean, how the message is written back out, and which transformations are valid.

8.1 HL7 v2

The default, and what most of this manual's examples use. Segments terminated by carriage return, fields by |, components by ^, repetitions by ~.

Two things about the encoding are worth knowing because they cause silent faults.

The delimiters are not fixed. They are declared in MSH-1 and MSH-2 of each message, and Perfuse reads them from there rather than assuming pipes. A sender that uses a different field separator parses correctly.

The consequence is that a message whose separators have been replaced — most often by a word processor or mail client substituting typographic look-alikes — parses perfectly into fields that are all wrong. Nothing errors. This is why the sample reader described in testing reports which separator character it found, and refuses to express confidence when it is unusual.

8.2 HL7 v3 and CDA

XML rather than delimited. Paths are element and attribute paths rather than field positions.

In v3 a value is almost always an attribute rather than element text. A comparison that only reads element text will report two documents as identical when the birth date, the gender and every identifier differ. Perfuse's comparison reads both, and this is why: the alternative silently succeeds.

hl7v3 options are in the format reference.

8.3 X12

Segments terminated by ~ conventionally, with delimiters declared in the ISA segment. Like HL7, they are read from the message rather than assumed.

X12's structure is envelopes within envelopes — interchange, functional group, transaction set — and a single interchange can hold many transactions.

By default an interchange is one message. The whole file gets one record, one outcome and one row in the interface, however many transactions it contains.

8.3.1 Mirth's X12 XML

Mirth Connect and Open Integration Engine show X12 as XML: a root X12Transaction (or EDIMessage when the input does not start with ISA) carrying the delimiters as attributes, and one element per segment and element named ISA.01, NM1.03.1 and so on. Channels and receivers built for Mirth read and write that form. Perfuse reads and writes the same one:

• x12: { arrives_as: xml } on an X12 channel takes that XML in and handles it as the X12 it stands for (the builder's It arrives as choice);
• x12_as: xml on a destination sends the X12 on as that XML (the builder's Send it as Mirth's X12 XML);
• perfuse x12 xml [file] and perfuse x12 from-xml [file] convert at the command line.

The format was written from Open Integration Engine 4.6's observed output and published format, and is checked against it: 25 generated interchanges and 4 kept examples come out byte for byte as OIE writes them, and back (see verification). A DOCTYPE is refused, as in every XML Perfuse reads.

8.3.2 Splitting an interchange

Setting split makes each transaction set a message in its own right, with its own record, its own metrics and its own row. An operator looking for one claim then finds one claim rather than a file of four hundred.

It is off by default because turning it on multiplies everything downstream — message counts, rows, alert thresholds — and a threshold tuned for files that is suddenly counting claims will not mean what it used to. That should be a decision somebody made rather than a default they inherited.

8.3.3 When the counts do not add up

X12 declares its own counts — how many segments, how many transactions — and the envelope key says what to do when they disagree with what is actually present. Those counts are the only mechanism X12 has for detecting that half a claims file arrived.

warn exists for a real situation: some partners' software has generated wrong counts for years in otherwise complete files, and a site that has to process those needs a way to say so out loud in the configuration rather than turning validation off wholesale.

8.3.4 Transactions Perfuse reads as structured data

Any X12 interchange can be routed, filtered and addressed by path. These transactions are additionally parsed into named fields, so a channel can ask what a payer decided rather than which element sits at position four.

Perfuse also builds the 270 eligibility inquiry and the 276 claim status request, under Payers → Claims & auth or through POST /api/x12/eligibility/build and /api/x12/claimstatus/build. Both are the HIPAA 5010 versions (005010X279A1, 005010X212), read back and envelope-checked before they are shown, and neither is sent from that page: delivering one is a channel's job, where the trading partner and its credentials are.

8.3.5 Eligibility, and the CAQH CORE data content rule

A 271 is a list of EB segments, each a single fact: active coverage, or a $25 co-payment for service type 30 in network, or $800 of the individual deductible remaining. The reader assembles them into the answer a front desk wants - "coverage active under Gold PPO 2000; co-payment in network $25; individual deductible remaining in network $800" - and names a rejection (an AAA segment) in words, with what the payer says to do next.

It also checks the response against the CAQH CORE Eligibility & Benefits data content rule: for an inquiry about health benefit plan coverage (service type 30), an active response should carry plan dates, the plan name, co-payment, coinsurance, deductible and remaining deductible both in and out of network, and the base service types (1, 33, 35, 47, 48, 50, 86, 88, 98, AL, MH, UC). Each is listed as met or missing. This is Perfuse's reading of the rule, useful for "why does this payer never tell us the deductible?" - it is not CORE certification, which CAQH's authorised testing vendors carry out.

8.3.6 Prior authorisation

Perfuse implements prior authorisation twice, on purpose.

The FHIR side is what CMS-0057-F requires payers to expose by 1 January 2027. The 278 is what payers accept today, and the rule does not replace it — Da Vinci PAS is in practice a mapping onto this transaction, because a 278 is what a utilisation management system speaks. An engine reading only the FHIR half can talk to the systems that will exist and not to the ones that do.

A 278 response carries the authorisation number, and that is the field the whole transaction exists to deliver. Without it a certified service is not billable: the claim goes in with no authorisation number and is denied for the lack of one, which reads downstream as a clinical denial.

A denial and a refusal to consider are not the same thing

This is the most expensive confusion in the transaction, and Perfuse reports the two separately.

Both read as "not approved" to anybody scanning, and the correct actions are opposite. Appealing something nobody ruled on achieves nothing; resubmitting a denial produces the same denial. The parsed outcome names which happened — denied against not-considered — and AAA04 carries the payer's own advice on whether the request is recoverable at all.

Partial certification is reported as partially-certified rather than folded into approval. There is an authorisation number to bill against, so it counts as approved, but the quantity certified is not the quantity requested — and a practice booking six sessions against three approved discovers it at the fourth claim.

An action code Perfuse does not recognise is reported as unknown, not as pending. Pending reads as "wait", and waiting is the wrong action for most of what an unrecognised code could be.

A channel can route on the decision directly:

filter: HCR-1 == "A3"

Converting between the two

Perfuse converts a parsed 278 into a Da Vinci PAS ClaimResponse, and reports every judgement the conversion needed rather than only the result. The conversion follows three rules:

• No decision is upgraded. Partial certification stays partial, and a request the payer refused to consider does not become a denial. Both collapses are available in the obvious mapping and both are wrong in the expensive direction.
• Nothing is invented to fill a required field. A certified event with no authorisation number is reported as such, not given a plausible one — a fabricated number produces a claim that is denied later for a reason nobody can trace.
• A decision carried only at line level is used. A payer answering per service can leave the event without a decision of its own; reading only the event level would report that as pending, and a practice waits for an answer it already has while the approval expires. Where the lines disagree, the least favourable wins, because an event with a refused line is not an approval.

Narrowing to a three-state vocabulary — approved, denied, pended — is available and explicit about what it discards. Narrowing a refusal to consider yields "denied" and says in words that the correct action is a corrected resubmission rather than an appeal.

Checked against PAS 2.2.1, not only against itself

The ClaimResponse is shaped to the Da Vinci PAS 2.2.1 profile and was checked with the official HL7 validator loaded with the published PAS package. The first version had only been checked by Perfuse's own tests, and the validator rejected it with six to eight errors per resource. Every one of them is something a payer's PAS endpoint would also have rejected:

The corrected output validates with no errors for a certification, a denial and a pend. The warnings that remain are the validator saying it cannot load X12's code systems, which X12 licenses. The authorisation number is carried in reviewAction.number, where the guide's own example puts it, and in preAuthRef when the response has only one.

The validator is not part of make check, because it needs Java and a download of the guide and its dependencies. What it found is held by a test instead: each rule it enforced is asserted, so a change that reintroduces one of those errors fails.

The Claims & auth view converts a pasted 278 and shows the decisions, the notes and the resource.

8.3.7 Attachments, and why they need special handling

CMS-0053-F makes the 275 a HIPAA standard for claims attachments, with compliance required by 26 May 2028. It carries a document — an operative note, an imaging report, a scanned form — tied to the claim it supports.

The 277 is the other half of the same conversation. A payer receives a claim, decides it needs documentation, and sends a 277 asking for it; the provider answers with a 275.

A channel can route on the status code directly, because STC01 is a composite and its second component is the status. Written in canonical form, because a component is addressed with a dot and the two notations cannot be mixed — STC-1.2 is element 1, component 2:

filter: STC-1.2 in ("227", "233", "252", "287")

Those are the codes that unambiguously mean a document is wanted. The status category in STC-1.1 is deliberately not used on its own: R4 means a documentation request in some implementation guides and "forwarded elsewhere" in others, so a filter on the category alone would put finalised claims in the queue for somebody to chase.

Two identifiers decide whether an attachment is ever associated with its claim, and both are reported: the attachment control number, which the provider put on the original claim to say documentation would follow, and the trace number, which matches the payer's request. An attachment arriving with neither is filed and never connected to anything, while the claim ages.

The 006020 form, which is the one the rule adopts

CMS-0053-F adopts version 006020, and its 275 differs from the 005010 form in two ways that matter.

• The payload is in BDS, not BIN. BDS01 names a filter, ASC or B64. BDS02 is the length and BDS03 the data.
• The payload is a MIME entity, with headers saying what the document is and a base64 body. With B64 the entity itself is base64 as well.

Perfuse unwraps the entity and reports the document inside it, with its content type and file name. The bytes it reports are exactly the ones the sender wrapped. An entity that cannot be unwrapped leaves the raw payload in place, with a note saying why.

Building a 275. Perfuse also builds 006020X314 attachments: an unsolicited one to accompany a claim, or a response to a payer's 277 request. The difference is BGN01 02 against 11, and whether TRN02 carries the claim's PWK06 or the 277's TRN02. Every built interchange is parsed back before it is returned, and the response says whether the document inside is the one that went in.

The structure comes from the two published companion guides for 006020X314: the CMS esMD guide and UnitedHealthcare's. It does not come from the X12 technical report, which X12 licenses and which this project does not hold.

• Where the two guides agree, Perfuse follows them.
• Where they differ, it satisfies both if it can. CAT02 is HL for an HL7 document, which esMD uses, and IA for an image, which UnitedHealthcare uses.
• Otherwise it sends the optional segment only when given the value: esMD's REF*X1 claim identifier and UnitedHealthcare's DTP*472 service date.

There is no validation against the technical report. The partner's companion guide governs.

8.3.8 Electronic signatures on attachments

CMS-0053-F also adopts a signature standard, at 45 CFR 162.2002(e): the HL7 Implementation Guide for CDA Release 2, Digital Signatures and Delegation of Rights, Release 1. It applies to signatures put on attachment information when it is sent in a HIPAA attachment transaction, from 26 May 2028. A payer may not ask for more than the guide does.

Perfuse signs a C-CDA that way on its way into a 275, and checks the signatures on every C-CDA in a 275 it reads.

• What is signed. The whole document except its legalAuthenticator and authenticator participants, so each later signer leaves the earlier signatures intact. The signature says so with an XPath Filter 2.0 transform any XML signature library can evaluate.
• Where it goes. Base64 in sdtc:signatureText on the signing participant, with a one-line plain-text description. The signer is the document's legal authenticator if it has an unsigned one, otherwise a new authenticator.
• What it states. The signer's certificate, the time in UTC, a role from the NUCC provider taxonomy and a purpose from ASTM E1762. The purpose defaults to *Author's signature* for a legal authenticator and *Coauthor's signature* otherwise, as in the guide's own example.
• How long it lasts. The guide asks for XAdES-X-L, which carries everything a payer needs to verify the signature years later without reaching the network. That is the certification path, an OCSP response or CRL from the CA, and two time-stamps from a time-stamping authority. Perfuse fetches the revocation data from the addresses in the certificate and the time-stamps from -tsa-url.

If any of that is unavailable, the signature is still made and holds. The result names the XAdES form it reached, and says what stopped it short of X-L: for example a self-signed certificate (no CA to ask) or no time-stamping authority.

The key is -signing-cert and -signing-key. Put the CA certificates after the signer's in the same file so the path travels with the signature. For a signature that means what DSDR means, the certificate should name the clinician, with their NPI, rather than the server. Signing is an admin action, as signing any document is.

The guide does not name a namespace for its own elements. Perfuse puts digitalSignature, authorizedSigner and SignaturePurpose in urn:hl7-org:sdtc. It also states the purpose as a XAdES commitment type with the ASTM OID, which XAdES tools understand. Delegation of rights, where a delegate signs with a SAML assertion from the authorised signer, is not produced, and a received one is reported as not verified.

The provider NPI is checked against its check digit. A payer matches an attachment to its claim partly on that number, and a mistyped one leaves the attachment unmatched while the claim is denied for missing documentation.

The Claims & auth view builds a 275 from a pasted C-CDA or an uploaded file, optionally signing the C-CDA, and reads one back with each signature's findings. Nothing on that page sends anything: the interchange is handed back to be delivered through a channel, which is where the partner, the credentials and the audit trail belong.

8.3.9 Binary segments

A BIN segment carries raw bytes, and raw bytes contain delimiters. Every other X12 segment ends at the segment terminator, so an ordinary parser finds segments by searching for one byte; an attachment cannot be found that way. A PDF containing a ~ would be cut into pieces, and each piece is a structurally valid segment — so the document is truncated, every segment after it is misaligned, and nothing reports an error.

Perfuse reads the byte count the segment declares and takes exactly that many bytes. Two consequences worth knowing:

• A declared length that does not match the data is refused, naming both numbers. The useful question is whether the sender's count was wrong or the file was truncated in transit, and only the two numbers answer it.
• BDS, the 006020 binary segment, keeps its count in BDS02 and its data in BDS03. It was refused until that could be confirmed from a published source rather than recalled, and two sources now confirm it: the CMS esMD companion guide's BDS table and UnitedHealthcare's guide.

The esMD guide's own sample interchange declares 16 bytes for the same 53-byte payload that its table correctly counts as 53. Perfuse refuses that sample, as it should. A test holds both the table's example and the sample's typo, so a change in either direction is noticed.

8.4 FHIR

8.4.1 What an HL7 v2 message becomes

The message type decides what is produced, and every conversion reports the judgements it needed as notes beside the bundle.

Anything else produces the Patient and a warning naming the type that was not mapped.

Scheduling. A booking, a reschedule, a cancellation and a no-show all land on the same Appointment. Its identity comes from the appointment's own numbers in SCH-1 and SCH-2, never from the message, so a cancellation updates the booking. The alternative would be a second, cancelled appointment beside a live one, which shows the patient booked into a slot that no longer exists.

• Status. The filler status in SCH-25 decides it, and the trigger event is used only when that is empty.
• Blocked slots. A blocked slot is not an appointment with a patient, and produces none.
• Start time. It is read from AIS, AIG, AIL or AIP first, then SCH-11, because version 2.5 moved it and feeds did not all move with it.
• Durations. A duration in a unit Perfuse does not recognise is left out, not guessed.

Documents. Text notes (TX, FT, ST) keep their line breaks, including blank lines, because a blank repetition in a note is a paragraph break.

• Embedded documents. An embedded PDF, TIFF or JPEG (ED) is carried byte for byte. Base64 that is not valid base64 is refused rather than passed on.
• Types. The document type in TXA-2 is kept as sent and, where there is a clear equivalent, given the LOINC code US Core uses.
• Signing. A note nobody has signed is preliminary, and T11 makes the document entered-in-error.
• No content. A notification with no content (T01, T03 and the other odd-numbered events) produces no DocumentReference. FHIR requires content, and an empty attachment would look like the note while saying nothing.

This is what CMS Interoperability Framework criterion 14 asks for: chart notes and clinical documents returned as FHIR attachments.

Immunizations. A dose is never reported as given when the message says otherwise.

• Refused doses. A refused or not-administered dose (RXA-20 RE or NA) is not-done, with the reason from RXA-18.
• Deletions. A deleted one (RXA-21 D) is entered-in-error.
• Historical records. A record transcribed from somewhere else (RXA-9 other than 00) is not a primary source.
• Unknown amounts. An amount of 999 means unknown, not 999.
• Routes and sites. Each dose takes the route and site from the RXR after it, so a message with two doses does not give the second one the first one's route.

Awkward input. Each of these is reported in the notes rather than decided silently:

• Identifiers. PID-2 and PID-4, withdrawn after v2.7 but still sent, are kept like PID-3. CX.7 and CX.8 become

Identifier.period. An assigning authority carrying an ISO OID (AUSHIC&2.16.840.1.113883.3.879&ISO) becomes urn:oid:. A type code outside HL7 table 0203 is kept as text, not labelled as one.

• Merges. MRG on a merge event (A40 and its kin) sends the retired record too, inactive, with Patient.link both ways. On any

other event, such as an A08, nothing is merged and a warning says the prior identifier is still live.

• Times. A time of birth in PID-7 goes to the patient-birthTime extension. A timestamp with no offset takes the configured

timezone, otherwise the offset on MSH-7 (v2 presumes the sender's local time), otherwise UTC. A time of birth is the exception: with no offset from any of the three it is left out rather than labelled UTC, because a wrong offset can move a birth to another day. birthDate is kept, and a warning says the time was dropped and that setting a timezone for the feed keeps it.

• Results. Repeats of a text result are joined with line breaks. An ED result, or a coded one whose value is plainly Base64, becomes a

DocumentReference that the Observation points to in derivedFrom, since an R4 Observation has no attachment value. An SN comparator of = is dropped as redundant; <> keeps the text, because no quantity can say "not equal".

• Visits. An A08 with a discharge date (PV1-45) is a finished encounter. A missing or unknown patient class is the null

flavor UNK, because R4 requires a class.

• Z segments are named in a warning, since there is no standard map for them.

• Names. When the sender splits a family name (XPN.1, XCN.2) into its parts - a surname prefix and a surname, the person's

own and a partner's, as Dutch and Flemish names are sent - family is the whole name and the parts go in HL7's family-name extensions (humanname-own-prefix, -own-name, -partner-prefix, -partner-name).

• Procedures. PR1 becomes a Procedure with status unknown, since an ADT does not say whether it was done or planned; the

anaesthetist (PR1-8) and surgeon (PR1-11) are performers with SNOMED CT roles. An OPS code also gets its SNOMED CT category from its chapter, by HL7 Deutschland's OPS-SNOMED-Category map, which ISiK requires.

8.4.2 What a site adds: the bundle script

A national profile often wants what an HL7 v2 message does not carry: a hospital's IK number or ODS code, which contact level a visit is (ISiK), whether a given name is a first name or an initial (the Dutch nl-core). Perfuse does not guess those. A fhir destination's bundle_script is where a site writes them: JavaScript run on each converted Bundle, as bundle, before it is validated and sent. What the script leaves is what goes out, checked like any conversion, and a script that throws fails the message as any transformer does. The console has it under the destination's *Add what your systems know*.

destinations:
  - name: kis
    type: fhir
    fhir:
      url: https://fhir.klinikum.example/fhir
      version: "4.0.1"
      identifier_systems: {KLINIKUM-MUSTERSTADT: "https://fhir.klinikum-musterstadt.example/sid/patientennummer"}
      bundle_script: |
        bundle.entry.forEach(function (e) {
          if (e.resource.resourceType === "Organization" && e.resource.name === "KLINIKUM-MUSTERSTADT") {
            e.resource.identifier = [{system: "http://fhir.de/sid/arge-ik/iknr", value: "260326822"}];
          }
        });

perfuse fhir convert -bundle-script FILE runs the same script, so a site can try it on its own messages first. Two worked examples are in the repository: examples/isik/bundle-script.js (IKNR, Kontaktebene, MR-typed patient number, Diagnosetyp) and examples/nictiz/bundle-script.js (first names and initials). With them the invented German and Dutch messages in conformance/national go from 18 to 42 of 47 resources valid against ISiK and from 12 to 18 of 24 against nl-core; what is left is in the messages or the terminology server, and is listed there.

The Bundle goes through Perfuse's model on its way back, so a script's changes are checked and written in the destination's FHIR version. Members the model has no field for are kept as the script wrote them, inside data types too.

8.4.3 US Core 9.0.0 and USCDI v6

-us-core (and claim_us_core on a fhir destination) puts a US Core profile in meta.profile, but only on a resource that has been checked against that profile and found to conform. One that falls short is still converted and sent without the claim, and a note gives the reason, such as "US Core requires an encounter type, and this Encounter has none". The checks are transcribed from US Core 9.0.0, the version ONC's 2026 Standards Version Advancement Process approves for USCDI v6. They cover Patient, Encounter, the laboratory Observation and DiagnosticReport, Specimen, Practitioner, Organization, Location, Immunization, DocumentReference, the encounter-diagnosis Condition and AllergyIntolerance.

What the converter carries, by USCDI v6 data class:

Not carried, because v2 messages of these types do not hold them or Perfuse does not map them: Medications, Procedures, Goals and Preferences, Health Status Assessments, Care Plan, Family Health History, Medical Devices (UDI), Health Insurance Information, Vital Signs as a distinct profile, and Provenance.

8.4.4 R4 in both directions

A FHIR server declaring R4 accepts R4. That was not true of Encounters until this release. The server converted what it served to R4 but read what it received as if it were already in its internal form, so an R4 Encounter was refused with a 400. So was every bundle Perfuse's own ADT conversion produced, because each carries Encounter.class, which R4 writes as a single coding.

It was found the first time anything posted a converted ADT to Perfuse's own R4 server. A test now does that for every mapped message type, and another checks that everything written as R4 is read back unchanged.

8.4.5 International Patient Summary

GET /fhir/Patient/{id}/$summary, or GET /fhir/Patient/$summary?identifier=system|value, returns an International Patient Summary (HL7 IPS 2.0.0): a FHIR document Bundle whose Composition lists the patient's active problems, allergies, medicines, immunizations, results, vital signs, procedures, devices, past illnesses, social history and care plans, each with a readable narrative. It is the short record a clinician who has never met the patient reads first, and the summary the European Health Data Space exchanges between countries from 2029.

It is built from what the FHIR store holds, and nothing is invented:

• Records marked entered-in-error are left out.
• A resolved condition goes under past illness, not problems.
• A medicine order that was stopped or completed is history, not a current medicine.
• The three sections the IPS requires (problems, allergies, medicines) are always present. When one has nothing in it, the section

carries the coded empty reason unavailable and says the server holds no information, "which does not mean there is none". An empty allergy list must never read as "no known allergies".

• The practitioners, organisations, medicines and locations the entries point at are included, so the document reads on its own.

Access follows $everything: a token limited to one patient gets a 403 for another, and an identifier that matches two patients is refused rather than guessed. Only the IPS profile is built; asking for another profile is refused. The document Perfuse produces from its test records validates against the IPS 2.0.0 Bundle profile with the HL7 validator, with no errors. A record built from real feeds can still fail where the feed's own codes do (a display name the code system does not use, for example), because the summary passes the data on as it was received.

Exchange → Health links → Share fills the content with a patient's summary: type the patient's FHIR id and choose Use their patient summary, then read it and create the link. Building it is audited as fhir.summary.

8.4.6 Transfer summaries for post-acute care (PACIO)

When a patient leaves hospital for a nursing home, a rehabilitation unit or home health, the hospital's EHR sends a C-CDA: a transfer summary, a discharge summary or a CCD. Perfuse turns that document into the transfer summary PACIO's Transitions of Care guide describes (hl7.fhir.us.pacio-toc 1.0.0): one FHIR R4 document Bundle, US Core 8.0.1 inside, that the receiving facility's system can file without anyone reading XML.

• Every one of the guide's fifteen sections is present, each with its own text, in the guide's order: advance directives,

allergies, behavioral health, functional status, immunizations, discharge instructions, medical devices, medications, plan of care, problems, procedures, reason for referral, results, social history and vital signs.

• A section the document did not have is said to be missing, never filled in. It goes out empty, with the coded reason

unavailable and the sentence "The sending document had no ... section". An empty allergy section must not read as "no known allergies".

• A section carried as text alone keeps its text and gets no entries. Prose is not turned into coded data. Functional

status, behavioral health (the C-CDA's mental status section), advance directives, medical devices, plan of care, discharge instructions, reason for referral and social history are sent this way today; the notes say so for each.

• Coded entries become resources by the same rules as the ordinary conversion: allergies (US Core AllergyIntolerance),

problems and discharge diagnoses (US Core Condition, problem list or encounter diagnosis), procedures, immunizations, results, vital signs, and medications as a PACIO medication list of MedicationStatements (104204-3, discharged medication list, from a discharge medications section; 104202-7, active medication list, otherwise).

• Vital signs in FHIR's form. A systolic and a diastolic pressure taken together become one blood pressure panel

(85354-9) with two components, and a more specific code (body weight measured, 3141-9) also carries the code FHIR's vital-signs profiles fix (29463-7), beside the original.

• Who and from where. The document's author becomes the Composition's author (a Practitioner, with the NPI when its check

digit is valid), its custodian the custodian Organization, its encompassing encounter the stay the summary closes. A document with no person as author, or no custodian, is refused: the guide requires both, and Perfuse will not put a name on a clinical record that nobody gave.

• Negation keeps its meaning. "No known allergies" (a negated allergy to any substance) is sent as SNOMED CT 716186003; a

negated allergy to one drug is refused, because FHIR cannot say it and the resource would say the opposite; a negated problem is refuted.

Three ways to make one:

• A channel: a cda destination with write: transfer posts each document's transfer summary to the FHIR server's

Bundle endpoint (url), or writes <document>.transfer.json to dir. In the channel builder: Emit › A PACIO transfer summary.

• The command line: perfuse fhir transfer [-authority OID=URI] [-out dir] <document.xml>....
• The console: Documents, turn on Also make a PACIO transfer summary, and read the document.

Checked with the official FHIR validator against the TOC 1.0.0 Bundle profile, on HL7's own C-CDA examples (a transfer summary, a discharge summary and a CCD). The one error it reports is in the guide: every vital sign matches both its simple-observation and its vital-signs Bundle entry slices, so it cannot be avoided by any sender. Not yet done: turning the text-only sections' entries (functional status, mental status, plan of care, devices) into coded resources, and the guide's TOC DocumentReference that indexes a stored transfer summary.

8.4.7 Subscriptions

With -fhir-subscriptions, the FHIR endpoint sends notifications when an Encounter or an Appointment is created or changed. It follows the FHIR Subscriptions R5 Backport IG for R4, which is what CMS Interoperability Framework criterion 15 and TEFCA's FHIR roadmap use for appointment and encounter notifications.

A client creates a Subscription naming a topic, and optionally a filter such as Encounter?patient=Patient/123. The topics are listed in the capability statement:

A filter that names anything else is refused, not ignored. An ignored filter is a subscription that notifies about every patient when the client asked about one.

The properties the implementation is built around:

• An acknowledged change is never a lost notification. The notification is recorded in the same database transaction as the change it describes, and delivered from there, so it survives a restart. A test writes an Encounter, starts a new server on the same database, and checks the notification arrives.
• Notifications arrive in order, and gaps are visible. Event 2 is not sent before event 1 is accepted, and each notification carries the running count, so a receiver can tell when it has missed one.
• The server decides when a subscription is active. A new subscription is requested, and becomes active only when the endpoint accepts a handshake. A client that asks for active gets requested. A refused handshake is tried again four times over about fifteen seconds before the subscription is an error: it goes out the moment the subscription is stored, often before the client that created it is listening.
• A full-resource notification carries the version that changed. A discharge notification carries the discharge, not whatever the Encounter had become by the time delivery succeeded.
• Failure is bounded. A refused delivery is retried with a growing delay. After ten consecutive failures the subscription goes to error: later changes are counted but not queued, and updating the subscription resumes delivery from the oldest held notification. The count then shows how many were missed.

What a client can make the server do is limited deliberately:

• Endpoints must be https unless the operator passes -fhir-subscriptions-allow-http, which is for a test receiver.
• The egress policy is applied when a subscription is created, again at every delivery, and on the address each connection actually reaches (so a name that changes what it resolves to between the check and the connection is still refused); redirects are not followed.
• The payload defaults to id-only, which says what changed and lets the receiver fetch it with its own credentials.
• Nothing a receiver sends back is shown to anybody, only its status code.

It is off unless asked for, because once on, a FHIR client can make this server send patient data to a URL of the client's choosing. It needs an R4 endpoint that accepts writes, and refuses to start otherwise.

Not implemented, so nobody has to find out by trying:

• channels other than rest-hook
• heartbeats
• notifications on delete
• the $status and $events operations

The Subscriptions view shows each subscription's topic, filter and endpoint, how many events it has had, how many were accepted and how many are waiting, and the last reason one was refused. Header values and the endpoint's query string are withheld, because that is where a subscriber's credentials live.

8.5 NCPDP Telecommunication Standard

Pharmacy claims. Fixed-width header followed by variable segments.

Two details that matter, both of which are easy to get wrong and produce plausible results:

The header is exactly 56 bytes and fixed width. A short header cannot be detected by length alone, because a truncated header plus the following segments still exceeds 56 bytes. Detection is that a correct header never contains a separator byte, so the header is scanned for one and a message that has one is refused with the number of bytes it is short by.

0x1E and 0x1C are group and field start markers, not separators. Treating them as separators shifts every field one place left, and most of the resulting values stay plausible — a quantity lands where a day supply was expected and both are numbers.

8.6 NCPDP SCRIPT

Electronic prescriptions, in XML. The internal package is called eprescribe because script was taken by the JavaScript engine.

The central safety concern is the substitution flag, and it reads backwards from the intuition: on the wire, 0 means substitution is allowed and 1 means dispense as written.

An absent substitution flag is refused rather than defaulted. Both possible defaults reach the patient — one may dispense a generic where the prescriber required the brand, the other prevents a substitution the prescriber permitted — so there is no safe assumption and the message stops.

A Schedule II prescription with refills is refused, and the builder will not produce one.

Refusals and warnings are kept as separate lists rather than one severity-tagged list, because a reader who has to check a severity field to know whether the message was sent will eventually not check it.

Electronic prior authorization (PAInitiationRequest, PARequest, PAAppealRequest, PACancelRequest) and Real-Time Prescription Benefit are answered by the payer side at /ncpdp/script and /ncpdp/rtpb, from the drug formulary; see CMS-0057.

8.7 DICOM

Imaging. Perfuse can receive DICOM objects, query a remote archive, and store to one, over the classic DICOM network services or over DICOMweb, and it can keep an archive of its own for viewers.

DICOM is not a message format in the same sense as the others — objects are large, and the association handshake matters more than the payload parsing. The called_ae and calling_ae titles are the commonest reason a first connection fails, and the failure looks like a network problem rather than a configuration one.

8.7.1 What a C-STORE listener accepts

Left open, a DICOM listener accepts anything from anyone that can reach the port. Four settings under What this listener accepts narrow that, and the first is the one worth understanding.

Only accept these calling AE titles is the restriction. The *called* AE title — the one alongside the address — is the name a sender dials, so it identifies this listener rather than the sender, and it is not a restriction. Anybody who can reach the port can use the correct called AE title, because it is published to them. Without a list of permitted callers, any host on the network may push images into a clinical channel.

Only accept these SOP classes and only accept these transfer syntaxes take comma-separated UIDs. Empty accepts every kind of object and negotiates whatever compression the sender offers, which includes kinds this channel's destinations cannot handle. Refusing at the association is clearer to the sender than accepting the object and failing afterwards.

Largest object accepted is in bytes, and zero means no limit. Whole-slide images and long series run to gigabytes, so the limit is otherwise memory.

8.7.2 DICOMweb

DICOMweb is DICOM over HTTP: QIDO-RS searches, WADO-RS and WADO-URI retrieve, STOW-RS stores. Browser viewers such as OHIF speak only DICOMweb, and so do the cloud imaging services (Google Cloud Healthcare, Azure Health Data Services, AWS HealthImaging). Perfuse uses it in three places.

The imaging archive. Start the server with -dicomweb-archive DIR (Settings › Data › Imaging archive) and it keeps objects in that folder, indexed in SQLite, and serves them at /dicomweb on the console's own address: QIDO-RS at the study, series and instance levels, WADO-RS for objects, metadata, frames and bulk data, WADO-URI at /dicomweb/wado, and STOW-RS. Reading takes the viewer role and storing the operator role, with a session or an API token; every read and store is in Activity as dicomweb.read or dicomweb.store. An account limited to a tenant or to channel groups is refused, because the archive belongs to the whole server. Objects are kept exactly as received, so what a viewer retrieves is byte for byte what was stored. Frames are returned in the transfer syntax they were stored in; a request that would need transcoding answers 406 rather than a converted image.

A search on an attribute the archive does not index answers 400 rather than ignoring the condition and returning more studies than were asked for. Indexed: patient name (wildcards, and fuzzy matching with fuzzymatching=true), patient ID, birth date, sex, study date and time (ranges), accession number, study ID, description, referring physician, study, series and SOP instance UIDs (lists), modality, body part, series number and description, SOP class, instance number, rows, columns and number of frames.

The source. type: dicomweb listens for STOW-RS, at /dicom-web/studies by default (the path Orthanc and dcm4chee use), and sends every object through the channel as a DICOM message. The channel needs dataType: dicom. Set a bearer token or a username and password: without one, anybody who can reach the port can send images into the channel. The answer lists each object as stored or failed, with the DICOM failure reason, so a sender knows which to resend.

name: imaging-from-viewers
dataType: dicom
source:
  type: dicomweb
  dicomweb:
    listen: 0.0.0.0:8043
    token: ${STOW_TOKEN}
    tls: { enabled: true, cert_file: /etc/perfuse/imaging.crt, key_file: /etc/perfuse/imaging.key }
destinations:
  - name: archive
    type: dicomweb
    dicomweb:
      url: https://perfuse.example/dicomweb
      token: ${ARCHIVE_TOKEN}

The destination is in delivery, under DICOMweb archives.

Pointing OHIF at the archive

Use a DICOMweb data source with qidoRoot and wadoRoot set to the archive's address (the Imaging screen shows it, with the whole data-source block to copy), wadoUriRoot to that address followed by /wado, imageRendering and thumbnailRendering to wadors, and supportsFuzzyMatching true. A viewer on another origin needs that origin in -dicomweb-cors (Browser origins allowed to call it), and its requests need an API token in the Authorization header, because a browser on another origin does not send the console's session cookie. Serving OHIF from the same origin through a reverse proxy avoids both.

Tested against Orthanc with its DICOMweb plugin, in both directions: the destination stores into Orthanc, and Orthanc's DICOMweb client searches Perfuse's archive and retrieves a study byte-identical to the one stored. OHIF 3 lists the archive's studies and displays their frames with the settings above. OHIF and several other clients send type= unquoted in the Accept and Content-Type headers, which RFC 2045 does not allow; Perfuse accepts it.

8.8 IHE document sharing: XDS.b, XCA, XDR, MHD, PIXm and PDQm

Clinical documents shared between organisations the way health information exchanges, Carequality and eHealth Exchange do: a repository holds them, a registry indexes their metadata, and a community answers other communities' queries through a gateway. Start the server with -xds REPOSITORY-OID (Settings › Data › Document sharing) and it is all three, in this server's database, at these addresses, each taking an API token as a bearer token (the viewer role to query and retrieve, the operator role to submit; most affinity domains add mutual TLS in front):

The SOAP transactions are SOAP 1.2 with WS-Addressing, and MTOM/XOP where documents travel (a document inline as base64 is accepted too). A failed transaction is answered with a RegistryResponse carrying IHE's error codes, not a SOAP fault: XDSDuplicateUniqueIdInRegistry, XDSNonIdenticalHash, XDSPatientIdDoesNotMatch, XDSMissingDocument, XDSRegistryMetadataError (with the field that is missing), XDSStoredQueryMissingParam, XDSUnknownStoredQuery, XDSUnknownRepositoryId, XDSUnknownCommunity, and UnresolvedReferenceException. A replacement (RPLC, XFRM_RPLC) deprecates the document it replaces, which then answers only queries asking for deprecated documents; APND, XFRM and signs are kept as associations. Hash and size are computed by the repository and checked against what the submission says. On-demand documents and metadata update (ITI-57) are not supported, and a submission asking for them is refused with the reason.

MHD is the same registry in FHIR: a document provided over MHD is found by ITI-18 and over XCA, and one provided over XDS.b is found by ITI-67. A DocumentReference's id is the entry's UUID, its masterIdentifier the uniqueId, and its attachment's url the ITI-68 address of the document. Patients are resolved to the affinity domain's identifier from the FHIR store: the first identifier whose system is urn:oid:, or the Patient carried in the Bundle. PIXm answers every other identifier of the Patient with the one given (sourceIdentifier=system|value, narrowed by targetSystem), and 404 for one it does not know; PDQm searches by identifier, name, birth date, gender, address and telecom.

Publishing. A channel's xds destination publishes each clinical document it receives, a CDA document or one carried in an HL7 v2 message, to any XDS.b repository with ITI-41. The metadata is read from the document: the patient (the identifier in patient_domain, the affinity domain's assigning authority), title, type (as typeCode and, unless set, classCode), creation and service times, author, confidentiality, language and format (C-CDA 2.1 or 1.1 structured body, XDS-SD, or mimeTypeSufficient, from its templates); and completed from what a document does not say: the sender's source_id, the facility_type and practice_setting every registry requires. The repository's RegistryResponse decides the delivery: a Failure, or an error in a PartialSuccess, is a failed delivery with the registry's error codes.

destinations:
  - name: hie
    type: xds
    xds:
      url: https://hie.example/xds/repository
      source_id: 1.2.840.114350.1.13.99
      patient_domain: 1.2.840.114350.1.13.99.2.7.5.737384.14
      facility_type: { code: "225732001", scheme: 2.16.840.1.113883.6.96, display: Community hospital }
      practice_setting: { code: "394802001", scheme: 2.16.840.1.113883.6.96, display: General medicine }
      tls: { enabled: true, cert_file: /etc/perfuse/hie.crt, key_file: /etc/perfuse/hie.key }

XDR. Add direct_from (your Direct address) and direct_to (the recipients') and the same destination sends XDR as Direct's transport, as the Direct Project's *XDR and XDM for Direct Messaging* describes it: a Direct addressing block (urn:direct:addressing) in the SOAP header names sender and recipients, and the submission's intendedRecipient names each recipient (||^^Internet^address). Point url at the recipient's XDR endpoint or a HISP that takes XDR. XDR travels over TLS, usually with a client certificate (tls), and is not S/MIME. A direct source takes XDR too (see Direct below).

    xds:
      url: https://xdr.hisp.example/xdr
      source_id: 1.2.840.114350.1.13.99
      patient_domain: 1.2.840.114350.1.13.99.2.7.5.737384.14
      facility_type: { code: "225732001", scheme: 2.16.840.1.113883.6.96, display: Community hospital }
      practice_setting: { code: "394802001", scheme: 2.16.840.1.113883.6.96, display: General medicine }
      direct_from: referrals@direct.hospital.example
      direct_to: ["intake@direct.clinic.example"]
      tls: { enabled: true, cert_file: /etc/perfuse/xdr.crt, key_file: /etc/perfuse/xdr.key }

PIX and PDQ in HL7 version 3. With the patient index on (-mpi), /pixv3 is a PIX Manager and /pdqv3 a PDQ Supplier over SOAP 1.2, for the hospitals and exchanges that still speak IHE's v3 profiles. A source feeds patients with ITI-44 (record added PRPA_IN201301UV02, revised PRPA_IN201302UV02, duplicates resolved PRPA_IN201304UV02): the patient's first identifier is its record, the others and those in asOtherIDs are identifiers it carries, and a merge folds the prior record's identifier into the surviving one, as an HL7 v2 A40 does. ITI-45 (PRPA_IN201309UV02) answers the other identifiers of the person holding one, narrowed by dataSource, in Patient.id; the queried identifier comes back only in the repeated query. ITI-47 (PRPA_IN201305UV02) matches demographics (name, gender, birth time, identifier, address, telecom) with the index's own matcher, minimumDegreeMatch as a score out of 100, otherIDsScopingOrganization limiting the domains, and initialQuantity paging the answer: the rest comes with QUQI_IN000003UV01 for ten minutes, or is dropped by its cancel. The answers follow the transactions' cases: an unknown patient or domain is AE with error 204 and the location of the parameter, a known patient with nothing in the domains asked for is NF. v3 names an authority by OID only, so an identifier whose system is a URL with no OID behind it (some national numbers) is left out of v3 answers and given over FHIR; set the enterprise identifier's system to an OID (urn:oid:..., in the index settings) for the EUID and the custodian to appear. The viewer role queries and the operator role feeds; every transaction is audited with an identifier, never a name. A bare v3 message posted as application/xml is answered in kind, which is handy for testing by hand.

Exchange › Document sharing shows what the registry holds and where it is reached, finds a patient's documents in this registry or another (a registry's ITI-18 or a gateway's ITI-38), downloads one, and publishes a CDA document by hand with the metadata a destination would give it.

Verified against the NIST XDS Toolkit 7.13.0, the IHE reference implementation: Perfuse's ITI-41, ITI-18 and ITI-43 against its Registry/Repository simulator (accepted with no validation errors, the document retrieved byte-identical), and its Initiating Gateway simulator querying and retrieving from Perfuse's Responding Gateway over XCA, with no errors in its log. Every SOAP message Perfuse writes validates against the ebXML Registry 3.0 and XDS.b schemas, and the MHD DocumentReference and SubmissionSet against IHE MHD 4.2.2 with the HL7 FHIR validator. XDR from an xds destination with a Direct addressing block was accepted by the toolkit's Document Recipient simulator, whose metadata validation found the one defect described in docs/verification.md, and by ONC SITE's XDR validator, the Direct XDR checklist the (h)(2) certification test applies. The PIX and PDQ v3 answers validate against IHE's HL7 V3 schemas (NE2008 multicacheschemas), and IHE's own sample messages (the ITI-44 feed, merge, ITI-45 query, ITI-47 query, continuation and cancel) are answered as their published responses show. Not yet checked against an independent PIX or PDQ v3 implementation, Gazelle or a Connectathon.

8.9 Direct secure messaging

Direct is how US providers send each other referrals, summaries and results by secure e-mail: every message is signed with the sender's certificate and encrypted to the recipient's (S/MIME), and travels between HISPs (Health Information Service Providers) that issue the addresses and vouch for them. Perfuse is the edge system beside your HISP, not a HISP: the HISP issues your address, its certificate and its key, and you keep its trust bundle (such as DirectTrust's). It follows the Direct Applicability Statement for Secure Health Transport 1.2, the Implementation Guide for Delivery Notification, IHE XDM (ITI TF-1 Annex 15) for documents with metadata, the Certificate Discovery for Direct Project Implementation Guide (DNS and LDAP), and XDR and XDM for Direct Messaging.

Sending. A direct destination signs each message as your address (SHA-256, RSA), encrypts it to every recipient's certificate and your own (AES-256-CBC, RSA key transport), and submits it to the HISP by SMTP with STARTTLS required. The message travels as an attachment named by its content (document.xml, message.hl7, resource.json), or, with xdm: true, a CDA document travels as an IHE XDM package (IHE_XDM/SUBSET01/METADATA.XML with the document and its hash and size, plus INDEX.HTM and README.TXT) that receiving EHRs import with its metadata. Recipient certificates come from the Direct address book (below), then from DNS, where Direct publishes them as CERT records (RFC 4398): under the address with its @ made a dot, else under its domain; then from the recipient domain's LDAP directory, which its _ldap._tcp SRV record names (or ldap: host:port; ldap: off never asks one): each naming context is searched anonymously for an entry whose mail is the address, then the domain, and its userSMIMECertificate or userCertificate read. A certificate is used only when it is for the address or its domain, has not expired, and chains to one of your anchors, fetching any intermediate issuer its Authority Information Access extension names; and it is refused when its issuer's revocation list (from its CRL distribution point, signed by that issuer) lists it. A list that cannot be fetched does not stop delivery. A recipient with no such certificate is a failed delivery, never plain e-mail. to and subject take field references such as {PV1-8.1}, and request_mdn asks the recipient for a delivery notification.

destinations:
  - name: referrals
    type: direct
    direct:
      address: referrals@direct.hospital.example
      cert_file: /etc/perfuse/direct/referrals.crt   # with its chain after it
      key_file: /etc/perfuse/direct/referrals.key
      anchors_file: /etc/perfuse/direct/anchors.pem
      to: ["intake@direct.clinic.example"]
      subject: "Referral for {PID-5.1}"
      text: "Please see the attached summary."
      xdm: true
      xdm_source_id: 1.2.840.114350.1.13.99
      smtp_host: smtp.hisp.example:587
      username: referrals
      password: ${DIRECT_HISP_PASSWORD}
      request_mdn: true

Receiving. A direct source is the SMTP server the HISP delivers your address's mail to. It takes mail for that address only (anything else is refused at RCPT), requires STARTTLS when given a certificate, and opens each message before anything reads it: decrypts it with your key, verifies the signature against your anchors, and checks that the signing certificate is for the From address or its domain. A message that is not encrypted S/MIME, is signed by a sender you do not trust, or is signed by a certificate for someone else is refused at DATA with the reason, so the HISP keeps it and reports it to the sender; Perfuse never accepts what it then drops. An XDM package's documents each become a message (checked against the hashes in its metadata); otherwise each attachment does, or the text when there is none. With smtp_host set, each message taken in is answered with a signed, encrypted "processed" notification (MDN), and notifications arriving for what you sent are logged.

source:
  type: direct
  direct:
    address: intake@direct.clinic.example
    cert_file: /etc/perfuse/direct/intake.crt
    key_file: /etc/perfuse/direct/intake.key
    anchors_file: /etc/perfuse/direct/anchors.pem
    listen: 0.0.0.0:2525
    tls_cert: /etc/perfuse/tls/server.crt
    tls_key: /etc/perfuse/tls/server.key
    smtp_host: smtp.hisp.example:587

From the HISP's mailbox. A HISP that keeps mail rather than delivering it gives the address an IMAP mailbox: imap reads it (TLS or STARTTLS, every poll a fresh session), opens each message as above, moves what was taken to move_to (or deletes it) and what could not be opened to error_folder, so nothing is read twice. listen may then be left out. A HISP whose mail server has a private certificate is trusted with tls.ca_file (its certificate, or its authority's) and tls.server_name; verification cannot be turned off.

    imap:
      host: imap.hisp.example
      username: intake@direct.clinic.example
      password: ${DIRECT_MAILBOX_PASSWORD}
      move_to: Processed

XDR. xdr takes XDR at /xdr on its own HTTPS address, as a HISP sends Direct it converted to SOAP or a partner sends point to point: an ITI-41 Provide and Register request whose documents each become a message. A submission whose Direct addressing block names another address is refused, and one the channel does not take is answered with a RegistryResponse failure saying why. client_ca_file requires a client certificate from those authorities. XDR is protected by TLS, not S/MIME, so a source that only takes XDR needs the address but not its certificate, key or anchors. Each document becomes a message of the channel's dataType: CDA documents need raw (passed on as they are) or hl7v3, since the default, hl7, expects HL7 v2 and refuses them.

    xdr:
      listen: 0.0.0.0:8445
      tls_cert: /etc/perfuse/tls/server.crt
      tls_key: /etc/perfuse/tls/server.key
      client_ca_file: /etc/perfuse/direct/hisp-clients.pem

Exchange › Direct lists the Direct addresses your channels send and receive as, with their certificates, expiry and anchors; keeps the address book of correspondents (name, organisation, notes and certificate, pasted from their HISP or found in DNS or LDAP, and refused when it is not for that address or domain); and looks up an address's certificates in DNS or LDAP without saving them. The book is the directory direct-certs beside the database, one PEM file per address or domain, which a destination reads unless it names its own recipient_certs_dir.

Verified against OpenSSL 4.0's cms and smime in both directions: what Perfuse signs and encrypts OpenSSL verifies and decrypts (PKCS#1 v1.5 and OAEP key transport), and Perfuse opens what OpenSSL signs and encrypts (AES-128 and AES-256). A message made with openssl smime and delivered over SMTP is received, opened and stored by a channel, and one Perfuse sends a message to another through a HISP stand-in, which answers with an MDN the sender opens. Certificates are found in OpenLDAP 2.4 (address-bound and domain-bound, written by OpenLDAP's own ldapadd); a Direct message is read from a GreenMail IMAP mailbox and opened, and one that is not Direct moved to the error folder; XDR from an xds destination is taken by a direct source and refused when addressed to someone else, and accepted by the NIST XDS Toolkit's Document Recipient and ONC SITE's XDR validator; SITE's Direct XDR Edge Test Tool sent both its minimal and full metadata messages to a direct source, which took them. Against ONC's Direct Certificate Discovery Tool, a Direct destination chooses the right certificate, or none, in all 18 of its discovery cases (D1 to D18: expired, revoked and AIA-issued certificates, SRV priority and weight, an unreachable directory). A Direct source reads a message from SITE's own HISP (Apache James) over IMAP with STARTTLS. Not yet tested: SMTP exchange with SITE's HISP (AWS holds outbound mail on port 25 for new accounts) or with an accredited HISP.

8.10 SQL on FHIR views

A ViewDefinition (HL7 SQL on FHIR v2) turns each FHIR resource of one type into rows of named columns, each column a FHIRPath expression, so FHIR data can be read as tables by DuckDB, Athena, Spark, a data warehouse or a spreadsheet. Perfuse runs them with its own FHIRPath engine: column, nested select, forEach, forEachOrNull, repeat and unionAll, where, constant (every value[x] type), collection columns, %rowIndex, and the getResourceKey() and getReferenceKey(type) join keys.

{
  "resourceType": "ViewDefinition",
  "name": "blood_pressure",
  "resource": "Observation",
  "constant": [{ "name": "systolic", "valueCode": "8480-6" }],
  "where": [{ "path": "code.coding.exists(system = 'http://loinc.org' and code = '85354-9')" }],
  "select": [{ "column": [
    { "name": "id", "path": "getResourceKey()", "type": "id" },
    { "name": "patient_id", "path": "subject.getReferenceKey(Patient)", "type": "id" },
    { "name": "systolic", "path": "component.where(code.coding.code = %systolic).value.ofType(Quantity).value.first()", "type": "decimal" }
  ]}]
}

Monitor › SQL on FHIR runs a view over this server's FHIR store (one patient, or all) or over resources pasted in (NDJSON from a bulk export, a Bundle, a JSON array), shows the rows, and downloads them as CSV, NDJSON or Parquet. It starts from five example views (patient demographics, observations with a value, blood pressure, conditions, encounters) and saves views to the views directory beside the database, one JSON file each.

The FHIR endpoint answers the specification's $sql-run at the system level, by GET or POST, for a ViewDefinition subject given inline (subjectResource), by subjectReference (ViewDefinition/<name>, a saved view) or by subjectCanonical (a saved view's url), with _format (csv, ndjson (the default), json or parquet), header, patient, _since, _limit, and resource to run over resources sent with the request instead of the store. It is a read: a SMART token needs read scope for the view's resource type, a token bound to one patient gets that patient's rows only, and granular scopes narrow the resources read, as they do a search. More than a million rows needs _limit, patient or _since.

perfuse sof -view v.json [-format csv|ndjson|json|parquet] [-o out] files... runs a view over FHIR files without a server: the NDJSON files of a bulk export, Bundles or arrays.

perfuse sof -view blood_pressure.json -format parquet -o bp.parquet export/Observation.ndjson
duckdb -c "SELECT patient_id, avg(systolic) FROM 'bp.parquet' GROUP BY 1"

Parquet files have one row group and uncompressed PLAIN pages; booleans are BOOLEAN, integer types INT64, decimals DOUBLE and everything else UTF-8 strings (a collection column as its JSON).

Verified with the official SQL on FHIR test suite (the 144 tests of the sql-on-fhir.js repository's tests/, run on every build: all pass), and the Parquet output read back by DuckDB 1.5.6 with the right types and values. Not supported: SQLQuery and SQLView Libraries (SQL over the views' tables), $sql-export, _format=fhir, and the source and group parameters; each is refused with the reason.

8.11 Digital quality measures

A digital quality measure counts the patients in each population of a FHIR Measure over a measurement period (initial population, denominator, denominator exclusions and exceptions, numerator, numerator exclusions) and scores the result. The answer is a FHIR MeasureReport, shaped as the Da Vinci Data Exchange for Quality Measures (DEQM) guide asks. This is where CMS's eCQM programmes and NCQA's digital HEDIS are heading.

In Perfuse the population criteria are FHIRPath ("language": "text/fhirpath"), run by the same engine as SQL on FHIR. Each criterion is evaluated once per patient. Its focus is a Bundle of that patient's record (the Patient compartment), and it has these variables: %subject (the Patient), %periodStart and %periodEnd (the period, as dateTimes) and %"Measurement Period". A criterion gives true or false; a single value that exists counts as true.

{
  "code": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/measure-population", "code": "numerator" }] },
  "criteria": {
    "language": "text/fhirpath",
    "expression": "entry.resource.ofType(Observation).where(code.coding.where(system = 'http://loinc.org' and code = '4548-4').exists() and effective.ofType(dateTime) >= %periodStart and effective.ofType(dateTime) <= %periodEnd).exists()"
  }
}

The populations nest as the Measure specification says. A patient is in the denominator only if in the initial population. A denominator exclusion takes the patient out before the numerator is judged. A denominator exception counts only for a patient not in the numerator. A proportion's score is (numerator − numerator exclusions) / (denominator − exclusions − exceptions); a ratio's is numerator / denominator; a cohort has counts and no score. Single-criterion stratifiers split every population by their value (sex, say).

Perfuse has no CQL engine. The published CMS eCQMs and HEDIS digital measures are written in CQL, so they cannot be run as they are. A Measure whose criteria are CQL is refused with that reason. Write the logic as FHIRPath instead. Continuous-variable scoring, multi-component stratifiers and Group or Practitioner subjects are refused the same way.

Monitor › Quality measures evaluates a measure over this server's FHIR store or over pasted resources, for a period. It offers three reports: a summary, a summary with the patients in each population, or one patient. The screen shows the populations, the score and the strata, and downloads the MeasureReport. It starts from three examples: blood pressure under control, diabetes with an HbA1c test, and patients seen in the period. They are illustrative, written for this manual, and are not CMS eCQMs or HEDIS measures. Save to the FHIR store checks the Measure and stores it as a Measure resource.

The FHIR endpoint answers Measure/[id]/$evaluate-measure and Measure/$evaluate-measure?measure=<url>, by GET or by POST of a Parameters resource. Parameters:

• periodStart and periodEnd: required. A date means the whole day.
• reportType: summary, subject or subject-list.
• subject: Patient/<id>.
• reporter: Organization/<id>. When it is absent, the report contains an Organization named by serve -measure-reporter.
• measure: a Measure sent inline, as a POST parameter.

The report is returned, not stored. The operation is a read, so a SMART token needs read access to Measure and to Patient. A token bound to one patient gets an individual report about that patient and no other.

perfuse measure -measure m.json -period-start 2026-01-01 -period-end 2026-12-31 [-type summary|subject|subject-list] [-subject Patient/ID] [-o out] files... evaluates a measure over FHIR files (a bulk export's NDJSON, Bundles, arrays) without a server. -measure example:example-bp-control runs a shipped example, and -examples lists them.

Verified. The HL7 FHIR validator checks the shipped Measures against FHIR R4, with no errors. It checks a summary, an individual and a subject-list MeasureReport against the DEQM 5.0.0 summary, individual and subject-list profiles, also with no errors. Not verified: equivalence with any published eCQM, since none can be run here without CQL.

8.12 The patient index (MPI)

A master patient index links the records every system keeps for a person (the hospital's MRN, the clinic's, the lab's) into one enterprise identifier, the EUID. It is off until somebody decides to keep one, because it is a table of patients' names, birth dates and identifiers: turn on Settings → Data → Patient index (or serve -mpi) and restart. It lives in mpi.db beside the main database.

Feeding it. Add a destination of type mpi (The patient index in the builder) to the channels that carry registrations. It reads the PID of each HL7 v2 message, or a FHIR Patient on a raw channel. The record's own identifier is the PID-3 repetition of type MR (id_type changes it); the others, and PID-19, become its other identifiers. An assigning authority with a universal identifier (PID-3.4.2 with type ISO) becomes urn:oid:...; one with only a namespace is mapped by authorities, or becomes urn:perfuse:aa:<namespace>. An A40, A34, A18 or A39 merges the person holding MRG-1's identifier into the person holding PID-3's (no_merge ignores them).

destinations:
  - name: index
    type: mpi
    mpi:
      authorities: { HOSP: "urn:oid:1.2.840.114350.1.13.1" }

Matching. A new record is linked in this order:

1. Trusted identifiers. A record sharing an identifier from a system listed as

trusted (a national identifier, an enterprise number) is the same person, with no scoring. Never list a system a family shares, such as a payer's subscriber number.

1. Score. Otherwise the people whose records could match are found by blocking

(the same-sounding family name and birth year, the same birth date, or the same phone number) and scored with Fellegi-Sunter weights over family and given name (Jaro-Winkler and Soundex, accents and punctuation ignored, swapped names noticed), birth date (a day and month swapped is partial agreement), sex, postal code, phone and address. Only fields both records have count. The score is the evidence found as a share of the evidence possible. Blocking uses five keys, so one error does not hide a person: family-name sound and birth year, birth date, phone, both names' sounds (in either order), and postal code with the given name's sound.

1. Decision. By default nothing links on a score alone. A record scoring at

or above the review threshold (60%) becomes a new person and the possible match waits on the review queue; those at or above the automatic threshold (90%) with family name and birth date both agreeing are marked *certain*. Linking two people into one (an overlay) puts one patient's results in another's chart, so automatic linking is a switch an administrator turns on (Link certain matches without asking anybody) once the queue has shown the certain ones are right. With it on, a certain match links when no second person scores as high. Below the review threshold the record is a new person.

National numbers. The NHS number (and Scotland's CHI and Northern Ireland's Health and Care number), Ireland's PPSN and IHI, Germany's KVNR, Austria's SVNR, Switzerland's AHV number, the Netherlands' BSN, Belgium's national register number, Luxembourg's matricule, France's INS (NIR and NIA), Italy's codice fiscale, Spain's DNI/NIE and CIP-SNS, Portugal's SNS number, the Nordic personal numbers (Sweden, Denmark, Norway with its D number, Finland, Iceland), the Baltic codes, Poland's PESEL, the Czech and Slovak birth numbers, and the Hungarian, Romanian, Bulgarian, Croatian, Slovenian and Greek numbers are known to the index. Each is stored one way: under its scheme's system, spaces and dots removed, so the NHS number sent as urn:oid:2.16.840.1.113883.2.1.4.1|999 000 0018 by one system and as https://fhir.nhs.uk/Id/nhs-number|9990000018 by another is one identifier. An HL7 v2 PID-3 repetition whose identifier type is NN and a country's three-letter code (NNDEU, NNNLD) is read as that country's main number, and type NH from the NHS authority as the NHS number. Every number's check digit is tested: one that fails is kept on its record, reported (masked) in the answer, and never used to link or to find anybody, since a mistyped digit usually makes somebody else's number. Denmark's CPR is checked for its date only, because numbers issued since 2007 need not pass the old modulus 11.

The settings list every scheme with its format, its check and the system it is stored under. Systems taken from the country's own FHIR guide (UK Core, fhir.de, Nictiz, CH Core, ANS, HL7 Italia, MedCom, the Swedish, Norwegian and Finnish OID registers) are marked as such; the others are defaults to change to the national value, which a site can do per scheme (the old one is still recognised). Trusting a scheme is one tick. National numbers are shown in full to editors and above by default and masked (the last few characters) to everyone else; Who sees numbers in full changes that, down to viewers or up to administrators only. Where a country's law limits a number's use (France's Référentiel INS, Ireland's PPSN, Belgium's national register number, Germany's §290 SGB V), the settings say so. GET /api/mpi/schemes lists the schemes and POST /api/mpi/check checks one number without storing it. FHIR $match and PIXm answer authorised clients with numbers in full.

A date written day- or month-first (08/15/1972) is kept as written and does not match a year-first one: the US and European orders disagree, and guessing would link the wrong people.

The Patient index screen (Build) shows the counts, finds people by name, number, EUID or birth date, and opens each person: their records, every identifier, and the history of what happened to them and who did it. Editors decide reviews (The same person links them; Different people keeps them apart for good), move a record to another person, take a record out (Not this person), and merge two people. Administrators set the thresholds, the trusted identifier systems, the national numbers and the EUID's system. Every search and every person read is written to the audit log.

Answering others. POST /fhir/Patient/$match (FHIR's operation, as IHE PDQm ITI-119 uses it) takes a Patient and returns the people who could be it, best first, each a Patient whose id is the EUID, with every identifier, search.score, and the match-grade extension (certain, probable, possible); onlyCertainMatches and count are honoured. PIXm (/mhd/Patient/$ihe-pix, ITI-83) answers from the index: every identifier of every record linked to the person, and the EUID. So do PIX and PDQ in HL7 v3 (/pixv3, /pdqv3; see IHE document sharing), which also feed it.

The API is /api/mpi (summary and search), /api/mpi/persons/{euid}, /api/mpi/find, /api/mpi/reviews, /api/mpi/records (register, link, unlink), /api/mpi/merge and /api/mpi/settings.

Weights. The default Fellegi-Sunter weights come from the record-linkage literature for hospital registration data. Estimate from our records (in the settings, administrators; POST /api/mpi/estimate) fits them to the site's own index with expectation-maximisation, no reviewed pairs needed: m (agreement among true matches) from the pairs blocking brings together, u (agreement by chance) from 20,000 pairs drawn at random, since blocked pairs agree on names and dates by construction. The estimate is shown beside the weights in use and changes nothing until it is used and saved. A field compared on too few pairs keeps its default. The fit assumes the fields are independent given the class, which they are not quite, so treat a large change with suspicion.

Measured. On FEBRL dataset 3 (5,000 synthetic records of 2,000 people, the duplicates carrying typing errors, swapped fields, missing values and nicknames; PERFUSE_TEST_FEBRL), registered in file order with a reviewer answering every queued pair correctly:

No record was ever linked to the wrong person, and none of the 2,000 new people was queued needlessly. The missed ones differ on nearly every field (a birth date and an address both mistyped, say) and score below the review threshold. FEBRL is synthetic and has few namesakes; a real index has more, so its review queue will be longer, and these numbers are a floor on care, not a promise.

8.13 Delimited

CSV and its relatives. The options are on the source in the builder, and the format reference lists the file keys.

Paths address columns. A named column is available when a header row is declared or the names are given; otherwise columns are positional.

8.13.1 Naming the columns

There are two ways, and they are exclusive. Either the first row of the file names them — the first row names the columns — or you list them yourself, in order. Declaring a header means the row is not treated as data.

If neither is set, columns can only be addressed by position, so a filter written against a name has nothing to match. Turning the header on removes the list of names rather than keeping both: with a header the names come from the file, so a list left behind would be ignored, and a channel that reads as though it chose the names when the file chose them is harder to debug than one that refuses.

8.13.2 What a filter or a script sees

One delimited document becomes many messages, so this needs stating before you write either.

With splitting on, everything runs per row. Declarative steps, the filter and the transformer script all see one row, and a path means *this* row's column. A filter that rejects a row rejects that row and no other, and the received count is rows rather than documents.

With splitting off, the message is the whole document and a write that crosses rows is refused rather than applied to the first one. That refusal is deliberate: silently writing to row one is the behaviour that produces a file which looks transformed and is not.

8.13.3 The three that change what counts as an error

Accept rows with the wrong number of columns is off by default. A row with too many or too few columns is then an error, which is what catches a file whose shape changed without warning. Turning it on accepts the row and leaves the missing columns empty.

Trim spaces around each value fixes the common case of a value padded to a column width. Leave it off where trailing spaces are significant, which they occasionally are in an identifier.

Keep blank lines as rows is off by default and usually should be. On, a blank line becomes a row of empty columns, which matters only when a count has to match the file exactly.

8.14 Raw

No parsing at all. The message is bytes.

Use this when the content is not something Perfuse understands and does not need to: a PDF being moved between systems, a proprietary format, an already-formed document being forwarded unchanged.

The cost is that nothing which depends on structure works — no field-level transformation, no filter on a field, no field-level comparison in the parity checker. A raw channel is a pipe, and it is honest about being one.

8.15 Choosing

If the message is HL7 v2, use hl7, even if you only intend to forward it unchanged. Parsing gives you the trace, the field-level statistics, the ability to filter later and the ability to compare. raw on parseable content buys nothing and loses all of that.

Use raw when parsing would fail or would be a lie about the content.

8.16 SMART Health Links and Cards

CMS's *Kill the Clipboard* asks providers to accept a patient's records from a QR code at check-in, and to hand the visit record back the same way. The QR code holds a SMART Health Link (shlink:/...): an address, a 256-bit key and, optionally, a label, an expiry and a passcode flag. Exchange → Health links reads one.

Receiving. Paste the link, or scan it with the camera where the browser can (Chrome and Edge). Perfuse fetches the manifest, decrypts each file with the key from the link, summarises any FHIR bundle - who the patient is, how many of each resource - and checks any SMART Health Card inside against its issuer's published key. *Deliver to the channel* hands the FHIR content to a channel as a message, which is how it reaches the EHR. The fetch is held to the egress policy at connect time, plain HTTP is refused, and the response of a server that is not a manifest server is never shown, because the address came from a stranger's QR code.

Sharing. *Share* encrypts a FHIR bundle, hosts it, and shows the link and its QR code once. The server keeps the ciphertext and not the key - it cannot open what it hosts, and cannot show the link again. A passcode is hashed; ten wrong ones disable the link. Links expire after 30 days by default, can be revoked, and list how often and by whom they were fetched. Start the server with -public-url set to the https address patients' phones reach; the manifest URL it builds must fit the specification's 128 characters.

Verifying a card. *Verify a card* takes a numeric shc:/ QR (one chunk or several), a .smart-health-card file or a JWS, and says whether the signature matches the issuer's key.

8.17 UN/EDIFACT

dataType: edifact reads UN/EDIFACT interchanges (ISO 9735): ORDERS, INVOIC, DESADV, IFTSTA and the rest, including the European healthcare claim and laboratory messages. The service string advice (UNA) is honoured, with the release character and, for syntax version 4, the repetition separator; functional groups (UNG/UNE) are optional. The interchange is delivered exactly as the sender wrote it.

name: supplier-orders
dataType: edifact
edifact:
  envelope: require      # require (default), warn, or ignore
  split: false           # true: one interchange per message
  acknowledge: contrl    # none (default) or contrl
filter: 'UNB-2.1 == "5412345000013"'
source:
  type: as2              # or http, sftp, file, email ...
  # ...
destinations:
  - name: orders
    type: file
    dir: /data/orders
    filter: 'UNH-2.1 == "ORDERS"'

The envelope. UNT's segment count and reference, UNE's message count and reference, and UNZ's count and reference are compared with what the interchange holds. With require, the default, a mismatch refuses the interchange (it is how a transfer cut short shows); warn accepts it and logs a warning; ignore does not check.

Paths, for the channel and destination filters, count elements and components from 1 in the order the segment is written, as implementation guides number them: BGM-2 (the document number), BGM-1.1, NAD(2)-2.1 (the second NAD's party), LIN-3(2).1 (a repetition), UNB-2.1 (the sender), UNH-2.1 (the message type). A path without an occurrence addresses every one.

Splitting delivers one interchange per message, each with the original UNB (and group header) and trailers that count one, so an order can be filtered, searched and retried on its own. Destination filters see each piece. A file destination names files by message type (ORDERS_INVOIC-20261017.edi), and ${control_id} is the interchange reference.

CONTRL. With acknowledge: contrl, a sender posting over HTTP is answered with a CONTRL syntax and service report: UCI action 7 when the interchange was read and delivered, 4 when it was refused or could not be delivered (HTTP 400 or 502 then). It cannot be combined with split, since a CONTRL answers a whole interchange. Over AS2 the partner's receipt is the acknowledgement.

Not offered: the message directories (which segments ORDERS D.96A allows), so the structure is checked, not the content; transformations, which would rewrite a partner's document; and filter or transformer scripts (a preprocessor runs, before parsing). Checked against pydifact 0.1.8, an independent parser, in both directions.

9 Acknowledgements

An acknowledgement tells the sender what happened. For HL7 v2 over MLLP it is an ACK message; the sender will not send the next message until it arrives, and will usually resend if it does not.

Getting acknowledgements wrong is the most common way an integration silently loses data, because a sender that is being acknowledged has no reason to complain.

9.1 Timing

Covered in message flow, and the summary is: ack.when is on_delivery by default, meaning the acknowledgement is sent only after every enabled destination accepted the message. on_receipt sends it as soon as the message is parsed and queued.

9.2 What Perfuse sends

An AA when the message was accepted, an AE when it was rejected for a reason the sender could act on, and an AR when it was rejected for a reason the sender cannot.

The distinction between AE and AR is who has to do something. AE means the message had a problem — a field that would not parse as a date, a required segment missing — and the sender can correct it and resend. AR means Perfuse could not accept it regardless of content, which usually means a configuration or availability problem at this end. A sender that resends after an AR will get the same answer.

9.3 Identifying this engine

ack.application and ack.facility populate MSH-3 and MSH-4 of the acknowledgement.

When both are empty the acknowledgement mirrors the original receiver — it uses whatever the incoming message had in MSH-5 and MSH-6. That is what most senders expect, and it is the default for that reason.

Set them explicitly when the sender validates them, or when several Perfuse instances handle the same feed and you need to know which one answered.

9.4 The trigger event

ack.include_trigger_event sends ACK^A01 rather than a bare ACK.

Some receivers require it and others reject it, which is why it is an explicit option with no clever default. If a sender is refusing your acknowledgements and the content looks right, this is the first thing to try.

9.5 Negative acknowledgements are not failures to hide

A NACK treated as a success is one of the most damaging misconfigurations possible, and it is common enough to be worth naming. It happens when a destination sends back a negative acknowledgement and the sending side records the *transmission* as successful because the bytes went out and something came back.

Perfuse reads the acknowledgement it receives from an MLLP destination and records the outcome accordingly. An AE or AR from a downstream system is a delivery failure, is retried according to the destination's policy, and counts towards the failure rate that alerts fire on.

9.6 Timeouts

Waiting for an acknowledgement is bounded. When it does not arrive in time the delivery is a failure and is queued for retry.

A timeout is not the same as a rejection and is recorded differently. A rejection means the far side considered the message and declined it; a timeout means you do not know whether it was processed. That distinction decides whether a retry is safe: retrying after a rejection is pointless, and retrying after a timeout risks a duplicate. Perfuse retries after a timeout, because a missing clinical message is generally worse than a duplicate one, and the receiving system is generally able to detect a repeated message control ID.

Whether that trade is right for a given feed is a judgement, and it is worth making deliberately for anything where a duplicate has a clinical consequence — an order, a medication administration — rather than accepting the default silently.

9.7 Sources that do not acknowledge

Not every transport has the concept. A file source has nowhere to send an acknowledgement; a broker source acknowledges to the broker rather than to the original sender; an HTTP source answers with a status code.

Where the source cannot deliver the acknowledgement mode a channel asks for, the channel is refused at load rather than starting and silently not acknowledging. A channel that believes it is acknowledging and is not is worse than one that does not start.

9.8 X12 acknowledgements

Everything above is about HL7 v2. X12 has its own acknowledgements, and unlike v2 they are off by default: an empty setting means none.

That default is the safe one, because a trading partner who is not expecting an acknowledgement and receives one may treat it as an unsolicited interchange. The acknowledge key on an X12 channel takes one of four values:

Which one to send is a property of the trading partner relationship rather than of the message, which is why it has to be configured and cannot be inferred. A 999 supersedes a 997 for HIPAA transactions, but plenty of partners — older payer connections especially — are set up to expect a 997 and will treat a 999 as an unrecognised file.

9.9 HL7 v3 acknowledgements

An HL7 v3 channel sends an acknowledgement by default, which is the opposite of X12 and worth knowing.

The reason is the transport rather than the standard: a v3 interaction generally arrives over a synchronous connection with the sending application waiting on a reply, and a sender that receives nothing will usually retry. That is how a patient gets registered three times.

Turning it off is possible and has to be done explicitly — "not set" and "set to false" are deliberately different, so the default stands unless somebody said otherwise.

10 Delivery, Queueing and Retry

A destination that cannot be reached is the normal case, not the exception. Systems restart, networks drop, and a hospital interface engine is unavailable during its own maintenance window. Delivery is built around that.

10.1 Queue per destination

Each destination has its own queue. A destination that is failing does not affect the others, and each has its own depth, age and retry state.

Queueing is per destination rather than per channel because the failure is per destination. A channel-wide queue would hold up delivery to three working systems because a fourth is down, and the two situations — one destination unavailable, all four unavailable — would look the same in the statistics.

10.2 Queue settings

queue on a destination:

The last two were missing from this table and from the builder, and they are the pair that stops a disk filling. A queue with neither grows until the filesystem is full, and that failure arrives as something unrelated breaking — a write failing somewhere else entirely — rather than as a queue problem.

Backoff grows between attempts up to max_backoff. Growing rather than fixed, because a destination that is down is usually down for minutes rather than seconds, and retrying every second for ten minutes produces several hundred log entries that bury the one that matters.

10.3 Ordering is preserved

Within a destination, messages are delivered in arrival order, and a message that fails holds its place. Later messages wait behind it rather than overtaking.

This is the right default for clinical data — an admission and a discharge applied in the wrong order is worse than both being late — and it has a consequence worth understanding: one message that always fails will hold up everything behind it.

That is why queue depth and queue age are separate alert conditions. A deep queue that is draining is a busy system. A queue whose oldest message keeps getting older is stuck, and the alert kinds queue-depth, queue-age and queue-stuck distinguish them.

10.4 When queueing is disabled

With queue.enabled false, a failed delivery is a failed delivery. It is recorded and not retried.

That is the right choice when late data is worse than no data — a real-time display, a paging system, anything where a message delivered forty minutes after the event would be misleading rather than merely delayed.

It is the wrong choice for anything that goes into a record, where the message is just as valid an hour later.

10.5 Retry versus queue

There are two mechanisms and they operate at different levels.

retry on a destination governs immediate attempts within one delivery — a connection that fails is tried again after a short pause, without leaving the delivery path. This handles transient faults: a dropped connection, a momentary refusal.

queue governs what happens once those immediate attempts are exhausted. The message leaves the delivery path and is retried later on a longer schedule.

Both exist because the two failures are different. A connection reset on the first attempt is usually gone by the second, and going through the queue for it would add minutes of latency to a fault that lasted milliseconds. A destination that has been switched off for maintenance will not come back within three immediate attempts, and hammering it is pointless.

10.6 What an HTTP endpoint counts as delivered

An HTTP destination has three settings that decide whether a message is treated as sent, and all three are on the destination in the builder.

Status codes that mean delivered. Empty means any 2xx. Some endpoints answer 202 Accepted for something they have not processed yet, and some answer 200 with an error in the body — the second is what *Treat as failed if the reply contains* is for. Setting an explicit list is worth doing when a partner has told you which code means what, because the alternative is discovering the difference from a message that was never delivered and never queued.

Follow redirects. Off by default, and deliberately. A redirect can point at a different host, so following one sends the message somewhere nobody configured and reports success.

Bearer token. Sent as an Authorization header. It is stored with the channel and never shown again, so leaving the box empty when editing an existing channel keeps the token already saved rather than clearing it.

10.7 Naming and pruning an archive folder

A file destination appends to one file per day and message type by default (20261012-ADT_A01.hl7), MLLP-framed so the file replays with perfuse send. Four settings on the destination change that.

File name (file_name) makes one file per message instead, named from ${date}, ${timestamp}, ${control_id}, ${message_type} and ${destination}. A name that is already taken (the same control ID twice) gets a unique suffix rather than overwriting the message there.

Append (append: true) writes every message into the file File name names, so ${date}.hl7 is one file a day for every type.

Suffix while writing (temp_suffix, one file per message only) defaults to .part and is removed by a rename once the file is complete. Whoever collects these files should not pick up a half-written one, and a rename within a folder is atomic. Change it only if the collector filters on a different extension.

Delete after (retain_hours) prunes files in the folder older than the given number of hours, checked at most every ten minutes while messages arrive. Only plain files directly in the folder are deleted, never a subfolder. Empty or zero keeps them forever, which is the default and is a decision rather than an oversight — but an archive nobody prunes fills the disk, and a full disk stops the channel rather than the archiving.

10.8 Sending to a FHIR server

Three settings decide how much is checked before a bundle leaves.

Claim US Core conformance adds the profile to each resource. Only claim it when the resource carries what the profile requires, because a receiver may validate against the claim and reject a bundle that would otherwise have been accepted.

Validate before sending checks each resource here rather than learning from the receiver. A rejection at the far end tells you less, later, and often only in a log you cannot read.

Treat warnings as rejections only has an effect when validation is on, and the control is unavailable until it is. It is strict enough to stop a bundle a receiver would accept, so it belongs on a feed being brought up rather than one in service.

10.8.1 Hosted FHIR services

A fhir destination's auth block signs in to the hosted services, where a pasted bearer token stops working within the hour:

fhir:
  url: https://healthlake.us-east-1.amazonaws.com/datastore/<id>/r4/
  auth: {type: aws, access_key_id: ${AWS_ACCESS_KEY_ID}, secret_access_key: ${AWS_SECRET_ACCESS_KEY}}

aws signs each request for AWS HealthLake with Signature Version 4, with the region read from the URL. azure gets a Microsoft Entra ID token for Azure Health Data Services from tenant_id, client_id and client_secret - an app registration holding the FHIR Data Contributor role - with the FHIR service URL as its audience. client_credentials does the same against any OAuth 2.0 token_url. Tokens are reused until a minute before they expire. The same choices are under the destination's Hosted service sign-in in the channel builder.

10.8.2 Public health case reporting

Tick Report reportable conditions to public health on a FHIR destination and it sends case reports rather than bundles. Each message is checked for a reportable-condition trigger code: a diagnosis, a lab test or a coded result. If it has one, the message becomes an HL7 eCR 2.1.2 eICR, wrapped in an eCR message and posted to the URL's $process-message. If it has none, nothing is sent and nothing fails; the destination counts it as not reportable.

fhir:
  url: https://ecr.agency.example/fhir
  ecr:
    rctc: /etc/perfuse/rctc.json
    source: https://fhir.springfield-general.example/fhir
    facility: {name: Springfield General Hospital, phone: +1-217-555-0100, city: Springfield, state: IL}

rctc is the Reportable Conditions Trigger Codes, as a FHIR ValueSet or the eRSD Bundle. It needs a UMLS licence, so it is not included; without it a short built-in sample is used, for testing only. source is where the agency sends its Reportability Response. The facility is required because eCR asks for its phone and address, and a v2 message has neither.

A report says what the message lacked rather than inventing it, and each gap is logged. Try a message in the FHIR lab's Public health case report panel before pointing a live feed at an agency.

10.8.3 Lab results to public health: ELR

perfuse elr -config elr.yaml results.hl7 turns a lab's results into the HL7 2.5.1 ELR messages state health departments receive, one for each message with a reportable result, and only the orders that carry one: a complete blood count beside a positive SARS-CoV-2 test is not public health's business. The trigger codes are the same as case reporting's, the RCTC you load or the built-in sample.

ELR names everybody by OID or CLIA number, which no lab feed carries for the sender and the receiver, so those come from the file:

sending_application: {namespace: Perfuse, id: 2.16.840.1.113883.19.5.9, type: ISO}
sending_facility: {namespace: Springfield Lab, id: 2.16.840.1.113883.19.5, type: ISO}
receiving_application: {namespace: ELR, id: 2.16.840.1.113883.19.6.1, type: ISO}
receiving_facility: {namespace: State DOH, id: 2.16.840.1.113883.19.6, type: ISO}
processing: T
ordering_facility: {name: Springfield Clinic, phone: "+1 217 555 0100", line: 1 Main St, city: Springfield, state: IL, postalCode: "62701"}
performing_lab: {name: Springfield Lab, line: 2 Lab Rd, city: Springfield, state: IL, postalCode: "62701"}
performing_lab_clia: 14D0000000
placer_authority: {namespace: SPRINGFIELD-EHR, id: 2.16.840.1.113883.19.5.1, type: ISO}
filler_authority: {namespace: SPRINGFIELD-LAB, id: 2.16.840.1.113883.19.5.2, type: ISO}

The ordering facility, performing lab and assigning authorities are used only where the lab's message leaves them out, and each use is a note. What only the lab knows is never filled in: a result with no specimen type goes with SPM-4 empty and a note saying so, because a guessed specimen in a report to public health is worse than a gap the state can ask about. Start with processing: T while the state's onboarding team tests the feed.

What the lab got right is kept as it was sent. A child order (a susceptibility panel or a reflex test whose OBR-29 names its parent and which has no ORC of its own) goes as received, with no ORC or specimen invented for it, and a child with no reportable result of its own goes with its parent's, since a susceptibility means nothing without the culture it belongs to. A note after the PID stays with the patient, and ORC-14, the call-back phone number, is copied from OBR-17 when the lab only put it there. All 28 example messages ONC publishes for its ELR certification tool come out valid with no errors.

MSH-2 is written as ^~\&#, the five characters ELR Release 1's errata require and ONC's certification tool checks. If your state's guide shows the older four, add encoding_characters: "^~\\&" to the file.

To send them from a channel rather than from the command line, give the destination that reaches the state an elr block naming the same file. Each lab result is reshaped on the way out, and one with nothing reportable is not sent at all, which is counted as delivered, not failed: the state asked for reportable results only.

destinations:
  - name: state-elr
    type: mllp                 # or http, sftp, file: whatever the state's onboarding team gives you
    address: elr.health.state.example:6661
    tls: {enabled: true}
    elr:
      config: elr.yaml         # beside this channel file
      rctc: rctc.json          # optional; the built-in sample is for testing only

The block applies on an HL7 v2 channel, to destinations that deliver the message itself (mllp, http, tcp, file, sftp, ftp, S3, Azure Blob, soap, the message brokers, or another channel); the channel refuses to load otherwise, and when the file is missing or lacks the sending facility, receiving application or receiving facility. The notes are written to the log with the message's control ID.

The ELR file is the channel's companion, not a channel: perfuse check and the Channels screen skip it rather than reporting a channel that will not load. In the channel builder the same two settings are under the destination, in Lab reporting (ELR 2.5.1); the trigger codes field opens once an ELR file is named, and saving refuses a file that is not beside the channel.

10.8.4 DICOMweb archives

type: dicomweb stores each object with STOW-RS: Orthanc, dcm4chee, the cloud imaging services, or a Perfuse server's own archive. Give the service root (https://pacs.example/dicom-web); /studies is added, and a URL already ending in /studies is refused rather than posting to /studies/studies. Authenticate with token (a bearer token) or username and password; headers adds others, such as a cloud service's project header. The channel needs dataType: dicom.

The server's answer decides the outcome, not its status code alone. An object the answer lists as failed is a failed delivery with the DICOM failure reason, and so is a 202 that lists nothing as stored: the server took the request and kept none of it. Timeout defaults to two minutes, because a large series is slow.

10.8.5 Document repositories (IHE XDS.b)

type: xds publishes each clinical document to an XDS.b repository with ITI-41 Provide and Register: a CDA document, or one an HL7 v2 message (MDM, ORU) carries. The metadata comes from the document and the destination's settings (source_id, patient_domain, facility_type, practice_setting), and the repository's RegistryResponse decides the delivery. See IHE document sharing.

10.8.6 Immunization registries

Every US state immunization registry (IIS) takes HL7 2.5.1 messages on the same SOAP interface, the one the CDC published in 2011 (namespace urn:cdc:iisb:2011). It has two operations: connectivityTest, which proves the endpoint, and submitSingleMessage, which carries the message. A VXU^V04 reports a shot and comes back as an ACK; a QBP^Q11 asks for a patient's history and forecast and comes back as an RSP^K11.

Choose Immunization registry (CDC IIS web service) as the service of a SOAP destination, or write profile: cdc-iis:

destinations:
  - name: state-registry
    type: soap
    soap:
      profile: cdc-iis
      url: https://iis.state.example/iis-ws/cdc
      username: clinic-submitter       # the registry account for this submitter
      password: "..."
      facility_id: FAC-1234            # optional in the WSDL; many registries require it
    queue: {enabled: true}

Perfuse builds the envelope, so there is no body to write. The username and password go inside the request, where the CDC WSDL puts them, not into HTTP authentication. The version is SOAP 1.2, the WSDL's binding, unless you set version: "1.1" for a registry whose guide asks for it. Where a registry requires a client certificate, set the destination's tls as for any HTTPS call.

The registry's acknowledgement decides whether the message was delivered, not the HTTP status. A registry answers a rejected shot with HTTP 200 and an AR inside, so a destination that trusted the status would report a lost immunization as delivered.

warnings_are_errors: true (Treat warnings as failures) makes every AE wait for a person. The reply, which response scripts and an HTTP caller waiting on the channel read, is the registry's HL7 message: the ACK, or the RSP with the history and forecast. examples/iis holds three channels to start from: VXU from an EHR over MLLP, QBP queries over HTTP, and a local stand-in for a registry.

The Connections dashboard asks a registry its connectivityTest when nothing has been submitted for seven days. That operation exists for this purpose and submits nothing, so it is the one application-level check Perfuse makes. It proves the address, TLS and the SOAP binding, not the username and password; only a real submission tests those.

A SOAP source can answer the same way: Answer as an immunization registry, or profile: cdc-iis on the source. It echoes connectivityTest, takes the message from submitSingleMessage, returns the channel's acknowledgement in return, and serves the CDC WSDL at ?wsdl. A username and password, when set, are checked against the ones in the request, and a wrong pair gets the WSDL's SecurityFault. A message the channel rejects goes back as a NAK, never as a fault, as the CDC guide says. Use it as a test double, or to receive submissions the way a registry does.

Not covered: the state-specific parts of onboarding. Each registry has its own endpoint, account process and local profile of the 2.5.1 guide (required RXA and OBX fields, VFC eligibility, refusal codes). Those are the messages' content, which the channel's transformations shape; no state's endpoint is built in. Perfuse has been tested against itself and against recorded registry answers, not against a live state registry.

10.9 When the transport says yes and the message did not arrive

"Did this arrive" is often not a question the transport can answer. An MLLP receiver returns an application acknowledgement whose meaning is in its text. An HTTP receiver returns 200 with an error document. In both cases the transport succeeded and the message did not arrive.

Inspect the reply on a destination takes a script given the receiver's response. Return false, or throw, and the delivery is marked failed — which means it retries, queues, and appears in the failure count instead of being silently counted as delivered.

It is offered only on destinations that receive a reply. On one that cannot, it is refused at load rather than left never running.

10.10 What a delivery outcome means

These are recorded per destination per message, so a message that reached three of four destinations is recorded as exactly that. There is no channel-level "success", because it would not mean anything.

10.11 Slow delivery

A destination that is accepting messages but taking a long time about it is a distinct problem from one that is failing, and it is easy to miss because every outcome is a success.

The slow-delivery alert kind exists for this. It is worth setting on anything where the sender's acknowledgement waits on delivery, because a destination whose response time has quietly doubled will eventually cross the sender's timeout and start producing resends — and at that point the symptom appears upstream, in a system you may not administer.

10.12 Writing to a database

type: database runs a statement per message with values bound from the message.

Placeholders are the driver's own — $1 for postgres, ? for mysql and sqlite, @p1 for sqlserver — and Perfuse does not rewrite them. That is deliberate: a translation layer that got a placeholder wrong would bind a patient's name to the wrong column, and the result would look like valid data rather than an error.

A statement written in the wrong dialect is refused when it is saved, naming the style the driver wants. Before that check existed the mistake surfaced as syntax error at or near "," from the server when a message arrived, which names a statement you did write and so sends you looking for a typo instead of at the dialect.

destinations:
  - name: warehouse
    type: database
    database:
      driver: postgres
      dsn: ${WAREHOUSE_DSN}
      statement: INSERT INTO messages (mrn, family_name, birth_date) VALUES ($1, $2, $3)
      params:
        - PID-3.1
        - PID-5.1
        - PID-7

A quoted parameter is a constant rather than a path, which is how a channel writes its own name or a source system code into a row beside the message data.

Values are always bound as parameters. A ${...} reference inside the statement is refused: a name containing an apostrophe would break the statement, and a hostile value would rewrite it.

10.13 Sending to a raw socket

type: tcp writes to a socket with framing you choose, which is what a device or a laboratory instrument usually wants. MLLP is one framing among several; this destination offers the others.

destinations:
  - name: instrument
    type: tcp
    tcp:
      address: instrument.lab:9100
      framing: delimited
      delimiter: \r
      expect_reply: true
      timeout: 30s

Framing has no default, deliberately. Writing with the wrong framing does not fail. The far end reads messages split in the wrong places, or waits for a terminator that never comes, and the symptom appears at the receiving system rather than here.

Only the settings the chosen framing uses are accepted. A record length on a delimited stream is refused rather than ignored, because a setting that is silently ignored is one somebody believes is in effect.

expect_reply changes what delivered means. Without it, success means the bytes reached the operating system's send buffer — which a peer that crashed a moment later never read.

10.14 Amazon S3, SQS and SNS

A channel can read from an SQS queue or an S3 bucket prefix, and deliver to SQS, SNS or S3. All five are signed HTTP with no AWS SDK in the binary, and all five take the same access settings: region, access_key_id, secret_access_key (write ${AWS_SECRET_ACCESS_KEY} to read the environment), an optional session_token, and endpoint for LocalStack, MinIO or a VPC endpoint. Under Channels → New channel, choose *We read from an Amazon SQS queue*, *We collect objects from an Amazon S3 bucket*, or the SQS, SNS and S3 destination types.

Nothing is acknowledged to AWS until the channel has handled it. An SQS message is deleted afterwards and otherwise reappears when its visibility timeout ends, so a queue's redrive policy is what moves one that keeps failing to a dead-letter queue. An S3 object moves to processed/ afterwards, or to error/ if it could not be handled, so one bad file does not stop the rest.

On a FIFO queue or topic, messages are grouped by patient by default - SQS keeps order within a group and nowhere else - and deduplicated by content, so a retry is not delivered twice.

An S3 archive can be written straight to Glacier with storage_class, and as JSON lines for Amazon Athena with format: ndjson; perfuse athena prints the table. The reference has every setting.

10.15 AMQP 1.0 and Azure

AMQP 1.0 is what Azure Service Bus and Event Hubs speak, and RabbitMQ 4, ActiveMQ and Artemis beside their other protocols. An amqp source receives from a queue or a subscription and accepts each message only once the channel has handled it; one that could not be handled is released as a failed delivery, so the broker redelivers it and, past the queue's limit, dead-letters it. An amqp destination reports success only when the broker accepts the message. For Service Bus: addr is <namespace>.servicebus.windows.net:5671 with tls, username the shared access policy name, password its key, and address the queue name, or <topic>/subscriptions/<name> to receive.

Azure Blob Storage: an azure_blob destination writes a blob per message in the access tier chosen - Hot, Cool, Cold or Archive - and an azure_blob source picks blobs up from a prefix, moving them to processed/ or error/ as the S3 source does. Prefer a SAS token limited to the container over the account key.

10.16 MQTT

An mqtt source subscribes to a topic filter (+ matches one level, # every level below) on any MQTT 3.1.1 broker: Mosquitto, EMQX, HiveMQ, AWS IoT Core, Azure Event Grid. At QoS 1, the default, each message is acknowledged only once the channel has handled it. MQTT has no way to refuse a single message, so one that could not be handled is left unacknowledged and the connection is made again; the broker keeps the session under the client id (perfuse-<channel> unless client_id says otherwise) and sends it again, first in line. QoS 0 is at most once: anything sent while Perfuse is down is lost. An mqtt destination publishes and, at QoS 1, reports success when the broker has the message.

source:
  type: mqtt
  mqtt:
    addr: broker.hospital.local:8883
    topic: hl7/+/adt
    username: perfuse
    password: ${MQTT_PASSWORD}
    tls: {enabled: true, ca_file: /etc/perfuse/broker-ca.pem}

AWS IoT Core wants a client certificate: give tls.cert_file and tls.key_file.

10.17 IBM MQ

ibm_mq reads and writes IBM MQ queues through the queue manager's messaging REST API (mqweb), which IBM MQ 9.1.5 and later ship on every platform, z/OS included, so no MQ client is installed beside Perfuse. The user needs the MQWebUser role and put, get and browse authority on the queue. A source browses the first message, hands it to the channel, and removes it by its message id only once it was handled; a message that fails stays first on the queue. Run one reader per queue. A destination puts persistent messages (unless non_persistent), with the HL7 control id as the correlation id.

destinations:
  - name: to-mainframe
    type: ibm_mq
    ibm_mq:
      url: https://mq.hospital.local:9443
      queue_manager: QM1
      queue: HL7.ADT.OUT
      username: perfuse
      password: ${IBM_MQ_PASSWORD}
      tls: {enabled: true, ca_file: /etc/perfuse/mq-ca.pem}

api_version is v3 for MQ 9.3 and later (the default), v2 for 9.1.5 to 9.2. A queue manager with an AMQP channel can also be reached with the amqp connector.

10.18 Google Cloud Pub/Sub and Cloud Storage

A pubsub source pulls from a subscription and acknowledges each message once handled; one that fails is handed back at once (its acknowledgement deadline set to zero), with the rest of its batch, so Pub/Sub delivers it again and, past the subscription's dead-letter policy, dead-letters it. A pubsub destination publishes with the HL7 message type and control id as attributes; order_by: patient sets the ordering key from PID-3.1, so a subscription with message ordering keeps each patient's messages in order.

A gcs destination writes an object per message, named as an S3 key is, in the storage class chosen (STANDARD, NEARLINE, COLDLINE, ARCHIVE). A gcs source picks objects up from a prefix and moves them to processed/ or error/ as the S3 source does.

Both sign in as a service account: credentials_file is its JSON key. Leave it empty on Google Cloud (a VM, GKE or Cloud Run) to use the service account attached there. endpoint names an emulator (the Pub/Sub emulator, fake-gcs-server), which takes no credentials.

source:
  type: pubsub
  pubsub:
    project: hospital-integration
    subscription: adt-to-perfuse
    credentials_file: /etc/perfuse/gcp-key.json

10.19 Reading a mailbox (IMAP and POP3)

An email source reads a mailbox and turns what it finds into messages: each attachment (take: attachments, the default, narrowed by attachment_names patterns), the text of the email (take: body), or the whole email (take: raw) for a script to take apart. Laboratories, imaging centres and small practices still send results this way.

Each check signs in, reads the unread mail oldest first, and signs out. Over IMAP an email is fetched without being marked read, handed to the channel, and only once every message from it was accepted is it moved to move_to (Processed), marked read (after_read: flag) or deleted. Mail that failed, or that was not taken (a sender outside allowed_senders, no attachment matching attachment_names, larger than max_message_size), moves to error_folder (Error) with the reason in the log. Both folders are created when missing. POP3 has no folders or flags, so it deletes: deletions are committed by the QUIT at the end of the check, so a session that breaks off deletes nothing and a handled email may be read again (never lost). POP3 mail that is not taken stays on the server and is reported once.

Sign-in is a password (${MAIL_PASSWORD}; an app password for Gmail) or OAuth 2.0 over SASL XOAUTH2, which Microsoft 365 requires (it has turned password sign-in off) and Gmail prefers:

source:
  type: email
  email:
    host: outlook.office365.com        # imap.gmail.com, pop.gmail.com, or your server
    username: results-feed@hospital.example
    oauth:
      provider: microsoft              # microsoft, google or custom (with token_url)
      tenant: hospital.onmicrosoft.com
      client_id: 00000000-0000-0000-0000-000000000000
      client_secret: ${MAIL_CLIENT_SECRET}
    attachment_names: ["*.hl7"]
    allowed_senders: [lab.example, results@partner.example]

With client_secret and no refresh_token, Microsoft 365 app-only access is used (the client-credentials grant, scope https://outlook.office365.com/.default): an administrator registers the app, grants it IMAP.AccessAsApp and limits it to the one mailbox with an Exchange service principal. With a refresh_token (a person's consent), the delegated scope IMAP.AccessAsUser.All or POP.AccessAsUser.All is used, and a rotated refresh token is kept for the life of the process. Gmail needs a refresh_token: Google offers no app-only access to a mailbox.

allowed_senders takes addresses and domains. The From line of an email can be forged, so it keeps out accidents and stray mail, not an attacker; a feed that must be trusted belongs on Direct (S/MIME signed), SFTP or a VPN. security is tls (993 or 995, the default), starttls (143 or 110) or none, which is allowed only to localhost. Checks are at least 10 seconds apart (60 by default), because mail services throttle accounts that check faster.

Tested against GreenMail 2.1.3 (IMAPS, IMAP, POP3S and POP3: sign-in refused with a wrong password, fetch without marking read, MOVE, flag, delete, a too-large email refused before it is read) and against Gmail's IMAP with an app password (create a folder, append, fetch, MOVE, delete). OAuth was tested against a stand-in token endpoint only: not against Microsoft or Google.

10.20 AS2

AS2 (RFC 4130) is how many payers, clearinghouses and suppliers exchange EDI: an HTTP POST whose body is signed with the sender's certificate and encrypted to the receiver's, answered with a receipt (an MDN) that names a digest of what arrived. The S/MIME is the same code Direct messaging uses. Both ends are on the channel builder: Trading partners send us EDI over AS2 as a source, A trading partner over AS2 as a destination.

# receive: partners post here
source:
  type: as2
  as2:
    listen: ":4080"            # path /as2 by default
    id: HOSPITAL-AS2           # our AS2 identifier (AS2-To)
    cert_file: as2/ours.crt    # partners encrypt to this
    key_file: as2/ours.key     # and receipts are signed with it
    tls: { enabled: true, cert_file: tls.crt, key_file: tls.key }
    partners:
      - id: PAYER-AS2
        cert_file: as2/payer.crt
dataType: x12

# send
destinations:
  - name: payer
    type: as2
    as2:
      url: https://as2.payer.example/as2
      from: HOSPITAL-AS2
      to: PAYER-AS2
      cert_file: as2/ours.crt
      key_file: as2/ours.key
      partner_cert_file: as2/payer.crt
      file_name: "${control_id}.x12"

Receiving. A message to any other AS2-To, or from a sender not in partners, is refused with 403 and no receipt. A partner's message must be signed and encrypted unless its entry sets allow_unsigned or allow_unencrypted. The payload is decrypted, its signature checked against the partner's certificate (partners usually exchange self-signed ones, which is fine: the certificate is the trust), and handed to the channel as its message format says. The partner gets the receipt it asked for: in the response, or posted to its Receipt-Delivery-Option URL; signed when it asked for a signed one. A message that fails gets a receipt naming why (decryption-failed, authentication-failed, insufficient-message-security, unexpected-processing-error).

Sending. Each message is signed (SHA-256) and encrypted (AES-256-CBC). With receipt: sync, the default, it counts as delivered only when the receipt verifies against partner_cert_file, says processed, and carries the same digest (MIC) as what was sent; anything else is a failed delivery and is retried. receipt: async asks for the receipt at receipt_url, which must be an AS2 source on this server that lists the partner: the message counts as delivered once the partner accepts the request, and a receipt that later disagrees is logged as an error. receipt: none asks for nothing. unsigned, unencrypted and unsigned_receipt relax each part for an agreement that says so; username and password add HTTP basic authentication for gateways that require it. The content type follows the channel's format (application/edi-x12 for X12) unless content_type sets one.

Triple DES, AES-128 and AES-192 are read as well as AES-256, since partners still send them, and so is the streaming BER (indefinite lengths) that Java gateways write.

Compression (RFC 5402). A compressed message is read whichever way it was built: compressed before signing or encryption, or a signed message compressed whole. The receipt's MIC follows the RFC: over what was signed when it is signed, over the uncompressed content when it is not. A message that would expand past ten times the source's max_message_size is refused with decompression-failed, so a few kilobytes cannot claim gigabytes of memory. A destination compresses with compress: true, before signing and encryption, as most gateways do; ask the partner first.

A message sent twice. A partner that never got our receipt sends the message again with the same Message-ID (RFC 4130 section 7.5). The source remembers each partner's Message-IDs for duplicate_window (default 720h, 30 days; an hour at least) and answers a resend with a processed receipt without passing it on again. The record is kept in the database, so a restart does not forget it. A message whose processing failed is not remembered, so the partner's retry goes through. Copies arriving at the same moment wait for one another, and only the first is passed on. If the record cannot be read, the message is refused with unexpected-processing-error and the partner retries later, rather than risking a second copy. A message with no Message-ID cannot be recognised and is logged as such.

Interoperability is tested against pyas2lib 1.4.3 in both directions, with Triple DES and AES-256, compressed and not, signed synchronous receipts included.

10.21 OpenPGP

Payers, clearinghouses and state agencies often take and send files only under OpenPGP. A pgp block on a source opens what arrives; one on a destination protects what leaves. Both are on the channel builder: Open PGP-encrypted messages under the source, Encrypt with OpenPGP on each destination.

source:
  type: sftp
  sftp: { host: sftp.payer.example, user: hospital, key_file: keys/id_ed25519, dir: outbound }
  pgp:
    decrypt_with: keys/our-secret.asc      # our secret key, armored or binary
    passphrase: ${PGP_PASSPHRASE}
    verify_with: [keys/payer.asc]          # the senders' public keys
    require_signature: true
destinations:
  - name: claims
    type: sftp
    sftp: { host: sftp.payer.example, user: hospital, key_file: keys/id_ed25519, dir: inbound,
            file_name: "${date}-${control_id}.x12.pgp" }
    pgp:
      encrypt_to: [keys/payer.asc]
      sign_with: keys/our-secret.asc
      passphrase: ${PGP_PASSPHRASE}

Key files are read relative to the channel file, and are read and unlocked when the channel loads: a missing key or a wrong passphrase stops the channel there, not on the first file.

• On a source, the whole file, object, email attachment or request body is

opened first and then split into messages, so a batch encrypted as one file works. One that will not open is refused: a file source moves it to its error folder, an HTTP sender is answered 400 with the reason. require_signature refuses a message not signed by one of verify_with; allow_unencrypted accepts one that is only signed; pass_plain lets a message that is not PGP at all through unchanged, for a folder that receives both.

• On a destination, what would have been delivered is encrypted (to any of

encrypt_to) and signed (with sign_with), after every other step. A file, SFTP, FTP, S3, Azure Blob or GCS destination still names the file from the plain message, so ${control_id} works, and any framing is inside the encryption. armor: true writes .asc text rather than binary; no_compress turns off compression; file_name is the name carried inside the message.

Messages are written with AES-256 in the RFC 4880 format older receivers read, and the newer RFC 9580 format is read as well. The cryptography is ProtonMail/go-crypto; Perfuse implements no primitive. Interoperability is tested against GnuPG in both directions: gpg decrypts and verifies what Perfuse writes, and Perfuse opens and verifies what gpg writes.

10.22 Delivery to another channel

A channel destination hands the message to another channel by name. The receiving channel treats it like any other arrival: it records it, filters it, transforms it and fans it out.

This is the supported way to build a chain. It is deliberately visible — two channels, two sets of statistics, two entries in the message history — because a chain hidden inside one channel is a chain nobody can monitor.

The message is handed over in memory rather than over a network, so there is no framing, no acknowledgement and no timeout between the two.

10.23 What happens when the process is killed

The question anyone who has run an interface engine asks first, and the one that is rarely answered, because the honest answer is usually embarrassing.

It was answered by killing the process with SIGKILL part way through a batch — which is what a power failure, an out-of-memory kill and a hypervisor reset all look like from inside — and counting what survived against what had been promised.

The property under test is not "nothing is lost". That is not achievable and claiming it would be a lie. It is the narrower promise a sender actually relies on: a message that was positively acknowledged is a message that arrived.

With ack.when: on_delivery, which is the default, every destination is written before the acknowledgement goes out, so an AA is a statement about the destination rather than about a queue. A message killed before its acknowledgement may well be lost, and that is correct: the sender was never promised anything and will send it again.

10.23.1 Acknowledging on delivery

Five runs, killed after 5, 25, 40, 75 and 110 messages of 120.

The promise held at every kill point, and nothing was duplicated. A duplicate would have been acceptable and a loss would not: a resent A08 is a nuisance receivers absorb, and a lab result that silently never arrived is a patient safety event.

10.23.2 Acknowledging on receipt

on_receipt answers as soon as the message is queued, before any destination has been written. This chapter has always said an acknowledged message can still be lost that way. Here is the size of it.

Essentially everything in flight. The setting is not a defect and there are feeds where it is the right choice, but it should be chosen knowing that a crash discards what has been acknowledged and not yet written, and that this is almost all of a burst.

Nothing recovered on restart, because perfuse run has no durable store. A destination that must not lose messages during an outage needs queue.enabled, which needs the database that perfuse serve provides — and perfuse run now refuses such a channel rather than starting it without the queue.

10.23.3 A sender that dies half way through a message

The most dangerous of these faults, because a truncated HL7 message usually still parses. The segments before the cut are complete and well formed, so a receiver has no way to know that PID and PV1 arrived and the OBX segments carrying the results did not.

A frame was opened, six tenths of a message sent, and the connection reset rather than closed. The partial message was not delivered, the listener survived, and a well-formed message sent immediately afterwards was accepted normally, so the fragment was not carried into the next message either.

The connection log now reports how many bytes of an unfinished frame were abandoned, for every failure mode rather than only a tidy close. Previously a crashed sender, a killed process and a pulled cable all logged messages=0 and nothing else, which cannot distinguish an empty health check from a lab result thrown away nine tenths of the way through.

10.23.4 A full disk

Space exhaustion is detected and logged rather than swallowed. Two things about it are worth knowing.

The sender does not get a prompt rejection. The delivery retries on the usual schedule — one second, two, four, eight — and the negative acknowledgement arrives about fifteen seconds later. A sender whose own timeout is shorter than that sees a stalled connection rather than an AE, and will conclude the network is at fault rather than the disk.

And a volume reporting zero bytes free can still accept small appends for a while, because adding a couple of hundred bytes to a file whose last block has room needs no new allocation. The first write failure is later than the moment the disk filled.

10.23.5 What was not tested

A destination directory losing write permission. It could not be injected with chmod: the engine holds the output file open, and changing a file's mode does not affect a descriptor already opened against it. Testing it properly needs the volume remounted read-only or removed underneath the process, which has not been done. It is named here rather than omitted, because a gap nobody mentions reads as a gap nobody looked for.

11 Alerting

Nothing outside Perfuse will tell you a feed has stopped. The sender is being acknowledged and is satisfied; the receiver has no way to know a message was sent. Alerting is the only thing standing between a broken interface and somebody noticing weeks later.

11.1 The alert kinds

The last four watch access to patient data, and are described below.

11.2 Silence is the hardest thing to detect

A channel that has stopped receiving produces no errors. There is nothing to count. This is why no-traffic exists, and why it is not good enough on its own.

no-traffic is a fixed threshold: alert if nothing has arrived for, say, two hours. On a feed that genuinely never goes quiet, that works. On a clinic's laboratory feed it is useless — the feed is silent every night and all weekend, so a two-hour threshold pages somebody at 1am every night, and a threshold long enough to survive the weekend will not notice a Tuesday morning outage until Tuesday afternoon.

There is no single number that is both. That is not a tuning problem; it is that the question "has this feed stopped" cannot be answered by a constant when the feed's normal varies by a factor of a hundred across the week.

11.3 Rhythm-aware detection

below-rhythm compares current traffic against what this channel normally does in this hour of this day of the week.

Perfuse learns each channel's week from its own recorded history: 168 hourly buckets, Monday first so a working week is contiguous. For each bucket it holds a median, a low and a high, a floor, and how many observations it is based on.

The threshold is a share of normal, defaulting to 0.8 (80 per cent in the console) — alert when traffic falls below four fifths of what is normal for this hour.

11.3.1 Median, not mean

A single backlog flush of forty thousand messages against a normal three hundred moves a mean far enough that the feed can go completely silent afterwards without ever falling below it. The median is unmoved by one extraordinary hour, which is exactly the property needed.

11.3.2 The floor is a percentile, not the minimum

Whether a channel's rhythm is reliable enough to alert on is decided by its low end, not its high end. A shortfall alert fires when traffic is *low*, so only the low end can tell you whether it will produce false positives. An early version of this compared the high against the median and got it wrong in both directions at once: it disqualified a perfectly steady feed for a month after one backlog, and it passed a genuinely erratic feed that swung between two and nine hundred messages in the same hour because its high was only three times its median.

The floor is the twentieth percentile rather than the minimum, because the minimum is dragged to zero by a single bank holiday. And the percentile is not interpolated — every number in an alert at two in the morning should be a count the feed actually produced, not an average of two counts it did not.

11.3.3 It will say when it cannot tell

A channel with no history at all is omitted entirely rather than treated as one that has stopped. A new channel must not look like a broken one.

Where the history is too thin or too erratic to support a judgement, the rule declines to fire rather than guessing. "I cannot honestly say" is a first-class answer here, and it is preferred to an alert that is right slightly more often than chance.

11.4 Setting alerts up

From the interface, under Alerts, per channel or across all of them. Each rule has a kind, a threshold and where to send the alert. The rules are saved to alerts.yaml beside the database (or the file -alerts names) and take effect at once; until the first save the built-in rules apply. The file can also be edited by hand: the change is picked up within thirty seconds, and a file that no longer loads is reported in the log and the rules in force are kept.

Worth doing before a feed goes live rather than after the first incident. The specific set worth having on any clinical feed:

1. below-rhythm — the feed has gone quiet when it should not be quiet.
2. error-rate — messages are arriving and failing.
3. queue-age — something is stuck rather than merely busy.
4. channel-down — the channel is not running at all.

The first is the one that catches the failure nobody else will report.

11.5 Watching access to patient data

A breach rarely announces itself. It looks like a feed carrying more than usual, traffic at three in the morning on a channel that only works office hours, a destination nobody set up, or one person opening patient after patient. Perfuse watches for those four, on by default (serve -watch-access=false turns it off), and reports what it sees through the alert rules above, so it is configured, acknowledged and delivered like any other alert.

• Bursts (phi-volume). Each channel's rate is compared with its own history at the same hour of the day, so a busy morning is not news. The threshold is a multiple of the usual rate, three by default. A burst is usually a backlog being released after an outage, and it is also what records being extracted through a feed look like.
• Night traffic on a daytime channel (phi-after-hours). A channel counts as daytime-only when under 2 per cent of what it has carried fell outside 07:00 to 19:00, in the server's time zone.
• A new destination (phi-new-destination). The address is what the destination names: a host and port, a URL, a folder. Renaming a destination is not news; pointing one at a new host is. The addresses each channel has sent to are kept in access-watch.json beside the database, so a destination changed while the server was down is still reported.
• Bulk reads (phi-bulk-reads). Counted from the audit trail: messages opened, patients searched for or looked up (PDQm, PIXm, identity search), documents and images read (XDS, MHD, DICOMweb), prior authorizations read, summaries and views run. Reading the same record again does not count twice. The threshold is how many different records in a minute, ten by default, by one account from one address.

Nothing is judged for a channel until it has carried 200 messages, because "unusual" means nothing without a pattern. The pattern is learned from the last fortnight of the message store when the server starts, so a restart does not make every channel new again. Anything seen is held for fifteen minutes, then the alert clears itself.

It only watches and reports. It never holds up a message or refuses a read: these are heuristics, and a feed stopped because a guess was wrong is a clinical problem. Each alert says what was seen and what it could innocently be, because most of them will be innocent.

Administrators see what the monitor has learned on the Alerts screen, under Watching access to patient data: each channel's pattern (still learning, daytime only, or day and night), how many destinations it knows, and everything seen in the last fifteen minutes, including what is under a rule's threshold.

11.6 Where alerts go

Alerts can be sent as JSON to a webhook (-alert-webhook: Slack, Teams, Mattermost, PagerDuty, Alertmanager or anything that accepts a POST), sent as SNMPv2 traps to SNMP managers (-snmp-traps, see SNMP), or written to the log for a collector to pick up. There is no email delivery of its own: point the webhook at a relay if alerts must arrive as email.

An alert that is only written to a log nobody reads is not alerting. If Perfuse is the only thing that will notice a stopped feed, the alert has to reach a person.

12 The Message Store

Every message Perfuse receives is recorded, as received, before anything modifies it. So is what was sent to each destination and what happened to it. The store is a SQLite file given by -db.

12.1 What is kept

Per message: the raw bytes as they arrived, when they arrived, which channel, the parsed message type and trigger event, and the filter outcome.

Per destination per message: the bytes that were sent, the outcome, the time taken, and any error or negative acknowledgement received.

This is the shape an investigation needs. "What did they send us", "what did we send them" and "what did they say about it" are three different questions and each of them gets asked.

12.2 Searching

By channel, by time range, by outcome, by message type and trigger event, and by field value.

Field search works on the parsed message, so searching for a record number finds it wherever in the message that field lives, rather than matching the digits anywhere in the text. A text search for 12345 in a message containing a quantity of 12345 finds a message that has nothing to do with the patient you are looking for.

12.3 Replay and reprocessing

Because the original is kept, a message can be run through the current configuration again.

Trace takes a recorded message and shows what the channel would do with it now, without sending anything. Covered in debugging.

Reprocess actually re-runs it, including delivery. This is what fixes a batch of messages that failed because a destination was misconfigured: correct the configuration, select the affected messages, reprocess.

12.4 Staleness

A trace of an old message against the current configuration is answering a hypothetical: what *would* happen now. That is usually what you want, but not always — if you are investigating what went wrong last Tuesday, the channel may have changed since.

Perfuse detects this and says so. A trace of a message that arrived before the channel was last edited is marked as such, so the answer is not mistaken for a reconstruction of what actually happened.

12.5 Retention

The store grows. cleanup.periodDays controls how long messages are kept.

Two things to weigh. Clinical messages may fall under retention requirements that are longer than anything you would choose for operational reasons, and the store is not the system of record — the receiving system is. Perfuse's copy exists to diagnose and to reprocess, and both of those needs fall off sharply after a few weeks.

Retention also decides how much history the rhythm learner has to work with. See alerting: a retention window shorter than a few weeks leaves it unable to distinguish a quiet Sunday from a stopped feed.

12.6 The store holds clinical data

This is the part of Perfuse that contains patient information, and it should be treated as such: on encrypted storage, backed up as clinical data, and access-controlled. See security.

The generated test messages described in testing exist partly so that this data does not have to leave the environment in order to reproduce a problem elsewhere.

13 Debugging

The question is almost always the same: this message came in, something wrong went out, where did it change? Perfuse answers it by replaying a recorded message through the current configuration and showing every step.

Nothing is sent while tracing. The channel keeps running untouched, and no redeploy is needed.

13.1 Tracing a message

Select any recorded message and trace it. The result shows, in order:

• What the filter read. Which fields it looked at and what values it found. A filter rejecting everything is usually reading a path that does not exist in this feed, and this names it.
• Each transformation. What it changed, from what to what.
• What each destination decided. Whether it would accept the message, and why not if it would not.
• The output. The message as each destination would send it.

13.2 Step by step

The step-through view runs each transformation on its own and snapshots the whole message after it. A numbered rail of steps, coloured by what happened, and the message as it stood at each point.

The whole message rather than only the change, because the change is often not where the problem is — a step that correctly modified the field it was aimed at, on a message where an earlier step had already put the wrong thing there, looks perfectly correct in isolation.

13.3 Four outcomes, and the distinction that matters

no-effect and skipped are reported separately, and this is the point of the whole feature.

From outside they are identical: the message is the same afterwards either way. They mean opposite things. skipped means the condition worked as written and this message was not one it applied to — usually correct. no-effect means the step ran and found nothing to do, which usually means it is aimed at a field that is not there.

An engine that reports both as "nothing happened" leaves you unable to tell a working conditional from a broken path, and that is the most common transformation bug there is.

13.4 Testing a change before saving it

The builder can run a candidate configuration against recorded traffic and report what would differ. This is the safest way to change a live channel: make the edit, see what it does to the last few hundred real messages, then save.

It is also how to find out that a change which looks obviously correct affects messages you had not thought about — a step conditioned on one trigger event, on a feed that turns out to carry four.

13.5 What tracing cannot tell you

It runs the current configuration. If the channel has been edited since the message arrived, the trace is a hypothetical rather than a reconstruction, and Perfuse marks it as such rather than letting the distinction pass silently.

It also does not exercise the transport. A trace shows what would be sent, not whether the destination would accept it — a message that is correct and a destination that is refusing connections produce a clean trace and a failed delivery. Those are visible in the delivery record instead.

13.6 Scripts

A script is one opaque step in the trace. Perfuse can show what went in and what came out, and cannot show what happened in between or which fields were read.

This is the concrete cost of using a script rather than declarative steps, and it is worth weighing when choosing. See transformation.

14 Testing

Standard advice for testing an interface is to build sample messages that reflect your own environment — your laboratory's codes, your case mix, your sender's habits — and to strip the patient data out by hand. That is slow, and doing it incompletely is the normal outcome.

Perfuse offers three things instead: generated traffic that matches a feed's shape without its content, a channel proposed from a sample somebody sent you, and a comparison against the engine you are replacing.

14.1 Generated test traffic

If a channel has handled messages, Perfuse can produce more messages like them.

What is faithful:

• Trigger events in the proportions actually observed, with at least one of each so a rare event still appears.
• Fields populated at the rates they really are — so the case where a field is *absent* gets tested, which is the case that breaks things.
• Repetitions where repetitions occur, composite structure where it occurs.
• Codes drawn from the code tables actually seen.

What is not faithful, and this is stated rather than implied: clinical coherence. A generated patient has an unrelated record number, a name-shaped string, and a diagnosis with no relationship to the observation. These messages exercise an interface. They are not a clinical test set and cannot be used to validate clinical logic.

14.1.1 Why it contains no real data

The argument is structural rather than a claim about effort. The generator's only input is the channel's traffic profile, and a profile holds fill rates, shapes, lengths, repetition counts and segment frequencies. It holds no values.

The single exception is code-table fields, and a code identifies nobody.

This is a stronger guarantee than de-identifying real messages, which is a process that can be done incompletely and usually is. Here there is no path by which a name could reach the output, because the name was never in the input.

Every generated message is parsed before it is returned — an unparseable corpus would send somebody hunting for a bug in their interface that is really a bug in the generator — and every one is marked T in MSH-11, with a deliberately synthetic sending application and facility.

14.2 Building a channel from a sample

Paste the message a laboratory, hospital or vendor emailed you and Perfuse proposes a channel for it. Nothing needs to be running first.

It handles what people actually paste: several messages in one block, any line ending, MLLP framing that survived the copy, and the covering note above the message. Refusing a sample because it arrived with Windows line endings would be an obstruction rather than a check.

14.2.1 Three lists

The proposal comes with what the sample shows, what has been guessed, and what the sample cannot tell you — three separate lists, weighted equally in the interface.

They are separate because a reader who cannot tell which is which has to verify everything or trust everything, and both are worse than knowing where to look.

From a single message the limits are named specifically rather than generally: which fields are optional, which segments repeat, which codes exist beyond the ones here, whether the sender ever sends a different trigger event. A general caution is one people skim.

Confidence is a word — low, moderate, reasonable — never a percentage. A percentage implies a calculation, and this is a judgement about how many samples there are.

Z-segments are called out by name, because a local segment is the thing no specification mentions and the commonest reason a channel built from a standard template does not work.

14.2.2 The separator warning

If the sample's field separator is not the usual |, that appears first, and confidence drops to low.

The reason is a genuine silent failure. HL7 takes its field separator from the message itself, so a sample whose pipes have been replaced by typographic look-alikes — which is what a word processor does — parses perfectly into fields that are all wrong. Nothing errors anywhere.

Refusing such a sample would be wrong, because a sender may legitimately use another separator. So it is flagged, the character is named, and asking for a plain text attachment is suggested.

14.3 Comparing against the old engine

Before moving a live feed, the question is whether Perfuse produces the same output as the thing that has been running for years. No amount of design quality answers that. See migration.

14.4 Verifying against the real thing, in containers

Three checks run against real implementations rather than against Perfuse's own idea of a protocol. They live outside make check because they need a container runtime, and a check that needs Docker is a check people stop running.

scripts/interop-up.sh starts all of them and prints what each one unlocks.

Every one skips rather than fails when its container is absent, so make check passes on a machine with no Docker.

Why this is separate from the rest of the suite. Every other test of these features had both halves written here: a document this codebase signed, read back by the code that signed it. That is agreement with oneself, and it is worth less than it appears.

The SAML canonicaliser is the case that proves the point. It carried a thousand lines of tests, five of them specifically about canonicalisation, and all of them passed while no real identity provider could ever have signed anybody in — the canonical form that a signature covers was being computed with namespace prefixes dropped, and the only way to find that was to hand it a document Perfuse had not written.

Two of the eight checks found defects outright, and a third prompted a real improvement. Three found nothing wrong. That ratio is the argument for keeping all of them: a check that passes has told you something you could not otherwise have known, and there was no way to tell in advance which ones they would be.

One pattern worth naming, because it appeared in both defects: acceptance is not verification. HAPI accepted the malformed identifier system and stored it; the defect only appeared on reading the resource back. A receiver that tolerates something is not evidence that it is right, only that this receiver was lenient.

Two captured assertions are committed, at internal/saml/testdata/keycloak-assertion.xml and entra-response.xml, with tests over both — so that particular regression is caught without a container.

Both are needed rather than one being spare. Keycloak prefixes its assertion and signature, Entra does not, and those are the two opposite cases in canonicalisation — which is precisely where the defect was. A test asserts each document still covers its own case, because a replacement capture that happened to be prefixed would quietly halve the coverage without failing anything. The general lesson does not generalise so cheaply: for anything else, the container is the check.

14.5 Diagnosing a test that fails once and never again

A test that fails in a full run and passes alone sixteen times is not a flaky test. It is a test that shared something with the run, and the way to find out what is to measure the shared thing rather than the test.

Two instruments exist for this, and both are meant to be run alongside a full suite:

./scripts/e2e-watchdog.sh /tmp/watchdog.log     # the HTTP server and the shared session
./scripts/e2e-mllp-probe.py /tmp/mllp.log       # the fixture channel's listener

Each discovers the run's ports from the setup's own state file and samples every 500 milliseconds until the server exits. They log every sample rather than only the failures, which is what makes them useful: a blip shows up in a run where nothing failed, so a fault that appears once in three runs becomes measurable on every one.

Set PERFUSE_E2E_KEEP=1 to keep the temporary directory, which holds the database as it was left and the server log for the whole run. The server log is usually the answer. In one investigated case it recorded a channel stopping and its listener rebinding 421 milliseconds later, and the probe's one refused connection fell inside that window.

Read the trace rather than error-context.md, which has been empty on more than one occasion where the trace held the real message.

Copy the artefacts out before re-running anything. A passing run clears test-results, so the trace of the failure you are investigating disappears the moment you try to reproduce it. Once lost, the question it would have answered cannot be answered.

Stop the interop containers first. Stop them before a full browser run, and start them with ./scripts/interop-up.sh afterwards if you still need them.

Eight containers hold around 9.8GB of memory, and on a machine without much more than that there is too little left for Chromium's processes, node and the Go toolchain together. What it produces is not an out-of-memory error but a renderer that stops being scheduled: one recorded trace shows a 60.2 second gap with no frames at all, during which Playwright waited for a button to become "visible, enabled and stable" and could not get two consecutive animation frames to compare. The server was healthy throughout, the slowest request in the whole run being 154 milliseconds.

That failure reads as a defect in whatever test happened to be running. It is worth knowing the shape of it: every request fast, the page visually frozen, the retry loop never reaching a second iteration, and the whole thing passing in isolation.

Only one run at a time. The suite shares one server, one signed-in session in web/e2e/.auth/admin.json, and one state file naming the server's process. None of that is per-run, so a second run starting while the first is going overwrites the state file, and whichever teardown finishes first kills the other run's server and deletes its session.

What that looks like is nothing like the cause. It produced a run of 279 failures whose first message was ENOENT: no such file or directory, open './e2e/.auth/admin.json', a run that stopped early reporting 217 passed, and two tests failing with bind: address already in use — none of which suggest two runs fighting. The suite now takes a lock and refuses to start, naming the process that holds it. A lock left by an interrupted run is taken over rather than blocking for ever, because a safety measure that wedges the suite is one somebody deletes along with the safety.

A related trap, now fixed: two specs named their listening ports outright, so a server left behind by an interrupted run made them fail on something they had nothing to do with. Ports are asked of the operating system now.

Do not answer any of this with retries. A test that passes on the second attempt found a real race and hid it, and playwright.config.ts sets retries: 0 for that reason.

One caution: sampling every 100 milliseconds spawned twenty processes a second, stretched a run by half again, and failed two tests on timeouts that had nothing wrong with them. An instrument that changes what it measures produces findings about itself.

14.6 What still needs real infrastructure

Several parts of Perfuse are implemented and have never been exercised against the real thing. They are listed here rather than left to be discovered:

• SMB against a real Windows share — the protocol code is complete and tested for path safety and argument handling, but no test opens a socket to a domain-joined server.
• A real serial port.
• The Mirth importer against XML a real Mirth produced. Tested against Mirth 4.5.2 in a container, and the finding was about this repository: the only migration fixture here was written by hand and Mirth will not load it — it stores the channel as invalid and discards every connector. What was settled is that the version attributes real Mirth writes on every element parse to the same channel, so they are not a hazard; what is not settled is everything else a real export contains.
• SAML against a hosted commercial identity provider. Keycloak is verified; one provider proves an implementation matches one vendor.
• An NCPDP claim through a real pharmacy switch.
• A SCRIPT message through Surescripts, where certification is a commercial process rather than a technical one.

The features in this chapter and the next exist so that you can gather your own evidence rather than taking anybody's word.

14.7 Measured against public conformance corpora

A test suite whose fixtures were written here proves agreement with oneself. These are other people's data.

14.7.1 FHIR R4, the specification's own examples

All 2,912 example files published with the FHIR R4 specification — every example the authors of the standard wrote.

Not one resource was validated incorrectly. Every failure is an explicit refusal naming the type it cannot read — 672 ValueSet, 80 ConceptMap and one Parameters. A validator that quietly passes what it does not understand is worse than one that says so.

The corpus found a defect, which is the reason for running it. Validating a bundle printed "Bundle validation from a file is not supported yet" and carried on. That was false in both directions: bundles whose entries happened to be types the parser could hold were already being validated, and a bundle that was genuinely invalid produced the same line, counted nothing, and exited zero — including under -strict, which exists so this can gate a build. Forty-two of the specification's own bundles were being skipped.

Bundles are now validated entry by entry, with three outcomes kept apart: an entry that is wrong fails and names the field, an entry of a type this build cannot read is counted as skipped and reported, and a bundle carrying no resource bodies is neither. The same corpus went from 2,100 resources checked to 13,723.

14.7.2 HL7 v2, the HAPI test corpus

The message fixtures from HAPI, the reference Java HL7 v2 implementation — deliberately awkward material including uuencoded payloads, escaped delimiters and repeating groups.

59 messages, 59 parsed, nothing refused. Seven message types in a corpus any single system would describe as one thing, which is the point perfuse profile exists to make.

14.7.3 What has not been run

DICOM against a public conformance set, and X12 against a published corpus. Neither has been done, and neither should be inferred from the two above.

15 Migration from Mirth

Two things are needed to replace a working engine: the channels have to come across, and somebody has to be able to show that the replacement produces the same output. Perfuse does the first by importing Mirth's own exports, and the second by comparing the two engines on your own traffic.

Everything in this chapter applies equally to the Open Integration Engine and BridgeLink. Mirth Connect stopped being open source at 4.6 in March 2025; OIE (hosted by the Eclipse Foundation) and BridgeLink (Innovar Healthcare) are the forks that continue the open-source line, and both write the same export formats. The importer is tested against all three, below.

15.1 Importing channels

Perfuse reads every export these engines write:

Point perfuse translate at any of them, or drop one on Administer → Migrate:

perfuse translate -o ./channels server-backup.xml

A code template library becomes lib/<library>.js beside the channels, and every channel Mirth had the library enabled for gets scripts.include: [lib/<library>.js] — so a transformer calling a site function such as formatMRN() still finds it. A channel the library was not enabled for does not include it, because its scripts could not see it in Mirth either. Drag-and-drop snippets are left out: Mirth only ever pastes those into a step by hand, so they are not code that runs on its own. In the browser, importing a channel saves the libraries it includes first.

A Channel Writer names the channel it delivers to by id. In a group or a backup the target is in the same document, so it becomes a channel destination naming that channel; from a single-channel export it is reported for you to fill in. Server-wide global scripts have no Perfuse equivalent and are reported rather than dropped.

The report says, per channel, whether it translated cleanly, translated with warnings, or could not be read.

The headline is a fraction with its denominator — "37 of 40 ready" — because "37 ready" tells you nothing about what you still have to do.

A channel that could not be read is a different problem from one that could not be translated. The first means the XML itself did not parse and is usually a truncated or partial export; the second means the channel's content has something without a Perfuse equivalent. The import separates them.

15.2 What translates and what needs a decision

Sources, destinations, filters and the ordinary transformer steps translate directly. The connectors that translate: TCP/MLLP (and raw TCP with its framing), HTTP, File, Database, JavaScript, DICOM, Web Service (SOAP), SMTP and Channel Reader/Writer. JMS and the Document Writer do not, and are reported as blockers.

A Mapper step that sets a variable puts it into the map its scope names — channelMap by default — exactly as Mirth does, so later steps reading it with $('name') find it.

JavaScript transformers do not, in general. Mirth channels commonly hold substantial code in a transformer, and there is no automatic conversion from arbitrary JavaScript to declarative steps. The importer reports these rather than attempting a translation that might be subtly wrong: a mistranslated transformer is worse than one flagged for a human, because it will run.

Where a script genuinely has to remain a script, Perfuse can run it — see the scripts key in the channel reference — at the cost of the step-level trace described in debugging.

15.3 What the importer has been tested against

Five engines, each authoring its own documents: Mirth 4.5.2, OIE 4.5.2, 4.6.0 and 4.7.0, and BridgeLink 26.9.0. scripts/mirth-engine-corpus.sh compiles a small program against each engine's own jars and has its own serialiser write three ordinary channels — an MLLP feed with a mapper, a script calling a code template library and a filter; an HTTP feed into a database; a file poll out over MLLP — plus the library and a channel group. It loads them into the running engine and downloads the engine's own server backup. The results are committed under internal/mirth/testdata/engines/, and the test suite holds the importer to every one of them on every build: each backup is read, translated, loaded, and the ADT channel is run with two messages to check the library pads the record number and the filter drops the result.

Perfuse's own exports go the other way — Perfuse channels imported into each running engine and checked that the engine did not store them as invalid. All five accept every transport Perfuse exports. Open Integration Engine 4.7.0 added two HTTP settings with no equivalent here: an HTTP Sender bound to a chosen local address is reported as a warning, and an HTTP Listener request-header limit only when it is above the 1 MB Perfuse accepts.

The first run against this corpus found four defects, all fixed: the translator refused HTTP and File sources as "only MLLP is supported" long after Perfuse had both; it read an HTTP Sender's address from a field none of the engines writes; it translated Mirth's socket buffer size as a 64 KB message limit; and a Mapper's variable became a JavaScript global that $('mrn') never saw, so the library padded an empty string.

The single-channel fixture that started this was also exported by Mirth 4.5.2, authored by Mirth itself rather than written here. That distinction earned its place: the only fixture in this repository used to be hand-written, and a real Mirth will not load it — the API accepts the POST and then stores the channel as This channel is invalid. Verify all required extensions are loaded correctly, with every destination connector discarded.

Hand-writing one was never going to work, and the reason is worth knowing if you are producing exports of your own. Mirth's serialiser ignores elements it does not recognise, so a wrong element name produces no error whatsoever — the connector simply is not there afterwards. There is nothing to read and nothing to correct against.

scripts/mirth-author-channel.sh builds one using Mirth's own model classes and its own serialiser, then posts it to a running server and fails if the server rejects it. Perfuse's importer reads the result: name, source transport and destinations all survive.

15.4 Proving it matches

This is the part that decides whether a migration happens, and it needs evidence rather than confidence.

Perfuse compares its own output against the old engine's, message by message, on your traffic. What it needs is pairs: the message as it arrived, and the message the old engine produced from it. Both are in Mirth's own message store and can be exported from its message browser.

15.4.1 Four numbers, not a pass rate

They are four numbers because they mean four different things and collapsing them hides the ones that need a decision.

Identical means byte for byte, not equivalent. A weaker test would let differences in segment order or trailing separators through, and those are exactly what a fussy downstream system rejects.

Cosmetic differences are counted separately rather than folded into the good column. They genuinely carry no information, so treating them as failures would bury real findings under thousands of nothing — but they are not identical either, and a receiver doing its own strict parsing may disagree.

"Would not run" is separate from "differ" because it is usually a configuration gap the importer could not fill, not a mapping decision. If everything is in that column, the verdict says so and tells you to look at the configuration before reading anything else.

15.4.2 Differences are grouped by field

A run over fifty thousand messages reporting four thousand differences has told you nothing you can act on. The same run reporting that PID-8 differs in every message because the old engine wrote Male where Perfuse writes M has told you exactly one thing to decide.

So each finding is a field, with a count, and it says whether the difference is systematic — the same value pair every time — or whether the field's content differs.

That distinction is the most useful thing in the report. One distinct value pair across four thousand messages is a single mapping decision. Four thousand distinct pairs is the content differing, which is a different and much worse problem, and the two must not read alike.

Findings are ordered by how many messages they affect, so the largest single cause is first.

15.4.3 The verdict does not round

It gives exact counts: 49,993 of 50,000, not "over 99%". The seven are the whole point of running it.

It is written to be quotable in a change request, because that is where the number ends up.

15.5 A suggested sequence

1. Import the channels and resolve anything reported as unreadable.
2. For each channel, review the warnings. Most will be scripts.
3. Export a few thousand message pairs from Mirth for the busiest channel and run the comparison.
4. Work through the findings. Systematic ones are one decision each.
5. Re-run until the only differences are ones you have decided are correct.
6. Run Perfuse in shadow alongside Mirth on live traffic, delivering nowhere, and compare again over a period that includes a weekend and a month end.
7. Cut over one channel, not all of them.

15.6 What only runs on one vendor's software

The migration screen answers a second question, and it is worth asking before you have any opinion about Perfuse: how much of your integration logic can only run on the software you have.

Every channel gets a Portability verdict, from the same scan that produces the migration notes. It runs against a channel export, so it needs nothing installed and changes nothing.

15.6.1 The distinction is the whole point

Most Java in Mirth scripts is not lock-in. SimpleDateFormat, HashMap, Apache Commons — all of it working around a JavaScript engine from 2009, all of it ordinary, all of it with direct equivalents. A channel with three hundred of those references is fully portable, and a tool that reported "300 Java references, you are trapped" would be lying to you.

Lock-in is specifically the calls that need the vendor's own server: com.mirth.connect.* and vendor jars. Five of those and you are stuck. Five hundred of the other kind and you are free.

So the verdict leads with the number that matters and says in the same sentence that the larger number is not it. Where there are vendor calls, they are listed by name — a count is an assertion, and a list is something your own engineer can go and check.

A third category is kept separate: capability that exists but not from a script. Starting a channel from JavaScript has no equivalent here, and there is an API endpoint that does exactly the same thing. Calling that lock-in would overstate the finding.

15.6.2 Java calls that run unchanged

The commonest of those Java classes run as they are written. Perfuse has no Java runtime, so these are JavaScript classes with the same names and methods, enough for the way channel scripts use them; importPackage(java.util) and importClass(...) bring them into scope by their short names, as in Rhino (JavaScript's own Date, Map, Set, Math, String and Boolean are never replaced: the Java ones are still there by full name). The migration report counts each of these calls as already supported.

They behave as Java does where scripts depend on it: Integer.parseInt("x") throws NumberFormatException, String.replaceAll and split take regular expressions while replace is literal, maps key strings by value, TreeMap and TreeSet iterate in order, and SimpleDateFormat.parse returns a date getTime() works on. A method a script calls that the equivalent lacks fails at that line, naming it; any other Java class fails by name, as before. BigDecimal is a double here, so it does not keep Java's exact decimal arithmetic: check scripts that use it for money.

15.6.3 External scripts are reported as unknown

A step that runs an external script file references a path on the old server, and the file is not in the export. Nothing can be said about what it contains, so it is counted as unknown rather than assumed either way. Fetch those files before concluding anything — in both directions.

15.6.4 Perfuse's own lock-in, stated in the same breath

This section would be dishonest without it.

Perfuse is Apache 2.0, which is irrevocable for code already released. You can fork what exists today and nobody can withdraw that. Channels are YAML files and scripts are ordinary JavaScript, so there is no proprietary surface to call — Mirth's flavour of Java dependency is structurally unavailable here, which is the one place a limitation is genuinely a feature.

What that does not promise: that a future version stays open, that a hosted service exists at a price you like, or that migrating away from Perfuse costs nothing. Moving any integration layer means re-testing every channel against real traffic. What you are choosing is whether the artefacts you build are readable and portable, and whether the exit depends on a licence somebody else controls.

15.6.5 Setting up step 6

The Shadow section starts a comparison. Choose the channel that is running, choose the candidate to compare against from the list, and start.

Three things about it are worth knowing before you rely on the numbers.

The candidate is chosen from a list, not typed. A shadow names a channel file, and a name that does not resolve makes the *live* channel invalid — Perfuse refuses a channel wholesale when anything it references is broken. So a typo does not produce a warning, it makes the running channel disappear.

The share is a percentage. Lower it only on a busy feed, and know what it costs: sampling reduces work and confidence in the same proportion, and the message that would have shown the difference is the unusual one.

Fields to ignore is usually needed. A channel that stamps a timestamp or a sequence number differs on every single message, which reports a difference rate of 100% and tells you nothing. MSH-7 and MSH-10 are the common pair.

A comparison is written to the channel file as soon as you start it, and begins observing when the channel next loads — the screen says so rather than claiming it is already running. Stopping a comparison leaves the candidate channel in place, because the candidate is the thing meant to go live.

Step 6 is the one that cannot be shortened. The differences that matter are usually in traffic that only appears occasionally — a rare trigger event, a month-end batch, a sender that behaves differently at midnight — and a sample taken over an afternoon will not contain them.

15.7 Going back the other way

A channel can be exported as a Mirth channel file, from the browser: Channels, then To Mirth on the channel you want.

This exists because the objection to replacing a working engine is rarely whether the replacement is any good. It is what happens if the decision turns out to be wrong, and an export that goes back the way it came is the cheapest answer to that.

Read what the dialogue tells you before you take the file. Mirth's format has nowhere to put a Perfuse filter, a transformation chain, a contract or a shadow comparison, so an exported channel does less than the one it came from. The transports and their addresses convert; the logic does not. Each loss is listed by name before the file is offered, and the same list goes into the channel's description so that whoever imports it sees it too.

A channel Mirth cannot express is refused rather than approximated. An S3 destination has no Mirth equivalent, and a channel that imported cleanly while delivering somewhere other than the bucket would be worse than no file at all. The refusal names the destination at fault.

The connector definitions are not written from a reading of Mirth's format. scripts/mirth-dump-connector-templates.sh has Mirth's own serialiser produce the defaults for each connector class, and Perfuse substitutes values into those documents — refusing any setting the template does not already contain. This matters because of how Mirth answers a channel it cannot parse: it does not refuse the import. It stores a channel whose description has been replaced with "This channel is invalid. Verify all required extensions are loaded correctly" and whose destinations have been silently discarded. An exporter checked against its own output rather than against a server passes every test while producing documents that are thrown away, which is exactly what happened here before the exports were tried against a running Mirth.

What crosses today: MLLP and TCP in both directions, HTTP in both directions, file reading and writing, database reading and writing, DICOM in both directions, and SMTP, SOAP and JavaScript destinations. Each pair is verified by importing into a real Mirth 4.5.2 and checking the server did not quietly replace the channel.

16 CMS-0057 for payers

The CMS Interoperability and Prior Authorization final rule (CMS-0057-F) requires impacted payers — Medicare Advantage organisations, state Medicaid and CHIP programs and their managed care plans, and QHP issuers on the federal exchanges — to run four FHIR APIs from 1 January 2027, and to post prior authorisation metrics on their public website every year from 2026.

Perfuse provides the four APIs on its FHIR endpoint and the conversions that fill them: adjudicated claims as CARIN Blue Button, prior authorisations as Da Vinci PDex, and the yearly metrics in the layout of CMS's own template. The CMS-0057 view, under Exchange, says which of the four this instance can answer and what each still needs, and does all three conversions in the browser.

Drugs are out of scope throughout, as they are in the rule's prior authorisation provisions: no pharmacy claims, no formulary, and a metrics row naming a drug is refused rather than counted.

16.1 The four APIs

The Patient Access API needs no operation of its own: it is the FHIR endpoint's ordinary read and search, protected by SMART, with CARIN and PDex resources in the store. Searching ExplanationOfBenefit supports the parameters CARIN names — patient, identifier, type, service-date, billable-period-start, provider, insurer, coverage — and Coverage supports subscriber-id, identifier and payor.

16.1.1 Two releases of the guides: 2.1.0 and 2.2.x

CMS-0057-F recommends CRD, DTR and PAS 2.0.1 and 2.1.0. The 2.0.1 releases rest on US Core 3.1.1, which expired on 1 January 2026, so 2.1.0 is the release an EHR built for the rule is likely to speak; the newest are CRD 2.2.1, DTR 2.2.0 and PAS 2.2.1. Perfuse answers in both. It works out which a caller speaks, most specific first:

1. from the request: CRD's CDS Hooks extension davinci-crd.requestedVersion ("2.1"), or the version on a Da Vinci profile a DTR

or PAS input claims (profile-pas-request-bundle|2.1.0);

1. from the caller's registration: davinci_version: "2.1" on a SMART client (-smart-clients) or a CDS client (-cds-clients);
2. from the server: serve -davinci-version 2.1; the default is 2.2.

clients:
  - issuer: https://ehr.example.org
    jwks_url: https://ehr.example.org/.well-known/jwks.json
    davinci_version: "2.1"

Every answer is decided and kept in the 2.2.x form and rewritten for a 2.1.0 caller as it is sent, so the rules, the review queue, the X12 278 link and the metrics are the same for both. The rewrite covers what the releases spell differently: CRD 2.1.0 has no indeterminate (Perfuse says conditional, with the reason) and no category on a coverage detail; DTR 2.1.0 names the package PackageBundle and leaves the QuestionnaireResponse to the app; PAS 2.1.0's $inquire answers with one Bundle, and it lacks the reviewer and transmission extensions. The full list, and the check against each 2.1.0 guide's own examples, is in conformance/davinci21. A PAS notification follows -davinci-version, since a subscription does not say which release its owner reads.

16.2 Coverage requirements and documentation: CRD and DTR

The Prior Authorization API is in practice three Da Vinci guides together. CRD tells the clinician, while the order is still a draft, whether it is covered, whether it needs prior authorisation and what documentation is wanted. DTR hands the EHR the questionnaire that gathers that documentation. PAS submits the request and returns the decision. Perfuse serves all three as the payer.

-crd-rules rules.yaml serves CRD over CDS Hooks at /cds-services: all six of CRD's hooks, order-sign, order-select, order-dispatch, appointment-book, encounter-start and encounter-discharge, each with a prefetch for the patient's active Coverage. The two encounter hooks also prefetch the encounter, and answer about the encounter itself, matched by its type and service type, as appointment-book answers about an appointment. The rules are the payer's policy, kept in a file because they change without software releases:

payer: Springfield Health Plan
rules:
  - description: Home oxygen equipment
    codes: [E0424, E0431]
    covered: covered            # covered, not-covered, conditional
    pa: auth-needed             # no-auth, auth-needed, satisfied, performpa, conditional
    documentation: [clinical]
    questionnaire: https://www.springfield-health-plan.example/fhir/Questionnaire/home-oxygen

Each order gets a systemActions update carrying CRD's coverage-information extension - which the EHR stores on the order and later sends on with the prior authorisation - and a card the clinician reads. An order whose code has no rule is answered conditional, never assumed covered; a request with no Coverage at all gets a card saying so. examples/crd/ has a rules file and a matching questionnaire.

A rule can also carry the rest of what CRD lets a payer say:

• billing_codes: the codes to bill under.
• details: limits and costs, such as allowed-period or in-network-copay.
• contact: who to call.
• expiry_days: how long the answer holds.
• depends_on: codes of other orders the answer depends on, so the EHR asks again if they change.
• doc_purpose: what the documentation is for (withclaim, withorder, retain-doc). withpa is refused, because CRD 2.2.1's

own invariant crd-ci-q4 rejects it.

What the EHR did not prefetch, Perfuse reads from the EHR's fhirServer with the token it sent. If that fails, the answer is indeterminate with CRD's technical reason, never a guess. A Coverage that has ended or is not active is answered not-covered, no-active-coverage.

members: fhir in the rules file resolves the coverage against the payer's own records in this server's FHIR store (start it with -fhir), the same records $member-match reads:

• a patient who is not a member is answered no-member-found;
• a member whose coverage does not match is answered coverage-not-found;
• a prior authorisation already approved there for the service (a ClaimResponse with a preAuthRef) makes the answer satisfied,

with that number.

Discovery declares davinci-crd.version and a coverage-info configuration option. When a client turns the option off, the answer is empty. EHR JWTs are checked as CDS Hooks defines them, with iss, aud, exp, iat and jti and no sub, and a repeated jti is refused.

Calls authenticate with the JWT an EHR signs for each call, from an issuer named in -cds-clients with its JWKS URL - which is how CDS Hooks describes it - or with a Perfuse API token. Discovery is open, as CDS Hooks requires.

DTR: load the questionnaires into the FHIR endpoint, and POST /fhir/Questionnaire/$questionnaire-package returns them as DTR package bundles, with the CQL Libraries they name. The request can name the questionnaire, or send the order and let its coverage-information say which.

Trying it: Payers → Claims & auth → Coverage requirements (CRD) sends an order to this server's rules, or to a payer's CDS service URL, and shows the cards and the coverage information.

16.3 Claims as CARIN Blue Button

perfuse cms0057 carinbb pairs each claim in an 837 with its payment in an 835, by the patient account number the 835 is required to echo back, and writes a FHIR transaction for each: the ExplanationOfBenefit with the Patient, Coverage, Organizations and Practitioners it references.

perfuse cms0057 carinbb -system https://fhir.your-plan.org/identifier -network innetwork \
    claims.837 remittance.835

The profile follows the claim: professional claims (837P) become C4BB-ExplanationOfBenefit-Professional-NonClinician, and institutional ones (837I) inpatient or outpatient by the type of bill. Every entry is a PUT with an id taken from the source identifiers, so loading the same claim twice updates it rather than making a second copy.

Three things are not in either X12 file, and each is handled by saying so rather than by guessing:

• The identifier system. CARIN requires the member identifier to name the payer's namespace. -system is required; there is no default, because a default would give every payer using Perfuse the same namespace.
• The network status. Neither transaction says whether the billing provider is in network, and it decides what the member pays. Without -network the benefit payment status is other and the conversion notes why.
• A claim the 835 does not mention. A CARIN ExplanationOfBenefit is an adjudicated claim. Without the 835 there is no payer claim number, no payment and no member liability, so the claim is reported as skipped and not converted.

Diagnoses are written with their decimal point (J02.9, not J029), because that is how the code system publishes them and a terminology server asked about the other spelling says it does not exist. A dependent's member identifier is the subscriber's, which is what the 837 carries, and the notes say so. An NPI whose check digit is wrong is reported before US Core rejects it.

16.4 Prior authorisations as PDex

perfuse cms0057 priorauth converts a Da Vinci PAS ClaimResponse — or the PAS response bundle that carries one — into a PDex prior authorisation ExplanationOfBenefit, which is what all three data APIs serve.

perfuse cms0057 priorauth pas-response.json pas-claim.json

The PAS Claim is optional and nearly always needed. An ExplanationOfBenefit must say which coverage the decision was made under, and only the request carries that; without it the conversion stops and says so. The review action — approved, denied, pended, with its authorisation number and reason — moves from PAS's extension to PDex's, and the X12 service type keeps its code under the URI PDex binds it to.

16.5 The Provider Access and Payer-to-Payer APIs

With -fhir-payer-apis the FHIR endpoint answers three more operations:

• POST /fhir/Patient/$member-match — HRex member matching. The coverage identifiers narrow to a few candidates, and the family name and date of birth must then agree; a given name is compared by initial, and gender only when both sides state it. More than one surviving candidate is not a match, and the answer is 422 rather than a guess, because a guess discloses a stranger's claims. An active Consent permitting disclosure is required, since the Payer-to-Payer API is opt-in for the member; -fhir-member-match-without-consent turns that off for testing.
• GET or POST /fhir/Group/{id}/$davinci-data-export — the Da Vinci bulk export of a Group's current members. exportType chooses the audience: hl7.fhir.us.davinci-pdex#provider-download or #provider-delta for Provider Access, #payertopayer for Payer-to-Payer.
• GET /fhir/Group/{id}/$export — the standard Bulk Data group export, treated as Provider Access.

The exports apply the rule's exclusions on the way out. Claims lose the payment and every cost-sharing and remittance amount, and keep the services, codes, dates and providers; the CARIN profile is removed from meta.profile because the resource no longer meets it. Payer-to-Payer also leaves out denied prior authorisations. Members holding an active PDex Provider Access opt-out Consent are left out of a provider export, and the log records how many. The patient parameter can only narrow to members of the Group; naming anyone else is refused.

Access to a Group's export is decided by the endpoint's authentication. SMART scopes say what kinds of resource a token may read, not which Group, so each provider needs a token that can reach only its own attribution list. An API token can be limited to Groups when it is made — perfuse token create -label riverside-provider-access -fhir-groups riverside-attributed, or the Limit to FHIR Groups field under Users → Machine credentials — and on the FHIR endpoint it can then read those Groups, run $davinci-data-export or $export on them and fetch what the export produced, and nothing else. Another provider's Group answers not-found rather than forbidden, so a token does not learn which other attribution lists exist; every other request, member matching and ordinary search included, is refused. The limit applies to API tokens; a token from a SMART issuer carries no Group limit. When SMART is configured as well, API tokens are refused unless Settings → FHIR → Accept Perfuse API tokens beside SMART tokens is on (see Security, *Who may call the FHIR endpoint*); a provider's Group-limited token needs it.

16.6 A provider directory: Plan-Net

CMS-0057 also asks payers for a provider directory, and the FHIR endpoint serves one to Da Vinci Plan-Net 1.1.0 with no option to turn on: load the Practitioners, PractitionerRoles, Organizations, OrganizationAffiliations, Locations, HealthcareServices, InsurancePlans and Endpoints, and members' apps can search them. Every Plan-Net search parameter is indexed - a role's network and service, a plan's coverage area, an affiliation's participating organization, an organization's partof - along with the includes and reverse chains (_has) the guide's queries use, and the CapabilityStatement lists the Plan-Net profiles.

Inferno's Plan-Net suite passes 199 tests. The 10 it fails are forward chains where the kit takes its search value from the first Organization it has seen rather than one the searched resources refer to; that is reported to the kit (its issue 34), and the server answers those queries correctly when given a value the data holds.

16.7 Prior authorisation metrics

perfuse cms0057 metrics reads a CSV of decisions exported from the utilisation management system and produces the public page CMS requires, in the layout of its *Prior Authorization Metrics Reporting — Overview and Template*.

perfuse cms0057 metrics -year 2025 -org "Springfield Health Plan" -services services.csv \
    decisions.csv > prior-authorization-metrics-2025.html

Columns are found by header: priority, received, decided and decision are required, and request_id, line_of_business, extended, appealed, appeal_decision, service_code and service_description are read when present. A request belongs to the year it was decided in; one still pending is listed as excluded, never counted. Every row that cannot be read is reported with its line number.

The arithmetic follows the template: for standard and expedited requests separately, the share approved and denied, approved and denied within the decision timeframe, approved after the review time was extended, and approved after appeal — out of appeals, not out of requests — with the mean and median time from receipt to decision. A median under a day is written in hours rather than rounded to "0 days", which the template asks for explicitly. Partly approved requests are counted as approved, since the template has no category for them, and the page says how many there were. Metrics are reported per line of business, which is the level CMS requires.

The page is self-contained — no script, no external stylesheet or font — because it is posted on a public website by whoever maintains that, and anything it loads from elsewhere is something else that can break or track a visitor. -format csv and -format json give the same numbers for other uses. Without -services the page carries a notice that the list of items and services requiring prior authorisation is missing, because CMS requires it on the same page.

16.8 Drugs: the formulary, Real-Time Prescription Benefit and electronic prior authorization

CMS-0062-P (proposed 14 April 2026) would bring drugs into prior authorization: impacted payers would support NCPDP SCRIPT electronic prior authorization, the NCPDP Formulary & Benefit standard and NCPDP Real-Time Prescription Benefit from 1 October 2027, decide drug requests within 24 hours (expedited) and 72 hours (standard), give a specific reason for every denial, and report drug metrics from 2028. Medicare Part D already requires SCRIPT ePA. One file, the formulary, answers all of it:

perfuse serve -fhir -pas -crd-rules payer-rules.yaml -formulary formulary.yaml

examples/formulary/formulary.yaml is a sample whose drugs are real RxNorm concepts with NDCs RxNorm lists for them (checked against RxNav). A file names the payer, its plans (each with the formulary it uses, its group IDs and its cost shares by pharmacy benefit and tier) and its formularies. Each drug is an RxNorm SCD or SBD with its RxNorm group (the SCDG or SBDG the Drug Formulary API requires), its NDCs, a tier, and its limits: prior_authorization, step_therapy, quantity_limit (a quantity in a rolling number of days, and a daily maximum), not_covered, alternatives (RxNorm codes, most preferred first), notes, and questionnaire, the canonical URL of the FHIR Questionnaire a prior authorization asks. cost_30_day is the plan's cost of a 30-day supply, which a coinsurance is a percentage of; without it a coinsurance is quoted as a percentage, never as an invented amount. The whole file is checked when it loads, every problem listed at once. A member is found by the file's members list, by group, or through the FHIR store: a Coverage whose subscriberId is the member ID and whose class of type plan is the plan's id. Payers › Drugs shows the formulary, prices a drug and runs a prior authorization end to end.

16.8.1 The Da Vinci US Drug Formulary API

Published at /formulary/fhir as Da Vinci US Drug Formulary 2.1.0: each plan a PayerInsurancePlan, each formulary a Formulary (both InsurancePlan), each drug a FormularyDrug (MedicationKnowledge) and each entry a FormularyItem (Basic). The guide's searches are served (Basic?code=formulary-item&formulary=...&drug-tier=...&pharmacy-benefit-type=...&period=..., subject:MedicationKnowledge.code, InsurancePlan?formulary-coverage=..., coverage-type, MedicationKnowledge?code=...&doseform=...) with _include=Basic:subject, Basic:formulary and InsurancePlan:formulary-coverage. It is public, with no credential, as CMS requires of a payer's formulary: it is served from a store of its own, in memory, that holds the formulary and nothing else, so being open cannot reach a patient's record. It is read-only. An excluded drug is not published, since the API lists what a formulary covers; RTPB and ePA still answer it as not covered. Verified with the HL7 FHIR validator against the guide's 2.1.0 package with terminology checked: every resource generated from the sample has no errors.

16.8.2 Real-Time Prescription Benefit

POST /ncpdp/rtpb takes an RTPBRequest (NCPDP RTPB v13) with an API token of the operator role and answers an RTPBResponse from the formulary: the coverage status, the formulary status, the member's estimated share and the plan's, and the coverage restrictions, with up to five covered alternatives priced the same way. Restriction codes and the status each maps to follow NCPDP's public RTPB Implementation Recommendations: 75 prior authorization required, 608 step therapy, 76 plan limits exceeded, 7X days supply over the plan limit (a drug not available by mail, say), 70 not covered, all *covered with restrictions* (CR) except 70 (NC). A member with an approved prior authorization on file gets CC and AB8, as the Surescripts guide asks, so the prescriber is not sent to ask again. A request that cannot be priced is NotProcessed with an NCPDP reject code: 52 for a member not found, E7 and 19 for a missing quantity or days supply. The pharmacy benefit is read from the request: a fill over 34 days is a three-month supply, and pharmacy type M is mail order.

16.8.3 Electronic prior authorization (NCPDP SCRIPT)

POST /ncpdp/script takes PAInitiationRequest, PARequest, PAAppealRequest and PACancelRequest with an API token of the operator role, and answers each with its response:

The question set is the drug's FHIR Questionnaire from the FHIR store, the same one DTR fills in: a boolean becomes a yes/no choice, a choice a choice, a number numeric, a date a date, and anything else free text; groups are flattened in order, and enableWhen is not carried, since SCRIPT branches by choice and not by condition. A drug with no questionnaire is asked three free-text questions: the diagnosis, what was tried, and why this drug. A PARequest becomes a Da Vinci PAS request: a Claim for the drug (RxNorm and NDC), the MedicationRequest it asks for, the patient, prescriber, payer and coverage, and the answers as a QuestionnaireResponse, with any attachments as DocumentReferences. It is then decided as every prior authorization on this server is: the rules file, a decision service (-pas-decider-url), or the reviewer queue, where it is marked Drug and held to the drug timeframes. A decision service sees a drug request exactly as it sees one from an EHR's PAS client. We recommend Vaglio, BioDream's source-available (PolyForm Shield) decision engine, which has drug policies with step therapy; a payer's own engine plugs in through the same -pas-decider-url, and none is needed for the rules file and reviewers to decide.

A decision made after the request was answered (a reviewer's, an appeal's) is sent to the prescriber as an unsolicited PAResponse or PAAppealResponse, routed to the channel named by -epa-reply-channel, which delivers it to the network. Without one, or when delivery fails, the case says the prescriber has not been told and the screen sends it again.

Payers › Drugs › Prior authorization sends the messages a prescriber's system would to this server's own endpoint (start, answer the questions, see the decision), lists every case with what the prescriber was told, and shows the drug figures CMS-0062-P proposes: requests approved, denied and pending, appealed and approved or denied on appeal, the mean and median hours from request to decision, and how many were decided late. Medical-benefit drugs requested through PAS (a HCPCS J code with a MedicationRequest, or an item coded in RxNorm or NDC) are counted as drugs in the PAS figures too.

What this rests on, stated plainly. NCPDP's schemas and implementation guides are licensed. The element names and order here follow the public Surescripts ePA and RTPB companion guides and their examples, and NCPDP's public RTPB recommendations. Two elements the public material never shows are written to the SCRIPT pattern used elsewhere and should be checked against a licensed copy before certification: Closed/ReasonCode and Denied/DenialReason. No message has been checked against NCPDP's XSD or a network's certification. The NCPDP Formulary & Benefit file is not produced: its full layout is in NCPDP's licensed guide, and a partial file would be refused by the network that loads it.

16.9 What was checked, and against what

The CARIN and PDex outputs were validated with the official HL7 FHIR validator, loaded with the published packages (hl7.fhir.us.carin-bb#2.2.0, hl7.fhir.us.davinci-pdex#2.2.0): professional, inpatient and outpatient claims and two PAS decisions, with no errors. The PDex inputs were the PAS guide's own examples rather than shapes written here to agree with the converter. The validator found five defects on the first run — among them that CARIN requires the profile version in meta.profile and the claim-type code system version on institutional claims — and each is fixed and covered by a test.

Building this found a defect older than it: the FHIR store dropped every element its internal model did not declare, so an ExplanationOfBenefit lost its items, diagnoses, adjudication and payment on the way in. The store now keeps whatever a resource carries, and a test loads a CARIN claim through the server and reads it back whole.

CRD's output - the updated order, and the CDS Hooks response against CRD's own logical model - and DTR's package output validate in the official HL7 validator against CRD 2.2.1 and DTR 2.2.0 with no errors.

DTR here is the payer's side of 2.2.0. $questionnaire-package takes the questionnaires named, those CRD named on an order, or the coverage assertion id CRD returned (context, while the same process is serving CRD), and returns each as a package bundle with a QuestionnaireResponse to fill in, the Libraries its CQL needs and their dependencies. The value sets its answers use travel in the package when they are loaded (PUT /fhir/ValueSet/{id}), and $expand lists their codes. $log-questionnaire-errors writes what a DTR app reports to the server log.

Adaptive questionnaires: write the whole questionnaire once, with SDC's questionnaireAdaptive extension and enableWhen on the questions that only apply sometimes. The package hands the app an empty shell, and each $next-question call adds the next question that applies to the answers so far, until there is nothing left to ask and the response is marked completed. The order and the branching are the payer's own rules; questions that do not apply are never shown.

Signing in as a client: DTR and PAS clients reach the payer with SMART Backend Services - a signed JWT exchanged for a token at the payer's authorization server. Point Perfuse at that server with -smart-issuer (and -smart-jwks if its address does not resolve from Perfuse), and pass -smart-backend-services so the discovery document says so. The Inferno DTR suite passes this way with Keycloak as the authorization server.

Perfuse can be that authorization server itself: serve -fhir -smart-clients clients.yaml issues Backend Services tokens at /auth/token to the clients listed, each with the public keys it signs its assertions with and the system scopes it may be granted, and the FHIR endpoint accepts them. No separate identity server is needed for a payer's machine-to-machine clients.

With -smart-users users.yaml as well, members and clinicians sign in there to authorize apps, which the Patient Access API needs: the app sends the person to /auth/authorize, they sign in, a clinician chooses the patient, and both see what the app asks for and can untick any of it. A member is only ever given their own record, whatever the app asks for. Each person in the file names the FHIR resource they are, Patient/… or Practitioner/…, and a password hash from perfuse smart hash; the password itself is never written down.

People can sign in at the organisation's own identity provider instead: -smart-oidc oidc.yaml names it (issuer, client id and where the secret is), and the sign-in page offers "Sign in with" it beside the password. Each person is linked by the provider's subject, oidc_subject in the users file, so the file still decides who may authorize apps and which FHIR resource they are; an account linked to nobody is refused. Codes, refresh tokens and revocations are kept in the database, so a restart signs nobody out.

Users → SMART apps in the console lists the registered apps and the people, and adds, edits and removes them. Each save is checked as the files are at start-up, written to them, and used at once. A confidential app saved without a secret is given one, shown once; a password is set there and never shown back. Removing an app, or a person, stops the access tokens already issued to it or granted by them at once, not when they expire, and their refresh tokens with them.

Scopes may be granular, as SMART App Launch 2 and US Core define them: patient/Observation.rs?category=laboratory reads only the Observations that search would find. A grant that is filtered for a type applies its filter to every search and every read of that type; an unfiltered grant for the type, or for *, lifts it. A filter that cannot be read grants nothing rather than everything.

16.10 Deciding prior authorisation requests: PAS

serve -fhir -pas -crd-rules rules.yaml answers Da Vinci PAS 2.2.1 at POST /fhir/Claim/$submit and POST /fhir/Claim/$inquire. The decisions come from the same rules file as CRD's answers, so the order a clinician is told needs authorisation is decided by the rule that said so:

  - description: Physical therapy
    codes: ["PT"]                       # matched on the item's productOrService, then the code of the order it requests
    system: https://codesystem.x12.org/005010/1365
    covered: covered
    pa: auth-needed
    pa_decision: approve                # approve, deny or pend; empty: not-covered is denied, no-auth approved, the rest pended
    details:
      - {code: allowed-quantity, value: "6"}   # asked for more, it is certified for six (A6, with the authorised detail)
  - description: MRI
    codes: ["62"]
    pa_decision: approve
    pa_alternative: {system: "https://codesystem.x12.org/005010/1365", code: "4"}  # approved as an X-ray instead (an added item)
  - description: Surgery
    codes: ["2"]
    pa: auth-needed                     # pended for a reviewer, asking for:
    questionnaire: https://payer.example.org/Questionnaire/surgery   # a DTR questionnaire
    pa_attachments: ["18776-5"]         # and documents, by LOINC attachment code

Each item gets an X12 review action: A1 certified, A3 not certified, A4 pended, A6 modified, C cancelled (certification type 3). A line that names no service is not decided but answered with an error (X12 901 AG, correct and resubmit). The response echoes what a 278 response echoes — item trace numbers, the requested service dates, the encounter's dates, the transmission identifiers with sender and receiver swapped — and gives each line the payer's own administration reference number. A service no rule names is pended, never approved: a decision nobody wrote down is a decision for a person.

Pended requests wait for a reviewer, who answers with POST /fhir/Claim/$decide:

{"resourceType": "Parameters", "parameter": [
  {"name": "claimResponse", "valueString": "<the ClaimResponse id>"},
  {"name": "decision", "valueCode": "approve"},
  {"name": "reason", "valueString": "Reviewed with the plan of care."},
  {"name": "reviewer", "valueString": "<the reviewer's NPI>"}]}

decision may also be modify: certified, but not as asked, with quantity (valueDecimal, the units certified) and/or alternative (valueCoding, the service approved instead). The response then says A6 Modified, with the certified detail or the alternative as an added item, and an authorization number. item (valueInteger, repeatable) limits the decision to some lines. The decision becomes a new version of the response, marked as reviewed by a person, and with -fhir-subscriptions it is delivered on the PAS topic (PASSubscriptionTopic, filtered by org-identifier, the requesting organisation's identifier) as the full PAS Response Bundle, in the same transaction that records it. $inquire returns the current response to every request that provider made about that member; another provider's inquiry finds nothing. $decide needs a write scope; $inquire is a read.

Requests and every version of their responses are kept in pas_requests and pas_responses in the server's database.

16.10.1 The reviewer queue

In the web console, Payers → CMS-0057 → Reviewer queue lists the pended requests soonest due first: an expedited request (Claim.priority stat) is due 72 hours after it arrived, a standard one 7 days. Choosing one shows the member, the provider, each service with the units asked for and where it stands, what the response asked for, and every document received for it, with plain-text documents shown inline. An editor records the decision there: approve, deny, or modify (units certified, or another service approved instead), with a reason and the reviewer's NPI. A modification has to certify fewer units than were asked for; as many or more is an approval, and is refused as a modification. A service approved instead starts in the code system of the one asked for. It is the same decision $decide makes, so the provider's subscription delivers it. Reading a request and deciding it are both written to the audit log.

Monitor → Team dashboards → Prior authorization shows, for the last 30 days, how many standard and expedited requests were decided within CMS-0057's timeframes, decided late, still waiting in time and overdue now, with the median time to decide, and how the services asked for were answered: approved, modified, denied or still pended. These two tiles are read from the requests themselves, so they are not in the dashboard's Grafana export, which says so in its description.

16.10.2 Receiving the documents a pended request asks for

A pended response asks for documents with a Task and one CommunicationRequest per document. A questionnaire is asked for as PAS describes it: a CommunicationRequest with the single LOINC code 102089-0, under the trace number of the line it is for (itemTraceNumber, which the ClaimResponse echoes; a line sent without one is given one). That trace number is the DTR context: $questionnaire-package with only context set to it returns the questionnaire. The provider sends what was asked for with Da Vinci CDex $submit-attachment (POST /fhir/$submit-attachment): the TrackingId is the request's own trace number (the ClaimResponse's first identifier, which is also the Task's), or a CommunicationRequest's identifier, AttachTo is preauthorization, and MemberId must be the request's member. Each attachment's DocumentReference or QuestionnaireResponse is kept with the request and shown to its reviewer; a document arriving decides nothing.

16.10.3 Deciding in an X12 utilization management system

Most payers decide prior authorizations in a UM system that speaks X12 278. With -pas-278-url, Perfuse is the FHIR front of that system: each $submit is sent as one 278 request (005010X217), every item a patient event. Each carries what PAS names for it: the review type (extension-serviceItemRequestType, UM01: health services, admission or specialty care), the certification type (extension-certificationType, UM02), the service type, the place of service (UM04), the level of service (extension-levelOfServiceCode, UM06: elective, urgent or emergency; a stat priority stands in for urgent), the date, an admission review's admission and discharge dates, the diagnoses, the care team's provider who will do the service, and the procedure and quantity, as a professional (SV1) or, on an institutional claim, a hospital (SV2) service line. The 278 response's action code and authorization number become the item's review action: certified, in part or modified, denied, pended, cancelled, or not considered (pended for a reviewer, with the reject reasons). Local rules are not consulted.

perfuse serve -fhir -pas -pas-278-url https://um.example/x12/278 -pas-278-receiver ACMEUM \
  -pas-278-token-env UM_TOKEN

A UM system that pends first and decides later posts its later 278 response to POST /fhir/Claim/$decide-278; each event is matched to its request by the trace number Perfuse sent, and decided as $decide would decide it. If the UM system cannot be reached, or answers with something that is not a 278 response, every item is pended for a reviewer and the provider is told only that; the reason is in the server log.

Inquiries the UM system answers

A provider's $inquire must find an authorization however it was asked for: by fax, through the payer's portal, by phone, or in a 278 another submitter sent. Perfuse holds only the requests that came through it; the UM system holds them all. So with a UM system that answers in real time (every transport but sftp), each $inquire is also sent there as a 278 inquiry (005010X215: BHT02 28, the member, the provider, the authorization number from the Claim's insurance.preAuthRef when it has one, and the event dates from billablePeriod or the items' service dates, else a year either side of today). Every authorization the answer holds that Perfuse does not (matched by the trace numbers it sent and the authorization numbers it already gave) comes back as one more Claim Inquiry Response Bundle: the UM system's decision for each service line, the authorization number and period, and a note saying where it was found. No Claim is made up for an authorization nobody submitted in FHIR: its ClaimResponse.request carries a data-absent-reason, as PAS's profile allows. An inquiry only reads; nothing in Perfuse's own records changes. If the UM system is down or answers with a TA1 or 999, the provider gets what Perfuse holds, and the link's status says why. The shape follows the 278 inquiry companion guides UnitedHealthcare, Cigna and Blue Cross Blue Shield of Massachusetts publish; it has not been tried against a real UM system.

How the 278s reach the UM system

The UM system's connectivity guide says how it takes 278s, and -pas-278-transport (Settings, Payers, Utilization management link) follows it:

A client certificate is -pas-278-cert and -pas-278-key; -pas-278-ca trusts a payer's own certificate authority. OAuth is -pas-278-oauth-token-url, -pas-278-oauth-client-id and the secret, fetched with the client-credentials grant and kept until a minute before it expires. Passwords, tokens and secrets are never flags: each is named by an environment variable (-pas-278-password-env, -pas-278-token-env, -pas-278-oauth-secret-env, -pas-278-sftp-password-env), or typed into the settings screen, where it is kept in the settings file (readable by the server's account only) and never shown again.

UM_PASSWORD=... perfuse serve -fhir -pas -pas-278-transport core-soap \
  -pas-278-url https://um.example/CORE/RealTime -pas-278-receiver ACMEUM \
  -pas-278-user perfuse -pas-278-password-env UM_PASSWORD

Over SFTP every request is pended until its answer arrives: the 278 response decides the items, and Perfuse puts a 999 accepting it in the outbound folder. A file it cannot read stays in the inbound folder for a person, and is offered again at the next read.

When the UM system cannot read a request

A UM system that cannot read a 278 answers with a TA1 (the envelope) or a 999 (the transaction) instead of a decision. Perfuse reads which and what it says, pends every item ("utilization management could not read the request"), and records it. Payer, CMS-0057, Reviewer queue shows the link: what was sent in the last seven days, each interchange by its control number, and what became of it (answered; acknowledged, answer to come; rejected, with the 999's segment, element and code; not reached). Each interchange has its own control number, one more than the last, which is what a TA1 or 999 names when it answers.

16.10.4 Deciding on the clinical evidence, with a decision service

A rules file decides by service code: a code needs no authorization, is not covered, or goes to a reviewer. Whether this patient meets the criteria for it is a different question, answered from the conditions, questionnaire answers and documents the provider sent with the request. With -pas-decider-url, every item the rules leave to a reviewer is first put to a decision service, such as Vaglio, which reads the same PAS request Bundle through Perfuse's published pas package. A public Vaglio, on invented requests only, runs beside Perfuse's test instance at https://vaglio.perfuse.health:8443 (sign in as demo, password try-vaglio-demo; it can look at everything and change nothing): every decision there has its proof, a plain-language letter and a receipt anyone can check.

perfuse serve -fhir -pas -crd-rules payer-rules.yaml -pas-decider-url https://vaglio.example/api/pas/decide \
  -pas-decider-token-env VAGLIO_TOKEN

The URL must be https, or plain http to this machine (localhost, 127.0.0.1), because it carries a patient's record and the token. Vaglio itself answers on https only; when it uses a certificate from its own authority, pass that authority with -pas-decider-ca DATA/tls/ca.crt (or any payer's internal authority the service's certificate comes from). The service is sent the request Bundle as the provider sent it, POST <url>?item=<sequence> (application/fhir+json), and answers {"decision": "approve" | "deny" | "pend", "why": "...", "requested": ["..."]}, or 404 when it decides nothing for that item, which leaves the rules' answer standing. why is the response's process note and is required for a denial, which is otherwise pended; requested is said to the provider as the information a pended request needs. A pend may also carry "questionnaire": "<canonical>" and "attachments": ["<LOINC>", ...], which are asked for in the response's CDex Task and CommunicationRequests beside whatever DTR questionnaire or attachments the rule asks for (the rule's questionnaire wins, since a Task asks for one; a code that is not LOINC's shape is dropped and logged). A rule that approves or denies is the payer's coverage policy and is not sent to the service. A failure, a timeout or an answer that is not one of the three decisions pends the item for a reviewer, with the reason in the server log: nothing here turns a failure into an approval. It cannot be combined with -pas-278-url, where the UM system answers every item.

Advice before submitting. With -crd-advisor-url beside -crd-rules, CRD also asks a decision service what a prior authorization request for each order needing one would be told as the record stands, and shows the answer as one more card: "Before you submit: a request for this would need: ...", or "would be approved", with what is still needed, the questionnaire that asks for it, and what would approve it. Vaglio answers at /api/pas/advise, with the same token and authority as above:

perfuse serve -fhir -pas -crd-rules payer-rules.yaml \
  -crd-advisor-url https://vaglio.example/api/pas/advise -crd-advisor-token-env VAGLIO_TOKEN

CRD sends POST <url> with {"service": {"system": "...", "code": "..."}, "resources": [ ... ]}, the resources being the hook's prefetch (the patient first, the coverage left out), and reads {"decides": true, "answer": "approve" | "pend" | "deny", "summary": "...", "missing": [...], "questionnaire": "...", "toApprove": [[...]], "policyTitle": "..."}. It is advice and changes nothing: the coverage-information, the other cards and the PAS decision are what the rules say. It waits at most three seconds, and no answer, a failure, or "decides": false leaves the response exactly as it is without it. Perfuse never needs a decision service.

The request carries X-PAS-Request-Id, the id the response is known by. A service with its own reviewers that pends an item can send their decision later as any reviewer's is sent: Claim/$decide with that id as claimResponse, the item's sequence, and the decision and reason. The provider's subscription delivers it as it would one made in the reviewer queue.

A subscription with id-only content tells the provider which answer changed without saying what it is: the notification's focus is Bundle/<id>. GET /fhir/Bundle/<id> returns the latest PAS Response Bundle, GET /fhir/Bundle/<id>/_history/<n> the version a notification sent, and GET /fhir/ClaimResponse/<id> the ClaimResponse alone. A token bound to one patient is told they do not exist, as for any record outside its patient.

Verified with the official Inferno PAS Server v2.2.1 suite (see verification). Not sent, though PAS marks them must-support: ClaimResponse.adjudication with a review action, ClaimResponse.extension:authorizedProvider and ClaimResponse.item.extension:communicatedDiagnosis, because the extensions they need are not allowed there by their own context in PAS 2.2.1 and the validator rejects a response carrying them; and request.extension:DataAbsentReason, because Perfuse always knows the request. The 278s sent to a utilization management system (above) are checked against PAS 2.2.1's own request examples, CMS's published esMD 278 samples and a 278 checker written from public companion guides, and every transport against a stand-in UM system written from CAQH's Connectivity Rules (see verification); not yet against a real UM system or clearinghouse, and not CORE certified. Not implemented: attachments sent back with CDex.

A rules file is checked against CRD's own invariants when it loads: a questionnaire needs documentation, a service that is not covered cannot need authorisation, satisfied belongs to one case and not a rule, and anything conditional must give a reason.

Not verified: the exports and member matching against another payer's implementation, the metrics against a payer's published figures, and CRD against a real EHR's CDS Hooks client.

16.11 Sending prior authorization requests to a payer (for providers)

Everything above answers requests, as a payer. A provider's side is the other way round: an EHR or a DTR app builds a Da Vinci PAS request Bundle, and something has to send it to the payer, keep the answer and pass it on. A pas destination does that.

name: prior-auth-out
dataType: raw
source:
  type: http
  http:
    listen: 127.0.0.1:8095
    path: /pas
destinations:
  - name: acme-health
    type: pas
    pas:
      payer: https://pas.acme-health.example/fhir
      bearer_token: ${ACME_PAS_TOKEN}     # or auth: { type: client_credentials, token_url, client_id, client_secret }
      results_to: pas-answers             # optional: a channel that takes each answer back to the EHR

Each message must be a whole PAS request Bundle on a raw channel. Perfuse posts it unchanged to {payer}/Claim/$submit: the payer decides on the Claim together with the patient, coverage and supporting resources in the Bundle, and a Claim rebuilt from a summary would lose them. Off this machine the payer's address must be https.

A decision is a delivered request, whatever it says. An approval, a denial and a pend are all recorded and none is retried, because retrying a denial submits the same request twice. What fails the delivery, and is retried, is a payer that did not decide: an error status, an OperationOutcome (its text is the error) or a ClaimResponse whose outcome is error. The decision is read item by item from the PAS review action codes (X12 306: A1 approved, A2 partly, A3 denied, A4 pended, A6 modified); a response with no code is listed as "no decision code" rather than taken as an approval. A denial with no reason anywhere is refused as not meeting CMS-0057.

The payer's answer is the destination's reply, so Inspect the reply can judge it, and results_to hands it to another channel. Every request is listed on CMS-0057, Requests sent to payers: when it went, the patient, the service, the decision and the payer's reference (preAuthRef), which a later inquiry names. The list is kept in prior-auth.json beside the database (at most 10,000 requests; the oldest decided ones go first, a pending one never does), and each tenant sees only its own.

Verified against the HL7 Da Vinci PAS payer reference implementation (docker image hlseven/davinci-prior-auth): a request sent through a running channel is pended by it with its reference, and the answer shows on the screen (see verification). Not yet tried against a production payer. Not built: following up a pended request with $inquire, or receiving the payer's later answer by subscription; a channel can do either today with an http or fhir destination.

16.12 CMS Aligned Networks

The CMS Interoperability Framework (CMS Health Technology Ecosystem) asks health data networks to self-attest to 26 criteria and be listed as CMS Aligned Networks; EHRs, providers, payers and apps connect to them. Criteria 13 to 16 have been in effect since 4 July 2026: FHIR APIs on US Core with a full CapabilityStatement and Bulk Data, documents as human-readable FHIR attachments, appointment and encounter notifications by FHIR Subscription, and a record locator.

Administer › CMS Aligned Network lists every criterion with what Perfuse provides for it and where this server stands, read from what is switched on here:

What the four in effect need from this server:

The screen is a worksheet for the attestation, not a certification: CMS reviews networks it suspects do not meet the criteria, and the framework's own text is the authority. Not built today: open quality gap queries (criterion 8), a payer's query for a claim's encounter data (9), reporting query metrics to the National Provider Directory (19), checking providers against that directory (6), reading mobile driver's licences or digital insurance cards (3, 23), and enforcing a general consent policy on every read (5). IAL2 identity proofing is the identity service's; Perfuse accepts the tokens of the one you choose.

17 Security

Perfuse handles clinical data. This chapter is what it does about that and what it leaves to you.

17.1 Transport security

TLS on the web interface is configured with -tls-cert and -tls-key. Without them the interface is plain HTTP, which is acceptable on a loopback address for a first look and nowhere else — it carries credentials and message content, both readable on the wire.

TLS on channel transports is per source and per destination, under a tls block. The available settings are in the source and destination references.

insecure_skip_verify accepts any certificate. It exists because hospital systems routinely present certificates that will not verify, and refusing to connect would mean refusing to integrate. It is named to be conspicuous, and using it means the connection is encrypted but not authenticated — you have protection against passive interception and none against an interposed server.

17.2 Authentication and roles

Users are held in the database. Each has one of five roles, and each role includes everything in the ones above it:

A sixth role, Platform, belongs to whoever runs a shared server: it creates tenants and sets their limits, and holds no channels of its own.

Monitor is for a help desk, or for an operations screen on a wall: everything needed to see that a feed has stopped, and nothing that names a patient. Viewer can read message content, which is clinical data; it is a low-privilege role for *configuration*, not for privacy. Operator separates fixing a failed delivery at night from changing what a feed does: the person who resends need not be able to rewrite the channel.

17.2.1 Repeated wrong passwords

Wrong passwords and failed passkey sign-ins are counted by the address the connection comes from, and after a few in a row that address waits before it may try again (the answer is 429, with Retry-After). Accounts are not locked by name, because that would let anybody lock out an administrator on purpose.

The address is the connection's own, never one a request claims in X-Forwarded-For, which the sender writes. Behind a reverse proxy on the same machine Perfuse uses the last X-Forwarded-For entry instead, the one the proxy added, so each client is still counted apart. A proxy on another machine reaches Perfuse from one address, and all its clients share one count: rate-limit sign-ins at that proxy as well.

17.2.2 Channel groups

A person (or an API token) can be limited to some channel groups: they then see and act on only the channels whose group is one of theirs. This is the arrangement of a hospital group on one server, each facility's analysts looking after their own feeds and a central team, with no limit, looking after all of them. Rhapsody calls it a locker.

The limit applies everywhere at once, because it is applied to the request rather than remembered by each screen: the channel list, the dashboard and flow map, messages and their search, counts and charts, the queue, alerts, metrics, certificates, contracts and code-set use. A channel outside the person's groups does not exist for them; asking for it by name answers *not found*, so its name is not confirmed either. A channel with no group is seen only by people with no limit.

Saving a channel keeps it inside the person's groups: they cannot create a channel in another group, or move one out of their own. What every facility shares - code tables, script libraries, prior-authorisation decisions - they can read but not change. Server-wide figures (prior authorisation, token use, tunnels) are shown only to people with no limit, and so are metrics and alerts about the whole server rather than a channel.

An administrator limited to groups is a facility's own administrator. They manage the people and tokens of their groups, start and stop their channels and clear their queues. A colleague they add gets their groups unless they name some of them, they cannot give a group they do not have, and they never see or change anybody with no limit. Everything else an administrator can do changes the whole server - settings, sign-on, restarting, alert rules, branding, fleet, the SMART server - and is refused to them.

Groups are set in Users (and for tokens in Tokens), as a comma-separated list. Each change is recorded in the activity log and takes effect at the person's next request.

A different role in each group

A person can hold a different role in each of their groups: lab=editor, adt in Users edits the lab's channels and has the role chosen beside it - say viewer - in the admissions ones. They see both groups' channels on every screen. Saving, starting or resending one in a group where their role is too low is refused with the role they hold there; it does not pretend the channel is missing, since they can see it. Their role at the top of the screen is the strongest they hold, which opens the screens that role uses, and every action on those screens is still narrowed to the groups where they hold it.

Only people limited to channel groups can have one. Somebody who sees every channel has one role, because "editor of the lab's channels" for a person with no limit would be editor of everything that belongs to no group, and of the server-wide pages. A facility's administrator can give a role per group only in the groups they administer, and never above their own role there.

17.3 Who may call the FHIR endpoint

The FHIR endpoint (serve -fhir) checks one of two kinds of token:

• Perfuse API tokens, made under Users → Machine credentials or with perfuse token create. Each carries a role, and can be

limited to FHIR Groups. This is the default when no SMART authorization server is configured.

• SMART access tokens, from Perfuse's own authorization server (-smart-clients) or an outside one (-smart-issuer). Each

carries scopes, and the endpoint holds every request to them.

With SMART configured, only SMART tokens are accepted, so every caller is held to its scopes. An API token has a role and no scopes: a viewer token can read every patient's record. A payer who turned SMART on to limit each app to what it was granted should not have a way in that is not limited.

Some sites need both all the same - an internal claims feed that holds an API token and has no SMART client, beside member apps that sign in through SMART. For those, Settings → FHIR → Accept Perfuse API tokens beside SMART tokens (-fhir-api-tokens at start-up) lets API tokens in as well. It is off by default, it takes effect on the next request in either direction, and changing it is written to the audit log. A token is told apart by its shape: a SMART token is a signed JWT, and an API token never is, so one is never checked as the other. Where you can, give such a system a SMART Backend Services client instead, with only the system scopes it needs.

17.3.1 A FHIR endpoint open to strangers

A public test server gives out credentials that can write, because testing prior authorization or subscriptions needs writes. Two limits keep one client from spoiling it for everybody, both under Settings → FHIR and both off by default:

• Writes a minute from one client (-fhir-writes-per-minute): creates, updates and deletes from one client address. Over it, a

write is answered 429 with Retry-After: 60. Reads and searches, including searches by POST, are never counted.

• Most resources held (-fhir-max-resources): past it, new resources are refused with 507, while updates and deletes still work.

A hospital's own endpoint needs neither.

17.4 AI agents: the MCP server

With Settings › Security › AI agents (MCP) on (or serve -mcp), Perfuse serves the Model Context Protocol at /mcp, so an AI agent such as Claude, ChatGPT or an IDE assistant can ask it what is happening. It is off by default, and switching it off stops every agent on its next call.

An agent connects with an API token from Administer › Users › Machine credentials as a bearer token, never with a person's browser session (that is refused, so an agent is never acting with a person's full access). A client configuration looks like:

{ "mcpServers": { "perfuse": { "type": "http", "url": "https://perfuse.example/mcp",
    "headers": { "Authorization": "Bearer <token>" } } } }

Every tool is answered by the same route or FHIR search a person's screen uses, called with the agent's own token, so the token's role, channel groups and tenant decide what it sees, exactly as they do in the console; and fhir_search gets the token's own access on the FHIR endpoint (which may refuse API tokens altogether; see the FHIR section above). An agent is offered only the tools its token may use. Reading is the default: a tool that changes something also needs the token's mcp:write scope ("Let an AI agent act with it" when issuing the token), so a token issued for a reporting agent cannot be talked into acting by a prompt. A monitor token's answers have message contents removed, whatever a route returns.

Every call is in Activity as mcp.tool with the token's name, the tool, its arguments and the outcome (ok, refused, invalid, rate-limited or the HTTP status); mcp.connect records which client connected. Each token may make 60 tool calls a minute (Tool calls a minute from one token); over that, a call is answered with an error the agent can read, and nothing is done. A request from a browser page on another origin is refused, which MCP asks of a server to stop DNS rebinding. The transport is MCP's Streamable HTTP, answered as JSON with no event stream; protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are accepted. Messages and FHIR resources hold patient data: an agent's answers go to whatever model it runs on, so give a token to an agent only where that model is allowed to see them, and give it the lowest role that does the job.

17.5 A demonstration account

serve -demo-account demo:PASSWORD creates a shared account for a public demonstration server, and the sign-in page shows its username and password with a button that signs in with them. The account is a viewer, so it can look at everything and change nothing. Unlike any other viewer it may also open the administrators' screens (users, machine tokens, settings, data protection, the fleet's peers), read-only: a demonstration is judged by its screens. It reads them as a viewer reads channels, with every credential shown as set or not, never its value, and every change refused. It may also press the checks that change nothing and reach nothing outside the server: a script's Check, and the channel editor's validate and parse. It cannot change its password or add a passkey, because the first visitor to do either would lock out everyone after them. Each start puts it back as a viewer with the published password. The password must be at least 12 characters, like any other. Only use it on a server holding test data: anyone who reads the sign-in page can read every message on the server.

17.6 Audit

Configuration changes, logins, and access to message content are recorded with who, what and when.

The audit log is in the same database as the messages. That is convenient and it is a limitation: somebody who can modify the database can modify the audit log. If your requirements include tamper-evident audit, the log needs shipping somewhere append-only, and Perfuse's own log output is the way to do that.

17.7 Secrets in configuration

Passwords, passcodes and keys appear in channel configuration, which means they are in the YAML files.

Two consequences. The files need filesystem permissions that reflect what they contain, and if they are in version control — which is otherwise recommended — the repository holds credentials and must be treated accordingly.

Where a value is a secret, the interface renders it as a secret and the API does not return it once saved. That protects it from being read over somebody's shoulder or leaked in a screenshot. It does not protect the file.

17.8 What is in the database

The message store holds messages as received, which for a clinical feed means patient-identifiable data. It should be on encrypted storage, backed up as clinical data with the retention that implies, and access-controlled at the filesystem level as well as through Perfuse's own roles.

cleanup.periodDays limits how long it is kept. See the message store for the tension between that and having enough history for rhythm-aware alerting.

17.9 Data protection (GDPR and UK GDPR)

The Data protection screen (Administer, administrators only) answers a person's requests under the GDPR and the UK GDPR. It decides nothing on the controller's behalf: whether a request must be granted, and whether an exemption applies, is the controller's decision, recorded with the request.

Finding what is held. A person is named by identifiers: system|value (an NHS number, an MRN with its assigning authority) or a number on its own. With a patient index, those widen to every number of every record linked to the same person, so a request quoting one hospital number finds the records filed under the others. See what is held then searches every store that keeps patient data:

What it cannot reach it says: traces sent to a collector (-trace-endpoint), the audit log (kept: it is the record of who did what, this request included), and backups.

Requests. A request is recorded with its kind (access, Article 15; portability, Article 20; erasure, Article 17; restriction, Article 18), who it is from as the controller's records refer to them, the identifiers, and a note (how the identity was confirmed, an extension and its reason). It is due one month after receipt (Article 12(3)); an overdue one is shown in red.

• Access and portability: Download the copy gives a zip: every message as

received with its record, every FHIR resource with every stored version, prior authorization requests and their answers, and the patient index's records, JSON throughout, with a README saying what each part is. Mark answered closes it.

• Erasure: a second administrator approves it (whoever recorded it cannot).

Erase now deletes everything found: messages whole (record, body, deliveries, identifiers, attachments no other message uses), queued deliveries (they are not sent), the FHIR resources with their history, prior authorization requests with their answers, attachments and tracking numbers, and the person in the patient index with every linked record and its history (one event records that an erasure happened, and by whom).

• Restriction: recorded as a legal hold, so nothing is erased or expires while

it lasts.

• Refuse closes a request with its reason, which the person must be told.

A closed request keeps only the last characters of the person's numbers: it stays as the record of an answer without being another copy of them. Every step is in the audit log with the numbers masked.

Legal holds. A hold names a person by identifiers, with its reason and an optional end date. While it is in force an erasure is refused outright, and the message store's retention window spares the person's messages (records and bodies) until the hold is lifted.

Backups and the erasure ledger. A backup made before an erasure still holds what was erased until it expires. Every erasure is written to a ledger: when, by whom, approved by whom, how much went from each store, and the person's identifiers as salted SHA-256 hashes rather than in clear. After restoring a backup, Apply erasures again hashes the identifiers the restored stores hold with each entry's salt and erases every person the ledger names. Short numbers can be found from their hashes by trying every value, so the ledger is itself personal data and is kept with the database's own protection.

Retention. The screen lists how long each kind of record is kept here and what changes it: message records and bodies by their retention windows, the queue until delivered or removed, the FHIR store, prior authorization requests and the patient index until erased (clinical records are not deleted on a schedule), the audit log kept.

Record of processing (Article 30). Record of processing downloads, as Markdown or CSV, what this server knows of it: the controller, the data protection officer and where the data is kept (Settings → Data → Data protection), the retention of each kind of record, and one processing activity per channel with what it receives, from where, to which destinations, and the hosts it sends to. The purposes, lawful bases and categories of data subject are left for the controller to fill in, and say so. A CSV cell beginning with =, +, - or @ is written with a leading apostrophe, so a spreadsheet does not run it.

Where the data is kept. Where the data is kept (Settings → Data → Data protection) states, in words a regulator can check, where the server, its database and its backups run; the Data protection screen and the record show it. A draft data processing agreement for organisations BioDream hosts is in docs/legal/dpa-template.md; it is a draft for a lawyer, not legal advice.

The API is /api/privacy (summary), /api/privacy/find, /api/privacy/requests (and /{id}/approve, /{id}/export, /{id}/erase, /{id}/close), /api/privacy/holds, /api/privacy/reapply and /api/privacy/register.

17.10 Tenants

A tenant is an isolation boundary: channels, messages, users and settings belong to one, and nothing crosses.

This exists for a service provider running feeds for several practices. Do not use it to separate departments within one organisation that need to see each other's traffic: the isolation is real and there is no cross-tenant view. For that, use channel groups (above), which divide the people of one organisation while letting a central team see everything.

17.10.1 Limits

A platform operator sets each tenant's limits in Tenants, so one customer cannot crowd out the rest of a shared server. Leave a limit empty for none.

• Channels: how many channels the tenant may have. Creating one more is refused, with the count and the limit.
• Messages a minute: how many messages its channels together may receive in a minute.
• Storage: how much stored message content it may keep, in megabytes.

None of them loses a message. Over the rate or the storage limit, a received message is refused the way a busy receiver refuses one, before anything is stored or delivered: MLLP gets no acknowledgement (not a rejection, which some senders take as "do not resend"), HTTP gets 429 with Retry-After, SOAP gets 503, DICOM gets a retryable status, and a queue, bucket or file is left where it was. The sender resends, as every interface engine and EHR does. Nothing already stored is deleted to make room. A raised limit takes effect within a minute, and every change of limits is recorded in the activity log.

17.11 Test data

The generated messages described in testing exist partly as a privacy control. Reproducing a problem elsewhere, sending an example to a vendor, or populating a test environment are all things that otherwise get done with real messages.

The generator's output contains no patient data by construction rather than by redaction. Prefer it to hand-stripped real messages, which is a process that can be done incompletely and usually is.

17.12 Single sign-on

Three mechanisms, and local accounts alongside all of them.

OpenID Connect (-oidc), a directory over LDAP (-ldap), and SAML 2.0 (-saml). Each is configured from Administer → Sign-on and written to the file the flag names, so the screen and the file are two views of one thing rather than two places to keep in step.

Local accounts are always available and cannot be turned off. That is deliberate: an on-premises integration engine whose only way in is an identity provider becomes unreachable exactly when the identity provider is unreachable, and a clinical interface is not a good place to learn that. The sign-on screen tells you how many local administrators exist before it encourages you to depend on anything else.

17.12.1 What a group mapping decides

All three map groups from the directory to Perfuse roles, and somebody in groups matching more than one gets the most privileged. That is the only safe direction to resolve it — the alternative is a person losing access they are entitled to because they are also in a lesser group.

Any of the six roles can be granted: monitor, viewer, operator, editor, admin and platform.

A group can also be limited to some channel groups, in the second box of its row (channel_groups in the file). Once any group names one, every sign-in sets the person's channel groups from the groups that granted their role: somebody in a group that edits the lab's channels and in another that views every channel is an editor of the lab's channels and nothing else. The strongest role is never joined to the widest reach, because neither group grants that. A group with an empty box gives every channel. While no group names any, sign-in leaves channel groups as an administrator set them in Users.

When every group a person matches names channel groups, each channel group gets the strongest role among the groups that name it: with Lab-Interfaces (editor, lab) and Clinical-IT (viewer, lab and adt), the person edits the lab's channels and views the admissions ones, as if set by hand. When one of their groups gives every channel, there is no list to hold a role per group, and the rule above applies.

roles:
  editor: [Lab-Interfaces]
  operator: [Night-Desk]
  viewer: [Clinical-IT]
  channel_groups:
    Lab-Interfaces: [lab, pathology]
    Night-Desk: [adt]

That is the OpenID Connect and SAML file. The directory's file maps each group to one role (roles: {Lab-Interfaces: editor}), and channel_groups sits beside roles there.

A mapping that grants nobody anything is refused rather than saved. A configuration that authenticates people and turns all of them away looks identical to a broken product from the outside: the round trip completes and everybody is denied with nothing explaining why.

Creating an account on first sign-in is off by default. With it off, somebody has to exist in Perfuse before they can sign in, so the directory decides who they are and Perfuse decides who is allowed in.

17.12.2 SAML, specifically

The parts worth knowing before you configure it:

• Only the certificate you configure is trusted. A certificate carried inside a response is never used. An attacker who can send a document can also put their own certificate in it, and a verifier that reads it is one anybody can authenticate to as anybody.
• A response has to answer a sign-in this server started. Perfuse remembers the request it sent and refuses a response naming anything else, or naming a request it has already answered. Without that check a valid response is a bearer token for whoever holds it: somebody signs in as themselves, keeps the response, and posts it into your browser, and you are then inside their account with the audit log recording their name.
• Sign-ins started at the identity provider are therefore off by default. Turn on *Accept sign-ins started at the identity provider* only if you need a portal tile, and knowing that it is what makes the above possible.
• The group attribute has no default and is required. Entra sends groups, Okta sends whatever the application was configured with, ADFS sends a claim URI. A guess would produce a sign-in that works and grants nobody anything. If a sign-in is refused for having no role, the server log names the attributes that did arrive — which is usually the whole answer.
• The reply URL must match exactly what is registered at the provider. A response says where it was destined and one addressed elsewhere is refused, because accepting it would mean accepting a response meant for a different service.

17.12.3 What each provider sends

The group attribute is where sign-ins go wrong, and the three common providers each name it differently.

A claim URI may be entered by its final segment: typing groups finds http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. A name that merely ends with the word does not match — excluded_groups is not groups.

Group membership arriving as one comma-separated value is treated as a single group name and matches nothing. That is the correct reading of the standard, and splitting on commas would mean a group legitimately containing one silently became two. If that is what your provider sends, change it there.

Test on the sign-on screen checks everything that can be checked without a person: the settings, the certificate, and whether a sign-in request can be built. It says plainly that it cannot prove somebody can sign in, because that needs a real assertion about a real person and the only way to get one is for them to try.

17.13 Accounts provisioned by the identity provider: SCIM

With -scim (Settings → Sign-in → Automatic accounts), an identity provider such as Okta, Microsoft Entra ID or Google Workspace creates, updates and removes Perfuse accounts itself at /scim/v2/Users, so a person who leaves the organisation loses access when their directory account is disabled, not when somebody remembers. The provider authenticates with an API token holding the admin role, made under Users → Machine credentials, sent as a bearer token.

• Disabling an account ends its sessions at once, and the server checks that none survived before answering. A provider is

never told an account was disabled when it was not, because a provider does not retry what it was told succeeded.

• A delete disables first, then deletes, so a failure half way leaves an account nobody can sign in with. The audit history of

a removed account is kept.

• The role comes from the person's groups or roles, matched by name: a group whose name contains *admin*, *editor*, *operator*,

*viewer* (or *read-only*) or *monitor* gives that role, so APP-Perfuse-Editor and Perfuse Operators work as they are named. Anything else gets -scim-default-role, viewer unless set otherwise. Platform can never be granted this way.

• No passwords. An account made by SCIM signs in through the identity provider; a second password nobody upstream knows about

would survive a disable there.

• /scim/v2/ServiceProviderConfig says what is supported: create, read, replace, patch and delete of Users, and filters up to 200

results. Bulk operations, sorting and ETags are not.

17.14 What Perfuse does not do

It does not encrypt the database at rest. Use filesystem or volume encryption.

It does not manage its own certificates or renew them. Point it at files and manage those files with whatever you already use.

SAML has been verified against two independent providers, each with a real browser sign-in, a real assertion and a real session: Keycloak 26 and Microsoft Entra. Two matters more than twice as much as one, because the two disagree in a way that turned out to be load-bearing — Keycloak writes its assertion with namespace prefixes and Entra writes the same elements without them, and the one defect this area has had was in prefix handling.

Start by reading your provider's metadata. Settings, then Sign-on, then the SAML tab: give the metadata URL or paste the document, and the sign-on address and signing certificate are filled in for you. Every SAML provider publishes one of these — Okta, Entra, AWS IAM Identity Center, Keycloak, ADFS — and it is the difference between configuring a provider and transcribing one. Doing it by hand means finding the certificate inside the XML, stripping the line breaks out of the base64 and wrapping it in PEM headers, where a single stray space produces a signature error that says nothing about formatting.

What comes back is described rather than dumped: each certificate's subject, expiry and SHA-256 fingerprint, so you can check it against what your provider's own console shows. An expired certificate is called expired rather than left as a date to compare by eye. Nothing is saved by reading — applying it to the form is a separate click, because a document somebody pasted is not yet a decision about what to trust.

A metadata URL is fetched over https only, and the address is checked against the same policy that governs channel destinations, so this cannot be used to make the server read cloud instance credentials. Redirects are not followed, because a permitted address redirecting to a blocked one would walk straight past that check.

If you are configuring Entra, five things will not match what the examples show you. It sends no email claim at all. Its NameID is an opaque identifier rather than an address. It sends no groups claim unless the application is explicitly configured to emit one, so a role mapping written against groups refuses every sign-in. When groups are emitted they are object GUIDs rather than names, unless your tenant synchronises from on-premises Active Directory. And its claim names live under schemas.microsoft.com/identity where most documentation shows schemas.xmlsoap.org. Perfuse handles all five; they are listed because the first four will otherwise look like faults in Perfuse when they are Entra being Entra.

That distinction is not theoretical here. The first genuine Keycloak assertion failed outright, because the canonical form the signature covers was being computed with namespace prefixes dropped. No real identity provider could have signed anybody in, and the package's own five canonicalisation tests passed throughout — each of them signed and verified with the same code, so they proved only that it agreed with itself. If you are the first to point a different provider at this, expect to find something, and the server log will name the stage that failed.

18 Operations

18.1 Deployment

One binary and two paths: a directory of channel files and a database file. There is no application server, no separate web tier and no message broker required.

perfuse serve -channels ./channels -db ./perfuse.db -addr 0.0.0.0:8443 \
  -tls-cert ./cert.pem -tls-key ./key.pem

Run it under whatever supervises services on the host — systemd, launchd, a container runtime. It expects to be restarted if it exits.

18.2 Where data may go (data residency)

serve -residency (Settings → Data → Where data may go) names the cloud regions this server's data may be sent to or read from: areas (eea, uk, ch) and region codes (eu-central-1, uksouth, europe-west2), comma-separated. eea is the AWS, Azure and Google Cloud regions in the European Economic Area (Frankfurt, Ireland, Paris, Stockholm, Milan, Spain; Netherlands, Germany, France, Sweden, Norway, Italy, Poland, Spain; Belgium, Netherlands, Germany, Italy, France, Finland, Spain, Poland), uk those in the United Kingdom, ch those in Switzerland.

With it set, a channel is refused, when it is saved and when it is loaded, if a connector names a region outside the list: an S3, SQS or SNS source or destination's region (or its endpoint, when that is an AWS hostname), or any destination whose address is an AWS hostname carrying a region (sqs.us-east-1.amazonaws.com, an API Gateway URL). The server refuses to start with a trace collector or alert webhook in another region. A connector pointed at a host that names no region (a hospital's own system, MinIO on the site's network) is not judged: the record of processing on the Data protection screen lists every host each channel sends to, for the controller to check. The dashboard and the Data protection screen say where data may go.

Hosting in the EU and the UK. deploy/hosted holds OpenTofu (or Terraform) for one hosted server per organisation in Frankfurt, Ireland or London: the server, its PostgreSQL database and backups, a backup bucket, logs and support-session records, all encrypted with a key in the Region, nothing replicated to another Region, support through Session Manager only, and Perfuse run with -residency. Its README says what it builds, what it does not cover, what has been verified (validated, and planned against a real account; not yet applied) and what it costs at list price in each Region.

18.3 Configuration as files

Channels are files, which means they can be in version control, reviewed before deployment, and diffed after an incident.

Files are re-read without a restart. A file that does not parse is reported and the previously loaded version keeps running, so a syntax error cannot take a working feed off the air.

18.4 Backup

Two things to back up, and they have different characteristics.

The channel directory is small, changes rarely, and is what you need to rebuild the service. Back it up as configuration; version control is usually sufficient.

The database holds messages, users and audit history. It is large, changes constantly, and contains clinical data — so it needs backing up as clinical data, with the retention and encryption that implies. Losing it does not stop the service, but it loses the ability to investigate anything that already happened and the history the rhythm learner depends on.

18.5 Restart behaviour

On restart, channels are loaded and sources begin listening. Queued deliveries resume.

The thing to understand is what happens to work in flight. Under the default on_delivery acknowledgement, a message that had not yet been acknowledged is not acknowledged, so the sender will resend it — which is the correct outcome. Under on_receipt, a message that was acknowledged but not yet delivered is in the queue, and resumes; if the queue is disabled, it is lost. See message flow.

18.6 Upgrading

Replace the binary and restart. The database schema is migrated forward automatically on start.

Migrations are forward-only. There is no downgrade, so a rollback to a previous binary after the schema has moved needs the previous database. Take a copy before upgrading — this is the one operational precaution worth being disciplined about.

18.7 Monitoring

Alerting from within Perfuse is covered in alerting and is what will tell you a feed has stopped.

From outside, monitor the process, the disk the database is on, and whether the web interface responds. The database grows and a full disk stops message recording, which is a failure mode with no other warning.

18.7.1 SNMP

For monitoring tools that speak SNMP (Nagios, Zabbix, PRTG, SolarWinds, LibreNMS), Perfuse runs a read-only SNMPv2c agent and sends a trap when an alert fires or resolves. Set it under Settings → Monitoring → SNMP, or with flags:

perfuse serve -snmp-listen :161 -snmp-community 'long-random-community' -snmp-allow 10.0.5.0/24 \
  -snmp-traps nms.example.org,10.0.5.9:1162

• The agent answers GET, GETNEXT and GETBULK, and only from the networks in -snmp-allow: v2c's community is a password sent in

clear, so it is never open to everyone. A community under 6 characters, or public/private, stops the server at startup.

• It serves the system group (sysDescr, sysUpTime, sysName from the fleet label, sysContact, sysLocation), totals under

BASE.1 (channels, running, broken, received, delivered, failed, queued) and a channel table under BASE.2.1 (name, running or stopped, received, delivered, failed, queued, age of the oldest queued message). The numbers are the ones the dashboard and /metrics show.

• Traps go to every manager in -snmp-traps: BASE.0.1 an alert fired, BASE.0.2 it resolved, carrying the alert's kind,

severity, channel, destination and summary. Never message content. An acknowledged alert sends no trap.

• BASE is 1.3.6.1.4.1.8072.9999.9999.16 (Net-SNMP's experimental space) unless -snmp-base-oid puts it under your own

enterprise number. Download the MIB on the Settings page (or GET /api/snmp/mib) gives a MIB for the base in use; the same panel says whether the agent is answering and how many traps went.

18.7.2 An inventory of every interface

-inventory interfaces.md (Settings → Monitoring → Inventory) writes a Markdown document listing every channel - its format, whether it runs, what it receives from and what it sends to - followed by each channel's own description, and rewrites it every -inventory-every (a day by default). It is meant to be committed beside the channel files, or handed to an auditor, and read without the application running.

18.8 Capacity

Perfuse's throughput ceiling has not been measured on real hardware under real traffic, and this manual will not print a number it cannot support.

What can be said: the architecture is one goroutine per connection with per-destination queues, so throughput scales with destinations rather than being serialised through one worker; message recording is a SQLite write per message, which makes the disk the most likely first constraint; and the message store grows linearly with traffic, so retention is the setting that governs long-term disk use.

If you are sizing this for a large feed, measure it with your own traffic using the generated test corpus described in testing. That is the honest answer, and it is also a better answer than a number from somebody else's hardware.

18.9 Where this installation got stuck

Activity carries a panel, visible to administrators, showing what Perfuse has refused to do — grouped by message, most frequent first — and how far the installation has got towards a working channel.

It exists because every other claim about whether this software is easy to use comes from the people who wrote it. A refusal does not: somebody wanted something, the server said no, and neither party was guessing. It is the only evidence in the product that does not come from BioDream LLC.

The funnel names the step that has not happened yet rather than leaving timestamps to compare. The state worth watching for is messages arrive and none has been delivered to a destination — a channel can take traffic for weeks and deliver none of it, and from every other screen that looks like it is working.

Nothing anybody typed is recorded. The table holds the request route with identifiers replaced by {id}, the status, and the server's own sentence. A validation message names a field and a rule, which is the useful part; the value that broke the rule is very often patient data, and a table of those would be a worse liability than the friction it measured.

Two deliberate exclusions. A 5xx is a fault in this software and is logged as one already — mixing the two would bury the cases where somebody could not work out what to type under the cases where nothing they typed would have helped. And an expired session produces a run of 401s that say nothing about usability and would drown every finding that does.

Reading the report also trims the table to its most recent five thousand rows. Refusals are 4xx responses so it grows slowly, and reading is a natural moment to tidy: no timer and nothing that runs when nobody is looking.

GET /api/friction returns the same thing for anyone who would rather read it as JSON.

18.10 Logs

Perfuse logs to standard output, which is where a supervisor or container runtime will collect it.

Message-level detail goes to the message store rather than the log, deliberately. A log line per message on a busy feed is noise that hides the lines that matter, and the store is searchable in ways a log file is not.

The log carries what the store cannot: startup and shutdown, configuration load results, channel state changes, and errors that are not attributable to a specific message.

18.11 Running two instances

Two or more servers can run as one cluster: when the one running a feed stops, another takes it over within a few seconds, and the sender's next attempt reaches it. They share one PostgreSQL database instead of each keeping a SQLite file, and agree between them, through it, which of them runs what.

perfuse serve -db 'postgres://perfuse:SECRET@db.hospital.internal/perfuse?sslmode=verify-full' \
  -cluster active-passive -node-name perfuse-01 -node-address https://perfuse-01.hospital.internal:8443 \
  -data /var/lib/perfuse

Start each server the same way with its own name and address. The database account needs to create tables and, once, the citext extension (or an administrator runs CREATE EXTENSION citext first). Each server keeps its own files in -data: its log, its node id, and its copies of the configuration.

Two ways of sharing the work.

• active-passive: the leader runs every channel and every job that must run once (FHIR subscription notifications). The

others wait. The simplest to reason about, and what a site with one busy server and a standby wants.

• active-active: the channels are spread over the live servers, about evenly. A server that stops hands its channels

to the rest; one that joins takes its share as channels come free, one at a time. Channels that route to one another (a channel destination) run on one server and move together, because routing happens inside a server. An administrator can move a channel by hand from Monitor → Fleet; it stays where it was put while that server lives.

Who runs what, and no moment with two. Each piece of work is a lease in the database, renewed every fifth of -cluster-lease (15 s by default). A server that cannot renew it (it crashed, its network failed, the database is unreachable) stops that work by itself once its own clock says the lease is nearly done, with a third of the lease to spare. Another server takes the lease only after its own clock has watched the lease's counter stand still for a whole lease. No clock is compared with another, so the servers' clocks and the database's need not agree; they need only run at about the same rate, which every clock does. Between the old holder stopping and the new one starting there is a short gap with nobody listening, which a sender sees as a refused connection and retries; there is never a moment with two listening on one feed or two workers draining one queue.

A server shutting down cleanly, or an administrator choosing Step down on the leader, hands over at once rather than after the lease.

What every server shares. Messages, the delivery queue, accounts and sessions, the audit log, the FHIR store, the terminology tables and the patient index are in the database, so whichever server runs a channel finds the queue the last one left. The channel files, the settings file, the alert rules, single sign-on files, the logo, Direct certificates and saved views are kept the same on every server through the database: each keeps its own copy on its own disk, a change on any server (in the console, by hand, by a git pull) reaches the others within two seconds, and a channel changed on another server restarts with its new file. The same file changed on two servers at once keeps the version that reached the database first, and the other beside it as NAME.conflict-SERVER. Settings that apply only at a restart (the message database, the ports the console listens on) are applied by each server at its next restart, and the log says so. What names something on one machine stays on that server's command line and out of the shared file: the certificate and key (-tls-cert, -tls-key), the SNMP listening address and the server's name in traces. Settings shows them as set on each server.

Start and stop. Starting or stopping a channel on any server applies to the cluster: the server that runs it starts or stops it within a second, and the answer says which server that is.

The load balancer in front. A feed's address must reach whichever server runs it. Point the sender at a virtual address (a load balancer, a floating IP, a DNS name with a short TTL) and have the load balancer check /readyz?channel=NAME, which answers 200 only on the server running that channel, and 503 on the others. For the console, /readyz is 200 on every live server; /readyz?role=leader only on the leader.

On an AWS Network Load Balancer, use a target group per feed with an HTTPS health check on /readyz?channel=NAME, a 5-second interval and a threshold of 2, and turn cross-zone load balancing on. With it off, the load balancer's node in a zone where no server runs the feed sees only unhealthy targets, sends to all of them anyway, and a sender that resolved to that node waits until the feed comes back to its zone (95 seconds in a test). Set the deregistration delay to 0, since a server that stops running a feed has nothing to drain.

What was tested. Two servers on PostgreSQL 16, a sender streaming 300 messages, resending until answered, and the server running the feed killed with SIGKILL twice (the first, then the second after the first came back). Every acknowledged message reached the receiver, in both shapes tried: delivered before the acknowledgement, and queued in the shared store while the receiver refused (185 acknowledged messages waited in the queue at the kill; the survivor delivered them all). Failover took 3 to 4 seconds on a 3-second lease. A duplicate is possible and was seen once in 600: a message the dying server delivered and could not acknowledge, which the sender resent. The coordinator's own tests cover a crash, a server cut off from the database while it runs on, step-down, spreading, moves, and shared configuration with conflicts. They run in CI against PostgreSQL with the race detector, with the whole suite.

The same was then done on AWS: two Linux servers (ARM) and one Windows Server 2022 in three availability zones, Amazon RDS PostgreSQL 16 over TLS with the certificate checked (sslmode=verify-full), an internal Network Load Balancer in front, and senders resending until answered:

With the default 15-second lease, a server cut off from the database stopped its feed 10 seconds after its last renewal, and the next server started it 6 to 8 seconds after that: never both at once. The skewed clocks changed nothing, since no clock is compared with another.

Not yet. A cluster serves one organisation: -cluster with -multi-tenant is refused. Listeners move with their channel, so the load balancer is the site's to provide.

A server on its own keeps working as it always has, on SQLite, with no cluster at all.

18.12 More than one server

A site with two instances has a question no single console can answer: is everything running? Mirth charges for the answer. This is the fleet view.

One instance is nominated as the place you look. It polls the others and shows every channel on every server in one table, with a rollup across all of them.

18.12.1 Adding a peer

Settings → Fleet, or PUT /api/fleet/peers. A peer needs a name, a URL, and a token issued by the peer itself.

The name is required and is not the URL, because a URL is not something anybody recognises at three in the morning.

The token must be created on the peer, under Users, and should be viewer-scoped. Adding a peer without one is refused, with those instructions, rather than accepted and then failing quietly on every poll. Reading another instance's health is the smallest privilege there is, and it is the only one the fleet view needs.

18.12.2 Controlling a peer, which is off

allow_control permits starting and stopping that peer's channels from here. It is off by default and every use is audited by name.

The two privileges are deliberately separate. Reading another server's health is minor; stopping its channels during a transfusion is not, and the second should never arrive silently attached to the first.

18.12.3 What the report says

Each server reports the total number of channels, how many are running, stopped or errored, the queue depth and the age of the oldest waiting message, how many alerts are firing, and whether it is draining for shutdown.

The rollup counts servers three ways: reachable, unreachable and undetermined. The third covers peers whose health nobody knows — not yet polled, refusing the token, or running a version this one cannot read. It is kept apart from unreachable because "we cannot tell" is not "it is down", and folding the two together is how a fleet page starts lying.

For the same reason the rollup carries knownFrom: how many instances the channel and queue figures were actually read from. Twelve channels running across a fleet means something different when two of five servers did not answer, and the total alone cannot say so.

An unreachable peer says why in terms an operator can act on. A refused connection is reported as the host being up with nothing listening on that port, which is a different problem from a host that does not answer at all.

18.12.4 Clock skew

The rollup reports the largest difference between the clocks of the servers in it. Worth a number of its own: correlating an incident across two instances whose clocks disagree by four minutes produces a sequence of events that did not happen.

18.12.5 What a peer learns about you

Counts and rates. The report one instance gives another carries no message identifiers, no channel-level detail and no patient data of any kind.

That is what stops a fleet view being a centralisation of clinical data: the aggregating instance learns how many channels are running and nothing whatsoever about what flowed through them. If you want the messages you open that server's own console, where the audit log records that you did.

18.12.6 A peer pointed at itself

Refused. An instance polling its own address through its own HTTP stack appears twice in its own fleet view and double-counts every channel it has.

18.12.7 TLS on internal networks

insecure_skip_verify accepts a peer's certificate without verifying it. It exists because hospital infrastructure runs on private certificate authorities, and refusing to work at all would push people onto plain HTTP, which is worse. It is named so it cannot be mistaken for a good idea.

19 The Command Line

Everything Perfuse does to a running system is reachable from the web interface, and that is deliberate: a feature that needs a terminal is treated as a defect rather than a design choice. The commands here are for the work that happens *around* a running system — before it exists, while you are deciding whether to trust it, and when you need to hand something to somebody else.

Several of them never touch a server at all. perfuse explain, perfuse profile, perfuse deident and perfuse translate read files and write files, so they are useful on a laptop against an estate that still runs entirely on something else.

Run any command with -h for its flags. This chapter says what each one is *for*.

19.1 Running channels

19.1.1 perfuse serve

Runs the web interface and the API, and by default runs the channels too. This is the command an installation uses.

Every option it takes is listed in Server Options, generated from the program. It refuses to serve plain HTTP to anything except loopback unless you pass -insecure. That is not configurable politeness: clinical traffic and a session cookie over an unencrypted LAN connection is a reportable event, and the flag exists so that saying yes is a decision somebody made rather than a default they inherited. See security.

19.1.2 perfuse run

Runs channels from YAML with no web interface and no database. Useful in a container that should do exactly one thing, and useful when you want to see a channel's behaviour without anything else running.

19.1.3 perfuse check

Validates channel definitions and prints what they do, without running them. The second half is the point: a channel that loads is not necessarily the channel you meant, and reading a plain-English summary of what a file will do catches a mistake that validation cannot see.

Exits non-zero on a fault, so it belongs in whatever checks your configuration before it reaches a server. -quiet prints nothing on success, for that use.

-allow-metadata-egress permits destinations pointed at cloud instance metadata addresses. Those addresses hold the machine's own credentials, so a channel that can be talked into sending there is a credential leak; the check refuses them unless you say otherwise.

19.1.4 perfuse test

Runs tests written against channel definitions. A test sends a message through the channel's real filter, real transformations and real scripts, in the real order, with only the network replaced — so what passes here is what the channel does.

Tests live in *_test.yaml or *.test.yaml beside the channels. See testing.

19.2 Migrating from another engine

These three are the ones to run first, before deciding anything. See migration.

19.2.1 perfuse explain

Reads Mirth, Open Integration Engine and BridgeLink exports — a channel, a channel group or a whole server backup — and describes what each channel does and what would block a migration. It changes nothing and needs no Perfuse installation, which makes it the cheapest possible first step: point it at an export of your estate and read what comes back.

-strict exits non-zero if anything is blocked, so it can gate a pipeline. -json emits the same findings for a machine.

19.2.2 perfuse translate

Converts Mirth, Open Integration Engine and BridgeLink exports into Perfuse channel files: one channel, a channel group, a code template export or a whole server backup.

perfuse translate -o ./channels server-backup.xml

Code template libraries are written to lib/ beside the channels, and each channel Mirth had a library enabled for includes it. See migration.

Nothing is silently dropped. Every part of a channel is either translated, carried across as a script that runs unchanged, or reported as needing a human. The third category is the honest one — a translator that produced a clean-looking file for every input would be hiding the decisions you most need to make.

19.2.3 perfuse compare

Runs the same traffic through two engines and reports where they disagree, grouped by field.

This is the command that answers "why should I trust this with patient data", and it answers it with evidence you gathered rather than a claim made here. It is the recommended last step before cutting over, and the recommended first step in any argument about whether Perfuse is ready.

19.3 Understanding a feed

19.3.1 perfuse profile

Reads messages and reports what is actually in them: which fields are always populated, which never are, the real value sets of coded fields, repetition counts, and which Z-segments appear.

Values are only reported for fields whose values form a small code set, so a profile of real traffic does not become a file full of patient data.

Saving a profile and comparing against it later is how you find out that a sender changed something:

perfuse profile -save last-month.json corpus/ perfuse profile -against last-month.json new/

19.3.2 perfuse contract

Turns the output of that thinking into something enforceable. A contract says what a feed must look like, so that the day it changes you are told, rather than finding out weeks later from a receiver that fell over — the messages are still valid HL7 when a field disappears, so nothing else notices.

perfuse contract promote -o adt.contract.yaml corpus/ perfuse contract check adt.contract.yaml today/

promote generates a starting point, not an answer. Read it and delete most of it: every line records whether it was measured or decided, which is what tells you which lines to keep.

19.4 Producing messages

19.4.1 perfuse generate

Produces synthetic HL7 v2 messages. Everything is invented — obviously fictional names, sequential identifiers, made-up addresses — so the output is safe to commit, mail, and attach to a ticket.

It can send straight at a channel rather than writing a file, which is the fastest way to prove a listener works:

perfuse generate -n 100 -send 127.0.0.1:6661

19.4.2 perfuse deident

Reads real messages and writes a corpus that keeps their structure, their codes and their intervals, and none of what identifies a patient. This is the difference between being able to send somebody a reproduction and not.

It is not the same tool as perfuse generate and the distinction matters. Generated messages are invented and therefore safe but unrealistic; a de-identified corpus is *derived from real traffic*, so it reproduces the oddities that actually break interfaces.

Two properties worth understanding before using it:

• The same salt always produces the same corpus, so a shared corpus can be regenerated rather than archived.
• Keep the salt secret. Pseudonyms are derived from real values, so anybody holding the salt can confirm a guess about who a record refers to.

19.5 Moving messages by hand

19.5.1 perfuse listen

Accepts HL7 v2 over MLLP and acknowledges it. A receiver that exists for as long as you need it, for proving that a sender can reach this machine at all.

19.5.2 perfuse send

Sends HL7 v2 messages over MLLP from files.

19.6 FHIR

19.6.1 perfuse fhir

Converts HL7 v2 to FHIR, validates FHIR, or serves it, depending on the subcommand.

The validating subcommand is useful on its own: it will tell you whether a resource somebody sent you satisfies US Core, which is the profile American regulation is written against. Being able to answer that without adopting an engine is the point.

19.6.2 perfuse x12

Converts X12 (or other delimited EDI) to the XML Mirth Connect and Open Integration Engine write for it, and back: perfuse x12 xml FILE and perfuse x12 from-xml FILE, standard input when no file is given. The output is what OIE 4.6 writes, byte for byte, so it can be compared with what a Mirth server produced or fed to a system built against it. A channel does the same with x12.arrives_as: xml and a destination's x12_as: xml; see X12.

19.6.3 perfuse sof

Runs a SQL on FHIR ViewDefinition over FHIR files (the NDJSON of a bulk export, Bundles or JSON arrays; - for stdin) and writes the table: -view FILE (required), -format csv|ndjson|json|parquet (csv by default), -header=false, and -o FILE (required for Parquet). See SQL on FHIR views.

19.6.4 perfuse measure

Evaluates a quality measure with FHIRPath criteria over FHIR files (the NDJSON of a bulk export, Bundles or JSON arrays; - for stdin) and writes the MeasureReport. Flags:

• -measure FILE, or -measure example:ID for a shipped example: required. -examples lists the examples.
• -period-start and -period-end: required.
• -type summary|subject|subject-list.
• -subject Patient/ID.
• -reporter NAME.
• -o FILE.

See digital quality measures.

19.6.5 FHIR flags on perfuse serve

The store keeps documents as well as resources: a document, collection or message Bundle PUT to /fhir/Bundle/{id} is kept whole, read back with every entry in the release served, and found by type, identifier, timestamp and composition. A transaction PUT there is kept as a record and not applied; a POST to /fhir applies one.

Answers are JSON unless the client asks for XML (Accept: application/fhir+xml, or _format=xml). Perfuse reads JSON only: a body sent as XML gets 415. A document Bundle POSTed to /fhir is kept when this server holds, by identifier, the patient and encounter its Composition names, and refused with 422 otherwise. A Binary read with Accept set to its own content type answers with the content itself.

19.7 Setting up and operating

19.7.1 perfuse init

Creates the directory layout, an example channel, and a service definition for the operating system it is run on. Nothing existing is replaced unless you pass -force.

perfuse init -dir /opt/perfuse -service systemd

19.7.2 perfuse service

Registers Perfuse as a Windows service, removes it, or reports whether it is installed and running. Windows only; on Linux the equivalent is the unit file perfuse init can write for you. See operations.

19.7.3 perfuse token

Issues credentials for machines rather than people. A token does not expire and is not affected by anybody signing out, which is what a server polling its neighbour needs and what a browser session deliberately is not.

perfuse token create -db perfuse.db -label fleet-from-site-a -role viewer perfuse token list -db perfuse.db perfuse token revoke -db perfuse.db -label fleet-from-site-a

Only the hash is stored, so a token is displayed once when it is created and cannot be recovered afterwards. A stolen database therefore yields no usable token. Give a token the lowest role that does the job: a fleet view needs viewer, and nothing that only reads should hold anything more.

-fhir-groups riverside-attributed,riverside-north limits a token to those FHIR Groups, for a provider's CMS-0057 Provider Access export: on the FHIR endpoint it can read those Groups and export them, and nothing else. See CMS-0057 for payers.

19.7.4 perfuse athena

Prints the Amazon Athena CREATE EXTERNAL TABLE for an S3 archive written with format: ndjson, using partition projection on the dt=YYYY-MM-DD part of the key, so no crawler has to run as days are added.

perfuse athena -bucket hospital-archive -destination archive

Printed rather than run, because creating a table needs Athena and Glue permissions this program should not hold.

19.7.5 perfuse sbom

Lists everything linked into the binary, read from the build itself rather than from go.mod — so it describes the binary in front of you and not what somebody once asked for.

-json emits CycloneDX and -spdx emits SPDX tag-value, which is usually what a procurement or security review is actually asking for. The browser code embedded in the binary is included, because a reviewer matching a binary against advisories needs to know it contains a React application.

19.7.6 perfuse version

Prints the version and the commit it was built from. Worth putting in a ticket: "the current one" is not a version, and two machines that were installed a week apart are frequently not running the same build.

20 Server Options

Every option perfuse serve takes, generated from the program itself, so this list cannot name an option that does not exist or leave one out. Most are also a setting in the web interface, named in the last column: a value saved there wins over the flag at the next start, and the flag remains the way to set it from a service definition. The listen address, the database and the channel directory stay flags only, because they say where the server finds what it would be editing.

Secrets are never flags. An option that needs a password or a token names an environment variable that holds it.

20.1 All options

21 Channel Reference

Every key that can appear at the top level of a channel file. These are extracted from the source, so this chapter cannot describe an option that does not exist or omit one that does.

21.1 Channel

Channel is one configured message flow: somewhere messages arrive, an optional filter, and one or more places they go.

Defined as Channel in internal/config.

21.1.1 name

Name identifies the channel in logs and metrics.

Required and unique.

21.1.2 group

Group is what this channel is part of, for organising a list that has grown too long to read.

Cosmetic at five channels and structural at two hundred: a site's channels divide by the system they talk to, or by the team that owns them, and a flat list of two hundred names is unusable however good the rest of the interface is.

A plain string rather than a group object with its own file, because a group has no behaviour. The moment it has a file it acquires settings, and settings on a group mean a channel's behaviour depends on something not written in the channel - which is the property that makes Mirth configuration hard to reason about. Groups here are a label and nothing more.

21.1.3 attachments

Attachments moves large payloads out of the message and puts them back before delivery.

Opt-in per channel: a feed of plain ADT messages has nothing to extract and should not pay for the machinery.

21.1.4 delimited

Delimited configures a delimited channel.

Only meaningful when the data type is delimited.

21.1.5 tables

Tables names files of shared mapping tables a transformation may refer to by name.

Shared because the domain tax is largely re-deriving a mapping somebody already derived: a site's sex codes and patient classes get translated identically in every channel that touches them, and a table inside a channel is a table only that channel can use.

21.1.6 enabled

Enabled defaults to true.

A disabled channel is loaded and validated but not started, so a file that is temporarily off is still checked by CI.

21.1.7 dataType

DataType is the format of the messages this channel receives.

Defaults to hl7, so every channel written before this existed keeps working.

21.1.8 x12

X12 holds the settings that only mean anything on an X12 channel.

Setting it on any other kind is refused rather than ignored.

21.1.9 script

Script configures an NCPDP SCRIPT channel.

Its steps live here rather than in the top-level transformations for the same reason every other non-v2 format's do: the step types differ per format, so one key would mean different things depending on dataType.

21.1.10 dicom

Imaging configures a DICOM channel's named transformation steps.

Named Imaging rather than DICOM because Source and Destination already have a DICOM field and three fields with the same name at different levels is how somebody sets the wrong one. The yaml key is dicom, which is what a person writing the file expects, and the Go name is the one that stops a mistake at the call site.

21.1.11 filter

Filter is an expression that must hold for a message to be forwarded.

A message that does not match is still acknowledged: the sender did nothing wrong, we simply are not interested.

21.1.12 transformations

Transformations are declarative changes applied to accepted messages, in order, before any script runs.

This is the layer meant to carry the ordinary work: each step is validated when the file loads, shows up in a diff, and can be reviewed by somebody who does not read JavaScript.

21.1.13 scripts

Scripts holds JavaScript for the cases the declarative steps cannot express, and is what a Mirth channel's own scripts drop into unchanged.

A channel with a script is marked as such in the interface, because its behaviour cannot be established by reading the configuration.

21.1.14 shadow

Shadow runs a candidate version of this channel beside it and reports where they differ.

Nothing it does can reach a receiver.

22 Source Reference

Every way a channel can receive messages, and every key each one accepts. A channel has exactly one source.

22.1 AMQP Source

AMQPSource receives from a queue or subscription.

A message is accepted only after the channel has handled it. One that could not be handled is released as a failed delivery, so the broker redelivers it and - on Service Bus, past the queue's max delivery count - dead-letters it.

Defined as AMQPSource in internal/config.

22.1.1 prefetch

Prefetch is how many messages the broker may send ahead.

Defaults to 10. They are still handled one at a time, in order.

22.1.2 reconnect

Reconnect is the wait after a lost connection.

Defaults to 5s.

22.2 AS2 Source

AS2Source receives AS2 (RFC 4130): EDI posted over HTTP, signed and encrypted with S/MIME, answered with a receipt (an MDN) carrying a digest of what arrived.

The payload is what the channel handles; X12 and EDIFACT are the usual ones.

Defined as AS2Source in internal/config.

22.2.1 path

Path is the URL path partners post to.

Default /as2.

22.2.2 tls

TLS serves HTTPS.

Most partners require it in their agreement, on top of the S/MIME.

22.2.3 id

ID is our AS2 identifier, which partners send in AS2-To.

A message to any other is refused.

22.2.4 partners

Partners are who may send here.

A message from anyone else is refused.

22.2.5 duplicate_window

DuplicateWindow is how long a partner's Message-ID is remembered, so a message sent again (the partner never got our receipt, and retried) is answered with a receipt and not passed on twice (RFC 4130 section 7.5).

Default 30 days.

22.3 Azure Blob Source

AzureBlobSource picks blobs up from a container prefix.

Defined as AzureBlobSource in internal/config.

22.3.1 move_to

MoveTo is where a handled blob moves.

Defaults to processed/.

22.3.2 error_prefix

ErrorPrefix is where a blob that cannot be handled moves, so it does not block the rest.

Defaults to error/.

22.3.3 poll_interval

PollInterval between listings.

Defaults to 30s.

22.3.4 max_object_size

MaxObjectSize refuses a larger blob, which is left where it is.

Defaults to 16 MiB.

22.4 Broker Source

BrokerSource reads messages from a message broker.

Mirth's JMS Reader, reached over STOMP because JMS is a Java API rather than a protocol. See internal/stomp for why STOMP and not OpenWire.

Defined as BrokerSource in internal/config.

22.4.1 addr

Addr is the broker's host and port.

Required. 61613 is the usual STOMP port.

22.4.2 destination

Destination is the queue or topic to read from.

Required.

Brokers spell these differently - /queue/name on ActiveMQ, a bare name on RabbitMQ - so it is passed through unchanged rather than being assembled here. Guessing would mean working against one broker and silently reading nothing on another.

22.4.3 login

Login and Passcode authenticate.

Most brokers refuse an anonymous connection.

22.4.4 passcode

Login and Passcode authenticate.

Most brokers refuse an anonymous connection.

22.4.5 host

Host is the virtual host.

Defaults to the address's host.

22.4.6 selector

Selector filters messages at the broker.

A JMS selector, passed through rather than interpreted. Filtering at the broker rather than here means the messages this channel does not want never cross the network - which on a shared queue is the difference between reading a hundred messages a day and a hundred thousand.

22.4.7 subscription_id

SubscriptionID names the subscription.

Defaults to the channel name.

Named rather than generated, because a durable subscription is identified by it: a generated one would create a new subscription on every restart and leave the old ones accumulating messages nobody reads.

22.4.8 heartbeat

Heartbeat keeps the connection alive.

Defaults to thirty seconds.

On by default here, unlike the client's own default, because a source holds one connection open for weeks. Without heartbeats a connection through a firewall that has silently dropped the route looks perfectly healthy from this end and messages simply stop arriving, with nothing logged.

22.4.9 reconnect

Reconnect is how long to wait before reconnecting after a failure.

Defaults to five seconds.

22.4.10 timeout

Timeout bounds connecting.

Defaults to thirty seconds.

22.5 DICOM Query Source

DICOMQuerySource polls an archive with C-FIND and emits a message per new study.

Mirth has no equivalent connector. Its DICOM support is a listener and a sender - it can receive images pushed at it and push them on, and that is all. Asking an archive what it holds has been requested on their forums since 2015.

What makes it worth having is not the query, it is the automation: a prefetch that runs at three in the morning, a reconciliation that notices the archive is missing a study the RIS says exists, a worklist built from what was actually scanned rather than what was ordered. Those are jobs sites currently do with a scheduled script outside the engine, which means they are invisible to it - no retries, no alerting, no message history.

Defined as DICOMQuerySource in internal/config.

22.5.1 address

Address is the archive's host and port.

Required.

Named to match the DICOM destination rather than shortened. The two were "address" and "addr" for an afternoon, which is the sort of inconsistency somebody hand-writing a channel file gets wrong once and then distrusts the whole format over.

22.5.2 called_ae

CalledAE is the archive's AE title.

Required in practice: most archives refuse an association addressed to anything else, and that refusal reads as an outage rather than as a configuration mistake.

22.5.3 calling_ae

CallingAE is the AE title Perfuse presents.

Archives commonly use it for access control.

22.5.4 level

Level is the query level: PATIENT, STUDY, SERIES or IMAGE.

Defaults to STUDY.

STUDY is the default because it is what almost every useful query wants and because the alternatives surprise people: IMAGE level against a large CT returns one response per slice, which is hundreds per study.

22.5.5 match

Match are the query keys.

A value filters; an empty value asks for the field to be returned.

Keys are named rather than numbered - "PatientID" not "0010,0020" - because a channel file is read by people, and a tag number in a configuration file is a lookup every reader has to perform.

22.5.6 return

Return are fields to bring back without filtering on them.

Separate from Match with an empty value, even though they encode identically, because the intent differs and a reader can see which keys are narrowing the search and which are being collected.

22.5.7 interval

Interval is how often to poll.

Required.

22.5.8 window

Window is how far back each poll looks, as a study date range.

Zero disables date filtering entirely.

A window is what keeps this bounded. Without one, every poll asks the archive for everything it has ever held and then discards what it has seen before - which works on a test archive and is antisocial against a real one holding millions of studies.

22.5.9 overlap

Overlap re-queries this far into the already-polled period.

Defaults to one hour.

Necessary rather than cautious. A study can be registered with yesterday's date, our clock and the archive's need not agree, and a poll boundary that lines up exactly with an arrival loses it. The overlap re-asks, and the already-seen check stops the duplicate - so the cost of overlapping is a slightly larger query and the cost of not overlapping is a silently missed study.

22.5.10 limit

Limit caps the matches accepted from one poll.

Defaults to 500.

A cap rather than no cap because a mistyped match key turns this into "give me everything", and the first symptom of that against a real archive is the archive's administrator asking who is hammering it.

22.5.11 timeout

Timeout bounds one poll.

Defaults to two minutes.

22.5.12 emit_on_first_poll

EmitOnFirstPoll sends messages for everything the first poll finds.

Defaults to false.

False matters. Pointing this at an archive that already holds a million studies and having it emit a message for each is not a useful first run, and it is the kind of mistake that is noticed downstream rather than here. The first poll records what exists and emits nothing; the second poll onwards reports what is new.

22.6 DICOM Source

DICOMSource receives imaging objects as a C-STORE service class provider.

What a hospital points a modality or a PACS at. Mirth calls this the DICOM Listener and it does C-STORE only, so this is parity rather than a subset.

Defined as DICOMSource in internal/config.

22.6.1 listen

Listen is the address to serve on.

Required. 104 is the registered DICOM port; 11112 is the common alternative where binding a privileged port is not possible.

22.6.2 ae_title

AETitle is what this endpoint calls itself.

Strongly recommended rather than required, and warned about when absent. A site's only access control on a DICOM endpoint is frequently the AE title, so an endpoint that accepts any title accepts anything that can reach it.

22.6.3 allowed_calling_ae

AllowedCallingAE lists the AE titles permitted to connect.

Empty accepts any caller.

This is the access control DICOM actually has. A PACS is routinely configured to accept one named calling title and reject everything else, and this end had no equivalent: the called title was checked - which is the name the caller dials, so anybody can send it correctly - while who was calling was recorded in the log and otherwise ignored.

Empty still accepts anything, because a modality nobody listed is the normal state of a first installation and refusing by default would break every deployment on day one. It warns instead, and the warning names the titles that have connected so somebody can fill this in from what actually arrived.

22.6.4 sop_classes

SOPClasses restricts what kinds of object to accept.

Empty accepts any.

Empty is a reasonable default here because this engine relays objects rather than interpreting them, so refusing an unfamiliar class would refuse valid images for no benefit.

22.6.5 transfer_syntaxes

TransferSyntaxes restricts the encodings to accept, in preference order.

Empty accepts the uncompressed three.

22.6.6 max_object_bytes

MaxObjectBytes bounds one received object.

Zero applies a default.

22.6.7 idle_timeout

IdleTimeout closes an association that has gone silent.

Zero means never, which is usually right - a modality holds an association open between studies.

22.6.8 tls

TLS encrypts inbound associations and can require a client certificate.

Worth stating plainly: Mirth needs its paid SSL Manager extension for this, and the community forks cannot ship it at all. DICOM carries patient names in its metadata, so this is one of the places where being a rewrite rather than a fork is a real advantage rather than a stylistic one.

22.7 DICO Mweb Source

DICOMwebSource accepts STOW-RS requests.

Defined as DICOMwebSource in internal/config.

22.7.1 listen

Listen is the address to serve on.

Required.

22.7.2 path

Path is the service root.

Objects are accepted at Path/studies and Path/studies/{uid}. Defaults to /dicom-web, which is what Orthanc and dcm4chee use, so a sender configured for either needs only the host changed.

22.7.3 token

Token, when set, is required as a bearer token.

Username and Password require HTTP basic authentication.

22.7.4 username

Token, when set, is required as a bearer token.

Username and Password require HTTP basic authentication.

22.7.5 password

Token, when set, is required as a bearer token.

Username and Password require HTTP basic authentication.

22.8 Database Source

DatabaseSource reads rows from a database and turns each one into a message.

This is how a great many hospital interfaces actually start. A department system has no HL7 capability, so somebody writes rows into a staging table and the interface engine polls it. It is unglamorous and it is everywhere.

It is also the single commonest way a Mirth channel stalls, and the reason is almost always the same shape: a row that cannot be processed is read, fails, and is read again, forever, because nothing marked it. The channel looks alive. The queue looks empty. Nothing moves, and every message behind the bad row waits for a row that will never succeed.

Most of the design here is about that.

Defined as DatabaseSource in internal/config.