This page is part of the FHIR Specification (v0.06: DSTU 1 Ballot 2). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions
Status: Approved infrastructure resource. Draft for comment
A transmission requesting action on a bundle of one or more resources or a response to such a request.
This page describes how FHIR Resources can be used in a traditional messaging context, much like HL7 v2. Applications claiming conformance to this framework claim to be conformant to "FHIR messaging".
In FHIR messaging, a "request message" is sent from a source application to a destination application when an event happens. Events mostly correspond to things that happen in the real world. The request message consists of a bundle of resources, with the first resource in the bundle being this Message resource. The Message resource has a code - the message event - that identifies the nature of the request message and carries additional request metadata. The other resources in the bundle depend on the type of the request.
The events supported in FHIR, along with the resources that are included in them, are defined below.
The destination application processes the request and returns one or more response messages which are also a bundle of resources, with the first resource in the bundle being a Message resource with a response section that reports the outcome of processing the message and any additional response resources required.
This specification assumes that content will be delivered from one application to another by some delivery mechanism, and then a response will be returned to the source application. The exact mechanism of transfer is irrelevant to this specification, but may include file transfer, http based transfer, MLLP (HL7 minimal lower layer protocol), MQ series messaging or anything else. The only requirement for the transfer layer is that requests are sent to a known location and responses are returned to the source of the request. This specification considers the source and destination applications as logical entities, and the mapping from logical source and destination to implementation specific addresses is outside the scope of this specification.
In principle, source applications are not required to wait for a response to a transaction before issuing a new transaction. However in many cases, the messages in a given stream are dependent on each other, and must be sent and processed in order. In addition, some transfer methods may require sequential delivery of messages.
This specification ignores the existence of interface engines and message transfer agents that exist between the source and destination. Either they are transparent to the message/transaction content and irrelevant to this specification, or they are actively involved in manipulating the message content. If these middleware agents are modifying the message content, then they become responsible for honoring the contract described below in both directions.
Some of the message delivery mechanisms mentioned above are reliable delivery systems - the message is always delivered, or an appropriate error is returned to the source. However most implementations use methods which do not provide reliable messaging, and either the request or the response can get lost in transit. FHIR messaging describes a simple approach to handle this that applications must conform to, whether messaging appears to be reliable or not.
A message receiver must always check the incoming bundle identifier (atom feed.id), and check them against a store of previously received messages (going back a reasonable period in time). If it receives a duplicate message id that it has already responded to, it should assume that the original response was lost (failed to return to the request issuer), and resend the original response in a new bundle. If the source application gets no response to its request from the destination application within a configurable timeout period, the source application should resend the same bundle with the same atom feed.id.
Applications may only claim to be conformant to "FHIR messaging" if they publish a conformance statement so the claim may be verified. A conformance statement lists all the message events they support, either as sender or listener, and for each event, a profile that states which resources are bundled (sender), or are required to be bundled (listener), and any rules about the information content of the individual resources. The conformance statement is a resource with the name "Conformance". TODO: make request and response profile mandatory.
There are two end-points defined for a RESTful server that supports Messages:
The first end-point is used for working within the message contents, for instance, for building messages piecemeal or for auditing received messages. Creating or updating Message resources to this end point does not represent the actual occurrence of any event, nor can it trigger any logic associated with the actual event. It is just for managing message resources.
The second end-point is used for actually sending messages as bundles, to indicate that the event identified by the code has occurred. The end-point responds with a message response as defined for the particular event, or an error indicating that the attempt to process the message was unsuccessful. The functionality of this end-point is described below.
Note: While the end-points above are defined for use with message resources and for delivering messages to a RESTful server, it is not necessary to use them; messages may be transported between systems using any method desired.
<Message xmlns="http://hl7.org/fhir"> <id><!-- 1..1 id id of this message --></id> <instant><!-- 1..1 instant Instant the message was sent --></instant> <event><!-- 1..1 code Code for the event his message represents --></event> <response> <!-- 0..1 If this is a reply to prior message --> <id><!-- 1..1 id Id of original message --></id> <code><!-- 1..1 code Type of response to the message --></code> <details><!-- 0..1 Resource(IssueReport) Specific list of hints/warnings/errors --></details> </response> <source> <!-- 1..1 Message Source Application --> <name><!-- 0..1 string Name of system --></name> <software><!-- 1..1 string Name of software running the system --></software> <version><!-- 0..1 string Version of software running --></version> <contact><!-- 0..1 Contact Human contact for problems --></contact> <endpoint><!-- 1..1 uri Actual message source address or id --></endpoint> </source> <destination> <!-- 1..1 Message Destination Application --> <name><!-- 0..1 string Name of system --></name> <target><!-- 0..1 Resource(Device) Particular delivery destination within the destination --></target> <endpoint><!-- 1..1 uri Actual destination address or id --></endpoint> </destination> <enterer><!-- 0..1 Resource(Agent) The source of the data entry --></enterer> <author><!-- 0..1 Resource(Agent) The source of the decision --></author> <receiver><!-- 0..1 Resource(Person|Organization) Intended "real-world" recipient for the data --></receiver> <responsible><!-- 0..1 Resource(Agent|Organization) Final responsibility for event --></responsible> <effective><!-- 0..1 Period Time of effect --></effective> <reason><!-- 0..1 CodeableConcept Cause of event --></reason> <data><!-- 0..* Resource(Any) The actual content of the message --></data> <extension><!-- 0..* Extension See Extensions --></extension> <text><!-- 1..1 Narrative Text summary of resource (for human interpretation) --></text> </Message>
Alternate definitions: Schema/Schematron, RDF (to do), XML, XMI (to do), Resource Profile
Terminology Bindings
| Path | Details | Strength |
|---|---|---|
| Message.event | the Event List in the messaging framework | complete/required |
| Message.response.code | The kind of response to a message (see http://hl7.org/fhir/response-code for values) | complete/required |
| Message.reason | The reason for an event occurring (not bound to any particular codes) | complete/unstated |
| Code | Description | Request | Response | Notes |
|---|---|---|---|---|
| MedicationAdministration-Complete | Change the stauts of a Medication Administration to show that it is complete. | MedicationAdministration | MedicationAdministration | |
| MedicationAdministration-Nullification | Someone wishes to record that the record of administration of a medication is in error and should be ignored. | MedicationAdministration | MedicationAdministration | |
| MedicationAdministration-Recording | Indicates that a medication has been recorded against the patient's record | MedicationAdministration | MedicationAdministration | |
| MedicationAdministration-Update | Update a Medication Administration record. | MedicationAdministration | MedicationAdministration | |
| admin-notify | Notification of a change to an administrative resource (either create or update). Note that there is no delete, though some administrative resources have status or period elements for this use | Animal | -- | |
| Device | -- | |||
| Group | -- | |||
| Organization | -- | |||
| Patient | -- | Patient Links cannot be updated using admin-notify. The links element must be empty | ||
| Person | -- | |||
| Device | -- | |||
| labreport-provide | Provide a lab report, or update a previously provided lab report | LabReport LabReport.patient LabReport.patient.person LabReport.patient.animal LabReport.admission LabReport.requestDetail.clinicalInfo LabReport.specimen LabReport.resultGroup.specimen | -- | |
| observation-provide | Provide a simple observation or update a previously provided simple observation | Observation Observation.subjectPatient Observation.subjectPatient.person Observation.subjectGroup Observation.subjectDevice Observation.subjectAnimal Observation.performerAgent Observation.performerAgent.person Observation.performerPatient Observation.performerPerson | -- | |
| patient-link | Notification that two patient records actually identify the same patient | Patient,Patient | -- | Follow ups: patient-unlink? |
| patient-unlink | Notification that previous advice that two patient records concern the same patient is now considered incorrect | Patient,Patient | -- |
The mailbox is the standard name for a service hosted on a RESTful server that accepts messages and processes them as transactions, and returns a message response appropriate for the message received. The server is under no obligation to do anything particular with the resources except as required by the semantics of the event code in the message resource. A server may choose to retain the resources and make them available on a RESTful interface, but is not required to do so. If the server returns 200 Ok, it must return a valid message that indicates what the outcome of the event processing is. An HTTP error indicates that the message was not processed successfully, and that it should be resubmitted (and doing so should not result in a duplicate message response). Repeated failures indicate either a fatal problem with the message or a problem with the receiving application.
The mailbox can also be used to accept documents. In this case, the document is "accepted" (the server takes responsibility for custody of the received document), and an HTTP status of 204 No Content is returned, or an HTTP error is returned. The server is under no obligation to do anything with the document except as specific trading partner agreements dictate.
The following rules apply to the mailbox:
This simple mailbox profile can be used by any HTTP end point that accepts FHIR messages or documents, not just FHIR RESTful servers.
Search Parameters for RESTful searches. The standard parameters also apply. See Searching for more information.
| $page : integer | Starting offset of the first record to return in the search set | single |
| $count : integer | Number of return records requested. The server is not bound to conform | single |
| $id : token | The logical resource id associated with the resource (must be supported by all servers) | single |
(See Searching).
This is an old version of FHIR retained for archive purposes. Do not use for anything else
Implementers are welcome to experiment with the content defined here, but should note that the contents are subject to change without prior notice.
© HL7.org 2011 - 2012. FHIR v0.06 generated on Tue, Dec 4, 2012 00:04+1100. License