On this page:

19.2MDM Survivorship rules

 

MDM supports flexible survivorship rules that determine which attributes are replaced and which are preserved in the Golden Record after MDM operations. These rules are defined as JavaScript handler functions in the MDM survivorship rules module configuration section. Rules can be defined at four different scopes: global, operation type, resource type, and both, operation and resource type. In case multiple handlers are defined, only the most specific one will be called. Please note that the script is not intended to preserve state. Please use bindings to track any required state.

Global Handler

The global handler function is applied to all MDM resources and request types, unless a more specific handler function is available.

function mdmApplySurvivorshipRules(targetRec, goldenRec, transactionContext) {
  // rule implementation goes here
}

MDM operation type handler

Operation type handler is more specific than the global handler. It is run on the MDM operations regardless of the resource type provided to the operation.

Handler function should follow the convention mdmApplySurvivorshipRulesOn<OperationType>, where <OperationType> is one of the MDM operation types:

  • CreateResource
  • UpdateResource
  • SubmitResourceToMdm
  • UpdateLink (only when switching update to match)
  • MergeGoldenResources

An example handler function for all resources for MergeGoldenResources operation type is included below:

function mdmApplySurvivorshipRulesOnMergeGoldenResources(targetRec, goldenRec, transactionContext) { 
 // rule implementation goes here
}

MDM Resource type handler

Resource type handlers apply to all requests with a given MDM resource type. Resource type handlers are considered more specific than operation type handlers. If resource type handler is available, operation type and global handlers will not be executed.

JavaScript function should be named as mdmApplySurvivorshipRulesFor<Resource>Type. <Resource> is any of the supported MDM resource types.

function mdmApplySurvivorshipRulesForPatientType(targetRec, goldenRec, transactionContext) {
 // rule implementation goes here
}

MDM Operation and Resource type handler

Operation and Resource type handlers are the most specific handler that are applied to MDM requests. JavaScript function should be named using the following convention: mdmApplySurvivorshipRulesOn<OperationType>For<Resource>Type. Where <OperationType> should be one of the MDM supported operation types and <Resource> is any of the supported MDM resource types.

function mdmApplySurvivorshipRulesOnCreateResourceForPatientType(targetRec, goldenRec, transactionContext) { 
  // rule implementation goes here
}

MDM survivorship bindings

MDM Helper class

There is a helper object available to the survivorship script. It can be used for copying values from the target record to the golden record. The helper object supports the following methods:

Method Description
MdmHelper(Fhir.getContext(), targetRec, goldenRec, transactionContext ) Constructor that accepts FHIR context, target record to copy values from, golden record to copy values to and transaction context.
helper.mergeAll() Adds all values from the target record to the golden record. IDs, identifiers and metadata values are not merged.
helper.replaceAll() Replaces all values in the golden resource with the values in the target resource. IDs, identifiers and metadata are not replaced.
helper.merge(fieldName) Adds the values from the field identified by the fieldName from target record to the golden record.
helper.mergeFields(fieldNames) Adds values from the fields in the fieldNames array from target record to the golden record.
helper.replace(fieldName) Replaces the values from the field identified by the fieldName from target record to the golden record.
helper.replaceFields(fieldNames) Replaces the values from the fields in the fieldNames array from target record to the golden record.
helper.isGoldenResourceFieldEmpty(fieldName) Checks if the fieldName is empty on the golden resource.
helper.isTargetFieldEmpty(fieldName) Checks if the fieldName is empty on the target resource.
helper.isValidTargetResourceField(fieldName) Checks if the fieldName exists on the target resource.
helper.isValidGoldenResourceField(fieldName) Checks if the fieldName exists on the golden resource.
helper.isGoldenResourceOlderThanTarget() Checks if Golden Resource was last modified before the Target Resource (i.e. so that the values form the Target Resources are more recent and we need to modify the Golden Resource appropriately, for instance). This method will return false if timestamp is missing on either the Target or Golden Resource.

Additional bindings

