Merging duplicate addresses

AD
DM

Source subscriptions can be used to merge addresses in bulk. Administrators and Data Managers can create source files to merge two addresses on an HCO or HCP. When two addresses are merged on an entity, the custom keys of the losing address are added to the winning address.

This feature is not enabled by default. To enable it for your Network instance, contact Veeva Support.

Addresses supported for bulk merge

Bulk merges are supported for the following types of addresses:

  • Customer-managed into customer-managed

  • Customer-managed into Veeva OpenData managed

  • Customer-managed into third party managed

Merging Veeva OpenData or third party owned addresses into customer-managed addresses is not supported. OpenData and third party addresses always win when they are merged with customer-managed addresses.

Source file requirements

To bulk merge addresses, an entity file and an address file must be loaded into the source subscription.

Entity file (HCO, HCP)

Tip: You can include an HCP file and an HCO file in the same bulk merge job.

The file must be a single column containing the following data:

  • ID or key of the HCP or HCO

Examples

HCP file

vid__v
243242421553464326

HCO file

vid__v
243242421553464375

Address file

The address file identifies the entity and the two addresses that are being merged.

Include the following data in the file:

  • Veeva ID (entity_vid__v) of the HCP or HCO

  • VID (vid__v) of the losing address

  • VID (merge_survivor_vid) of the winning address

Example

entity_vid__v vid__v merge_survivor_vid
243242421553464326 43324242155346479 54454242155346434
243242421553464375 33324242155795746 57654565495231456

Source subscription details

The subscription can be configured using Wizard Mode or Classic Mode.

Configuration

The source subscription should be configured just like any subscription for data loading; for example, it requires file definitions and a model map.

The match configuration is not required for address merge jobs. The source files consist of Veeva IDs so the job will perform a key match.

For more information, see Adding a source subscription.

[
  {
    "entity": "HCP",
    "from": "HCP",
    "attributes": [
      "HCP.* AS *"
    ]
  },
  {
    "entity": "HCO",
    "from": "HCO",
    "attributes": [
      "HCO.* AS *"
    ]
  },
  {
    "entity": "ADDRESS",
    "from": "ADDRESS JOIN HCP ON HCP.vid__v = ADDRESS.entity_vid__v",
    "attributes": [
      "ADDRESS.* AS *",
      "HCP.VDM_ENTITY_ID AS VDM_FKENTITY_ID"
    ],
     "customkeys": [
        {
          "value": "ADDRESS.AMS_locid__v"
        }
     ]
  },
  {
    "entity": "ADDRESS",
    "from": "ADDRESS JOIN HCO ON HCO.vid__v = ADDRESS.entity_vid__v",
    "attributes": [
      "ADDRESS.* AS *",
      "HCO.VDM_ENTITY_ID AS VDM_FKENTITY_ID"
    ]
  }
]

Required properties

To bulk merge addresses, the following property must be added to the Advanced Properties in the source subscription configuration.

  • "job.merge.allowSourceMerge": "true",

The bulk merge job adds the custom keys from the losing address to the winning address. If you do not want the keys moved to the winning address, include this property:

  • "job.merge.mergeInstruction.ADDRESS": "NoKeysMerge",

Important: If custom keys remain on the losing address, any updates from sources using custom keys will update the losing address.

When the subscription is configured, run the job to merge the addresses.

Job issues

When the job runs, the data is validated. Addresses that do not meet the requirements will be skipped so the job can continue.

Addresses are not merged for the following reasons:

  • The losing or winning addresses are not sub-objects of the main entity.

  • The entity does not exist.

  • The address does not exist.

  • The losing address is owned by Veeva OpenData or a third party source.

  • The record state is Under_Review for the winning or losing address.

  • The winning or losing address is copied to the entity from a parent affiliation through Network Address Inheritance.

On the Job Details page, the Job Error Log section displays a message if any of these issues occur.

Example

Network address inheritance considerations

Inherited addresses will be resynced during the next Network address inheritance Refresh job if the parent address is merged into another address. However, merging between inherited addresses on an entity is restricted.

Primary address considerations

Primary addresses are retained during the bulk merge job. If either of the addresses were defined as a primary address before the merge, the winning address will be set to primary during the bulk merge job.

Network calculated primary addresses

If the winning address is inactive or invalid, the primary address will be recalculated to find a new primary address on the entity.

Unique checkbox primary addresses

The options that you have selected in the unique checkbox configuration determines if the primary address should be recalculated.

License considerations

If the losing address is linked to any license on the entity, the license will be updated with the winning address.

Data change requests

Change requests submitted for the losing address will be automatically rejected. For In-Queue and associated tasks, the task will be closed automatically if the change requests applies only to the losing address. If the change request contains other changes, the change for the losing address is rejected and Data Stewards can process the remaining changes.