7.1.1Rules

7.1.1.0.1candidateSearchParams

7.1.1.0.2candidateFilterSearchParams

When searching for match candidates, only resources that match this filter are considered. E.g. you may wish to only search for Patients for which active=true.

{
   "candidateFilterSearchParams": [
      {
         "resourceType": "Patient",
         "searchParam": "active",
         "fixedValue": "true"
      }
   ]
}

For example, if the incoming patient looked like this:

{
   "resourceType": "Patient",
   "id": "example",
   "identifier": [
      {
         "system": "urn:oid:1.2.36.146.595.217.0.1",
         "value": "12345"
      }
   ],
   "name": [
      {
         "family": "Chalmers",
         "given": ["Peter", "James"]
      }
   ]
}

then the above candidateSearchParams and candidateFilterSearchParams would result in the following two parallel searches for candidates:

• Patient?given=Peter,James&family=Chalmers&active=true
• Patient?identifier=urn:oid:1.2.36.146.595.217.0.1|12345&active=true

If you also wish to search for Practitioners for which active=true, the resourceType must be defined in the candidateSearchParams before the candidateFilterSearchParams can be applied.

The candidateSearchParams should look like this:

{
   "candidateSearchParams": [
      {
         "resourceType": "Patient",
         "searchParams": ["given", "family"]
      },
      {
         "resourceType": "Practitioner",
         "searchParam": "email"
      }
   ]
}

and candidateFilterSearchParams should look like this:

{
   "candidateFilterSearchParams": [
      {
         "resourceType": "Patient",
         "searchParam": "active",
         "fixedValue": "true"
      },
      {
         "resourceType": "Practitioner",
         "searchParam": "active",
         "fixedValue": "true"
      }
   ]
}

For example, if the incoming patient looked like this:

{
   "resourceType": "Patient",
   "id": "example",
   "identifier": [
      {
         "system": "urn:oid:1.2.36.146.595.217.0.1",
         "value": "12345"
      }
   ],
   "name": [
      {
         "family": "Chalmers",
         "given": ["Peter", "James"]
      }
   ]
}

and the incoming practitioner looked like this:

{
   "resourceType": "Practitioner",
   "id": "example",
   "identifier": [
      {
         "system": "urn:oid:1.2.36.146.595.404.0.1",
         "value": "56789"
      }
   ],
   "name": [
      {
         "family": "Smith",
         "given": ["Adam"]
      }
   ]
}

The resulting searches would be:

• Patient?given=Peter,James&family=Chalmers&active=true
• Patient?identifier=urn:oid:1.2.36.146.595.217.0.1|12345&active=true
• Practitioner?given=Adam&family=Smith&active=true
• Patient?identifier=urn:oid:urn:oid:1.2.36.146.595.404.0.1|56789&active=true

If the practitioner resourceType was not defined in the candidateSearchParams, active=true would not be added to that resourceType and the resulting searches would be:

• Patient?given=Peter,James&family=Chalmers&active=true
• Patient?identifier=urn:oid:1.2.36.146.595.217.0.1|12345&active=true
• Practitioner?given=Adam&family=Smith
• Patient?identifier=urn:oid:1.2.36.146.595.404.0.1|56789

For instances where the candidateFilterSearchParams criteria is identical across both resource types and you would like to apply it to all resources, the * wildcard could be used in resourceType.

Since multiple resource types cannot be defined at once, the following candidateFilterSearchParams would be incorrect:

{
   "candidateFilterSearchParams": [
      {
         "resourceType": ["Patient, Practitioner"],
         "searchParam": "active",
         "fixedValue": "true"
      }
   ]
}

However if you would like to apply the candidateFilterSearchParams to specific resource types only, the resource types must be individually defined, like in:

{
   "candidateFilterSearchParams": [
      {
         "resourceType": "Patient",
         "searchParam": "active",
         "fixedValue": "true"
      },
      {
         "resourceType": "Practitioner",
         "searchParam": "active",
         "fixedValue": "true"
      }
   ]
}

