Operation Definition

<?xml version="1.0" encoding="UTF-8"?>


  
  
    
    
      
      
      
      
      
        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 message to process (or, if using asynchronous messaging, it may be a response message
                 to accept)

            
          
        
        
          
          
          
          
            
          
          
          
            
              

            
          
        
        
          
          
          
          
            
          
          
          
            
              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

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

            
          
        
      
      

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="MessageHeader-process-message"/> 
  <text> 
    <status value="generated"/> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p class="res-header-id">
        <b> Generated Narrative: OperationDefinition MessageHeader-process-message</b> 
      </p> 
      <a name="MessageHeader-process-message"> </a> 
      <a name="hcMessageHeader-process-message"> </a> 
      <p> URL: [base]/$process-message</p> 
      <h3> Parameters</h3> 
      <table class="grid">
        <tr> 
          <td> 
            <b> Use</b> 
          </td> 
          <td> 
            <b> Name</b> 
          </td> 
          <td> 
            <b> Scope</b> 
          </td> 
          <td> 
            <b> Cardinality</b> 
          </td> 
          <td> 
            <b> Type</b> 
          </td> 
          <td> 
            <b> Binding</b> 
          </td> 
          <td> 
            <b> Documentation</b> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> content</td> 
          <td/>  
          <td> 1..1</td> 
          <td> 
            <a href="bundle.html">Bundle</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The message to process (or, if using asynchronous messaging, it may be a response
                 message to accept)</p> 
            </div>           </td>         </tr>         <tr>           <td> IN</td>           <td> async</td>           <td/>            <td> 0..1</td>           <td>             <a href="datatypes.html#boolean">boolean</a>           </td>           <td/>            <td>             <div>               <p> If 'true' the message is processed using the asynchronous messaging pattern</p>             </div>           </td>         </tr>         <tr>           <td> IN</td>           <td> response-url</td>           <td/>            <td> 0..1</td>           <td>             <a href="datatypes.html#url">url</a>           </td>           <td/>            <td>             <div>               <p> 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</p> 
            </div>           </td>         </tr>         <tr>           <td> OUT</td>           <td> return</td>           <td/>            <td> 0..1</td>           <td>             <a href="bundle.html">Bundle</a>           </td>           <td/>            <td>             <div>               <p> A response message, if synchronous messaging is being used (mandatory in this case).

                 For asynchronous messaging, there is no return value</p> 
            </div>           </td>         </tr>       </table>       <div> 
        <p> This operation does not use the parameters resource; the parameters &quot;async&quot;
           and &quot;response-url&quot; always go in the URL, if they are used, and the &quot;content&quot;
           parameter is always the body of the HTTP message.

        

        

          
            : 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.
          

          
            : Indicates that the receiving system has accepted custody of the message
          

          
            : Indicates that the message has been fully processed and would normally have had an application-lev
            el response, but because of instructions from the sender (e.g. the 
             extension), no response is being provided
          

          
            : Indicates that the message was not successfully processed.  The server MAY return an
             
             with additional information, and SHOULD do so if the response code is 400 or greater.&lt;br/&gt;
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 operation only accepts POST transactions - any other HTTP method will result in an
             HTTP error

          The request content type submitted is always 
             with type &quot;message&quot; containing a 
             resource as the first resource
          

          The response content type returned is always 
             with type &quot;message&quot; containing a 
             resource as the first resource, or an HTTP error
          

          If the response is an error, the body SHOULD be an 
             resource with full details
          


           and &quot;response-url&quot; always go in the URL, if they are used, and the &quot;content&qu
          ot; parameter is always the body of the HTTP message.</p> 
        <p> When processing messages, a server may return one of several status codes:</p>         <ul>           <li>             <strong> 200 OK</strong> : 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.
          </li>           <li>             <strong> 202 Accepted</strong> : Indicates that the receiving system has accepted custody of the message          </li>           <li>             <strong> 204 No Content</strong> : 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 
            <a href="https://build.fhir.org/ig/HL7/fhir-extensions/StructureDefinition-messageheader-response-requ

            est.html">http://hl7.org/fhir/StructureDefinition/messageheader-response-request</a>  extension), no response is being provided
          </li>           <li>             <strong> 300+</strong> : Indicates that the message was not successfully processed.  The server MAY return

             an 
            <a href="operationoutcome.html">OperationOutcome</a>  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.
          </li>         </ul>         <p> The following rules apply when using $process-message:</p>         <ul>           <li> The operation only accepts POST transactions - any other HTTP method will result

             in an HTTP error</li> 
          <li> The request content type submitted is always             <a href="bundle.html">Bundle</a>  with type &quot;message&quot; containing a             <a href="messageheader.html">Message Header</a>  resource as the first resource          </li>           <li> The response content type returned, if not empty, is always             <a href="bundle.html">Bundle</a>  with type &quot;message&quot; containing a             <a href="messageheader.html">Message Header</a>  resource as the first resource, or an HTTP error          </li>           <li> If the response is an error, the body SHOULD be an             <a href="operationoutcome.html">OperationOutcome</a>  resource with full details of the Errors ∓ Warning          </li> 
          <li> 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 
           SHALL be followed when messages are processed using this operation.
        

        

        

        

          

          


             OAuth</li> 
        </ul>         <p> The $process-message operation can be used by any HTTP end-point that accepts FHIR

           messages, not just FHIR RESTful servers.</p> 
        <p> In order to ensure consistency of processing, the           <a href="messaging.html#reliable">logical rules regarding processing of Bundle.id and message id</a>  SHALL be followed when messages are processed using this operation.        </p>         <p> The $process-message operation may be used synchronously, or asynchronously.</p>         <p> The following rules apply when using the $process-message operation synchronously:</p>         <ul>           <li> The URL (http://server/base/$process-message) has no parameters</li>           <li> It is an error if the sender POSTs a message that requires multiple response messages</li> 
          <li> 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 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 
             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-messages]


             (they are allowed to process them sequentially internally, but multiple concurrent
             submissions is not an error in its own right)</li> 
        </ul>         <p> The following rules apply when using the $process-message operation asynchronously:</p>         <ul>           <li> The URL has at least one parameter: http://server/base/$process-message?async=true</li>           <li> The server acknowledges the message with a 200 OK with no body, or returns an HTTP

             error if the message cannot be processed</li> 
          <li> Accepting the message means that the server has understood the message enough to

             know where to respond</li> 
          <li> An             <a href="operationoutcome.html">OperationOutcome</a>  SHOULD be returned in either case          </li>           <li> 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]</li> 

          <li> Since the source end-point may be manipulated by message transfer engines, an alternative
             response address may be specified using the parameter &quot;response-url&quot;: http://server/base/$
            process-message?async=true&amp;amp;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

        

      
    
  
  
    
  
  
    
  
  
  
  
  
  
  
  
  
    
      
      
    
    
      
      
    
  
  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.
  

             response address may be specified using the parameter &quot;response-url&quot;:
             http://server/base/$process-message?async=true&amp;response-url=http://server2.com/base/anyth
            ing.  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)</li> 
          <li> The server submits response messages to the appropriate end-point with the parameter

             async=true. There is no response message for the response messages</li> 
        </ul>       </div>     </div>   </text>   <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">    <valueInteger value="4"/>   </extension>   <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status">    <valueCode value="trial-use"/>   </extension>   <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-wg">    <valueCode value="inm"/>   </extension>   <url value="http://hl7.org/fhir/OperationDefinition/MessageHeader-process-message"/>   <version value="6.0.0-ballot3"/>   <name value="ProcessMessage"/>   <title value="Process Message"/>   <status value="draft"/>   <kind value="operation"/>   <experimental value="false"/>   <date value="2025-11-12T19:40:08+00:00"/>   <publisher value="HL7 International / Infrastructure And Messaging"/>   <contact>     <telecom>       <system value="url"/>       <value value="http://hl7.org/fhir"/>     </telecom>     <telecom>       <system value="email"/>       <value value="fhir@lists.hl7.org"/>     </telecom>   </contact>   <contact>     <telecom>       <system value="url"/>       <value value="http://www.hl7.org/Special/committees/inm"/>     </telecom>   </contact>   <description value="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."/> 
  <jurisdiction>     <coding>       <system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/>       <code value="001"/>       <display value="World"/>     </coding>   </jurisdiction>   <affectsState value="true"/>   <code value="process-message"/> 
  <comment value="This operation does not use the parameters resource; the parameters &quot;async&quot;
   and &quot;response-url&quot; always go in the URL, if they are used, and the &quot;content&quot;
   parameter is always the body of the HTTP message.

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

   and &quot;response-url&quot; always go in the URL, if they are used, and the &quot;content&qu
  ot; 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-messageheader-response-request.html) extension),
   no response is being provided
