Release
4
5
Exchange
This
page
is
part
of
the
FHIR
Specification
(v4.0.1:
R4
(v5.0.0:
R5
-
Mixed
Normative
and
STU
)
).
This
is
the
current
published
version
in
it's
permanent
home
(it
will
always
be
available
at
this
URL).
The
current
version
which
supercedes
this
version
is
5.0.0
.
For
a
full
list
of
available
versions,
see
the
Directory
of
published
versions
.
Page
versions:
R5
R4B
R4
R3
R2
|
FHIR
Infrastructure
Work
Group
|
Maturity Level : 3 | Standards Status : Trial Use |
FHIR
Resources
can
be
used
in
a
traditional
messaging
context,
much
like
HL7
v2
V2
(see
detailed
comparison
).
Applications
asserting
conformance
to
this
framework
claim
to
be
conformant
to
"FHIR
messaging"
(see
Conformance
).
In
FHIR
messaging,
a
"request
message"
"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
real-world.
Messages
are
Bundle
identified
by
resources,
with
the
following
rules:
message
MessageHeader
The MessageHeader resource has a code - the message event - that identifies the nature of the request message, and it also 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
zero
or
more
response
messages
which
are
also
a
bundle
of
resources
identified
by
the
type
"message",
with
the
first
resource
in
each
bundle
being
a
MessageHeader
resource
with
a
response
section
that
reports
the
outcome
of
processing
the
message
and
any
additional
response
resources
required.
The message bundle SHALL include only the MessageHeader resource, and any resources directly or indirectly (e.g. recursively) referenced from it.
This
specification
assumes
that
content
will
be
delivered
from
one
application
to
another
by
some
delivery
mechanism,
and
then
one
or
more
responses
will
be
returned
to
the
source
application.
The
This
specification
provides
a
direct
delivery
mechanism
below,
although
the
exact
mechanism
of
transfer
is
irrelevant
to
this
specification,
but
can
be
abstracted,
and
may
include
file
transfer,
HTTP
based
transfer,
MLLP
(HL7
minimal
lower
layer
protocol),
Apache
Kafka,
MQ
series
messaging
messaging,
or
anything
else.
It
is
expected
that
these
additional
types
of
transfer
mechanisms
will
define
their
own
implementation
guides
to
define
the
exact
message
transfer
protocol.
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,
though
this
specification
does
provide
a
direct
delivery
mechanism
below.
specification.
The agreements around the content of the messages and the behavior of the two applications form the "contract" that describes the exchange. The contract will add regional and local agreements to the rules defined in this specification.
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 (in particular, the source and destination headers are often changed). If these middleware agents are modifying the message content, then they become responsible for honoring the contract that applies (including applicable profiles) in both directions.
A key aspect of a message is the impact of its content:
| consequence | The message represents/requests a change that should not be processed more than once; e.g., making a booking for an appointment. |
| currency | The message represents a response to query for current information. Retrospective processing is wrong and/or wasteful. |
| notification | The content is not necessarily intended to be current, and it can be reprocessed, though there may be version issues created by processing old notifications. |
Some Events defined by a FHIR IG are assigned to one of these categories, but others are not able to be categorized in advance, and the category must be determined by the content, context, or use case.
When it is necessary to receive an acknowledgement from multiple parties for a message of notification it becomes a message of consequence: The sender will have to send multiple messages, even if they have the same endpoint.
Another key aspect of a message is the impact of its destination.receiver. In some circumstances it may be sufficient to direct a message to an endpoint, while in others it may be necessary to direct the message to a specific organization or person.
| Consequence | A message of consequence SHOULD have one and only one receiver specified. |
| Currency | A message of currency MAY have one or more receivers specified. |
| Notification |
A
message
of
|
Each
FHIR
request
message
typically
has
one
or
more
response
messages.
There
must
be
at
least
one
The
response
message
so
that
message(s)
inform
the
sender
can
know
that
the
message
was
properly
received.
Multiple
response
messages
SHALL
NOT
be
returned
for
messages
of
consequence,
and
SHOULD
not
be
returned
for
notifications.
For
some
notification
scenarios
it
reasonable
to
only
expect
either
only
an
http
response,
possibly
accompanied
by
an
OperationOutcome.
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.
For this reason, a synchronous exchange pattern - where the sender sends a message, and waits on the same channel for a single response, and then sends the next message - is the easiest to understand and manage:
This kind of messaging exchange is the most common because it's the simplest to understand.
However
The
synchronous
message
exchange
described
above,
however,
does
not
cater
for
multiple
response
messages,
which
may
arise
when
processing
queries,
and
also
imposes
through-put
limitations
which
may
become
relevant
at
high
volumes.
Additionally,
it
might
not
be
practical
or
appropriate
to
wait
for
response
messages.
In
these
cases,
the
asynchronous
message
pattern
should
be
used.
In Asynchronous messaging, the server acknowledges receipt of the message immediately, and responds to the sender separately. The server may respond more than once to any given message.
When
a
message
is
received,
a
receiver
can
determine
from
the
content
of
the
message
header
whether
it's
a
new
message
to
process,
or
a
response
to
a
message
that
has
already
been
sent.
Note
that
asynchronous
messaging
can
be
harder
to
implement
due
to
the
amount
of
complexity
opposed
compared
to
synchronous
messaging;
more
can
go
wrong.
This
specification
does
not
dictate
any
particular
error
handling
protocols
or
responsibilities;
these
are
left
to
trading
partner
agreements
between
implementers.
Implementation Note: Previous releases used a combination of Bundle.id and MessageHeader.id in an attempt to establish the message identity. This posed problems when crossing the boundaries between messaging and RESTful exchange. The current release uses Bundle.identifier exclusively to establish and maintain the message identity. The subsequent sections reflect this change.
A message has 2 important timestamps:
In addition, the message may have additional timestamps in additional resources in the message, either .meta.lastUpdated or others throughout the resources. The meaning of these will depend on the message event.
An
incoming
message
contains
two
identifiers:
the
Bundle.id
and
exactly
one
Bundle.identifier
which
identifies
the
MessageHeader
.id.
message.
Each
time
a
new
message
is
created,
it
SHALL
be
assigned
an
identifier
(MessageHeader.id)
(Bundle.identifier)
that
is
unique
within
that
message
stream.
Note
that
since
message
streams
are
often
merged
with
other
streams,
it
is
recommended
that
the
identifier
should
be
globally
unique.
This
can
be
achieved
by
using
a
UUID
or
an
OID.
Each
time
a
message
is
sent,
the
Bundle.id
Bundle.identifier
should
be
changed
to
a
new
value.
When
a
receiver
receives
and
processes
the
message,
it
responds
with
a
new
message
with
a
new
identifier,
wrapped
contained
in
a
bundle
which
also
has
a
new
id.
the
Bundle.identifier
element
of
the
wrapping
bundle.
The
response
message
also
quotes
the
request
MessageHeader.id
Bundle.identifier
in
MessageHeader.response.identifier
so
that
the
source
system
can
relate
the
response
to
its
request.
A
message
has
2
important
timestamps:
Bundle.timestamp
:
the
time
the
message
was
sent
Bundle.meta.lastUpdated
:
Note
that
Bundle.id
and
MessageHeader.id
also
must
be
present,
according
to
the
last
time
rules
of
the
message
was
updated
(either
by
storing,
or
by
modification)
In
addition,
underlying
Resource.id
definition,
which
allows
the
message
may
have
additional
timestamps
in
potential
additional
resources
in
the
message,
either
.meta.lastUpdated
or
others
throughout
the
resources.
The
meaning
complementary
use
of
these
will
depend
on
resources
using
the
message
event.
FHIR
RESTful
API.
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.
For
systems
exchanging
FHIR
messaging
messages
over
infrastructure
that
does
not
guarantee
reliable
messaging,
the
remainder
of
this
section
describes
a
simple
approach
that
senders
and
receivers
SHOULD
conform
to
in
order
to
handle
the
absence
of
reliable
messaging
that
ensures
reliable
delivery
and
maintains
predictable
functionality.
If
the
a
sender
of
the
message
implements
reliable
messaging,
this
protocol,
it
SHALL
do
the
following
when
it
receives
no
response
to
a
message
within
a
configured
timeout
period
based
on
the
value
specified
in
the
CapabilityStatement
messaging.event.category
for
the
event
associated
with
the
message:
| Consequence |
|
| Currency |
|
| Notification |
|
When
a
receiver
implements
reliable
messaging,
it
SHALL
check
the
incoming
Bundle.id
and
MessageHeader.id
Bundle.identifier
against
a
cache
of
previously
received
messages.
The
correct
action
to
take
depends
on
what
is
received:
|
|
|
|
|
The original response has been lost (failed to return to the request issuer), and the original response SHALL be resent |
The duration period for caching does generally not need to be very long. At a minimum, it could be 1 minute longer than the timeout of the sending system, though it may need to be longer depending on the re-sending policies of the sending system.
Applications that implement reliable messaging declare their reliable cache period in their Capability Statement .
In
the
first
example,
a
Clinical
EHR
issues
an
order
for
a
particular
imaging
examination
to
be
performed
on
a
patient.
This
is
considered
to
be
a
message
of
Consequence
:
multiple
orders
should
not
be
created
(in
practice
there
are
usually
human
review
processes
that
catch
multiple
orders,
but
repeat
orders
create
entropy
in
the
system
that
is
harmful).
The
EHR
sends
a
message
where
the
Bundle.id
Bundle.identifier
is
UUID
1
(72edc4e0-6708-42ab-9734-f56721882c10),
with
a
MessageHeader.id
of
UUID
2
(dad53a57-dcb4-4f18-b066-7239eb4b5229).
(72edc4e0-6708-42ab-9734-f56721882c10).
The
EHR
system
never
receives
a
response
to
the
message;
it
does
not
know
whether
the
request
message
got
lost,
or
the
imaging
management
systems
was
unable
to
process
the
request,
or
whether
it
successfully
processed
the
message
and
the
response
was
lost.
In
this
case,
the
EHR
system
resends
the
message
with
same
two
identifiers.
Bundle.identifier.
In
this
case,
the
imaging
system
successfully
received
the
message,
and
processed
it.
Because
it
receives
the
resent
order
after
1
minute
(which
is
within
its
15
minute
cache
time),
and
the
two
UUIDs
UUID
1
and
2
match
matches
the
Bundle.identifier
of
a
message
it
has
already
processed,
it
knows
that
it
already
processed
the
order,
and
simply
returns
the
previous
response.
In
the
case
of
additional
resent
queries,
requests,
the
application
keeps
sending
the
original
response,
though
it
may
also
alert
system
administrators
that
the
same
original
message
keeps
being
resent,
since
lost
messages
should
be
a
rare
occurrence.
When
the
EHR
system
finally
receives
the
message,
it
knows
how
the
imaging
management
system
responded;
it
can
be
sure
because
the
message
id
Bundle.identifier
from
the
original
request
is
echoed
in
the
response
portion
of
the
returned
message.
In
this
second
example,
a
Clinical
EHR
needs
to
know
what
appointment
slots
are
available
for
a
particular
imaging
procedure.
This
is
a
message
of
Currency
:
available
slots
are
ever
disappearing,
and
ordering
a
slot
that
has
become
unavailable
is
a
waste
of
time
for
the
humans
and
systems
involved.
The
EHR
sends
a
message
where
the
Bundle.id
is
UUID
3
(4c7f5cb2-5964-4d42-b719-e0227461818c),
with
a
MessageHeader.id
Bundle.identifier
is
UUID
4
(63ed7d68-b2cc-421d-ba1c-a6c7785581f2).
2
(4c7f5cb2-5964-4d42-b719-e0227461818c)
The
EHR
system
never
receives
a
response
to
the
message;
it
does
not
know
whether
the
request
message
got
lost,
or
the
imaging
management
systems
was
unable
to
process
the
request,
or
whether
it
successfully
processed
the
message
and
the
response
was
lost.
In
this
case,
the
EHR
system
resends
the
message
with
same
MessageHeader.id
(UUID
4),
but
creates
a
new
Bundle.id
different
Bundle.identifier
UUID
3
(c7c17fe4-9560-49c7-b2ae-42636476fb86).
In
this
case,
the
imaging
system
successfully
received
the
first
message,
and
processed
it.
When
it
receives
the
resent
order
after
1
minute
(which
is
within
its
15
minute
cache
time),
it
sees
that
although
the
a
new
message
id
is
the
same,
the
Bundle.id
has
changed,
of
currency
with
Bundle.identifier
UUID3,
and
it
reprocesses
processes
the
message
again,
new
message,
and
sends
a
new
response.
When the EHR system finally receives the message, it knows the current slot availability on the imaging management system responded. If for some reason both responses arrive, the EHR system knows that the response linked to the message with UUID 3 is the more current.
Note
that
the
existence
of
active
intermediaries
(or
"middleware")
creates
the
need
for
this
protocol
-
the
original
sender
matches
the
response
to
the
request
based
on
the
MessageHeader.id,
Bundle.identifier,
and
so
an
active
intermediary
that
choose
chooses
the
re-initiate
a
query
that
it
previously
relayed
cannot
change
the
MessageHeader.id.
This
protocol
avoids
the
need
for
the
MessageHeader.id
to
change,
and
only
requires
change
to
the
Bundle.id
which
is
never
the
basis
for
context
linking
outside
the
immediate
message
exchange
protocol
described
here.
Bundle.identifier.
Applications may only assert conformance to "FHIR messaging" if they publish a Capability statement so the claim may be verified. A Capability statement lists all the message events supported (either as sender or receiver) and for each event, a profile that states which resources are bundled (sender), or are required to be bundled (receiver), and any rules about the information content of the individual resources.
The
simplest
way
to
handle
messages
where
there
are
also
RESTful
interactions
occurring
is
to
use
the
$process-message
.
This
operation
accepts
a
message,
processes
it
according
to
the
definition
of
the
event
in
the
message
header,
and
returns
a
one
or
more
response
messages.
See
the
opreation
operation
definition
for
further
details.
As
well
as
this
The
messaging
framework
documented
here,
here
is
in
addition
to
the
FHIR
also
defines
a
RESTful
API
.
defined
in
this
specification.
The
messaging
and
RESTful
frameworks
are
related
in
that
both
share
the
same
set
of
resources
on
which
they
operate.
In
fact,
the
basic
MessageHeader
resource
that
the
messaging
framework
is
implemented
is
itself
a
resource
that
can
treated
in
a
RESTful
approach.
The kinds of functionality that the RESTful API and the messaging framework offer are very similar; their primary difference is architectural in nature.
For instance, the messaging framework defines an event for notifying that an administration resource has been created or updated; the REST API offers similar services ( history and Subscription ). On the other hand, there are differences in the capabilities offered - while a patient merge can be implemented as a series of RESTful operations performed by the client that update all resources linked to the patient, when a message command to merge patient records is processed, the server will do all the work, and is also able to merge in areas not exposed on the RESTful API. The REST API, however, provides a set of basic operations on all resources that would need special definitions in the messaging framework - definitions that are not provided.
There is no expectation that RESTful systems will need to offer messaging support, or vice versa, though systems may find it useful to support both sets of functionality in order to satisfy a wider range of implementers.
In such systems, the RESTful representation of the message is the complete Bundle resource, as the message identity is always driven by the Bundle (and Bundle.identifier). The MessageHeader within the Bundle does not have reliable identity.
As
a
resource
that
can
be
used
with
the
RESTful
framework,
the
MessageHeader
resource
has
the
normal
resource
end-point
(/MessageHeader),
(/MessageHeader).
A
FHIR
server,
which
is
used
also
a
message
sender,
can
use
a
MessageHeader
instance
to
manage
stage
the
creation
of
a
set
message,
for
example:
It is possible to exchange messages using the RESTful end-point as a central point of exchange. This is not particularly efficient compared to other methods, but is useful for low-volume asynchronous exchange.
To
send
a
message,
a
sender
posts
the
message
bundle
to
the
/Bundle
end-point,
with
a
uri
that
identifies
the
receiver
at
MessageHeader.destination.endpoint
.
The
RESTful
server
accepts
the
bundle,
stores
it
as
a
single
bundle,
resource,
and
indexes
it
on
the
contents
of
the
included
MessageHeader
.
To receive messages, a receiver searches for all messages destined for itself, since its last check:
GET [base]/Bundle?message.destination-uri=[rcv]&_lastUpdated=>2015-03-01T02:00:02+01:00GET [base]/Bundle?message.destination-uri=[rcv]&_lastUpdated=gt2015-03-01T02:00:02+01:00
The receiver works through the response, processing each message. As each message is processed, the receiver creates a response message, reversing the source and destination, and posts it back to the server.
To check for responses, the original sender searches for response messages destined for itself, since its last check:
GET [base]/Bundle?message.destination-uri=[snd]&message.response-id:missing=false&_lastUpdated=>2015-03-03T06:03:522+01:00&_lastUpdated=gt2015-03-03T06:03:522+01:00
This lightweight protocol needs ongoing administration to ensure that multiple parties do not interfere with each other by re-using the same system identifier (and against malicious attack).
The
message.code
MessageHeader.event[x]
element
carries
a
Coding
that
identifies
the
event
that
the
message
conveys.
Events may be defined using the MessageDefinition resource. This specification does not define any events, but may do so in the future if implementers find this useful.
A message can be used to invoke an operation as defined for a RESTful interface using an operation definition. To invoke an operation using a message:
urn:ietf:rfc:3986
OperationDefinition.url
MessageHeader.data
MessageHeader.focus
refers
to
a
Parameters
resource
The recipient executes the operation as specified, and then:
MessageHeader.data
MessageHeader.focus
refers
to
a
Parameters
resource
Here's an example:
<Bundle xmlns="http://hl7.org/fhir"><id value="urn:uuid:77831928-2a35-4c08-9496-8232323bf48c"/><id value="77831928-2a35-4c08-9496-8232323bf48c"/> <identifier> <system value="urn:example-org:sender.identifiers"/> <value value="6daec3d0-e3ee-42d4-a51d-50cfacad94a9"/> </identifier> <type value="message"/> <!-- normal bundle stuff --> <entry> <fullUrl value="urn:uuid:6080d4a7-5e05-45dc-96d5-f75329564d1f"/> <resource> <MessageHeader><id value="cac8143e-6138-4f45-b086-bb8ebf976aae"><id value="6080d4a7-5e05-45dc-96d5-f75329564d1f"/> <!-- normal message header stuff --><event><eventCoding> <system value="urn:ietf:rfc:3986"/> <!-- value set expansion --> <code value="http://hl7.org/fhir/OperationDefinition/ValueSet-expand"/></event></eventCoding> <!-- more normal message header stuff --><data> <reference value="urn:uuid:00213637-dc7c-40d2-a7de-f4ef1eea5685"/> </data></MessageHeader> </resource> </entry> <entry> <fullUrl value="urn:uuid:00213637-dc7c-40d2-a7de-f4ef1eea5685"/> <resource> <Parameters> <parameter> <name value="identifier"/> <valueUri value="http://hl7.org/fhir/ValueSet/identifier-type"/> </parameter> </Parameters> </resource> </entry> </Bundle>
Note that there's no way to anchor the execution of the operation against a URL. The only operations that can be executed in this way are defined to be executed at the System or Resource level for a particular resource.
In
the
same
way
To
perform
a
search
with
messaging
that
mirrors
REST
functionality,
the
message
should
leverage
a
defined
operation
can
be
invoked,
Parameters
instance
with
a
regular
standard
parameter
name
of
"url"
and
a
valueString
that
corresponds
to
the
search
operation
can
string
that
would
typically
be
invoked.
This
also
uses
to
the
Parameters
resource,
with
right
of
the
following
rules:
base
URL.
E.g.
if
in
REST
you
would
say
http://someserver.org/fhir/Patient?name=joe
code>,
then
the
parameter
would
have
a
value
of
Patient?name=joe
.
The
event
in
this
case
would
be
either
code
is
"search-type"
search-type
or
"search-system"
search-system
in
the
system
http://hl7.org/fhir/restful-interaction
.
(If
If
the
event
type
search-system
is
"search-type"
there
SHALL
be
a
parameter
"resourceType"
used,
the
string
would
start
with
specifies
a
?
rather
than
[resource]?
.)
Systems
would
indicate
support
for
this
search
mechanism
using
their
CapabilityStatement
as
they
would
any
other
messaging
event.
If
a
system
supports
messaging
search
but
not
RESTful
search,
the
type
means
of
resource
being
searched
The
describing
any
limitations
on
what
resources,
search
parameters
are
converted
to
FHIR
data
types
according
parameters,
qualifiers,
etc.
they
support
is
not
currently
defined.
Messaging
interfaces
may
also
choose
to
the
following
table
Search
Parameter
Type
Data
Type
number
integer
date
dateTime
string
string
token
string
or
Coding
(split
the
system
and
code
apart)
reference
uri
composite
string
quantity
string
define
alternative
search
mechanisms
including
query-by-example
searches
that
pass
in
a
partially
completed
resource,
or
Quantity
(split
the
syntax
out)
uri
uri
Here's
an
example:
that
use
a
Parameters
instance
populated
in
other
ways.
FHIR
®©
HL7.org
2011+.
FHIR
Release
4
(Technical
Correction
#1)
(v4.0.1)
R5
hl7.fhir.core#5.0.0
generated
on
Fri,
Nov
1,
2019
09:37+1100.
QA
Page
Sun,
Mar
26,
2023
15:26+1100.
Links:
Search
|
Version
History
|
Table
of
Contents
|
Credits
Glossary
|
QA
|
Compare
to
R3
R4
|
Compare
to
R4B
|
|
Propose
a
change