Custom merge rules


Administrators and data managers can define business logic for merge rules to ensure that field values are not lost or overwritten when two records are merged together; particularly custom field values.

When custom merge rules are applied to fields, they override regular Network survivorship rules. If custom merge rules are not defined, the field values that are retained during a merge are determined either by source survivorship or by the winning record.

Custom merge rules must be explicitly created for each object and country. They can be applied to Veeva fields (__v) and custom fields (__c); custom keys are not supported.

Applicable merges

Custom merge rules are automatically applied when records are merged during the following jobs:

  • Suspect Match
  • Unmerge - when combining 2 or more source records into a new record.
  • OpenData subscription
  • Bulk Merge
  • Data deduplication
  • Veeva OpenData takes ownership of record (under_review records and Send to OpenData requests).

Custom merge rules are only applied when you merge two or more records. They are not applied to update jobs (for example, source subscription update jobs).

Create custom merge rules

To define merge rules for objects in your Network instance:

  1. In the Admin console, click Data Model > Custom Merge Rules.

    The Custom Merge Rules page contains a section for each object type in your Network instance.

  2. Optional - Expand the Country list to filter the page for a specific country.
  3. In an object section (for example, Health Care Professional), click + Add Rule.

  4. In the Rule Name field, type an identifiable name for this merge rule.

    Name requirements:

    • Must be unique for each object; for example, Health Care Professional cannot have two rules with the same name.

    • Limited to 100 characters
    • Contains alphanumeric characters, hyphens (-) and underscores (_) only. Spaces are not permitted.
  5. Expand the Field list and select the field that this rule applies to. The fields are filtered by the object type.

    Custom merge rules support the following field types:

    • Numbers (integers, decimals)
    • Date (Date, Date and Time)
    • Checkbox
    • Reference
  6. The Winning Condition setting displays after the Field is selected. The condition is based on the field type. For example, if you choose cholecap_target__c (a checkbox field), the list displays the available options: True Wins or False Wins.

    Condition options

    Field Type Winning Condition Options
    Integer/Decimal Number Highest Value Wins / Lowest Value Wins
    Date Most Recent Wins / Oldest Value Wins
    Checkbox (reference with Boolean Reference list) True Wins / False Wins
    Reference Fields Upload the list of fields.
    Rank the reference codes for survivorship and then upload the edited file back into Network.
  7. Expand the Countries list and select all of the countries where this rule applies.

    The list contains all of the countries that the selected Field is enabled for; however, if the field is used for a country in another rule, that country removed from the list. This ensures that there is only one custom merge rule for a field for each country.

  8. The Enabled field is selected by default. Clear the field if you do not want to use this rule yet.
  9. Save your changes.

If the rule is enabled, the next time a merge action occurs, the field value survivorship will be defined by this rule.

Defining reference rankings

If you select a reference field type field for a custom merge rule, you can apply new rankings to the reference codes.

  1. In the Winning Condition field, click Upload New Ranking.
  2. In the Update Reference Rankings dialog, click Download. A .csv file is downloaded to your local computer; for example, ReferenceRanking_HCP_hcp_segment2__v_2019_03_04_GMT.csv.
  3. Open the .csv file and update the Ranking column to specify survivorship for each reference code.

    Considerations for ranking values:

    • Ranking value can be a positive integer or blank.
    • Ties are allowed; multiple reference values can have the same ranking value. If a tie occurs during a merge, the most recently updated reference value will be retained on the winning record.
    • Codes can have blank values. The ranking is treated as the lowest ranking.

    Example ranking file: hcp_segment2__c field

  4. In the Update Reference Rankings dialog, click Upload. Choose the updated file on your local computer.
  5. The Winning Condition field will update to display New ranking uploaded successfully.

After the custom merge rule is saved, the field survivorship rule will run when records are merged to preserve the requested field data on the winning record.

Field survivorship example

The rankings that were defined for the hcp_segment2__v field in the .csv file result in the following behavior after a merge.

