Messageheader-operation-process-message

Snapshot 3: Connectathon 32 Base

This page is part of the FHIR Specification (v5.0.0-snapshot3: R5 Snapshot #3, to support Connectathon 32). 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

2.16.10.1 Operation $process-message on MessageHeader

Infrastructure And Messaging icon

Work Group

Maturity Level: 4

Trial Use

Compartments: N/A

This operation accepts a message, processes it according to the definition of the event in the message header, and returns one or more response messages.

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 canonical URL for this operation definition is

 http://hl7.org/fhir/OperationDefinition/MessageHeader-process-message

Formal Definition (as a OperationDefinition).

URL: [base]/$process-message

This is not an idempotent operation

In Parameters:

Name

Cardinality

Type

Binding

Profile

Documentation

content

1..1

Bundle

The message to process (or, if using asynchronous messaging, it may be a response message to accept)

async

0..1

boolean

If 'true' the message is processed using the asynchronous messaging pattern

response-url

0..1

url

A URL to submit response messages to, if asynchronous messaging is being used, and if the MessageHeader.source.endpoint is not the appropriate place to submit responses

Out Parameters:

Name

Cardinality

Type

Binding

Profile

Documentation

return

0..1

Bundle

A response message, if synchronous messaging is being used (mandatory in this case). For asynchronous messaging, there is no return value

Note: as this is the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

This operation does not use the parameters resource; the parameters "async" and "response-url" always go in the URL, if they are used, and the "content" parameter is always the body of the HTTP message.

When processing messages, a server may return one of several status codes:

200 OK: Indicates that the message has been fully processed. If an application-level response is expected for the submitted message, that response SHALL be returned as the body of the 200 response.
202 Accepted: Indicates that the receiving system has accepted custody of the message
204 No Content: Indicates that the message has been fully processed and would normally have had an application-level response, but because of instructions from the sender (e.g. the messageheader-response-request extension), no response is being provided
300+: Indicates that the message was not 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 unaltered message, and a 5xx response to indicate an unexpected error occurred on the part of the server, with the implication that it may be appropriate to resubmit the original message. Doing so 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 when using $process-message:

The operation only accepts POST transactions - any other HTTP method will result in an HTTP error
The request content type submitted is always Bundle with type "message" containing a Message Header resource as the first resource
The response content type returned, if not empoty, is always Bundle with type "message" containing a Message Header resource as the first resource, or an HTTP error
If the response is an error, the body SHOULD be an OperationOutcome resource with full details of the Errors &mp; Warning
The mailbox may be authenticated using standard HTTP authentication methods, including OAuth

The $process-message operation can be used by any HTTP end-point that accepts FHIR messages, not just FHIR RESTful servers.

In order to ensure consistency of processing, the logical rules regarding processing of Bundle.id and message id SHALL be followed when messages are processed using this operation.

The $process-message operation may be used synchronously, or asynchronously.

The following rules apply when using the $process-message operation synchronously:

The URL (http://server/base/$process-message) has no parameters
It is an error if the sender POSTs a message that requires multiple response messages
Servers SHALL accept multiple concurrent message submissions and process them correctly (they are allowed to process them sequentially internally, but multiple concurrent submissions is not an error in its own right)

The following rules apply when using the $process-message operation asynchronously:

The URL has at least one parameter: http://server/base/$process-message?async=true
The server acknowledges the message with a 200 OK with no body, or returns an HTTP error if the message cannot be processed
Accepting the message means that the server has understood the message enough to know where to respond
An OperationOutcome SHOULD be returned in either case
By default, the server responds by invoking the $process-message using the sender's stated end-point in the message: POST [MessageHeader.source.endpoint]/$process-message]
Since the source end-point may be manipulated by message transfer engines, an alternative response address may be specified using the parameter "response-url": http://server/base/$process-message?async=true&response-url=http://server2.com/base/anything. The endpoint at the specified URL SHALL implement the signature of the $process-message operation (parameter async=true, accept a Bundle, return a 200 OK or an error)
The server submits response messages to the appropriate end-point with the parameter async=true. There is no response message for the response messages

2.16.10.1.1 Examples

Request: Request to link 2 patients, and respond asynchronously

POST /ehr/fhir/$process-message?async=true&response-url=http://example.org/clients/ehr-lite
[other headers]

<?xml version="1.0" encoding="UTF-8"?>
<Bundle xmlns="http://hl7.org/fhir">
	<id value="10bb101f-a121-4264-a920-67be9cb82c74"/>
	<type value="message"/>
	<timestamp value="2015-07-14T11:15:33+10:00"/>
	<entry>
		<fullUrl value="urn:uuid:267b18ce-3d37-4581-9baa-6fada338038b"/>
		<resource>
			<MessageHeader>
				<!-- 
          Note about the id: according to the spec, the fullUrl must not 
          disagree with the id in the resource. For instance, if the fullUrl 
          was http://server/path/MessageHeader/267b18ce-3d37-4581-9baa-6fada338038b,
          then the id of the resource must be 267b18ce-3d37-4581-9baa-6fada338038b.
          
          However, in this case, a fullUrl of urn:uuid:[x] makes no claim about
          the id of the resource, and it can be different, or missing. Note, though
          that this doesn't really make sense; if it's present, there's less 
          potential for confusion if they match, like in this case
        -->
				<id value="267b18ce-3d37-4581-9baa-6fada338038b"/>
				<text>
					<status value="generated"/>
					<div xmlns="http://www.w3.org/1999/xhtml">
						<p>This message is a request to link Patient records 654321 (Patient Donald DUCK @ Acme Healthcare, Inc) and 123456 (Patient Donald D DUCK @ Acme Healthcare, Inc)</p>
					</div>
				</text>
				<eventCoding>
					<system value="http://example.org/fhir/message-events"/>
					<code value="patient-link"/>
				</eventCoding>
				<source>
					<endpoint value="http://example.org/clients/ehr-lite"/>
				</source>

				<responsible>
					<reference value="http://acme.com/ehr/fhir/Practitioner/2323-33-4"/>
				</responsible>
				<response>
					<identifier>
						<value value="efdd254b-0e09-4164-883e-35cf3871715f"/>
					</identifier>
					<code value="ok"/>
				</response>	
		<!--  this message is posted to http://acme.com/ehr/fhir, 
             with an event 'link' to link 2 patient records, and nominates
             2 patients on the server  -->
				<focus>
					<reference value="http://acme.com/ehr/fhir/Patient/pat1"/>
				</focus>
				<focus>
					<reference value="http://acme.com/ehr/fhir/Patient/pat12"/>
				</focus>
			</MessageHeader>
		</resource>
	</entry>
	<entry>
		<fullUrl value="http://acme.com/ehr/fhir/Patient/pat1"/>
		<resource>
			<Patient>
				<id value="pat1"/>
				<text>
					<status value="generated"/>
					<div xmlns="http://www.w3.org/1999/xhtml">
						<p>Patient Donald DUCK @ Acme Healthcare, Inc. MR = 654321</p>
					</div>
				</text>
				<identifier>
					<use value="usual"/>
					<type>
						<coding>
							<system value="http://terminology.hl7.org/CodeSystem/v2-0203"/>
							<code value="MR"/>
						</coding>
					</type>
					<system value="urn:oid:0.1.2.3.4.5.6.7"/>
					<value value="654321"/>
				</identifier>
				<active value="true"/>
				<name>
					<use value="official"/>
					<family value="Donald"/>
					<given value="Duck"/>
				</name>
				<gender value="male"/>
				<contact>
					<relationship>
						<coding>
							<system value="http://example.org/fhir/CodeSystem/patient-contact-relationship"/>
							<code value="E"/>
						</coding>
					</relationship>
					<organization>
						<reference value="Organization/1"/>
						<display value="Walt Disney Corporation"/>
					</organization>
				</contact>
				<managingOrganization>
					<reference value="Organization/1"/>
					<display value="ACME Healthcare, Inc"/>
				</managingOrganization>
			</Patient>
		</resource>
	</entry>
	<entry>
		<fullUrl value="http://acme.com/ehr/fhir/Patient/pat12"/>
		<resource>
			<Patient>
				<id value="pat2"/>
				<text>
					<status value="generated"/>
					<div xmlns="http://www.w3.org/1999/xhtml">
						<p>Patient Donald D DUCK @ Acme Healthcare, Inc. MR = 123456</p>
					</div>
				</text>
				<identifier>
					<use value="usual"/>
					<type>
						<coding>
							<system value="http://terminology.hl7.org/CodeSystem/v2-0203"/>
							<code value="MR"/>
						</coding>
					</type>
					<system value="urn:oid:0.1.2.3.4.5.6.7"/>
					<value value="123456"/>
				</identifier>
				<active value="true"/>
				<name>
					<use value="official"/>
					<family value="Donald"/>
					<given value="Duck"/>
					<given value="D"/>
				</name>
				<gender value="other">
					<extension url="http://example.org/Profile/administrative-status">
						<valueCodeableConcept>
							<coding>
								<system value="http://terminology.hl7.org/CodeSystem/v2-0001"/>
								<code value="A"/>
								<display value="Ambiguous"/>
							</coding>
						</valueCodeableConcept>
					</extension>
				</gender>
				<managingOrganization>
					<reference value="Organization/1"/>
					<display value="ACME Healthcare, Inc"/>
				</managingOrganization>
			</Patient>
		</resource>
	</entry>
</Bundle>

Response: Response - since this is asynchronous, the response is empty


200 OK
[other headers]

Response: Response - if the message couldn't be accepted (e.g. there'll be no asynchronous response


500 OK Internal Server Error
[other headers]

<?xml version="1.0" encoding="UTF-8"?>
<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="exception"/>
  <text>
    <status value="generated"/>
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>SQL Link Communication Error (dbx = 34234)</p>
    </div>
  </text>
  <issue>
    <severity value="error"/>
    <code value="exception"/>
    <details>
      <text value="SQL Link Communication Error (dbx = 34234)"/>
    </details>
  </issue>
</OperationOutcome>

For more information about operations, including how they are invoked, see Operations.