7.1.1.0.3matchFields

Once the match candidates have been found, they are then each compared to the incoming Patient resource. This comparison is made across a list of matchFields. Each matchField returns true or false indicating whether the candidate and the incoming Patient match on that field. There are two types of matchFields: matcher and similarity. matcher matchFields return a true or false directly, whereas similarity matchFields return a score between 0.0 (no match) and 1.0 (exact match) and this score is translated to a true/false via a matchThreshold. E.g. if a JARO_WINKLER matchField is configured with a matchThreshold of 0.8 then that matchField will only return true if the JARO_WINKLER similarity evaluates to a score >= 0.8.

By default, all matchFields have exact=false which means that they will have all diacritical marks removed and all letters will be converted to upper case before matching. exact=true can be added to any matchField to compare the strings as they are originally capitalized and accented.

Here is a matcher matchField that uses the SOUNDEX matcher to determine whether two family names match.

{
   "name": "familyname-soundex",
   "resourceType": "*",
   "resourcePath": "name.family",
   "matcher": {
      "algorithm": "SOUNDEX"
   }
}

Here is a matcher matchField that only matches when two family names are identical.

{
   "name": "familyname-exact",
   "resourceType": "*",
   "resourcePath": "name.family",
   "matcher": {
      "algorithm": "STRING",
      "exact": true
   }
}

While it is often suitable to use the resourcePath field to indicate the location of the data to be matched, occasionally you will need more direct control over precisely which fields are matched. When performing string matching, the matcher will indiscriminately try to match all elements of the left resource to all elements of the right resource. For example, consider the following two patients and matcher.

{
   "resourceType": "Patient",
   "name": [
      {
         "given": ["Frank", "John"]
      }
   ]
}

{
   "resourceType": "Patient",
   "name": [
      {
         "given": ["John", "Frank"]
      }
   ]
}

{
   "name": "firstname-meta",
   "resourceType": "Patient",
   "resourcePath": "name.given",
   "matcher": {
      "algorithm": "METAPHONE"
   }
}

In this example, these two patients would match, as the matcher will compare all elements of ["John", "Frank"] to all elements of ["Frank", "John"] and find that there are matches. This is when you would want to use a FHIRPath matcher, as FHIRPath expressions give you more direct control. This following example shows a matcher that would cause these two patient's not to match to each other.

{
   "name": "firstname-meta-fhirpath",
   "resourceType": "Patient",
   "fhirPath": "name.given[0]",
   "matcher": {
      "algorithm": "METAPHONE"
   }
}

Since FHIRPath expressions support indexing it is possible to directly indicate that you would only like to compare the first element of each resource.

Special identifier matching is also available if you need to match on a particular identifier system:

{
   "name": "identifier-ssn",
   "resourceType": "*",
   "resourcePath": "identifier",
   "matcher": {
      "algorithm": "IDENTIFIER",
      "identifierSystem": "http://hl7.org/fhir/sid/us-ssn"
   }
}

Here is a similarity matchField that matches when two given names match with a JARO_WINKLER threshold >= 0.8.

{
   "name": "firstname-jaro",
   "resourceType": "*",
   "resourcePath": "name.given",
   "similarity": {
      "algorithm": "JARO_WINKLER",
      "matchThreshold": 0.8
   }
}

The following algorithms are currently supported:

7.1.1.0.4matchResultMap

These entries convert combinations of successful matchFields into an MDM Match Result for overall matching of a given pair of resources. MATCH results are evaluated take precedence over POSSIBLE_MATCH results. If the incoming resource matches ALL of the named matchFields listed, then a new match link is created with the assigned matchResult (MATCH or POSSIBLE_MATCH).

{
   "matchResultMap": {
      "firstname-meta,lastname-meta,birthday": "MATCH",
      "firstname-jaro,lastname-jaro,birthday": "POSSIBLE_MATCH"
   }
}

7.1.1.0.5eidSystems