Operation Definition

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

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Encounter-merge"/> 
  <text> 
    <status value="generated"/> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p class="res-header-id">
        <b> Generated Narrative: OperationDefinition Encounter-merge</b> 
      </p> 
      <a name="Encounter-merge"> </a> 
      <a name="hcEncounter-merge"> </a> 
      <p> URL: [base]/Encounter/$merge</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> source-encounter</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="references.html#Reference">Reference</a>  (
            <a href="encounter.html" title="http://hl7.org/fhir/StructureDefinition/Encounter">Encounter</a> )
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> A direct resource reference to the 
                <strong> source</strong>  encounter resource (this may include an identifier).
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> source-encounter-identifier</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#Identifier">Identifier</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> When source-encounter-identifiers are provided, the server is expected to perform
                 an internal lookup to identify the 
                <strong> source</strong>  encounter. The server SHALL reject the request if the provided identifiers do
                 not resolve to a single encounter record. This resolution MAY occur asynchronously,
                 for example, as part of a review by a user.
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> target-encounter</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="references.html#Reference">Reference</a>  (
            <a href="encounter.html" title="http://hl7.org/fhir/StructureDefinition/Encounter">Encounter</a> )
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> A direct resource reference to the 
                <strong> target</strong>  encounter resource.
              </p> 

              <p> This is the surviving encounter resource, the target for the merge.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> target-encounter-identifier</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#Identifier">Identifier</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> When target-encounter-identifiers are provided, the server is expected to perform
                 an internal lookup to identify the target encounter record. The server SHALL reject
                 the request if the provided identifiers do not resolve to a single encounter record.
                 This resolution MAY occur asynchronously, for example, as part of a review by a
                 user.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> result-encounter</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="encounter.html">Encounter</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The details of the Encounter resource that is expected to be updated to complete
                 with and must have the same encounter.id and provided identifiers included.</p> 

              <p> This resource MUST have the record-linkage extension with a link=replaces referencing
                 the source encounter resource.</p> 

              <p> It will be used to perform an update on the target encounter resource.</p> 

              <p> In the absence of this parameter the servers should copy all identifiers from the
                 source encounter into the target encounter, and include the record-linkage extension
                 (as shown in the example below).</p> 

              <p> This is often used when properties from the source encounter are desired to be
                 included in the target resource.</p> 

              <p> The receiving system may also apply other internal business rules onto the merge
                 which may make the resource different from what is provided here.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> preview</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#boolean">boolean</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> If this is set to true then the merge will not be actually performed; an OperationOutcome
                 will be returned in the Parameters response that will indicate that no merge has
                 occurred and may include other diagnostic info if desired, such as the scale of
                 the merge.</p> 

              <p> e.g. Issue.details.text &quot;Preview only Encounter merge - no issues detected&quot;</p> 

              <p> e.g. Issue.diagnostics &quot;Merge would update: 10 years of content or 120 resources&quot;</p> 

              <p> The resulting target encounter resource will also be returned in the result.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> OUT</td> 
          <td> return</td> 
          <td/>  
          <td> 1..1</td> 
          <td> 
            <a href="parameters.html">Parameters</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The status of the response will be one of:</p> 

              <ul> 

                <li> 200 OK - If the merge request doesn't expect any issues (although warning may be
                   present) for a preview, or was completed without issues if not a preview</li> 

                <li> 202 Accepted - The merge request has been accepted and does not expect any issues
                   and will continue processing the merge in the background, and you can monitor the
                   Task for completion</li> 

                <li> 400 Bad Request - There are errors in the input parameters that need to corrected</li> 

                <li> 422 Unprocessable Entity - Business rules prevent this merge from completing</li> 

              </ul> 

              <p> The Parameters resource will include:</p> 

              <ul> 

                <li> The Input parameters to the operation</li> 

                <li> An OperationOutcome containing errors, warnings, and information messages</li> 

                <li> The resulting merged Encounter resource (or an encounter reference if the encounter
                   is not committed)</li> 

                <li> Optionally a Task resource to track any additional processing that was required.</li> 

              </ul> 

              <p> 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</p> 

            </div> 
          </td> 
        </tr> 
      </table> 
      <div> 
        <p> There must be exactly 1 source encounter, which may be identified by either the
           source-encounter or source-encounter-identifier parameters. Similarly, there must
           be exactly 1 target encounter, identified by either the target-encounter or target-encounter-
          identifier parameters. In both cases, either a reference to the encounter or a list
           of identifiers that can be used to identify the encounter may be provided, but
           not both.</p> 

        <p> The result-encounter.id must be the same as the target encounter reference (if
           the encounter reference is provided as an input parameter).</p> 

        <p> If a client needs the server to create a new encounter merged from the 2 encounter
           resources, the client should create a new encounter record and then call the merge
           operation to merge each source encounter resource into the newly created encounter
           resource.</p> 

        <p> A server may decide to delete the source record, but this is not defined by the
           standard merge operation, and if this occurs then the target encounter's link property
           will remain unchanged.</p> 

      </div> 
    </div> 
  </text> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="0"/> 
  </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="pa"/> 
  </extension> 
  <url value="http://hl7.org/fhir/OperationDefinition/Encounter-merge"/> 
  <version value="6.0.0-ballot3"/> 
  <name value="Merge"/> 
  <title value="Encounter Merge"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <experimental value="false"/> 
  <date value="2025-08-30T14:16:05+00:00"/> 
  <publisher value="HL7 International / Patient Administration"/> 
  <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/pafm"/> 
    </telecom> 
  </contact> 
  <description value="The merge operation is used to request two encounter resources be merged. One of
   the two encounter is identified as the source and one as the target. The target
   is the remaining encounter resource (survivor), the source will be marked as inactive
   (or in some systems deleted).