Example Losing Record Winning Record End Result
1 Segment A (Ranking:1) Segment B (Ranking:2) Segment A
2 Segment D1 (Ranking:4) Segment C (Ranking:3) Segment C
3 Segment C (Ranking:3) Segment D1 (Ranking:4) Segment C
4 Segment D1 (Ranking:4) Null Segment D1
5 Segment D2 (Ranking:4) No Value Segment D2

Tie breaker cases

When a tie occurs between two reference code rankings, the winning value is retained from the record where the field was most recently updated.

Example Losing Record Winning Record End Result
6 Segment D1 (Ranking:4)
Last Modified: March 5, 2019
Segment D2 (Ranking:4)
Last Modified: January 1, 2019
Segment D1
7 Segment D2 (Ranking:4)
Last Modified: February 3, 2019
Segment D1 (Ranking:4)
Last Modified: March 13, 2019
Segment D1

View custom merge rules from the data model

You can view the rules that you've applied to a field from that field's data model page.

A Custom Merge Rules section displays on each data model field page. If the field has been used in a rule, the associated object displays in the merge rule summary. To edit or add a rule, click the Custom Merge Rules link to navigate to go to that page.

Suspect match exceptions

When custom merge rules for fields are enabled, they override Network survivorship rules. However, when data stewards are processing suspect match tasks, they can determine which fields survive on the winning record for fields on the object level (HCP, HCO, and so on). In this case, data stewards can override the defined custom merge rules because they often have information outside of this logic that would help them determine field survivorship.

This applies to object fields only; data stewards cannot pick sub-object and relationship object fields. Also, suspect match tasks that are generated from the Source Dedupe option in source subscriptions do not allow data stewards to pick object field values.

Bulk merge considerations

Two subscription properties can be used for merging records in bulk using source subscriptions; job.merge.allowSourceMerge and job.merge.mergeInstruction.

Custom merge rules are applied differently depending on the properties that are defined.

  • Custom merge rules apply to all applicable fields (recommended)

    Applies when the following properties are defined:

    "job.merge.allowSourceMerge": "true"

    and

    "job.merge.mergeInstruction": "InclusiveMerge"

    Inclusive merge means that all items (keys, sub-objects, fields) are considered for merging.

  • Custom merge rules apply to all applicable fields (recommended)

    Applies when the following properties are defined:

    "job.merge.allowSourceMerge": "true"

    and

    "job.merge.mergeInstruction": "ExclusiveMerge"

    Exclusive merge means that the values on the winning record are always retained.

  • Custom merge rules apply to custom fields only

    Applies when the following property is defined:

    "job.merge.allowSourceMerge": "true"

    If there is no merge instruction defined, merge applies to keys and custom fields only.

For more information about the bulk merge instructions, see Bulk merge.

Merge survivorship comparison

Field value survivorship can depend on the object type, field ownership, the type of merge job, and the merge instruction applied to the job.

Review this table to understand how field value survivorship is determined when merge rules are applied, and not applied, for each merge situation.

Merging two Veeva OpenData records

  Merge Logic for Objects
(HCP, HCO, custom object)
Merge Logic for Sub-objects / Relationship Objects
  Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied. Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied.
Fields without merge rules Veeva OpenData value wins Value from winning record retained. If no value on winning record, value from losing record retained. Veeva OpenData value wins. Value from winning record retained. If no value on winning record, value from losing record retained

Merging a locally managed record into a third party master record

