This page is part of the FHIR Specification (v5.0.0: R5 - STU). This is the current published version. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4
Infrastructure And Messaging 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 | Scope | 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 | Scope | 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:
The following rules apply when using $process-message:
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 following rules apply when using the $process-message operation asynchronously:
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"/> <identifier> <system value="urn:example-org:sender.identifiers"/> <value value="efdd254b-0e09-4164-883e-35cf3871715f"/> </identifier> <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> <endpointUrl value="http://example.org/clients/ehr-lite"/> </source> <!-- 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.