* **300+**: Indicates that the message was not successfully processed.  The server MAY
   return an [OperationOutcome](operationoutcome.html) with additional information, and SHOULD
   do so if the response code is 400 or greater.&lt;br/&gt;
    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](bundle.html) with type &quot;message&quot;
   containing a [Message Header](messageheader.html) resource as the first resource
* The response content type returned is always [Bundle](bundle.html) with type &quot;message&quot;
   containing a [Message Header](messageheader.html) resource as the first resource, or an
   HTTP error
* If the response is an error, the body SHOULD be an [Errors &amp;mp; Warning](operationoutcome.html
  ) resource with full details
* 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.


   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 [http://hl7.org/fhir/StructureDefinition/messageheader-response-request]
  (https://build.fhir.org/ig/HL7/fhir-extensions/StructureDefinition-messageheader-response-requ
  est.html) extension), no response is being provided
* **300+**: Indicates that the message was not successfully processed.  The server
   MAY return an [OperationOutcome](operationoutcome.html) 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](bundle.html) with type
   &quot;message&quot; containing a [Message Header](messageheader.html) resource
   as the first resource
* The response content type returned, if not empty, is always [Bundle](bundle.html)
   with type &quot;message&quot; containing a [Message Header](messageheader.html)
   resource as the first resource, or an HTTP error