Merge Job Merge Logic for Objects
(HCP, HCO, custom object)
Merge Logic for Sub-objects / Relationship Objects
Merge a locally managed under_review record into a third party master record (DCR)
Third Party Master Field Custom Fields Third Party Master Field Custom Fields
Fields with merge rules Merge rule not applied.
Third party master value wins.
Merge rule applied. Merge rule not applied.
Third party master value wins.
Merge rule applied.
Fields without merge rules Third party master value wins. Value from winning record retained. If no value on winning record, value from losing record retained. Third party master value wins. Value from winning record retained. If no value on winning record, value from losing record retained.
Data Deduplication
Third Party Master FieldCustom FieldsThird Party Master FieldCustom Fields
Fields with merge rulesMerge rule not applied.
Third party master value wins.
Merge rule applied.Merge rule not applied.
Third party master value wins.
Merge rule applied.
Fields without merge rulesThird party master value wins.Source survivorship determines the winning value.Third party master value wins.Source survivorship determines the winning value.
Suspect Match - No field picking (tasks that are generated from Source Dedupe)
Third Party Master FieldCustom FieldsThird Party Master FieldCustom Fields
Fields with merge rulesMerge rule not applied.
Third party master value wins.
Merge rule applied.Merge rule not applied.
Third party master value wins.
Merge rule applied.
Fields without merge rulesThird party master value wins.Value from winning record retained. If no value on winning record, value from losing record retained.Third party master value wins.Value from winning record retained. If no value on winning record, value from losing record retained.
Suspect Match - Field picking allowed (objects only)
Third Party Master FieldCustom FieldsThird Party Master FieldCustom Fields
Fields with merge rulesMerge rule not applied.
Third party master value wins.
Merge rule not applied.
Field picked by data steward wins.
Merge rule not applied.
Third party master value wins.
Merge rule applied.
Fields without merge rulesThird party master value wins.Field picked by data steward wins.Third party master value wins.Value from winning record retained. If no value on winning record, value from losing record retained.
Bulk Merge - No Merge Instruction (default)
Third Party Master FieldCustom FieldsThird Party Master FieldCustom Fields
Fields with merge rulesMerge rule not applied.
Third party master value wins.
Merge rule applied.Merge rule not applied.
Third party master value wins.
Merge rule applied.
Fields without merge rulesThird party master value wins.Source survivorship determines winning value.Third party master value wins.Source survivorship determines winning value.
Bulk Merge - Inclusive Merge Instruction
Third Party Master FieldCustom FieldsThird Party Master FieldCustom Fields
Fields with merge rulesMerge rule not applied.
Third party master value wins.
Merge rule applied.Merge rule not applied.
Third party master value wins.
Merge rule applied.
Fields without merge rulesThird party master value wins.Source survivorship determines winning value.Third party master value wins.Source survivorship determines winning value.
Bulk Merge - Exclusive Merge Instruction
Third Party Master FieldCustom FieldsThird Party Master FieldCustom Fields
Fields with merge rulesMerge rule not applied.
Third party master value wins.
Merge rule applied.Merge rule not applied.
Third party master value wins.
Merge rule applied.
Fields without merge rulesThird party master value wins.Value from winning record retained. If no value on winning record, value from losing record retained.Third party master value wins.Value from winning record retained. If no value on winning record, value from losing record retained.

Merging a locally managed record into a Veeva OpenData record

Merge Job Merge Logic for Objects
(HCP, HCO, custom object)
Merge Logic for Sub-objects / Relationship Objects
Merging an under_review record into a Veeva OpenData record (data change request, Send to OpenData)
  Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied. Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied.