Instance Description
BundleUtil Convenience object for retrieving resources with the resourceName from the provided bundle.
Converter Utility instance for converting HL7v2 time to FHIR format and decoding/encoding URL stings.
Environment Convenience object for retrieving JavaScript-related system properties.
Exceptions Convenience object for creating exception instances.
Fhir Utility object for accessing FHIR context.
FhirClientFactory Factory object for creating new FHIR client instances.
Hl7V2 Utility for creating HL7 v2 message segments.
Http Factory object for building HTTP requests.
LdapFactory Utility object for creating LDAP resources.
Log Convenience logger instance.
OAuth2Exceptions Utility object for creating authentication / authorization exceptions.
ResourceBuilder Builder object responsible for creating new FHIR resource instances
TransactionBuilder Builder object responsible for creating new transaction bundles.
Util Utility object pausing current execution.
Uuid Helper object for generating UUIDs.

Sample MDM Survivorship Rules

/*
   Objects available to the survivorship script:

   * BundleUtil - Convenience object for retrieving resources with the resourceName from the provided bundle.
   * Converter - Utility instance for converting HL7v2 time to FHIR format and decoding/encoding URL stings.
   * Environment - Convenience object for retrieving JavaScript-related system properties.
   * Exceptions - Convenience object for creating exception instances.
   * Fhir - Utility object for accessing FHIR context.
   * FhirClientFactory - Factory object for creating new FHIR client instances.
   * Hl7V2 - Utility for creating HL7 v2 message segments.
   * Http - Factory object for building HTTP requests.
   * LdapFactory - Utility object for creating LDAP resources.
   * Log - Convenience logger instance.
   * OAuth2Exceptions - Utility object for creating authentication / authorization exceptions.
   * ResourceBuilder - Builder object responsible for creating new FHIR resource instances
   * TransactionBuilder - Builder object responsible for creating new transaction bundles.
   * Util - Utility object pausing current execution.
   * Uuid - Helper object for generating UUIDs.

*/

/*
   Global handler
 */
function mdmApplySurvivorshipRules(targetRec, goldenRec, transactionContext) {
   // by default replace name on the golden record, if target has it
   var helper = new MdmHelper(Fhir.getContext(), targetRec, goldenRec, transactionContext);
   if (!helper.isTargetFieldEmpty('name')) {
      helper.replace('name');
   }

   // also replace DOB and phone
   helper.replaceFields(['birthDate', 'telecom']);
}

/*
   Request Type handler
 */
function mdmApplySurvivorshipRulesOnMergeGoldenResources(targetRec, goldenRec, transactionContext) {
   // merge all fields by default
   var helper = new MdmHelper(Fhir.getContext(), targetRec, goldenRec, transactionContext);
   helper.mergeAll();
}

/*
   Request and resource type handlers
 */
function mdmApplySurvivorshipRulesOnMergeGoldenResourcesForPatientType(targetRec, goldenRec, transactionContext) {
   var helper = new MdmHelper(Fhir.getContext(), targetRec, goldenRec, transactionContext);
   if (helper.isGoldenResourceFieldEmpty('address')) {
      // if golden resource has no address, keep the address from the target resource
      helper.replace('address');
   } else {
      // otherwise keep all addresses
      helper.merge('address');
   }
   // re-apply global handler
   mdmApplySurvivorshipRules(targetRec, goldenRec, transactionContext);
}

Sample Global handler that copies identifiers in golden records

/*
   Global handler, that copy identifiers in golden records.
 */
function mdmApplySurvivorshipRules(targetRec, goldenRec, txContext) {
    var helper = new MdmHelper(Fhir.getContext(), targetRec, goldenRec, txContext);
    // Replaces all values in the golden resource with the values in the target resource.
    // But IDs, identifiers and metadata are not replaced.
    helper.replaceAll();
    // Now, copy identifiers (system and value) in the golden record
    for (let i = 0; i < targetRec.getIdentifier().size(); i++) {
        let targetId = targetRec.getIdentifier().get(i);
        let goldenId = getIdentifier(goldenRec, targetId.getSystem());
        if (goldenId === null) {
            goldenRec.addIdentifier(targetId.copy());
        } else {
            goldenId.setValue(targetId.getValue());
        }
    }
}
function getIdentifier(resource, system) {
    for (let i = 0; i < resource.getIdentifier().size(); i++) {
        var id = resource.getIdentifier().get(i);
        if (id.getSystem().equals(system)) {
            return id;
        }
    }
    return null;
}