In May 2023, the rules for merging two persons were changed. The change was made on the server side and there is no need for users to upgrade their SDK.
This article explains the new rules for merging to help users troubleshoot any potential issues more easily.


In every merge operation, there are two persons (two FIFA_IDs) involved: PRIMARY and SECONDARY. The FIFA_ID passed to a Merge(...) method as SECONDARY will become "inactive" meaning the record will no longer be available. Any client trying to execute any operation on the SECONDARY merged record, will receive a 301 ("Person merged") error. One reason for introducing Notifications (you can find more here: Connect ID Notifications) was to inform the data holders of the SECONDARY merged FIFA_ID so that they know that they should replace their FIFA_ID. FIFA_ID passed as PRIMARY will continue to exist without any changes.


When is it allowed to merge two persons?

The simplest way to explain the rule is as follows: you can merge if you have any registration for a given record and your registration is equal to or higher-ranked (in terms of the status, so "active" > "pending" > "inactive") than other MA's registration for a SECONDARY record. 


In practice, you will be able to merge SECONDARY record into PRIMARY record if:

  1. either you're the only MA to have any SECONDARY registration
  2. or you have an "active" SECONDARY registration
  3. or you have a "pending" SECONDARY registration and all other SECONDARY registrations have "pending" or "inactive" status only (PRIMARY registrations may be active, pending or inactive)
  4. or you have an "inactive" SECONDARY registration and all other SECONDARY registrations have "inactive" status only (PRIMARY registrations may be active, pending or inactive)

 

Even if none of the above conditions is fulfilled, you'll also be able to merge if:

  1. you have an "active" PRIMARY registration
  2. you have a "pending" PRIMARY registration and all other MA's SECONDARY registrations are "pending" or "inactive"
  3. you have an "inactive" PRIMARY registration and all other MAs' SECONDARY registrations are "inactive"


The lack of symmetry in the rules is caused by the fact that the merge is going to "invalidate" the SECONDARY FIFA_ID, requiring other MAs to replace their FIFA_IDs. At the same time any PRIMARY MAs will not be affected at all.


Merge scenarios

There are two typical merge scenarios that you may encounter when resolving duplicate player records in Connect ID.


Scenario 1 – Both duplicate records exist in your NRS


In this scenario, your National Registration System (NRS) contains both duplicate player records.

You should perform your standard internal merge operation within your NRS and, as part of that process, also send the corresponding MergePersonsAsync request to the Connect ID Service. This ensures that the duplicate records are merged centrally as well.


Scenario 2 – Only one record exists in your NRS


To resolve the duplicate:

  • Update your local player record to use the Primary FIFA ID (the FIFA ID that will remain after the merge).
  • Send the corresponding MergePersonsAsync request to the Connect ID Service.


Additional actions after a merge


If the player is currently registered and actively playing in your Member Association, you should also make sure and if needed add the player's latest registration to the Primary FIFA ID in Connect ID. This effectively performs a takeover of the record, making your Member Association the current Data Owner.


If the player only played historically in your Member Association and is no longer active there, you should be careful. If your MA is more recent then the other one, you can still add an inactive registration and become a Data Owner. But if the registration of the other MA is more recent than yours, you should do nothing and they should remain a Data Owner.

If you are merging as part of the data fixing actions recommended in a DXP ticket, you don't need to analyse whether to add a registration or not. DXP will look at the dates automatically and either display a 3rd data fixing action "Add a registration…" or not.


When is it NOT allowed to merge two persons?

You will not be able to merge a SECONDARY record into a PRIMARY record if:

  1. either you don't have any registration for any of the records, regardless of the registration status.
  2. or your registration for a SECONDARY record is lower-ranked than a registration of another MA for a SECONDARY record
    1. your registration is "inactive" while the other registration is "pending" or "active"
    2. your registration is "pending" while the other registration is "active"
  3. or your registration for a PRIMARY record is lower-ranked than a registration of another MA for a SECONDARY record


Point 1 is easy to explain: if you do not have a stake in any of the persons (i.e. you don't have a registration) you should not be allowed to manage them.


Rule number 2 is caused by the fact, that merging a record as SECONDARY makes it unavailable. Because another MA has a registration, merging causes them some trouble - at least until they act on a notification and replace the FIFA_ID. Hence the rule that only allows you to do it if your registration is equal to or higher-ranked than of the other MA.


Rule number 3 can be explained in the same way as rule number 2. Merges cause some trouble for registration owners of SECONDARY record, so our registration should be equal to or higher-ranked to perform the merge. Let's observe again that the algorithm never compares your registration with PRIMARY registrations. The reason is that owners of PRIMARY registrations are not affected by the merge.


When are the new rules less restrictive than the previous ones? 

In general, the new rules are less restrictive.

We no longer require MA to have an active registration for any of the FIFA_ID. Their registration can be pending or inactive, as long as other MA's secondary registrations are also pending or inactive.

Additionally, the new rule addresses a bug that prevented persons to be merged if any of the registrations was "pending".


When are the new rules more restrictive? 

There is only one such case. Previously you could merge even if you didn't have any registration as long as none of the persons had any active registrations. This is now forbidden.


Error codes/messages

If you are not allowed to merge or unmerge two persons, the operation will fail and throw an exception of type "DataValidationException" with message to aid with troubleshooting. The message will specify which player registrations are missing from either of the players. An example of this message is as follows:


You are not allowed to merge person {SECONDARY_FIFA_ID} (secondary) into {PRIMARY_FIFA_ID} (primary). In order to perform this merge you need to have: either active/pending registration in secondary or either active/pending registration in primary. For more details refer to the documentation.


Ummerge operations

Rules for the unmerge operation are identical.


If you are interested in merges, you may also find the following resources interesting:
What to do if two or more records come up as potential duplicates?
Connect ID Notifications
Merging: how to decide which record is primary?
Merging: Understanding Primary and Secondary FIFA IDs After a Merge in Connect ID