* If the response is an error, the body SHOULD be an [OperationOutcome](operationoutcome.html
  ) resource with full details of the Errors &amp;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](messaging.html#reliable) 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](operationoutcome.html) SHOULD be returned in either case

   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](operationoutcome.html) 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-messages]
* Since the source end-point may be manipulated by message transfer engines, an alternative
   response address may be specified using the parameter &quot;response-url&quot;: http://server/base/$
  process-message?async=true&amp;amp;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)

   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 &quot;response-url&quot;:
   http://server/base/$process-message?async=true&amp;amp;response-url=http://server2.com/base/a
  nything.  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
  
  
  
  
  
    
    
    
    
    The message to process (or, if using asynchronous messaging, it may be a response message
     to accept)
    
  
  
    
    
    
    
    
    
  
  
    
    
    
    
    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
    
  
  
    
    
    
    
    A response message, if synchronous messaging is being used (mandatory in this case). For
     asynchronous messaging, there is no return value
    
  

   async=true. There is no response message for the response messages"/> 
  <resource value="MessageHeader"/>   <system value="true"/>   <type value="false"/>   <instance value="false"/>   <parameter>     <name value="content"/>     <use value="in"/>     <min value="1"/>     <max value="1"/>     <documentation value="The message to process (or, if using asynchronous messaging, it may be a response

     message to accept)"/> 
    <type value="Bundle"/>   </parameter>   <parameter>     <name value="async"/>     <use value="in"/>     <min value="0"/>     <max value="1"/>     <documentation value="If 'true' the message is processed using the asynchronous messaging pattern"/>     <type value="boolean"/>   </parameter>   <parameter>     <name value="response-url"/>     <use value="in"/>     <min value="0"/>     <max value="1"/>     <documentation value="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"/> 
    <type value="url"/>   </parameter>   <parameter>     <name value="return"/>     <use value="out"/>     <min value="0"/>     <max value="1"/>     <documentation value="A response message, if synchronous messaging is being used (mandatory in this case).

     For asynchronous messaging, there is no return value"/> 
    <type value="Bundle"/>   </parameter> 


</

OperationDefinition

>