Operation Definition

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

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Patient-merge"/> 
  <text> 
    <status value="extensions"/> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p> URL: [base]/Patient/$merge</p> 
      <p> Parameters</p> 
      <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-patient</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="references.html#Reference">Reference</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> A direct resource reference to the 
                <strong> source</strong>  patient resource (this may include an identifier).
              </p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> source-patient-identifier</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#Identifier">Identifier</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> When source-patient-identifiers are provided, the server is expected to perform
                 an internal lookup to identify the source patient record. The server SHALL reject
                 the request if the provided identifiers do not resolve to a single patient 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-patient</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="references.html#Reference">Reference</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> A direct resource reference to the 
                <strong> target</strong>  patient resource.
              </p> 

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

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> target-patient-identifier</td> 
          <td/>  
          <td> 0..*</td> 
          <td> 
            <a href="datatypes.html#Identifier">Identifier</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> When target-patient-identifiers are provided, the server is expected to perform
                 an internal lookup to identify the target patient record. The server SHALL reject
                 the request if the provided identifiers do not resolve to a single patient 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-patient</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="patient.html">Patient</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The details of the Patient resource that is expected to be updated to complete
                 with and must have the same patient.id and provided identifiers included.</p> 

              <p> This resource MUST have the link property included referencing the source patient
                 resource.</p> 

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

              <p> In the absence of this parameter the servers should copy all identifiers from the
                 source patient into the target patient, and include the link property (as shown
                 in the example below).</p> 

              <p> This is often used when properties from the source patient 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 Patient 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 patient 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 Patient resource (or a patient reference if the patient is
                   not committed)</li> 

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

              </ul> 

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

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

        <p> If a client needs the server to create a new patient merged from the 2 patient
           resources, the client should create a new patient record and then call the merge
           operation to merge each source patient resource into the newly created patient
           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 patient'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> 
  <url value="http://hl7.org/fhir/OperationDefinition/Patient-merge"/> 
  <version value="5.0.0-draft-final"/> 
  <name value="Merge"/> 
  <title value="Patient Merge"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <experimental value="false"/> 
  <date value="2023-03-01T23:03:57+11:00"/> 
  <publisher value="HL7 (FHIR Project)"/> 
  <contact> 
    <telecom> 
      <system value="url"/> 
      <value value="http://hl7.org/fhir"/> 
    </telecom> 
    <telecom> 
      <system value="email"/> 
      <value value="fhir@lists.hl7.org"/> 
    </telecom> 
  </contact> 
  <description value="The merge operation is used to request two patient resources be merged. One of
   the two patients is identified as the source and one as the target. The data from
   the source patient will be merged with the data of the target patient.

The source Patient resource will be updated to add a new Patient.link reference
   to the target Patient resource with a link-type of replaced-by. The source Patient
   will also be updated to have a status of inactive, unless the source Patient resource
   was deleted.

The target Patient resource will be updated to add a new Patient.link reference
   to the source Patient resource with a link-type of replaces unless the source Patient
   resource is deleted. The target Patient resource must be included in the result-patient
   parameter if used."/> 
  <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 patient, which may  be identified by either the
   source-patient or source-patient-identifier parameters. Similarly, there must be
   exactly 1 target patient, identified by either the target-patient or target-patient-identifie
  r parameters. In both cases, either a reference to the patient or a list of identifiers
   that can be used to identify the patient may be provided, but not both.

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

If a client needs the server to create a new patient merged from the 2 patient
   resources, the client should create a new patient record and then call the merge
   operation to merge each source patient resource into the newly created patient
   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 patient's link property
   will remain unchanged.
"/> 
  <resource value="Patient"/> 
  <system value="false"/> 
  <type value="true"/> 
  <instance value="false"/> 
  <parameter> 
    <name value="source-patient"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="A direct resource reference to the **source** patient resource (this may include
     an identifier)."/> 
    <type value="Reference"/> 
    <targetProfile value="http://hl7.org/fhir/StructureDefinition/Patient"/> 
  </parameter> 
  <parameter> 
    <name value="source-patient-identifier"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="*"/> 
    <documentation value="When source-patient-identifiers are provided, the server is expected to perform
     an internal lookup to identify the source patient record. The server SHALL reject
     the request if the provided identifiers do not resolve to a single patient record.
     This resolution MAY occur asynchronously, for example, as part of a review by a
     user."/> 
    <type value="Identifier"/> 
  </parameter> 
  <parameter> 
    <name value="target-patient"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="A direct resource reference to the **target** patient resource.

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

This resource MUST have the link property included referencing the source patient
     resource.

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

In the absence of this parameter the servers should copy all identifiers from the
     source patient into the target patient, and include the link property (as shown
     in the example below).

This is often used when properties from the source patient 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="Patient"/> 
  </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 Patient merge - no issues detected&quot;

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

The resulting target patient 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 Patient resource (or a patient reference if the patient
     is not committed)
* Optionally a Task resource to track any additional processing that was required."/> 
    <type value="Parameters"/> 
  </parameter> 
</OperationDefinition>