EHR systems emit HL7 ADT-A04 "Register a Patient" events whenever a patient is registered, but clinical analytics and Salesforce Data Cloud (Data360) need FHIR R4 Patient resources to build unified patient profiles and power AI-driven care models. Without a translation layer, Data Cloud cannot ingest the demographic event at the moment it fires from the EHR, and every downstream consumer that touches patient data must write its own bespoke HL7 parser. This integration receives the ADT-A04 message from the EHR over MLLP, transforms it into a FHIR R4 Patient resource, publishes the result to a Kafka topic for fan-out consumption, inserts the record directly into Salesforce Data Cloud via the SDC connector for near-real-time profile unification, and returns a synchronous HL7 ACK — so every newly registered patient is available across the Salesforce platform within seconds of the EHR event.
Tags: healthcare, provider, patient-360, personalization, population-health, interoperability, fhir, hl7v2, salesforce, kafka, event-driven, pub-sub, process-api, data-cloud, data360
HL7 ADT-A04 to FHIR Patient
Objective: EHR systems emit HL7 ADT-A04 "Register a Patient" events whenever a patient is registered, but clinical analytics and Salesforce Data Cloud (Data360) need FHIR R4 Patient resources to build unified patient profiles and power AI-driven care models. Without a translation layer, Data Cloud cannot ingest the demographic event at the moment it fires from the EHR, and every downstream consumer that touches patient data must write its own bespoke HL7 parser. This integration receives the ADT-A04 message from the EHR over MLLP, transforms it into a FHIR R4 Patient resource, publishes the result to a Kafka topic for fan-out consumption, inserts the record directly into Salesforce Data Cloud via the SDC connector for near-real-time profile unification, and returns a synchronous HL7 ACK — so every newly registered patient is available across the Salesforce platform within seconds of the EHR event.
Prerequisites
- Access to the Anypoint Platform environment where this application will be deployed (Sandbox for testing, Production for go-live).
- MLLP port
2575 open on the server hosting this Mule application; source HL7 systems must be able to route TCP connections to that address.
- Apache Kafka cluster credentials: SSL bootstrap server addresses, a client keystore (
keystore.p12, PKCS12 format) and truststore (truststore.jks, JKS format), and their passwords. The topic patient-events must be pre-created on the cluster with appropriate retention and replication settings.
- HL7 EDI connector licence — the
/hl7/v2_3/ADT_A04.esl schema is bundled with mule-hl7-extension, which requires a MuleSoft licence. Confirm your organization holds this entitlement before beginning the build.
- Salesforce Data Cloud org access and a Connected App (OAuth 2.0 Client Credentials) with the Data Cloud Ingest API permission. The
mule4-sdc-connector authenticates against Data Cloud using these credentials.
- The target Data Cloud Data Stream (source object) and Data Lake Object names for
sdc:insert-objects. These correspond to the sourceNameUriParam and objectNameUriParam on the connector operation and must be configured before deployment — the application will fail to start without valid values.
Choose your path
- MLLP listener (synchronous) — Choose this when the sending system is a traditional ADT feed that expects a real-time HL7 ACK (AA/AE) response on the same TCP connection. This is the primary path implemented in
listen-to-hl7-adt-a04-and-craft-fhir-message.
- Kafka consumer → Salesforce Data Cloud (asynchronous fan-out) — Choose this when you need near-real-time patient profile unification in Data Cloud without blocking the MLLP source. The
consume-fhir-patient flow demonstrates this path: it reads from the patient-events topic, transforms the FHIR Patient JSON to the XML shape expected by the target Data Stream, and inserts the record into Salesforce Data Cloud via the SDC connector.
Architecture
1. Ingest HL7 ADT_A04 over MLLP and publish FHIR Patient to Kafka
- What to build: The MLLP listener binds to
127.0.0.1:2575 and receives raw HL7 v2.3 frames. The HL7 EDI connector parses the message against the ADT_A04.esl v2.3 schema, making PID segments available as a structured DataWeave object. A single ee:transform step simultaneously produces the FHIR R4 Patient JSON (set as the message payload) and the ACK structure (stored in vars.ACK), keeping both derived from the same parsed input. The Kafka producer publishes the FHIR JSON to ${kafka.topic} over TLS using the PKCS12 keystore and JKS truststore. After publishing, the HL7 Write operation serialises vars.ACK back to the MLLP connection.
- The decision behind this order: The ACK is written after the Kafka publish. This means the sender does not receive an
AA until the event is durably on the Kafka broker, preventing a scenario where the sender believes the message was accepted but it never reached the event backbone.
- The failure this step prevents: Without a synchronous ACK, the sending HL7 system will indefinitely retry the ADT message. Returning
MSA-01: AA (Application Accept) tells the sender the message was received and processed, halting retries and preventing duplicate patient registrations in downstream systems.
2. Consume FHIR Patient from Kafka and stream into Salesforce Data Cloud
- What to build: The
consume-fhir-patient flow subscribes to the patient-events Kafka topic using the same TLS bootstrap configuration as the producer. A DataWeave step transforms the FHIR Patient JSON to the XML shape required by the target Salesforce Data Cloud Data Stream (<Patient><name/></Patient> in the current implementation — extend this mapping to cover all FHIR fields your Data Cloud Data Lake Object schema defines). The Salesforce Data Cloud connector's insert-objects operation calls the Data Cloud Ingest API to write the record near-real-time into the target Data Lake Object. Before go-live, set sourceNameUriParam to the Data Stream source name and objectNameUriParam to the Data Lake Object name defined in your Data Cloud org.
- What to watch out for: The Data Cloud Ingest API is eventually consistent — records appear in Data Lake Objects within seconds but unification into unified profiles and calculated insights may take minutes depending on your Data Cloud configuration. Kafka consumers default to
earliest offset for new consumer groups; if this consumer starts after messages have accumulated, it will replay all historical patient registrations into Data Cloud. Decide on an explicit auto.offset.reset strategy and confirm whether Data Cloud upsert semantics (based on the primary key of the Data Lake Object) will handle duplicate inserts safely.
3. Security and compliance
- HIPAA: Patient demographics transported and stored here — name (PID-05), date of birth (PID-07), sex (PID-08), and race (PID-10) — constitute Protected Health Information (PHI). This integration must operate under a Business Associate Agreement (BAA) with the Kafka hosting provider, Salesforce (for Data Cloud), and every cloud infrastructure component involved. Salesforce Health Cloud / Data Cloud offers a HIPAA BAA — confirm it is in place for your org before writing any PHI.
- Data in transit: Kafka connections use SSL (
kafka+ssl:// bootstrap endpoints) with mutual TLS (client keystore + truststore). The MLLP listener is bound to 127.0.0.1; if it must accept remote connections, place it behind a TLS-terminating proxy or restrict access at the firewall/network layer.
- Data at rest: The Kafka topic
patient-events must be encrypted at rest on the broker. Establish and document a key rotation schedule for keystore.p12 and truststore.jks, and rehearse rotation without dropping MLLP connections.
- Audit logging: Log the HL7 message control ID (
MSH-10), processing timestamp, and correlation ID for every message. Never log PID-05 (patient name), PID-07 (date of birth), or PID-10 (race code) in any appender. The current INFO loggers emit #[payload] — replace these with sanitised correlation-ID-only log statements before promoting to any non-development environment.
Sample payload — ADT_A04 input and resulting FHIR Patient
HL7 ADT_A04 input (as DataWeave sees it after HL7 EDI parse):
{
"Delimiters": "|",
"Id": "ADT_A04_001",
"Name": "ADT_A04",
"Data": {
"ADT_A04": {
"MSH": { "MSH-10": "MSG001" },
"PID": {
"PID-05": [{ "XPN-01": "Smith", "XPN-02": "John" }],
"PID-07": { "TS-01": "19800115" },
"PID-08": "M",
"PID-10": "2106-3"
}
}
}
}
Resulting FHIR R4 Patient resource (published to patient-events Kafka topic):
{
"resourceType": "Patient",
"gender": "male",
"birthDate": "1980-01-15",
"extension": [
{
"url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
"extension": [
{
"url": "ombCategory",
"valueCoding": {
"system": "urn:oid:2.16.840.1.113883.6.238",
"code": "2106-3",
"display": "White"
}
}
]
}
],
"name": [
{
"use": "official",
"family": "Smith",
"given": ["John"]
}
]
}
HL7 PID segment → FHIR Patient field mapping:
| HL7 PID Field |
Description |
FHIR Field |
PID-05[0].XPN-01 |
Family name |
name[0].family |
PID-05[0].XPN-02 |
Given name |
name[0].given[0] |
PID-07.TS-01 |
Date of birth (yyyyMMdd) |
birthDate (ISO 8601 Date) |
PID-08 |
Administrative sex (M/F) |
gender (male/female) |
PID-10 |
Race OMB category code |
extension[us-core-race].valueCoding.code |
Testing and validation
- Happy path end to end: Send an HL7 v2.3 ADT_A04 message via an MLLP client (such as HAPI TestPanel or a
mllp-send CLI tool) to localhost:2575. Verify an AA ACK is returned within 5 seconds. Then consume from the patient-events Kafka topic and assert the FHIR Patient JSON contains the correct gender, birthDate, name.family, name.given[0], and race extension code matching the PID values sent.
- Edge case — partial or missing birth date: PID-07 may contain a partial date (e.g.,
198001 — year and month only, 6 characters). The DataWeave guard sizeOf(...) >= 8 ensures birthDate is null rather than a malformed date string. Confirm birthDate: null in the output for any input shorter than 8 characters; a missing or invalid date must not cause the overall transform to fail or publish a non-FHIR-compliant resource.
- Mapping correctness (not just runtime): Use the DataWeave playground input at
src/test/resources/hl7-adt-a04-to-fhir-patient/playground/inputs/payload.json to run the transform in isolation. Assert field by field: PID-08: "M" → gender: "male", PID-07.TS-01: "19800115" → birthDate: "1980-01-15", PID-10: "2106-3" → valueCoding.display: "White". Proving the mapping in the playground catches DataWeave logic errors before any MLLP, Kafka, or Data Cloud infrastructure is involved. Additionally, after a Sandbox Data Cloud insert, verify the record appears in the target Data Lake Object using the Data Cloud Query API or the Data Cloud UI object explorer — this confirms the XML shape matches what the Data Stream expects.
Phased rollout
Phase 1 — Connect
- Stand up the Mule application in the Sandbox environment. Confirm MLLP connectivity from a test HL7 sender (HAPI TestPanel is sufficient). Validate Kafka TLS authentication using the provided keystore and truststore — a successful producer connection to the bootstrap brokers proves certificates and passwords are correct before any patient data is involved. Confirm the
patient-events topic exists and the service account has WRITE ACL on the producer side and READ ACL on the consumer side.
Phase 2 — Map and validate
- Send a representative set of real (de-identified) ADT_A04 messages from the Sandbox HL7 system. Verify FHIR Patient resources on the Kafka topic against the mapping table above. Spot-check edge cases: female patients (
PID-08: F), patients with non-White race codes where display will be an empty string (document and decide whether to extend the mapping), and messages with partial birth dates. Populate sourceNameUriParam (Data Stream source name) and objectNameUriParam (Data Lake Object name) on sdc:insert-objects, then query the Data Cloud Sandbox org to confirm records land correctly in the target Data Lake Object. Replace #[payload] loggers with sanitised correlation-ID log messages.
Phase 3 — Production
- Route production ADT feeds from the EHR system to the new MLLP endpoint. Monitor the Kafka consumer group lag on
patient-events to ensure the consumer keeps pace with EHR registration volume. Set up Anypoint Monitoring alerts on error-rate thresholds for both flows. Confirm the EHR's outbound HL7 retry queue is empty within the first hour (absence of duplicate ACKs indicates clean processing). Hand off operational runbook to the platform team, including key rotation procedures and Kafka consumer group reset instructions.
Success metrics
- Registration event latency: Time from HL7 ADT_A04 reception to FHIR Patient available on the Kafka topic. Target: under 2 seconds at p99. This metric is already tracked by Anypoint Monitoring request latency on the
listen-to-hl7-adt-a04-and-craft-fhir-message flow.
- ACK success rate: Percentage of inbound ADT_A04 messages that result in an
AA ACK. Target: ≥ 99.9%. A drop in this metric is the first signal of Kafka connectivity or transform failures.
- Kafka consumer lag: Number of unconsumed messages on
patient-events for the consume-fhir-patient consumer group. Target: near zero under normal load. Sustained lag indicates the Salesforce Data Cloud Ingest API is the bottleneck — check for rate limiting or Data Stream ingestion errors in the Data Cloud UI.
- Salesforce Data Cloud profile unification latency: Time from Kafka message produced to the patient record appearing as a unified profile in Data Cloud. This is governed by Data Cloud's identity resolution and calculation jobs; establish a baseline in Sandbox and set an alert if the observed latency exceeds 2× the baseline.
- Duplicate patient rate (business metric): Data Cloud's count of duplicate unified profiles per day for newly registered patients. This should remain at zero if the Data Lake Object primary key is correctly mapped to the HL7 patient identifier — confirm the key field is populated in the DataWeave transform.
Troubleshooting
- MLLP listener binds but no messages are received — Likely cause: the sending HL7 system is routing to the wrong host or port, or a firewall is blocking TCP on port
2575. Fix: use telnet <host> 2575 from the sender's network to verify TCP reachability. If the listener is bound to 127.0.0.1, it only accepts connections from localhost — change the host to 0.0.0.0 or the server's external IP if remote senders are required.
org.mule.extension.kafka.api.exception.KafkaPublishException on startup — Likely cause: incorrect bootstrap server address, or the JKS/PKCS12 credentials do not match the broker's expected certificates. Fix: confirm kafka.bootstrap values in config.properties, verify keystore and truststore passwords, and test connectivity with kafka-console-producer --bootstrap-server <addr> --producer.config client.properties from a machine with network access to the brokers.
sdc:insert-objects fails with 404 Not Found — Likely cause: sourceNameUriParam or objectNameUriParam does not match the exact Data Stream source name or Data Lake Object name in the Data Cloud org. Fix: navigate to Data Cloud → Data Streams in the Salesforce UI, copy the exact source name and object name, and update the connector operation parameters. Names are case-sensitive.
sdc:insert-objects fails with 401 Unauthorized — Likely cause: the Connected App OAuth credentials are incorrect, expired, or the Connected App does not have the Data Cloud Ingest API OAuth scope enabled. Fix: regenerate the client secret in the Connected App settings, update the connector configuration, and confirm the sfdc.datacloud.api.ingest scope is listed under the Connected App's OAuth policies.
- Records arrive in the Kafka topic but do not appear in the Data Cloud Data Lake Object — Likely cause: the DataWeave transform is producing XML that does not match the Data Lake Object's expected field names or data types, causing silent rejection by the Ingest API. Fix: enable verbose logging on the SDC connector, inspect the raw HTTP response body from the Ingest API for field-level validation errors, and align the DataWeave output field names with the Data Lake Object schema.
Deliverable: A running Mule application with two flows — listen-to-hl7-adt-a04-and-craft-fhir-message (MLLP ingest → FHIR transform → Kafka publish → HL7 ACK) and consume-fhir-patient (Kafka consume → DataWeave → Salesforce Data Cloud insert) — that makes every patient registered in the EHR available as a unified profile in Salesforce Data Cloud within seconds of the ADT event, with no bespoke HL7 parsing required in any downstream system.