31.4.1MDM Operations

Smile CDR provides several custom operations for working with Master Data Management (MDM).

31.4.2$mdm-evaluate Operation

$mdm-evaluate is a custom Smile CDR operation, which you can use to test out different MDM algorithms available and get match results based on the input values.

This operation is only available when a FHIR persistence module is configured to use MDM. This operation will be available on the base FHIR endpoint url.

This operation takes in Parameters FHIR resource for inputs and responds with a Parameters resource with the match results.

31.4.2.1Permissions

• Users require FHIR_EXTENDED_OPERATION_ON_SERVER permission on $mdm-evaluate in order to execute this operation.

31.4.2.2Limitations

• This custom operation is available for FHIR version DSTU3 and FHIR versions released after.
• This custom operation does not support two matcher type algorithms:
  • IDENTIFIER
  • EXTENSION_ANY_ORDER

31.4.2.3Input Parameters

31.4.2.4Output Parameters

31.4.2.5Sample Request

Below is a sample request and response when using $mdm-evaluate for similarity type algorithm.

POST http://fhir.example.com/baseR4/$mdm-evaluate

Sample request body

{
	"resourceType":"Parameters",
	"parameter":[
		{
			"name":"compareTo",
			"valueString":"My tsring"
		},
		{
			"name":"compareWith",
			"valueString":"My string"
		},
		{
			"name":"algorithmType",
			"valueString":"similarity"
		},
		{
			"name":"algorithm",
			"valueString":"JARO_WINKLER"
		},
		{
			"name":"threshold",
			"valueDecimal":0.5
		}
	]
}

Sample response body

{
	"resourceType": "Parameters",
	"parameter": [
		{
			"name": "match",
			"valueBoolean": true
		},
		{
			"name": "score",
			"valueDecimal": 0.974
		}
	]
}

Below is a sample request and response when using $mdm-evaluate for matcher type algorithm.

POST http://fhir.example.com/baseR4/$mdm-evaluate

Sample request body

{
	"resourceType":"Parameters",
	"parameter":[
		{
			"name":"compareTo",
			"valueString":"Gail"
		},
		{
			"name":"compareWith",
			"valueString":"Gael"
		},
		{
			"name":"algorithmType",
			"valueString":"matcher"
		},
		{
			"name":"algorithm",
			"valueString":"CAVERPHONE1"
		}
	]
}

Sample response body

{
	"resourceType": "Parameters",
	"parameter": [
		{
			"name": "match",
			"valueBoolean": true
		}
	]
}

31.4.3$sdh.mdm-bundle-match Operation

$sdh.mdm-bundle-match is a custom Smile CDR operation that processes a FHIR Bundle to match resources against existing resources in the repository using MDM rules. This operation helps prevent duplicate resources by identifying and removing resources in the input Bundle that match existing resources in the repository before persisting the bundle.

This Bundle operation is only available when a FHIR persistence module is configured to use MDM. Similar to Patient/$match, this operation does not require the heavier MATCH_AND_LINK MDM mode to use; It is also available in lightweight MATCH_ONLY MDM mode.

31.4.3.1How It Works

For each resource in the input bundle:

1. The operation uses MDM rules to find matching resources in the repository 2. If a resource matches exactly one resource in the repository:
   1. Without merge (default): It removes the resource from the bundle and updates all references to that resource in the bundle to point to the matched resource
   2. With merge (merge=true): It applies survivorship rules to merge the bundle resource with the repository resource, then includes the merged resource as an UPDATE operation in the bundle 3. If a resource matches more than one resource in the repository:
   3. It throws a ResourceVersionConflictException 4. If a resource doesn't match any resources in the repository:
   4. It keeps the resource in the bundle, updating references to removed resources as necessary

In addition to the above rules, if the input Bundle is a Document bundle and the first entry in the Bundle is a Composition resource, the Composition resource is removed. The operation returns a new transaction Bundle with matched resources removed and references updated. This bundle can then be submitted to the repository to create only the non-duplicate resources as determined by the MDM Rules.

31.4.3.2Permissions

• Users require FHIR_EXTENDED_OPERATION_ON_TYPE permission on $sdh.mdm-bundle-match for the Bundle resource type in order to execute this operation.

31.4.3.3Limitations

• This custom operation is available for FHIR version DSTU3 and FHIR versions released after.

31.4.3.4Input Parameters

31.4.3.5Output

