Operation Definition

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

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="Patient-match"/> 
  <text> 
    <status value="generated"/> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p class="res-header-id">
        <b> Generated Narrative: OperationDefinition Patient-match</b> 
      </p> 
      <a name="Patient-match"> </a> 
      <a name="hcPatient-match"> </a> 
      <a name="Patient-match-en-US"> </a> 
      <p> URL: [base]/Patient/$match</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> resource</td> 
          <td/>  
          <td> 1..1</td> 
          <td> 
            <a href="resource.html">Resource</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> Use this to provide an entire set of patient details for the MPI to match against
                 (e.g. POST a patient record to Patient/$match).</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> onlySingleMatch</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#boolean">boolean</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> If there are multiple potential matches, the server should identify the single
                 most appropriate match that should be used with future interactions with the server
                 (for example, as part of a subsequent create interaction).</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> onlyCertainMatches</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#boolean">boolean</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> If there are multiple potential matches, the server should be certain that each
                 of the records are for the same patients.  This could happen if the records are
                 duplicates, are the same person for the purpose of data segregation, or other reasons.
                  When false, the server may return multiple results with each result graded accordingly.</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> IN</td> 
          <td> count</td> 
          <td/>  
          <td> 0..1</td> 
          <td> 
            <a href="datatypes.html#integer">integer</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The maximum number of records to return. If no value is provided, the server decides
                 how many matches to return. Note that clients should be careful when using this,
                 as it may prevent probable - and valid - matches from being returned</p> 

            </div> 
          </td> 
        </tr> 
        <tr> 
          <td> OUT</td> 
          <td> return</td> 
          <td/>  
          <td> 1..1</td> 
          <td> 
            <a href="bundle.html">Bundle</a> 
          </td> 
          <td/>  
          <td> 
            <div> 
              <p> The bundle type is &quot;searchset&quot;</p> 

              <p> A bundle contain a set of Patient records that represent possible matches, optionally
                 it may also contain an OperationOutcome with further information about the search
                 results (such as warnings or information messages, such as a count of records that
                 were close but eliminated)  If the operation was unsuccessful, then an OperationOutcome
                 may be returned along with a BadRequest status Code (e.g. security issue, or insufficient
                 properties in patient fragment - check against profile)</p> 

            </div> 
          </td> 
        </tr> 
      </table> 
      <div> 
        <p> The response from an &quot;mpi&quot; query is a bundle containing patient records,
           ordered from most likely to least likely. If there are no patient matches, the
           MPI SHALL return an empty search set with no error, but may include an operation
           outcome with further advice regarding patient selection. All patient records SHALL
           have a search score from 0 to 1, where 1 is the most certain match, along with
           an extension &quot;
          <a href="https://build.fhir.org/ig/HL7/fhir-extensions/StructureDefinition-match-grade.html">http://hl7.org/fhir/StructureDefinition/match-grade</a> &quot; that indicates the MPI's position on the match quality.
        </p> 

      </div> 
    </div> 
  </text> 
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="5"/> 
  </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/Patient-match"/> 
  <version value="6.0.0-ballot2"/> 
  <name value="Match"/> 
  <title value="Find patient matches using MPI based logic"/> 
  <status value="draft"/> 
  <kind value="operation"/> 
  <experimental value="false"/> 
  <date value="2024-12-12T18:56:29+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="A Master Patient Index ([MPI](http://en.wikipedia.org/wiki/Enterprise_master_patient_index)
   ) is a service used to manage patient identification in a context where multiple
   patient databases exist. Healthcare applications and middleware use the MPI to
   match patients between the databases, and to store new patient details as they
   are encountered. MPIs are highly specialized applications, often tailored extensively
   to the institution's particular mix of patients. MPIs can also be run on a regional
   and national basis.  

To ask an MPI to match a patient, clients use the &quot;$match&quot; operation,
   which accepts a patient resource which may be only partially complete. The data
   provided is interpreted as an MPI input and processed by an algorithm of some kind
   that uses the data to determine the most appropriate matches in the patient set.
    Note that different MPI matching algorithms have different required inputs. Consult
   with the vendor implementing the $match operation as to its specific behaviors.

  The generic $match operation does not specify any particular algorithm, nor a
   minimum set of information that must be provided when asking for an MPI match operation
   to be performed, but many implementations will have a set of minimum information,
   which may be declared in their definition of the $match operation by specifying
   a profile on the resource parameter, indicating which properties are required in
   the search.

The patient resource submitted to the operation does not have to be complete, nor
   does it need to pass validation (i.e. mandatory fields don't need to be populated),
   but it does have to be a valid instance, as it is used as the reference data to
   match against.

  Implementers of the $match algorithm should consider the relevance of returning
   inactive patients, particularly ones associated with patient merges.

E.g. If an inactive patient is &quot;matched&quot; and its merged target resource
   will be included, then the inactive one may be excluded, however if a patient was
   just marked as inactive for other reasons, it could be included in the results.

(any specific MPI algorithm may or might not behave as in these examples)"/> 
  <jurisdiction> 
    <coding> 
      <system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/> 
      <code value="001"/> 
      <display value="World"/> 
    </coding> 
  </jurisdiction> 
  <affectsState value="false"/> 
  <code value="match"/> 
  <comment value="The response from an &quot;mpi&quot; query is a bundle containing patient records,
   ordered from most likely to least likely. If there are no patient matches, the
   MPI SHALL return an empty search set with no error, but may include an operation
   outcome with further advice regarding patient selection. All patient records SHALL
   have a search score from 0 to 1, where 1 is the most certain match, along with
   an extension &quot;[http://hl7.org/fhir/StructureDefinition/match-grade](https://build.fhir.o
  rg/ig/HL7/fhir-extensions/StructureDefinition-match-grade.html)&quot; that indicates
   the MPI's position on the match quality."/> 
  <resource value="Patient"/> 
  <system value="false"/> 
  <type value="true"/> 
  <instance value="false"/> 
  <parameter> 
    <name value="resource"/> 
    <use value="in"/> 
    <min value="1"/> 
    <max value="1"/> 
    <documentation value="Use this to provide an entire set of patient details for the MPI to match against
     (e.g. POST a patient record to Patient/$match)."/> 
    <type value="Resource"/> 
  </parameter> 
  <parameter> 
    <name value="onlySingleMatch"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="If there are multiple potential matches, the server should identify the single
     most appropriate match that should be used with future interactions with the server
     (for example, as part of a subsequent create interaction)."/> 
    <type value="boolean"/> 
  </parameter> 
  <parameter> 
    <name value="onlyCertainMatches"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="If there are multiple potential matches, the server should be certain that each
     of the records are for the same patients.  This could happen if the records are
     duplicates, are the same person for the purpose of data segregation, or other reasons.
      When false, the server may return multiple results with each result graded accordingly."/> 
    <type value="boolean"/> 
  </parameter> 
  <parameter> 
    <name value="count"/> 
    <use value="in"/> 
    <min value="0"/> 
    <max value="1"/> 
    <documentation value="The maximum number of records to return. If no value is provided, the server decides
     how many matches to return. Note that clients should be careful when using this,
     as it may prevent probable - and valid - matches from being returned"/> 
    <type value="integer"/> 
  </parameter> 
  <parameter> 
    <name value="return"/> 
    <use value="out"/> 
    <min value="1"/> 
    <max value="1"/> 
    <documentation value="The bundle type is &quot;searchset&quot;

A bundle contain a set of Patient records that represent possible matches, optionally
     it may also contain an OperationOutcome with further information about the search
     results (such as warnings or information messages, such as a count of records that
     were close but eliminated)  If the operation was unsuccessful, then an OperationOutcome
     may be returned along with a BadRequest status Code (e.g. security issue, or insufficient
     properties in patient fragment - check against profile)"/> 
    <type value="Bundle"/> 
  </parameter> 
</OperationDefinition>