HL7 RAS messages report a pharmacy or treatment administration — the record that a medication or treatment was actually given to a patient, when, in what amount, and by whom, against an existing order. A RAS message confirms the administration of a treatment that was ordered, typically through an RDE pharmacy encoded order, and is most often sent from the administering application — a nursing application — to the pharmacy, treatment, ordering, or another clinical application. This page explains what a RAS message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how a RAS administration relates to FHIR. Sample content is constructed for illustration with fictional identifiers.
What a RAS message represents
A RAS message — RAS stands for Pharmacy/Treatment Administration — communicates that a medication or treatment has been administered to a patient. The core of the message is the RXA segment, which carries the administration data for a single instance of giving a medication or treatment: the administered code, the amount and units, and the date and time the administration started. A single RAS message can report several administrations against one order, because each administration instance is carried by its own repeating RXA segment.
The sender is most commonly the administering application — a nursing application — and the receiver is the pharmacy or treatment application, the ordering application, or another clinical application, which can use the data to generate medication administration reports. RAS sits one step downstream of the dispense: an RDE encoded order tells the pharmacy what to prepare, an RDS message reports what was dispensed, and the RAS message reports what was actually administered to the patient. Because the administration is the event that records that a dose reached the patient, the RXA — not the order or the dispense — is the authoritative record of what was given.
When a RAS message is sent
A RAS message is created by the administering application for each instance of administration for an existing order. A single order can produce a series of administrations over time, and the administering application can report several administrations for a given order within a single RAS message — each instance reported by a separate, repeating RXA under one ORC.
Trigger event
The RAS message type carries a single trigger event:
RAS^O17– Pharmacy/treatment administration message.
Because RAS has one trigger event, the receiver's handling turns on the contents of RXA — the administered code, the amount and units, the start time, and the completion status — rather than on the trigger code in MSH-9.
Integration topology
The diagram shows the administering application emitting an administration event through the integration engine to the systems that record and act on it.
{{diagram: nursing/administering application → RAS message → integration engine → pharmacy/treatment app / ordering app / medication administration record}}
Typical senders: nursing or other administering application, electronic medication administration record (eMAR) system.
Typical receivers: pharmacy or treatment application, the ordering application, and other clinical applications that record administrations or generate medication administration reports.
Direction: unidirectional notification from the administering source to the systems that record and reconcile the administration.
Segments in a RAS message
The RAS_O17 message is organised into groups: an optional PATIENT group (PID through the patient-visit segments) and one or more ORDER groups, each opening with ORC and carrying the administration. Within an order, the ORDER_DETAIL (RXO) and ENCODING (RXE) groups are optional, while the ADMINISTRATION group — one or more RXA segments followed by a RXR route — is required and repeats. Cardinality follows HL7 notation: [X] optional, {X} repeating, [{X}] optional and repeating; a bare code is required. Each segment code links to its canonical field-by-field reference.
| Segment | Description |
|---|---|
MSH | Message Header. Opens every RAS message. It names the sending and receiving applications and facilities, stamps the creation time, declares the trigger event in MSH-9 (RAS^O17), carries the message control id in MSH-10, and pins the HL7 version. Receivers route on MSH-9 and deduplicate on MSH-10. |
[{SFT}] | Software Segment. Identifies the software product behind the sender — vendor, product, and version. Useful when administration behaviour differs across releases. Optional and repeating. |
[{NTE}] | Notes and Comments. Message-level notes that apply to the administration as a whole. Optional and repeating. |
[PID] | Patient Identification. Identifies the patient the medication or treatment was administered to — the identifier list in PID-3, the name in PID-5. Required when the PATIENT group is present; the group as a whole is optional. |
[PD1] | Patient Additional Demographic. Supplements PID with data such as the patient's primary-care facility. |
[{NTE}] | Notes and Comments. Notes relative to the patient. Optional and repeating. |
[{AL1}] | Allergy Information. Patient allergies carried with the administration. Optional and repeating. |
[PV1] | Patient Visit. The encounter the administration belongs to — patient class, assigned location, and the providers on the visit. Required when the patient-visit group is present. |
[PV2] | Patient Visit Additional. Companion to PV1 with admit reason and expected dates when a visit is present. |
ORC | Common Order. Opens each order group and ties the administration to its order. For an administration the ORC carries the order control code RE and the filler order number, which links the administration back to the originating RDE order. Required, and the order group repeats. |
[{TQ1}] | Timing/Quantity. The dosing schedule and timing for the order. Optional and repeating; introduced as the replacement for the deprecated quantity/timing field in v2.5. |
[TQ2] | Timing/Quantity Relationship. Relates this order's timing to another order, when sequenced or conditional dosing applies. |
[RXO] | Pharmacy/Treatment Order. The original order as the prescriber expressed it, carried for reference. Optional; when present it has its own route, note, and component segments. |
[RXE] | Pharmacy/Treatment Encoded Order. The pharmacy-encoded prescription the administration relates to, with its own encoded timing, route, and components. Optional — present only when the receiving application needs its data; the administration itself stands on RXA. |
{RXA} | Pharmacy/Treatment Administration. The core of the message and the required clinical segment in the order. It records the administration as it happened: the give sub-id counter in RXA-1, the administration sub-id counter in RXA-2, the date/time start of administration in RXA-3, the date/time end of administration in RXA-4, the administered code in RXA-5, the administered amount in RXA-6, the administered units in RXA-7, the administering provider in RXA-10, the substance/treatment refusal reason in RXA-18, and the completion status in RXA-20. Required and repeating — several administrations for one order are reported as repeating RXA segments. |
RXR | Pharmacy/Treatment Route. The route of administration in RXR-1 (oral, IV, IM) and the administration site in RXR-2 for the administered medication, a continuation of the RXA segment. Required within the administration group. |
[{OBX}] | Observation/Result. Administration-time observations such as a vital sign recorded at the time of administration. Optional and repeating; each OBX may be followed by its own notes. |
[{NTE}] | Notes and Comments. Notes relative to an observation following the OBX. Optional and repeating. |
[{CTI}] | Clinical Trial Identification. Identifies the clinical trial, phase, and study the order is associated with, when the administration is part of a study. Optional and repeating. |
[ ] = optional, { } = repeating
The order group from ORC onward repeats, and within each order the administration group repeats, so a single RAS message can report several administrations — and several orders — together. The canonical segment pages carry the full field-by-field detail.
Sample RAS message
Note. Constructed for illustration. Patient identifiers, order numbers, dates, and names are fictional.
MSH|^~&|NURSING|MERCYGEN|PHARM|MERCYGEN|202006151000||RAS^O17^RAS_O17|MSG00021|P|2.5.1
PID|1||MR12345^^^MERCYGEN^MR||DOE^JOHN^Q||19800101|M
ORC|RE|ORD789^EHR|RX456789^PHARM
RXE|1^BID^^202006150900|00071015523^Lisinopril 10 MG Oral Tablet^NDC|10||MG|TAB
RXA|0|1|202006151000||00071015523^Lisinopril 10 MG Oral Tablet^NDC|10|MG|||NURSE01^ROE^MARY^^^^RN|||||||||CP
RXR|PO^Oral^HL70162
What this sample shows
The RAS^O17 in MSH-9 marks a pharmacy/treatment administration. PID carries the medical record number MR12345, and ORC carries the order control code RE with filler order number RX456789, linking the administration to its order. The RXE echoes the encoded order the administration relates to (Lisinopril 10 MG). The RXA reports the actual administration: a give sub-id counter of 0 and administration sub-id counter of 1 (RXA-1, RXA-2), a start time of 202006151000 (RXA-3), the administered code (RXA-5), an amount of 10 in MG (RXA-6, RXA-7), the administering provider NURSE01 (RXA-10), and a completion status of CP — complete — in RXA-20. The RXR gives the oral route in RXR-1.
Working with RAS messages
Read the administration from RXA, not the order
The administered code, amount, units, and start time live in RXA, not in the order. RXA records what was actually given on this occasion, so an administration that differs from the order — a partial dose, a held dose, or a refusal — shows up in RXA, not in the order or the encoded order. Reconcile against RXA rather than assuming the administration matched the order.
Multiple administrations per order
A single ORC can carry several repeating RXA segments, each a separate administration instance for that order. Iterate over the RXA segments within an order group rather than assuming one administration per message, and use the give sub-id and administration sub-id counters in RXA-1 and RXA-2 to distinguish them.
Completion and refusal status
RXA-20 carries the completion status of the administration, and RXA-18 carries the substance or treatment refusal reason. Surface these on the medication administration record rather than discarding them — an administration that was not completed, or that the patient refused, differs clinically from one given in full, and a refusal reason in RXA-18 records why a scheduled dose was not given.
Idempotency and deduplication
Use MSH-10, the message control id, as the deduplication key, and treat the filler order number in ORC together with the administration sub-id counter in RXA-2 and the start time in RXA-3 as the natural business key for an administration. Administration feeds are replayed after outages, and treating a repeated control id as a duplicate prevents a replayed administration from being recorded twice.
Vendor variance. The encoded order in
RXEis optional and is included only when the receiving application needs its data, so some systems repeat the full order on every RAS while others send only the administration inRXA. Confirm a partner's field usage against their interface specification rather than assuming the base standard.
FHIR equivalent
A pharmacy or treatment administration corresponds conceptually to the FHIR MedicationAdministration resource, with the patient as a Patient resource and, for a messaging exchange, a MessageHeader at the head of a Bundle.
There is, however, no published message map to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for RAS_O17. The RXA segment does have a published ConceptMap, but it maps RXA to Immunization — the resource used by the immunization message VXU — not to MedicationAdministration. A FHIR MedicationAdministration produced from a RAS message is therefore mapped manually, taking the administered medication, amount, units, start time, and completion status from RXA, the route from RXR, and referencing the authorising order derived from ORC.
Common pitfalls
Pitfall. Recording an administration from the ordered or dispensed quantity instead of the administered amount. The administration record follows
RXA-6andRXA-7, the actual administered amount and units, not the quantity in the order or the dispense.
Pitfall. Assuming one administration per message. A single order group can carry several repeating
RXAsegments; reading only the first under-counts the doses given.
Pitfall. Ignoring the completion status. Treating every
RXAas a completed dose hides held, partial, and refused administrations recorded inRXA-20andRXA-18.
Pitfall. Assuming a fixed date-time precision. Some senders stamp
RXA-3asYYYYMMDDand others as a full timestamp with an offset; do not assume a timezone — normalize on ingest.
How Vorro handles RAS messages
Vorro ingests the RAS feed over MLLP or another transport, deduplicates on MSH-10, and routes each administration to every subscribed destination in the format that system expects — the medication administration record, the pharmacy or treatment application, and other clinical systems. Vorro reads the administered code, amount, units, start time, and completion status from RXA, takes the route from RXR, links each administration back to its order through the filler order number in ORC, and, where a FHIR destination is configured, maps the administration to a MedicationAdministration resource — composed manually, since the v2-to-FHIR Implementation Guide publishes no map for this message and the only published RXA ConceptMap targets Immunization.
Related messages
- RDE — the pharmacy encoded order that a RAS administration is given against.
- RDS — the dispense message that records the medication actually supplied.
- RGV — the give message that records medication-administration intent.
Sources
- HL7 v2-to-FHIR IG — message maps index — confirms no message map for RAS_O17
- HL7 v2-to-FHIR IG — segment maps index — confirms the RXA ConceptMap targets Immunization, not MedicationAdministration
- HL7 Messaging Standard Version 2.5.1 product brief
- HL7 v2 RAS_O17 message description (hl7.eu standard mirror)
- HL7 v2 RAS_O17 message structure, Chapter 4A (hl7.eu standard mirror)
- HL7 v2 RXA segment definition (hl7.eu standard mirror)
- HL7 v2 RXR segment definition (hl7.eu standard mirror)
- HL7 v2 ORC segment definition (hl7.eu standard mirror)
