The MFA (Master File Acknowledgment) segment reports, on a per-record basis, whether each master file change requested by a corresponding MFE segment was applied. It appears in MFK acknowledgment messages that respond to MFN master file notification messages. Each MFA echoes the record-level event code and the originating MFN control ID, and optionally returns an error code when the change could not be processed.
Purpose
The MFA segment lets a receiving application tell the originator the outcome of each individual master file record it was asked to add, update, deactivate, or reactivate. Because a single MFN message can carry many MFE records, the MFK response carries a matching MFA for each one. The segment ties the acknowledgment back to the original request through MFA-2 (MFN Control ID) and the primary key values in MFA-5 and MFA-6, while MFA-4 conveys the specific error when a record was rejected.
Used in
The MFA segment is used in MFK master-file acknowledgment messages, which are generated in response to MFN master file notification messages. See the MFN message reference for how MFE request records and MFA acknowledgment records correspond.
Field-by-field reference
Source: HAPI HL7v2 v2.5.1 javadocs (MFA segment). Length is not asserted by the javadoc and is shown as —. Required and Table # are taken from the HL7 v2.5.1 standard where well-established.
| Seq | Name | Data Type | Length | Req | Repeat | Table # | Description |
|---|---|---|---|---|---|---|---|
| MFA-1 | Record-Level Event Code | id | — | R | — | HL70180 | Action acknowledged for this master file record |
| MFA-2 | MFN Control ID | st | — | O | — | — | Echoes control ID from the originating MFE |
| MFA-3 | Event Completion Date/Time | ts | — | O | — | — | When the acknowledged change took effect |
| MFA-4 | MFN Record-Level Error Return | ce | — | O | — | HL70181 | Error code when the record was rejected |
| MFA-5 | Primary Key Value - MFA | varies | — | R | Y | — | Primary key identifying the master file record |
| MFA-6 | Primary Key Value Type - MFA | id | — | R | Y | — | Data type of each MFA-5 primary key value |
Most-used fields
- MFA-1 Record-Level Event Code: states which action (such as add, update, or deactivate) is being acknowledged for the record.
- MFA-2 MFN Control ID: links the acknowledgment to the original MFE record so the sender can reconcile each request.
- MFA-4 MFN Record-Level Error Return: present only when a record failed; carries the coded reason for rejection.
- MFA-5 Primary Key Value - MFA: identifies which master file entry the acknowledgment refers to, and repeats when the key is composite.
- MFA-6 Primary Key Value Type - MFA: declares the data type for each repeating primary key value in MFA-5.
Version differences (2.3 to 2.8.2)
- 2.3: MFA carried the record-level event code, MFN control ID, event completion date/time, error return, and a single primary key value with its type.
- 2.3.1 to 2.4: Structure remained stable; the primary key value and its type were clarified to support composite keys through repetition.
- 2.5 and 2.5.1: MFA-5 (Primary Key Value - MFA) and MFA-6 (Primary Key Value Type - MFA) are defined as repeating, paired fields, allowing multi-part keys to be acknowledged precisely.
- 2.6 to 2.8.2: No material change to the field set; the MFN/MFK record-level acknowledgment model is retained as application-level master file control.
Common mistakes
- Omitting MFA-1 or sending an event code that does not match the originating MFE event, breaking reconciliation.
- Failing to keep MFA-5 and MFA-6 aligned so each repeating key value lacks its matching type declaration.
- Populating MFA-4 with a free-text reason instead of a coded value from the record-level error return table.
- Treating MFA as a message-level acknowledgment; it is per-record and must appear once for each acknowledged MFE.
- Sending an MFA with an error in MFA-4 while still reporting a success-style event code, producing an ambiguous result.
Examples
Minimal MFA acknowledging a single record:
MFA|MAD|MFN10241|20260610093000||^9920^STAFF
Fully populated MFA with an error return and composite key:
MFA|MUP|MFN10242|20260610093215|205^Record update failed: lock contention^HL70181|^7741^STAFF~^DEPT04^DEPT|ST~ST
Annotated breakdown of the fully populated example:
MFA-1 MUP Record-Level Event Code (update acknowledged)
MFA-2 MFN10242 MFN Control ID from the originating MFE
MFA-3 20260610093215 Event Completion Date/Time
MFA-4 205^Record update MFN Record-Level Error Return (coded reason)
failed: lock
contention^HL70181
MFA-5 ^7741^STAFF~^DEPT04^DEPT Primary Key Value - MFA (two repeating values)
MFA-6 ST~ST Primary Key Value Type - MFA (type per key)
In-context excerpt 1: an MFK acknowledging a successful staff record add.
MSH|^~&|HRMASTER|CENTRAL|FEEDSYS|WEST|20260610093000||MFK^M01^MFK_M01|ACK77120|P|2.5.1
MSA|AA|MFN10241
MFI|STF^Staff Master^HL70175|HRMASTER|UPD|20260610092900|20260610093000|AL
MFA|MAD|MFN10241|20260610093000||^9920^STAFF|ST
In-context excerpt 2: an MFK reporting one accepted and one rejected record.
MSH|^~&|HRMASTER|CENTRAL|FEEDSYS|WEST|20260610093215||MFK^M01^MFK_M01|ACK77121|P|2.5.1
MSA|AE|MFN10242
MFI|STF^Staff Master^HL70175|HRMASTER|UPD|20260610093100|20260610093215|AL
MFA|MUP|MFN10242|20260610093210||^7740^STAFF|ST
MFA|MUP|MFN10242|20260610093215|205^Record update failed: lock contention^HL70181|^7741^STAFF|ST
FHIR mapping
- Source: MFA segment.
- Target: Not mapped at the segment level.
- The v2-to-FHIR Implementation Guide does not publish a segment-level ConceptMap for MFA. MFA is master-file acknowledgment control; it describes the outcome of an HL7 master file transaction rather than clinical or demographic content, so it has no direct FHIR resource equivalent. In a FHIR context the equivalent behavior is expressed through transaction or operation outcome responses, not a mapped resource.
Engine considerations
- Match each inbound MFA to its originating MFE using MFA-2 and the primary key values, not message order alone.
- Preserve the MFA-5 and MFA-6 repetition pairing when transforming, so each key value keeps its declared type.
- Surface MFA-4 error codes to monitoring so partial master file failures are visible rather than silently dropped.
- Confirm the MSA acknowledgment code (AA, AE, AR) is consistent with the aggregate of the MFA record-level outcomes.
- Retain the event completion date/time for audit reconciliation of when master file changes were applied.
How Vorro parses and produces MFA
Vorro parses MFA by reading MFA-1 to classify the acknowledged action and MFA-2 to bind the record back to the original MFE request. The repeating MFA-5 and MFA-6 fields are read as paired key-value and type entries so composite primary keys are reconstructed faithfully. When MFA-4 is present, Vorro normalizes the coded error into its internal result model and flags the record as a partial failure. When producing MFA, Vorro emits one segment per acknowledged record, carries the originating control ID into MFA-2, stamps MFA-3 with the completion time, and populates MFA-4 only on rejection, keeping the MSA code aligned with the overall outcome.
