DSTU2
This
page
is
part
of
the
FHIR
Specification
(v0.0.82:
(v1.0.2:
DSTU
1).
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
.
Page
versions:
R5
R4B
R4
R3
R2
|
FHIR
Infrastructure
Work
Group
| Maturity Level : N/A | Ballot Status : DSTU 2 |
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".
messaging"
(see
Conformance
).
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
Bundle
identified
by
the
tag
type
"http://hl7.org/fhir/tag/message",
"message",
with
the
first
resource
in
the
bundle
being
a
MessageHeader
resource.
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
or
more
response
messages
which
are
also
a
bundle
of
resources
identified
by
the
tag
type
"http://hl7.org/fhir/tag/message",
"message",
with
the
first
resource
in
the
each
bundle
being
a
MessageHeader
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
one
or
more
responses
will
be
returned
to
the
source
application.
The
exact
mechanism
of
transfer
is
irrelevant
to
this
specification,
but
may
include
file
transfer,
http
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,
though
this
specification
does
provide
a
direct
delivery
mechanism
below.
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
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
it's
its
content:
| Consequence |
The
message
represents/requests
a
change
that
should
not
be
processed
more
than
|
| 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 FHIR 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, or the context.
Each
FHIR
request
message
has
one
or
more
response
messages.
There
must
be
at
least
one
response
message
so
that
the
sender
can
know
that
the
message
was
properly
received.
Multiple
response
messages
SHALL
not
NOT
be
returned
for
messages
of
consequence,
and
SHOULD
not
be
returned
for
notifications.
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
-
are
is
the
easiest
to
understand
and
manage.
The
Mailbox
$process-message
operation
described
below
works
in
this
fashion.
However
synchronous
message
exchange
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.
Because
of
this,
other
complex
Additionally,
it
may
not
be
practical
or
appropriate
to
wait
for
response
messages.
In
these
cases,
the
asynchronous
message
patterns
are
allowed,
though
none
are
pattern
described
in
detail
in
this
specification.
below
should
be
used.
An
incoming
message
contains
two
identifiers:
the
envelope
id
(
feed
.id)
Bundle.id
and
the
message
.identifier.
MessageHeader
.id.
Each
time
a
new
message
is
created,
it
SHALL
be
assigned
an
identifier
(MessageHeader.id)
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
or
appropriately
chosen
URI
with
a
serially
incrementing
number.
OID.
Each
time
a
message
is
sent,
the
bundle
identifier
(feed.id)
Bundle.id
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
in
a
bundle
which
also
has
a
new
id.
The
response
message
also
quotes
the
request
message
identifier
MessageHeader.id
in
MessageHeader.response.identifier
so
that
the
source
system
can
relate
the
response
to
its
request.
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 that receivers SHOULD conform to in order to handle the absence of reliable messaging that maintains predictable functionality.
If
the
sender
of
the
message
implements
reliable
messaging,
it
SHALL
do
the
following
when
it
receives
no
response
to
a
message
within
a
configured
timeout
period:
period
based
on
the
value
specified
in
the
Conformance
messaging.event.category
for
the
event
associated
with
the
message:
| Consequence |
Resend
the
same
message
|
| Currency |
Resend
the
same
message
|
| Notification |
Resend
the
same
message
|
When
a
receiver
implements
reliable
messaging,
it
SHALL
check
the
incoming
envelope
id
Bundle.id
and
message
identifier
MessageHeader.id
against
a
cache
of
previously
received
messages.
The
correct
action
to
take
depends
on
what
is
received:
|
Both
the
|
This is the normal case, and the message should be processed |
| Both envelope and message already received | The original response has been lost (failed to return to the request issuer), and the original response SHALL be resent |
|
The
|
A previously seen message has been resubmitted for processing again. The server may either reprocess the message, or reject the message |
|
The
|
This
is
an
error
-
|
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 conformance 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
envelope
id
(feed.id)
Bundle.id
is
UUID
1
(urn:uuid:72edc4e0-6708-42ab-9734-f56721882c10),
(72edc4e0-6708-42ab-9734-f56721882c10),
with
a
Message
Header
that
contains
a
message
id
MessageHeader.id
of
UUID
2
(urn:uuid:dad53a57-dcb4-4f18-b066-7239eb4b5229).
(dad53a57-dcb4-4f18-b066-7239eb4b5229).
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.
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
it's
its
15
minute
cache
time),
and
the
two
UUIDs
1
and
2
match
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,
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 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
envelope
id
(feed.id)
Bundle.id
is
UUID
3
(urn:uuid:4c7f5cb2-5964-4d42-b719-e0227461818c),
(4c7f5cb2-5964-4d42-b719-e0227461818c),
with
a
Message
Header
that
contains
a
message
id
of
MessageHeader.id
is
UUID
4
(urn:uuid:63ED7D68-B2CC-421D-BA1C-A6C7785581F2).
(63ed7d68-b2cc-421d-ba1c-a6c7785581f2).
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
message
id
MessageHeader.id
(UUID
4),
but
creates
a
new
envelope
id
(feed.id):
(urn:uuid:c7c17fe4-9560-49c7-b2ae-42636476fb86).
Bundle.id
(c7c17fe4-9560-49c7-b2ae-42636476fb86).
In
this
case,
the
imaging
system
successfully
received
the
message,
and
processed
it.
When
it
receives
the
resent
order
after
1
minute
(which
is
within
it's
its
15
minute
cache
time),
it
sees
that
although
the
message
id
is
the
same,
the
envelope
id
Bundle.id
has
changed,
and
it
reprocesses
the
message
again,
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.
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
message
id,
MessageHeader.id,
and
so
an
active
intermediary
that
choose
the
re-initiate
a
query
that
it
previously
relayed
cannot
change
the
message
id.
MessageHeader.id.
This
protocol
avoids
the
need
for
the
message
id
MessageHeader.id
to
change,
and
only
requires
change
to
the
envelope
id
Bundle.id
which
is
never
the
basis
for
context
linking
outside
the
immediate
message
exchange
protocol
described
here.
Applications may only assert conformance to "FHIR messaging" if they publish a conformance statement so the claim may be verified. A conformance 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 conformance statement is a resource with the name "Conformance" .
The
mailbox
is
the
standard
name
for
a
service
hosted
on
a
simplest
way
to
handle
messages
where
there
are
also
RESTful
server
interactions
that
accepts
messages
and
processes
them
as
transactions
and
returns
a
message
response
appropriate
for
the
message
received.
The
server
occurring
is
under
no
obligation
to
do
anything
particular
with
use
the
resources
except
as
required
by
$process-message
.
This
operation
accepts
a
message,
processes
it
according
to
the
semantics
definition
of
the
event
code
in
the
message
resource.
A
header,
and
returns
a
one
or
more
response
messages.
For
example,
in
addition
to
processing
the
message
event,
a
server
may
choose
to
retain
all
or
some
the
resources
and
make
them
available
on
a
RESTful
interface,
but
is
not
required
to
do
so.
The
mailbox
can
also
be
used
to
accept
queries
or
documents.
In
the
case
of
documents,
the
document
is
"accepted"
(the
server
takes
responsibility
for
custody
of
the
received
document)
or
an
HTTP
error
is
returned.
The
server
is
under
no
obligation
to
perform
any
particular
processing
of
the
document
except
as
specific
trading
partner
agreements
dictate.
In
the
case
of
queries,
the
server
receives
a
bundle
containing
a
query
and
a
set
of
other
related
resources,
processes
the
query,
and
returns
a
bundle
with
a
query
which
is
a
response,
and
any
additional
resources
that
are
part
of
the
query
response.
2.3.3.2
Result
of
submission
Depending
on
the
semantics
of
the
event
code
or
When
processing
done
on
the
query
or
document,
messages,
a
server
may
return
a
status
code
of
200
OK,
201
Created,
202
Accepted
or
204
No
Content.
a
process/error
code
(300+).
If
the
server
returns
200
OK,
it
SHALL
return
a
bundle
with
that
is
the
outcome
of
message
response.
For
any
other
response
code,
the
event
or
document
processing.
In
case
of
errors,
message
has
not
been
successfully
processed.
The
server
MAY
return
an
OperationOutcome
with
additional
information,
and
SHOULD
do
so
if
the
response
code
is
400
or
greater.
The
client
SHALL
interpret
a
4xx
response
to
indicate
that
there
is
no
point
resubmitting
the
message
or
document,
unaltered
message,
and
a
5xx
response
to
indicate
an
unexpected
error
occurred
on
the
part
of
the
server,
which
means
with
the
implication
that
it
is
worth
resubmitting
(and
doing
may
be
appropriate
to
resubmit
the
original
message.
Doing
so
should
not
SHOULD
NOT
result
in
a
duplicate
message
response).
Repeated
failures
indicate
either
a
fatal
problem
with
the
submission
or
a
problem
with
the
receiving
application.
The
following
rules
apply
to
the
mailbox:
when
using
$process-message:
This
simple
mailbox
profile
The
$process-message
operation
can
be
used
by
any
HTTP
end
point
end-point
that
accepts
FHIR
messages
or
documents,
messages,
not
just
FHIR
RESTful
servers.
In
order
to
ensure
consistency
of
processing,
the
logical
rules
regarding
processing
of
envelope
id
Bundle.id
and
message
id
described
above
SHALL
be
followed
when
messages
are
processed
using
this
operation.
The $process-message operation may be used synchronously, or asynchronously.
Synchronous
messaging
is
the
mailbox.
No
such
easiest
to
understand;
the
sender
sends
a
message
to
the
receiver
(the
server),
the
server
processes
it,
and
then
returns
a
response.
Usually
(though
not
always)
the
sender
waits
for
the
response
to
the
current
message
before
sending
the
next
message.
This
kind
of
messaging
exchange
is
the
most
common
because
it's
the
simplest
to
understand.
The
following
rules
apply
regarding
documents
-
if
when
using
the
client
receives
$process-message
operation
synchronously:
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.
The following rules apply when using the $process-message operation synchronously:
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 is less reliable than 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.
As well as this messaging framework documented here, FHIR also defines a RESTful API . 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
a
administration
resource
has
been
created
or
updated,
as
does
updated;
the
REST
API.
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.
As a resource that can be used with the RESTful framework, the MessageHeader resource has the normal resource end-point (/MessageHeader), which is used to manage a set of static message resources. This could be used to make an archive of past messages available. Creating or updating MessageHeader resources in this fashion 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 a set of message header resources.
It
is
possible
to
exchange
messages
can
be
transported
between
systems
using
any
other
method
by
which
the
RESTful
end-point
as
a
stream
central
point
of
bytes
(the
exchange.
This
is
not
particularly
efficient
compared
to
other
methods,
but
is
useful
for
low-volume
axynchronous
exchange.
To
send
a
message,
a
sender
posts
the
message
bundle)
can
be
moved
from
one
place
bundle
to
another.
There
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,
and
indexes
it
on
the
MessageHeader
.
To receive messages, a receiver searches for all messages destined for itself, since it's last check:
GET [base]/Bundle?message.destination-uri=[rcv]&_lastUpdated=>2015-03-01T02:00:02+01:00
The
receiver
works
through
the
response,
processing
each
message.
As
each
message
is
no
requirement
processed,
the
receiver
creates
a
response
message,
reversing
the
source
and
destination,
and
posts
it
back
to
use
HTTP.
the
server.
To check for responses, the original sender searches for response messages destined for itself, since it's last check:
GET [base]/Bundle?message.destination-uri=[snd]&message.response-id:missing=false
&_lastUpdated=>2015-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
element
carries
a
Coding
that
identifies
the
event
that
the
message
conveys.
This
table
lists
the
message
event
codes
defined
in
this
specification
(the
system
value
for
these
is
"http://hl7.org/fhir/message-type"):
"
http://hl7.org/fhir/message-events
"):
The
request
and
response
details:
The
column
values
are
either
a
resource
that
is
included
as
part
of
the
result
response,
or
an
element
that
refers
to
another
resource,
which
means
that
the
target
of
processing
these
references
SHALL
also
be
in
the
query.
query
--
Used
when
queries
are
performed
asynchronously
message.
In
this
table,
the
request
and
response
columns
list
the
focus
resource
for
the
event,
along
with
other
resources
that
should
also
be
carried
in
the
message
directly
(if
they
exist).
DSTU Note: Additional events may be defined elsewhere, though this specification does not yet define how.
DSTU: Input on thisFeedback is sought
duringhere
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
refers
to
a
Parameters
resource
The recipient executes the operation as specified, and then:
MessageHeader.data
refers
to
a
Parameters
resource
Here's an example:
<Bundle xmlns="http://hl7.org/fhir">
<id value="urn:uuid:77831928-2a35-4c08-9496-8232323bf48c"/>
<!-- normal bundle stuff -->
<entry>
<fullUrl value="urn:uuid:6080d4a7-5e05-45dc-96d5-f75329564d1f"/>
<resource>
<MessageHeader>
<id value="cac8143e-6138-4f45-b086-bb8ebf976aae">
<!-- normal message header stuff -->
<event>
<system value="urn:ietf:rfc:3986"/>
<!-- value set expansion -->
<code value="http://hl7.org/fhir/OperationDefinition/ValueSet-expand"/>
</event>
<!-- 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 that a defined operation can be invoked, a regular search operation can be invoked. This also uses the Parameters resource, with the following rules:
| 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 or Quantity (split the syntax out) |
| uri | uri |
Here's an example:
<Bundle xmlns="http://hl7.org/fhir">
<id value="urn:uuid:77831928-2a35-4c08-9496-8232323bf48c"/>
<!-- normal bundle stuff -->
<entry>
<fullUrl value="urn:uuid:c466754c-09c0-4f59-9f76-a48bd0ea27c9"/>
<resource>
<MessageHeader>
<!-- normal message header stuff -->
<event>
<system value="http://hl7.org/fhir/restful-interaction"/>
<!-- Search against Patient -->
<code value="search-type"/>
</event>
<!-- more normal message header stuff -->
<data>
<reference value="urn:uuid:59a17a19-46eb-42d9-821a-f93a0c530cac"/>
</data>
</MessageHeader>
</resource>
</entry>
<entry>
<fullUrl value="urn:uuid:59a17a19-46eb-42d9-821a-f93a0c530cac"/>
<resource>
<Parameters>
<parameter>
<name value="resourceType"/>
<valueString value="Patient"/>
</parameter>
<parameter>
<name value="gender"/>
<valueString value="m"/>
</parameter>
</Parameters>
</resource>
</entry>
</Bundle>
©
©
HL7.org
2011+.
FHIR
DSTU
(v0.0.82.2943)
DSTU2
(v1.0.2-7202)
generated
on
Tue,
Sep
30,
2014
18:10+1000.
Sat,
Oct
24,
2015
07:44+1100.
Links:
What's
a
DSTU?
Search
|
Version
History
|
Table
of
Contents
|
Compare
to
DSTU1
|
|
Propose
a
change