001/*-
002 * #%L
003 * HAPI FHIR - Master Data Management
004 * %%
005 * Copyright (C) 2014 - 2024 Smile CDR, Inc.
006 * %%
007 * Licensed under the Apache License, Version 2.0 (the "License");
008 * you may not use this file except in compliance with the License.
009 * You may obtain a copy of the License at
010 *
011 *      http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 * #L%
019 */
020package ca.uhn.fhir.mdm.api;
021
022import ca.uhn.fhir.mdm.model.MdmTransactionContext;
023import org.hl7.fhir.instance.model.api.IBase;
024
025/**
026 * Service that applies survivorship rules on target and golden resources.
027 */
028public interface IMdmSurvivorshipService {
029
030        /**
031         * Merges two golden resources by overwriting all field values on theGoldenResource param for CREATE_RESOURCE,
032         * UPDATE_RESOURCE, SUBMIT_RESOURCE_TO_MDM, UPDATE_LINK (when setting to MATCH) and MANUAL_MERGE_GOLDEN_RESOURCES.
033         * PID, identifiers and meta values are not affected by this operation.
034         *
035         * Applies survivorship rules to merge fields from the specified target resource to the golden resource. Survivorship
036         * rules may include, but not limited to the following data consolidation methods:
037         *
038         * <ul>
039         *  <li>
040         *  Length of field - apply the field value containing most or least number of characters - e.g. longest name
041         *  </li>
042         *  <li>
043         *  Date time - all the field value from the oldest or the newest recrod - e.g. use the most recent phone number
044         *  </li>
045         *  <li>
046         *  Frequency - use the most or least frequent number of occurrence - e.g. most common phone number
047         *  </li>
048         *  <li>
049         *  Integer - number functions (largest, sum, avg) - e.g. number of patient encounters
050         *  </li>
051         *  <li>
052         *  Quality of data - best quality data - e.g. data coming from a certain system is considered trusted and overrides
053         *  all other values
054         *  </li>
055         *  <li>
056         *  A hybrid approach combining all methods listed above as best fits
057         *  </li>
058         * </ul>
059         *
060         * @param theTargetResource        Target resource to merge fields from
061         * @param theGoldenResource        Golden resource to merge fields into
062         * @param theMdmTransactionContext Current transaction context
063         * @param <T>                      Resource type to apply the survivorship rules to
064         */
065        <T extends IBase> void applySurvivorshipRulesToGoldenResource(
066                        T theTargetResource, T theGoldenResource, MdmTransactionContext theMdmTransactionContext);
067
068        /**
069         * GoldenResources can have non-empty field data created from changes to the various
070         * resources that are matched to it (using some pre-defined survivorship rules).
071         *
072         * If a match link between a source and golden resource is broken, this method
073         * will rebuild/repopulate the GoldenResource based on the current links
074         * and current survivorship rules.
075         *
076         * @param theGoldenResource - the golden resource to rebuild
077         * @param theMdmTransactionContext - the transaction context
078         * @param <T> - Resource type to apply the survivorship rules to
079         */
080        <T extends IBase> T rebuildGoldenResourceWithSurvivorshipRules(
081                        T theGoldenResource, MdmTransactionContext theMdmTransactionContext);
082}