The operation returns a FHIR transaction Bundle with matched resources processed according to the survivorship setting and references updated.

31.4.3.6Survivorship Integration

When the merge parameter is set to true, the operation applies MDM survivorship rules to matched resources. This allows you to merge data from incoming bundle resources with existing repository resources according to your configured survivorship script.

Key behaviors with survivorship enabled:

• Matched resources are not removed from the bundle
• Instead, they are converted to UPDATE operations targeting the matched repository resource
• Survivorship rules determine which data elements are preserved from the bundle vs. repository resource
• The merged resource maintains the ID of the repository resource
• All references in the bundle are updated to point to the repository resource ID

Use cases for survivorship:

• Data enrichment: Adding new information to existing resources
• Data correction: Updating incorrect information in repository resources
• Selective updates: Only updating specific fields based on survivorship rules

For more information on configuring survivorship rules, see MDM Survivorship documentation.

31.4.3.7Sample Request

Below is a sample request when using $sdh.mdm-bundle-match:

POST http://fhir.example.com/baseR4/Bundle/$sdh.mdm-bundle-match

Sample request body

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "bundle",
      "resource": {
        "resourceType": "Bundle",
        "type": "transaction",
        "entry": [
          {
            "fullUrl": "urn:uuid:1",
            "resource": {
              "resourceType": "Patient",
              "name": [
                {
                  "family": "Smith",
                  "given": ["John"]
                }
              ],
              "birthDate": "1970-01-01"
            },
            "request": {
              "method": "POST",
              "url": "Patient"
            }
          },
          {
            "fullUrl": "urn:uuid:2",
            "resource": {
              "resourceType": "Observation",
              "status": "final",
              "code": {
                "coding": [
                  {
                    "system": "http://loinc.org",
                    "code": "8480-6",
                    "display": "Systolic blood pressure"
                  }
                ]
              },
              "subject": {
                "reference": "urn:uuid:1"
              },
              "valueQuantity": {
                "value": 120,
                "unit": "mmHg",
                "system": "http://unitsofmeasure.org",
                "code": "mm[Hg]"
              }
            },
            "request": {
              "method": "POST",
              "url": "Observation"
            }
          }
        ]
      }
    }
  ]
}

Below is a sample request when using $sdh.mdm-bundle-match with survivorship enabled:

POST http://fhir.example.com/baseR4/Bundle/$sdh.mdm-bundle-match

Sample request body with survivorship:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "bundle",
      "resource": {
        "resourceType": "Bundle",
        "type": "transaction",
        "entry": [
          {
            "fullUrl": "urn:uuid:1",
            "resource": {
              "resourceType": "Organization",
              "name": "Updated Hospital Name",
              "identifier": [
                {
                  "system": "http://example.org/hospital-ids",
                  "value": "12345"
                }
              ],
              "telecom": [
                {
                  "system": "phone",
                  "value": "+1-555-NEW-PHONE"
                }
              ]
            },
            "request": {
              "method": "POST",
              "url": "Organization"
            }
          }
        ]
      }
    },
    {
      "name": "merge",
      "valueBoolean": true
    }
  ]
}

31.4.4MDM Bundle Match Processor

The MDM Bundle Match Processor is a Camel processor that provides access to the $sdh.mdm-bundle-match operation functionality within a Camel route.

• Example URI: <to uri="smile:mdm/mdmBundleMatchProcessor"/>
• Description: Processes a FHIR Bundle to match resources against existing resources in the repository using MDM rules.

31.4.4.1Input

The processor takes an IBaseBundle (FHIR Bundle) as input.

31.4.4.2Parameters

The processor supports the following optional parameters:

31.4.4.3Output

The processor returns a reconciled IBaseBundle (FHIR Bundle) with matched resources processed according to the survivorship setting and references updated.

31.4.4.4Example

The following example shows a route that reads a FHIR Bundle from a file, processes it with the MDM Bundle Match Processor, and then stores the reconciled bundle in a FHIR repository:

<route>
    <from uri="file:input/bundles?noop=true"/>
    <to uri="smile:mdm/mdmBundleMatchProcessor"/>
    <to uri="smile:persistence/bundleProcessor"/>
</route>

The following example shows how to use the processor with survivorship enabled by setting the merge parameter:

<route>
    <from uri="file:input/bundles?noop=true"/>
    <to uri="smile:mdm/mdmBundleMatchProcessor?merge=true"/>
    <to uri="smile:persistence/bundleProcessor"/>
</route>