Fields without merge rules Veeva OpenData value wins Value from winning record retained. If no value on winning record, value from losing record retained. Veeva OpenData value wins. Value from winning record retained. If no value on winning record, value from losing record retained
Data Deduplication
Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied. Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied.
Fields without merge rules Veeva OpenData value wins. Value from winning record retained. If no value on winning record, value from losing record retained. Veeva OpenData value wins. Value from winning record retained. If no value on winning record, value from losing record retained.
Suspect Match - No Field Picking (tasks that are generated from Source Dedupe)
Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied. Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied.
Fields without merge rules Veeva OpenData value wins. Value from winning record retained. If no value on winning record, value from losing record retained. Veeva OpenData value wins. Value from winning record retained. If no value on winning record, value from losing record retained.
Suspect Match - Field Picking Allowed (objects only)
Veeva fieldsCustom FieldsVeeva FieldsCustom Fields
Fields with merge rulesMerge rule not applied.
Veeva OpenData value wins.
Merge rule not applied.
Field picked by data steward wins.
Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied.
Fields without merge rulesVeeva OpenData value wins.Field picked by data steward wins.Veeva OpenData value wins.Value from winning record retained. If no value on winning record, value from losing record retained.
Bulk Merge - No Merge Instruction (default)
Veeva fieldsCustom FieldsVeeva FieldsCustom Fields
Fields with merge rulesMerge rule not applied.
Veeva OpenData value wins.
Merge rule applied.Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied
Fields without merge rulesVeeva OpenData value wins.Source survivorship determines winning value.Veeva OpenData value wins.Source survivorship determines winning value.
Bulk Merge - Inclusive Merge Instruction
Veeva fieldsCustom FieldsVeeva FieldsCustom Fields
Fields with merge rulesMerge rule not applied.
Veeva OpenData value wins.
Merge rule applied. Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied.
Fields without merge rulesVeeva OpenData value wins.Source survivorship determines winning value.Veeva OpenData value wins.Source survivorship determines winning value.
Bulk Merge - Exclusive Merge Instruction
Veeva fieldsCustom FieldsVeeva FieldsCustom Fields
Fields with merge rulesMerge rule not applied.
Veeva OpenData value wins.
Merge rule applied.Merge rule not applied.
Veeva OpenData value wins.
Merge rule applied.
Fields without merge rulesVeeva OpenData value wins.Value from winning record retained. If no value on winning record, value from losing record retained.Veeva OpenData value wins.Value from winning record retained. If no value on winning record, value from losing record retained.

Merging two locally managed records

Merge Job Merge Logic for Objects
(HCP, HCO, custom object)
Merge Logic for Sub-objects / Relationship Objects
Bulk Merge - Inclusive Merge Instruction
  Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule applied. Merge rule applied. Merge rule applied. Merge rule applied.
Fields without merge rules Source survivorship determines winning value. Source survivorship determines winning value. Source survivorship determines winning value. Source survivorship determines winning value.
Bulk Merge - Exclusive Merge Instruction
Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule applied. Merge rule applied. Merge rule applied. Merge rule applied.
Fields without merge rules Value from winning record retained. If no value on winning record, value from losing record retained. Value from winning record retained. If no value on winning record, value from losing record retained. Value from winning record retained. If no value on winning record, value from losing record retained. Value from winning record retained. If no value on winning record, value from losing record retained.
Bulk Merge - No Merge Instruction (default)
Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule not applied.
Value is retained from the winning record, even if the value is null.
Merge rule applied. Merge rule not applied.
Value is retained from the winning record, even if the value is null.
Merge rule applied.
Fields without merge rules Value is retained from the winning record, even if the value is null. Source survivorship is applied. Value is retained from the winning record, even if the value is null. Source survivorship is applied.
Suspect Match - Field Picking Allowed (object fields only)
Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule not applied.
Field picked by data steward wins.
Merge rule not applied.
Field picked by data steward wins.
Merge rule applied. Merge rule applied.
Fields without merge rules Field picked by data steward wins. Field picked by data steward wins. Value from winning record retained. If no value on winning record, value from losing record retained. Value from winning record retained. If no value on winning record, value from losing record retained.
Suspect Match - No Field Picking (tasks that are generated from Source Dedupe)
Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule applied Merge rule applied Merge rule applied Merge rule applied
Fields without merge rules Value from winning record retained. If no value on winning record, value from losing record retained. Value from winning record retained. If no value on winning record, value from losing record retained. Value from winning record retained. If no value on winning record, value from losing record retained. Value from winning record retained. If no value on winning record, value from losing record retained.
Data Deduplication
Veeva fields Custom Fields Veeva Fields Custom Fields
Fields with merge rules Merge rule applied. Merge rule applied. Merge rule not applied. Merge rule applied.
Fields without merge rules Source survivorship determines winning value. Source survivorship determines winning value. Source survivorship determines winning value. Source survivorship determines winning value.

Managing configurations

You can export custom merge rules so you can import them to a target environment. Custom merge rules for custom object fields are not supported for configuration packages.

For more information about creating export packages and importing them to another environment, see Managing configurations.