The source-encounter resource will be updated to add a new link reference to the
   target-encounter resource (link-type=replaced-by in the record-linkage extension),
   and also update the status to inactive (unless the resource was deleted)

The target-encounter resource will be updated to add a new link reference to the
   source-encounter resource (link-type=replaces in the record-linkage extension)
   - and must be included in the result-encounter parameter if used (if the source
   encounter is deleted, then this link is not required)."/> 
  <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="merge"/> 
  <comment value="There must be exactly 1 source encounter, which may be identified by either the
   source-encounter or source-encounter-identifier parameters. Similarly, there must
   be exactly 1 target encounter, identified by either the target-encounter or target-encounter-
  identifier parameters. In both cases, either a reference to the encounter or a list
   of identifiers that can be used to identify the encounter may be provided, but
   not both.

The result-encounter.id must be the same as the target encounter reference (if
   the encounter reference is provided as an input parameter).

If a client needs the server to create a new encounter merged from the 2 encounter
   resources, the client should create a new encounter record and then call the merge
   operation to merge each source encounter resource into the newly created encounter
   resource.

A server may decide to delete the source record, but this is not defined by the
   standard merge operation, and if this occurs then the target encounter's link property
   will remain unchanged.
"/> 
  <resource value="Encounter"/> 
  <system value="false"/> 
  <type value="true"/> 
  <instance value="false"/> 
  <parameter> 
    <name value="source-encounter"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="A direct resource reference to the **source** encounter resource (this may include
     an identifier)."/> 
    <type value="Reference"/> 
    <targetProfile value="http://hl7.org/fhir/StructureDefinition/Encounter"/> 
  </parameter> 
  <parameter> 
    <name value="source-encounter-identifier"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="When source-encounter-identifiers are provided, the server is expected to perform
     an internal lookup to identify the **source** encounter. The server SHALL reject
     the request if the provided identifiers do not resolve to a single encounter record.
     This resolution MAY occur asynchronously, for example, as part of a review by a
     user."/> 
    <type value="Identifier"/> 
  </parameter> 
  <parameter> 
    <name value="target-encounter"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="A direct resource reference to the **target** encounter resource.

This is the surviving encounter resource, the target for the merge."/> 
    <type value="Reference"/> 
    <targetProfile value="http://hl7.org/fhir/StructureDefinition/Encounter"/> 
  </parameter> 
  <parameter> 
    <name value="target-encounter-identifier"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="When target-encounter-identifiers are provided, the server is expected to perform
     an internal lookup to identify the target encounter record. The server SHALL reject
     the request if the provided identifiers do not resolve to a single encounter record.
     This resolution MAY occur asynchronously, for example, as part of a review by a
     user."/> 
    <type value="Identifier"/> 
  </parameter> 
  <parameter> 
    <name value="result-encounter"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="The details of the Encounter resource that is expected to be updated to complete
     with and must have the same encounter.id and provided identifiers included.

This resource MUST have the record-linkage extension with a link=replaces referencing
     the source encounter resource.

It will be used to perform an update on the target encounter resource.

In the absence of this parameter the servers should copy all identifiers from the
     source encounter into the target encounter, and include the record-linkage extension
     (as shown in the example below).

This is often used when properties from the source encounter are desired to be
     included in the target resource.

The receiving system may also apply other internal business rules onto the merge
     which may make the resource different from what is provided here."/> 
    <type value="Encounter"/> 
  </parameter> 
  <parameter> 
    <name value="preview"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="If this is set to true then the merge will not be actually performed; an OperationOutcome
     will be returned in the Parameters response that will indicate that no merge has
     occurred and may include other diagnostic info if desired, such as the scale of
     the merge.

e.g. Issue.details.text &quot;Preview only Encounter merge - no issues detected&quot;

e.g. Issue.diagnostics &quot;Merge would update: 10 years of content or 120 resources&quot;

The resulting target encounter resource will also be returned in the result."/> 
    <type value="boolean"/> 
  </parameter> 
  <parameter> 
    <name value="return"/> 
    <use value="out"/> 
    <min value="1"/> 
    <max value="1"/> 
    <documentation value="The status of the response will be one of:

* 200 OK - If the merge request doesn't expect any issues (although warning may
     be present) for a preview, or was completed without issues if not a preview
* 202 Accepted - The merge request has been accepted and does not expect any issues
     and will continue processing the merge in the background, and you can monitor the
     Task for completion
* 400 Bad Request - There are errors in the input parameters that need to corrected
* 422 Unprocessable Entity - Business rules prevent this merge from completing

The Parameters resource will include:

* The Input parameters to the operation
* An OperationOutcome containing errors, warnings, and information messages
* The resulting merged Encounter resource (or an encounter reference if the encounter
     is not committed)
* Optionally a Task resource to track any additional processing that was required.

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"/> 
    <type value="Parameters"/> 
  </parameter> 
</OperationDefinition>