This article explains the basics of Service Bus communication: why is the communication required and how to implement a minimal version needed to properly implement Connect ID integration. Intended reader is a developer responsible for integrating their Football Management System with Connect ID SDK. Information in this article is valid from version 6.1.381 of the SDK.


One of the intended benefits of FIFA Connect ID Service is that a football player - whether amateur or professional - who changes clubs or even countries (MAs), keeps their FIFA_ID. Knowing the whole football history of a given player is important during transfers and for all the solidarity mechanisms to work correctly. At the same time, Connect ID Service cannot store any personal details of a player or their history - this information stays within local Football Management Systems (FMS) due to data protection regulations. With these constraints, can we somehow know that a person who wants to register at a club, has any football history in our or different MA? And how do we avoid data duplication, that is registering the same player with a new FIFA_ID?


Connect ID provides both the process & infrastructure for duplicate detection and thus prevents re-registering the same player with a new FIFA_ID. We will first look at the process and then explain how to use the existing infrastructure to align with this process at a minimal effort.


Process of duplicate detection


When MA tries to register a player in Connect ID Service (via SDK), the following happens:

  • SDK provides name & date of birth of a Person and requests a new FIFA_ID
  • Connect ID Service runs a duplicate check based on the name & date of birth alone and if potential duplicates are found...
  • Connect ID Service returns the list of FIFA_IDs of potential duplicates and information where (in which MAs) they are registered
  • as there is no personal data in the return message from FIFA_ID, a human operator cannot effectively decide whether a record is indeed a duplicate or not. To achieve this, full player details are needed.
  • SDK communicates with other MAs (over Service Bus), automatically requesting and receiving person details.
  • person details received from other MAs are displayed to human operator who can now decide whether a given person is indeed a duplicate or not.


Note that although this process is fully automated (single register method), it requires every MA to implement a mechanism to receive a request and send back person details. Implementing such a mechanism is a mandatory condition for successfully integrating with Connect ID Service. The second part of this article shows how to do it in the most effective way (single method).


Infrastructure for duplicate detection; implementation


Two MAs communicate with each other using Service Bus architecture, which is focused on queues and messages. That means vendors are not sending messages directly to themselves. Instead, each of them sends message to dedicated Service Bus queue. Then messages from queues are read by vendors and processed. The SDK that we provided, wraps up and makes this functionality easier to use, so there's a feeling of peer-to-peer connection.  


Each MA that use .NET version of the SDK needs to implement and set up background listener (that needs to run constantly). It is responsible for getting messages from other MAs as well as for sending messages with person details to other MAs. Example implementation is described in the documentation (2.4 Configure listener) which is attached to SDK package. In order to provide person details in your solution, you need to create a class implemening IPersonDetailsProvider interface.


Main part of classes that implement mentioned interface is GetPersonDetails() method. Here you need to fetch person (identified by request.UniqueFifaId) data from your local database and return it in XML format compliant with FIFA Data Standard. Our recommendation here is to use PersonLocalXmlSerializer service, so that creating document is easier and generated output is automatically validated against FIFA Data Standard. See an example below: 


public string GetPersonDetails(PersonDetailsRequest request)
{
    // creating an instance of the object
    // required fields
    var personLocal = new PersonLocal("ΧΑΡΑΛΑΜΠΟΥΣ", Gender.Male, ISO3166CountyCode.CY,
        new DateTime(1990, 11, 11), ISO316613CountyCode.CY, "Larnaca", ISO6392LanguageCode.Gre, ISO3166CountyCode.CY);
    var personFIFAId = request.UniqueFifaId;

    // optional fields
    personLocal.PersonFIFAId = "105C3Z1";
    personLocal.LocalFirstName = "ΑΓΓΕΛΗΣ";
    personLocal.LocalSystemMAId = "1234567";
    personLocal.InternationalFirstName = "ANGELIS";
    personLocal.InternationalLastName = "CHARALAMBOUS";
    personLocal.RegionOfBirth = "Larnaca";

    var playerRegistration = new PlayerRegistration(personFIFAId, Status.Active, "105C40I", new DateTime(2003, 4, 11),
        RegistrationLevel.Amateur, Discipline.Football, PlayerRegistrationNature.Registration);

    // optional fields
    playerRegistration.RegistrationValidTo = new DateTime(2006, 6, 15);

    // include player registration in PersonLocal
    personLocal.AddPlayerRegistration(playerRegistration);

    // add photo
    var absolutePathToPhoto = "C:\\image.png";
    var picture = new PictureEmbedded(absolutePathToPhoto);

    // include photo in PersonLocal
    personLocal.Photo = new Photo(picture);

    // serialize object into XML
    var xmlSerializer = new PersonLocalXmlSerializer();

    String xmlString = null;
    try
    {
        xmlString = xmlSerializer.Serialize(personLocal);
    }
    catch (XmlSerializationException e)
    {
        var validationErrors = e.XmlValidationErrors;
        // handle serialization exception
    }

    return xmlString;
}


As shown above, first step to serialize data to XML structure is creating PersonLocal instance. All required fields (in accordance with FIFA Data Standard) must be provided, otherwise any deficiencies will be detected during validation. This rule applies for all model classes used in XML serialization process.


Each registration type can be included in XML file by adding new elements to lists by following methods: AddPlayerRegistration(), AddTeamOfficialRegistration(), AddMatchOfficialRegistration() and AddOrganisationOfficialRegistration(). When creating registration instances (i.e. PlayerRegistration) all mandatory fields are required by constructor of the class - same as for it goes for PersonLocal.


Usage of PersonLocalXmlSerializer is limited to running method Serialize() which takes PersonLocal object as an input. Under the hood, this method creates XML string and executes validation against FIFA Data Standard. In case validation fails, XmlSerializationException will be thrown giving a message with all possible issues that were found during validation. As all of this happens in background listener, you should implement a proper error handling when catching the exception, so to get notified in case when XML response was not generated. Note that in case of exception thrown, MA that was asking for person details, won't receive a correct answer, so it's important to keep data structure valid and try to limit number of exceptions.


For more detailed information please go to SDK documentation - chapter 3.1 Working with PersonLocal.