The following instruction is a step-by-step guide to kick off integration with Connect ID Service. It is divided into 5 stages which can be seen as levels of integration - the higher the stage, the more advanced and complete the integration is.

Before starting this instruction, we recommend that you read this article describing the basic concepts of the Connect ID Service. While this is not mandatory reading, it will help you understand why we ask you to do certain steps in this instruction.


If you run into any trouble during the implementation, feel free to contact us via our Support Portal (see below) but also take a look at the FAQ section. With so many MAs on-boarded the chance is that someone has been there before!


Note: whenever the instruction below refers to the [main] SDK documentation, we mean the HTML file contained in the zipped SDK package we ask you to download in Stage 1. It may have a different name depending on the technology and version of the package. Currently, the documentation is in the following files:

  • fifa-connectid-sdk-php-6.1.html
  • fifa-connectid-sdk-net-6.1.html
  • fifa-connectid-sdk-java-6.2.html


Stage 1 - basics

This chapter lists all the preparatory steps required to start integrating your solution with ConnectID. It includes getting credentials, downloading libraries and registering them in your solution. When you have completed the steps in Stage 1, you will be ready to start the integration and implement the first business scenario of a person registration.


  1. Go to the Support Portal (https://support.id.ma.services/support/home) and press "New support ticket".
  2. Request credentials for the Beta environment from the ConnectID team. Specify the name of your Member Association. More on the environments we use can be found here.
  3. Credentials will be sent to your e-mail address as ClientID and SecretKey values. You will later need to set these values in the source code and ConnectID will use them to verify your identity and permissions.
  4. We will also send you a new user & password which you will later use to access our Admin Console system for troubleshooting & reporting purposes. E.g. if you used an SDK to register a player, you will probably want to log in to the Admin Console and confirm that the player has been registered.
  5. The same user & password as in point 4. can be used to access DevTools - the system you can use to verify and track your integration progress.
  6. Download the latest version of the SDK from the Support Portal (https://support.id.ma.services/support/solutions/7000001343). Choose the version that fits your technology (.NET, Java, PHP).
  7. Unpack the SDK (it comes as a zip file).
  8. Find the file fifa-connectservicebus-certificates-generation.html and follow the instructions inside. This will allow you to generate your public & private key. They will be used to encrypt direct communication with other MAs via Service Bus.
  9. Reference ConnectID libraries in your solution. Libraries to be referenced are listed in chapter 2. Setup of the SDK documentation.


Stage 2 - force registration of a person

The goal of this Stage is to verify that you can successfully authenticate with the ConnectID Service and pass information to it from your system, which is required to register a person. In this stage, we will only look at the most basic scenario assuming that there are no potential duplicates found by the ConnectID Service. In order to ensure that the service will ignore duplicates, you will use force registration instead of a standard one.


Note that in stages 2, 3 and 4, you will only use class RegistrationFacade. Methods in this class allow you to simplify the integration as they hide all the technical complexity of the ConnectID Service behind a few easy-to-use methods. You are not expected to use the class FifaConnectIDClient described in chapter 3.3 Working with FIFA Connect ID Client of the SDK documentation.

  1. Go to the SDK documentation and follow the instructions described in chapter 2.3 Using Registration Facade. The RegistrationFacade class will need to know the location of your private key. It will use it in Stage 3, when we deal with records that cannot be registered due to existing duplicates. For our particular scenario (force registration), the private key won't be used but the constructor of RegistrationFacade requires it anyway.
  2. Follow the instructions in chapter 2.3 to create the RegistrationFacade. Note that you are passing already generated credentials, i.e. ClientID, SecretKey and PrivateKey [location].=
  3. Jump to chapter 3.2.1 (Register new person) and create a PersonData object as described in the first code snippet.
  4. Pass your person object to the RegistrationFacade.ForceRegisterPerson(...) method. Remember that at this stage our goal was to register a person but bypass a duplicate check. Therefore you were not required to use method RegistrationFacade.RegisterPersonAndWaitForDetailsInCaseOfDuplicates(...) as described in the code snippet from chapter 3.2.1.
  5. Note, that in order to ensure data consistency, you have to use personLocalId as an additional parameter during person registration (with or without the force). More on this in chapter 3.2.1.1 Idempotency.
  6. Go to the Admin Console https://fci-adminconsole-beta.azurewebsites.net/ and navigate to the Audit Trail. If your registration has been successful, you will see your record at the top.
  7. We assume that you have remembered to save the FIFA_ID of the newly registered person in your Football Management System. If not, please do it - we'll need it in Stage 4 of this instruction.

  8. Note: remember all the details of the person you have registered. In Stage 4 we will ask you to register the same person again - this time without the force.


Now, when you have successfully registered your first person, it is time to address the topic of handling international duplicates. You are going to do it in two stages. First you will implement a service that will reply to other MAs when they ask for person details from your system. Later you will learn how to ask for person details yourself and how to interpret replies from other MAs.


Stage 3 - sharing person details with other MAs

Stage 3 lists the steps required to share person details with other Member Associations. This is required to prevent them from registering a duplicate. 


Later, in Stage 4, you will learn how to ask other MAs for details of potential duplicates of your record. We will however start the topic of duplicates by asking you to implement a service that will reply to other MAs' queries for player details. This functionality will address the most important scenario of person registration. Imagine that MA X tries to register a person. They get information from the ConnectID Service about a potential duplicate. No personal details are given to MA X - remember that the ConnectID Service does not store personal data. However, MA X gets information that potential duplicate belongs to your MA and it has a certain FIFA_ID.

In this situation, MA X is going to send you, via the Service Bus, an encrypted message: request-for-person-details. We will now show you how to recognize such a message and send a reply. 


The good news is that all the complexity behind communicating with other MAs has already been solved for you. SDK takes care of encrypting your message and decrypting messages sent to you. SDK will also understand that a message arrived and that the type of message is a request-for-person-details. The following is left for you to implement:

  • implement custom code (PersonDetailsProvider interface) which, based on the FIFA_ID received as a PersonDetailsRequest parameter, will fetch person details from your own Football Management System and return them. Complete information about the person details provider can be found in chapter 2.4.1 Person Details Provider.
    Although the message travels in XML format, you don't need to worry about manual XML generation and validation - SDK comes with a tool (PersonLocalXmlSerializer) to transform your PersonLocal object to XML automatically. Guide on handling the XML is available in chapter 3.1 Working with PersonLocal.
    • You might wonder what information you should return to another MA when it asks for person details. Here we directly follow FIFA's Data Standard and to make things even easier, all information required by the standard is also required in the PersonLocal constructor: last name, gender, nationality, date of birth, country of birth, place of birth, language and country. We recommend that you pass much more information (e.g. player's history) in the final implementation, but for now it is enough to fill in mandatory data. Please be aware that the above-mentioned fields are mandatory so you need to fill them in each case of a Person Detail request. Please check whether you have records in your database where some of these fields might be missing so that workarounds can be defined (e.g. if Place of Birth is missing, you can provide "unknown").
  • start your background listener to make sure that you can send & receive messages to/from other MAs. Listener configuration depends on the technology you use. .NET and Java are multi-threaded while PHP is not and it needs an additional layer to share data between the listener and the web application/registration script. In the SDK documentation (2.4 Configure listener) you will find a detailed description of how to start the listener in your technology.


If you implemented the steps listed above, you should have a running listener waiting for requests for person details from other MAs. You can automatically verify if the setup is correct by going to DevTools and running the tests: PE02, PE04, PE05 and PE06.

Your solution is now able to:

  • force register a person
  • reply with person details to other MA to help them determine whether their person is a duplicate of someone from your Football Management System

The last element of the person registration scenario will be to learn how to ask another MA for person details and how to interpret their answer.


Stage 4 - understanding the details of potential duplicates

In Stage 4 you will develop the final version of a person registration scenario. You will learn how to handle potential duplicates during the registration and how to acquire person details from other Member Associations.


Remember how you created a PersonData object and passed it to the RegistrationFacade.ForceRegisterPerson(...) method in Stage 2? That method can be used in Production system but only under specific circumstances - when you already know that the person you are about to register has no true duplicates. So how do we know whether something is an actual duplicate and not a so-called false positive? The full, recommended process of a person registration should work in the following way (business description follows here, exact technical steps will be specified after):

  • when you have created the object PersonData, instead of force registering it as in Stage 2, you should try to register it with the method RegistrationFacade.RegisterPersonAndWaitForDetailsInCaseOfDuplicates(...)
  • what this method does in the background is to contact the ConnectID Service and check for duplicates. If there are any, download basic information to the client/SDK
  • still inside this method, our code sends encrypted messages via the Service Bus to all MAs owning potential duplicates, asking them to provide full person details
  • the method exits when all replies have been received (but no later than the timeout seconds given as a parameter) and returns a collection of potential duplicates with person details received from other MAs
  • having personal data of potential duplicates, you are now able to display them to the Football Management System user, so that they can take a decision whether the person they want to register has duplicates or not (details in the article Building user interface for duplicate resolution)
  • actions that should be performed resulting from this decision depend on the business processes (described here) but for now, we recommend that you don't worry about that. It's enough to understand that if all duplicates turned out to be false positives, you should force register a person (like in Stage 2) and if a true duplicate has been found, their FIFA_ID should be used (and potentially a transfer process started).

Note that all the complexity of checking the duplicates and getting details from other MAs is hidden from you behind the RegistrationFacade class. That's actually why we named the class that.


If you still wonder why the whole mechanism of the Service Bus communication is required for a simple person registration, remember that the Connect ID Service does not store personal data. If we relied only on information from ConnectID when deciding about duplicates, the user would rarely be able to take the right decision. For example, they would see something like this: "The person you are trying to register seems to be a duplicate of: football amateur player from France, male, born on 1978-04-23. Names are matching with 0.6 score.". We wouldn't even be able to show the full name of a potential duplicate, let alone their photo or history!

There's one more thing you need to know before we'll show you how to implement this scenario. Perhaps you even thought of it already: "what if the record I'm trying to register does not have an international but a local/national duplicate?". "Do I need to provide an additional implementation that would first check if there are local duplicates and only then proceed to checking international ones with Connect ID?".

Good news: no, you don't. We use exactly the same mechanism for checking both local and international duplicates! Read the description of the process given above again - does it say anywhere that the system will only contact MAs other than yours? Fortunately not. If ConnectID finds a duplicate in your MA, your client/SDK will simply send a message via Service Bus to itself, execute PersonDetailsProvider which you implemented in Stage 3, and send back person details. In the end, your user will see the details coming from your own Football Management System. It is true that this communication goes around a bit, and there is a shortcut. But to have a shortcut, you would need to implement a separate mechanism for handling local duplicates and we don't want you to spend time on this. Instead we made Service Bus more powerful, so that it can handle all the communication required.

After this somewhat long introduction, you are now good to proceed to the technical implementation. As we mentioned two scenarios above (for national and international duplicates), we'll do the same with implementation.


Scenario 1 - Getting duplicate details from your own database (national duplicates)

  • you already registered a person in Stage 2 of this instruction. Now let's take their data and try to register the same person again. This time, however, you will use RegistrationFacade.RegisterPersonAndWaitForDetailsInCaseOfDuplicates(...) instead of RegistrationFacade.ForceRegisterPerson(...) method. This particular operation is well described in chapter 3.2.1 Register new person of SDK documentation. As person is already registered in FIFA database, it is not possible to register the same record again (assuming that registration is not forced) - request will return 409 HTTP error code (conflict). Remember, though, that it all happens behind the scenes. When 409 is returned internally, SDK will automatically send requests for person details to all MAs who owns potential duplicates in their local databases. In this particular case, your SDK will send this request to itself and respond back also to itself (because person is registered in your system, right?).
  • please take a look at the code snippet from chapter 3.2.1 - in string duplicateWithDetails.PersonDetails you will find a response in XML format that was generated and returned by your PersonDetailsProvider. When you open the XML document, you will see that it contains the same data as you set using PersonLocal class in Stage 3.


If you reached this point, you proved that your implementation correctly responds with person details. We checked it for you at the end of Stage 3 using our tool, but now you have proven it yourself.


Scenario 2 - Getting duplicate details from other MAs (international duplicates)

  • basically, steps that will be done here are very similar to what you did in the first scenario. Main difference is to use persons registered by other MAs in Beta environment instead of your own. Below you can find the list of such persons - you can run this scenario for some or all of them and compare number of duplicates that should be returned.
  • in that case, what you need to do is to follow the instructions given in chapter 3.2.1 Register new person. In simple words, you need to create PersonType object and fill it with data of a person from the list.
  • running RegistrationFacade.RegisterPersonAndWaitForDetailsInCaseOfDuplicates(...) now will also result with 409 error code internally, but this time your implementation of PersonDetailsProvider won't be triggered. You will get an XML response from other MAs - the ones owning details of the person that you wanted to register. Remember PersonLocalXmlSerializer class that you used in Stage 3? You can use the same tool to create an instance of PersonLocal out of raw XML string (more details about that can be found in chapter 3.1.3 Deserialize XML with person details of SDK documentation). Whether to use XML with person details or deserialize it to PersonLocal object, depends on your preference and context.


Scenario 3 - Understanding registrations created in my MA by different system

If during implementation you will notice that RequestRecipientOrganisationSystemId property under PersonDuplicateWithDetails is filled go to section Advanced Concepts where you can find more details about registrations created by external systems. 

List of test persons registered in Beta environment (first name, last name, date of birth):

  • Tres Bruno, 29 April 1989
  • Yacine Adli, 29 July 2000
  • Nabil Alioui, 18 February 1999
  • Danilo Cataldi, 06 Aug 1994


Please note that the list was valid at the time of writing this article. In case when you cannot receive details of above persons (i.e. because the empty string is returned instead of XML), please let us know, so we could check it and provide you a set of new names.

If you are here and have successfully implemented Stages 1 through 4, we congratulate you! Although you still have some work ahead of you, the most important concepts are now done. Your solution should now be able to:

  • register a person, receive FIFA_ID and save it in your Football Management System
  • register a person and in case of duplicates, request details from other MAs, get the details and understand them
  • force register a person
  • respond with player details from your Football Management System when asked by other MAs


From the system perspective:

  • you are integrated with ConnectID Service
  • you are integrated with ConnectID Service Bus, and able to use public/private key infrastructure to exchange messages with other "users" of Service Bus


The things you still need to implement are described in Stage 5.


Stage 5 - advanced concepts


The final stage shows you how to implement remaining business operations, like:

  • person update
  • club registration
  • facility registration
  • transfer process

It also explains how to provide more details when sharing person data with other MAs.


This chapter has links to three additional resources, so called checklists. They help you verify whether you implemented all the operations required to integrate with Connect ID. For convenience we provide those links here but note that they are also listed in relevant sections:

Note, that since October 2019 a new tool is available intended to help MA with a self assessment of where they are in the implementation process. The tool uses the same login as Admin Console and can be found here.

Update information related to a person’s profile

A person that you registered in Stage 3 can be modified or updated. We can distinguish several operations that can be performed in order to change a person’s information:

  • Update person
  • Add registration(s) to a person
  • Update person's registration(s)
  • Merge persons

 

UpdatePerson method gives the possibility of updating a person's name(s), date of birth or gender. When calling this method, at least one of the mentioned arguments is required - that means you can update all 3 arguments at once or pick just one (e.g. date of birth) and leave others with null values.


Note, that when updating the name of a person, you need to specify all pairs of names. For example if you originally registered a person with both local and international name, you need to specify both pairs even if you are changing only one name. Connect ID is only able to replace an existing set of names with a new set. The reason for this is personal data protection, which allows the service to store hashes but not names.


Keep in mind that an update operation can cause potential duplicates. In order to get into such a scenario, please follow instructions in chapter 3.2.2 of SDK documentation:

  1. Create and force register two persons with different data/information.
  2. Use UpdatePersonAndWaitForDetailsInCaseOfDuplicates method in order to update second registered person with first registered person’s information (names, date of birth and gender) - in such case you should get a potential duplicate(s) as a result of the operation.
  3. You can now try to perform same operation (UpdatePersonAndWaitForDetailsInCaseOfDuplicates) using different data. Try to experiment with updating only one value. When updating names try to use as many unique values, as possible - then you could test "person update without getting duplicates" scenario.

 

Apart from changing person's personal data, you can also modify their registrations. This can be done through either adding a registration or updating an existing one. Let's train both scenarios, start by adding registrations: 

  1. Begin by registering a person with an active football registration in your MA. You can follow chapter 3.2.1.
  2. As a result of the above operation, you will get an unique FIFA ID of the registered person. At this point, you can log to the admin console (https://fci-adminconsole-beta.azurewebsites.net/) and verify whether you can see that person and check that in fact they have an active football registration in your MA.
  3. Now jump to chapter 3.3.6 (and its sub-chapter 3.3.6.1 in particular). Using the person FIFA identifier that you just gained and ID of your MA (as organisationId) you can now create PlayerRegistrationType instance and assign it to AddRegistrationsRequestType. Use beach soccer instead of football as a discipline and keep the other attributes the same.
  4. At this point, you're ready for sending the request. Looking at a code snippet from chapter 3.3.6.1 you probably wonder what is the client and how to get it in the easiest way. As we told you in Step 2, we won't create the FifaConnectIDClient instance separately - you can get it from RegistrationFacade by triggering ConnectIdClient property or getConnectIdClient method - depending on a technology that you use (2.5.1).
  5. Now, just call AddRegistrations method, wait for a response and then check your person in Admin Console (best by using Audit Trail functionality). You will see 2 registrations proving that everything worked as expected.

 

Let's make it even more complicated and try to update the registration of a person:

  1. As in the previous step, we added PlayerRegistrationType to our person, now please perform the same operation. This time, however, please add different type of registration (you can pick from following: MatchOfficialRegistrationType, OrganisationOfficialRegistrationType and TeamOfficialRegistrationType). 
  2. After you're ready, go to Admin Console and get sure that you see two registrations on the person's page.
  3. Jump to chapter 3.3.6.2 and try to update only one registration of the person - say that we could try to change the status of player registration.

 

At some point in using FIFA Connect ID SDK, you might have a need for merging two registered persons (primary and secondary). Just to remind - there is no possibility of removing a person from the database, so the only way of having the correct entry in case of the same person registered twice is merging records. Technically process is quite easy and can be achieved just by calling MergePersons method - see chapter 3.3.4. As a result of such operation:

  • In Admin Console you will see (on person details and Audit Trail pages) that a secondary person was merged into a primary person.
  • No registrations will be moved/copied, so both persons will remain the same registrations after merge as they had before merge operation.
  • All registrations will keep their current status.
  • GetPerson method will throw FifaPersonMergedException when asked for secondary person ID


If you followed the step-by-step guide up to this point you should be able to perform all operations on Person entities required for integration with FIFA Connect ID.
Please refer to this article which contains a checklist with operations that each Football Management System should be able to perform.

Club registration

FIFA Connect ID database is prepared to store clubs that belong to all Member Associations. Each club, after registration, receives a unique FIFA identifier. Please note that:

  • Each person registration is related only to a member association (we do not keep relations between persons and clubs).
  • If possible, you should use club ID when returning XML with a person details (that's the place where you can relate registration with club ID). Please go to chapter 3.1.1 of SDK documentation to check how to prepare data for XML serialization.


Now, let's use SDK in order to register a club: 

  • Same as when adding registrations to a person, we need to retrieve FifaConnectIDClient from RegistrationFacade. 
  • Then please jump to chapter 4.1 where you will see how to construct and execute the request of the registration process. 
  • Each organisation type requires different fields required when registering. When speaking about club registrations, you need to provide the following properties: Status, InternationalName, LocalName, LocalLanguage, LocalCountry, OrganisationNature, ParentOrganisationFIFAId, and OfficialAddress.
  • Other fields are optional, but if possible, we recommend to provide them as well (so they could be used by club deduplication algorithm).


When deciding on the logic for International & Local Names of organisations, use the following article as a reference: https://support.id.ma.services/support/solutions/articles/7000064033-definition-of-name-fields-local-vs-international-for-persons-and-clubs.



Mentioned above steps assume that no duplicates were found during registration.
If a duplicate is found You will receive FifaDuplicatedOrganisationFoundException with details of possible duplicate.

If you decide that it is a false positive duplicate you can use optional force parameter to force register organisation.


Same way as for persons, it is possible to update or merge clubs/organisations. All required information about those actions can be found in chapters 4.3 and 4.4.


Same as for Persons we have also prepared a checklist for Organisations, which can be found here.


Facility registration

The third type of entities that the Connect ID database can store is Facility (e.g. stadium).
You can register a facility which will be associated with the provided organisation (National Association or any other type of organisation).

Here are the steps required to register a facility:

  • Same as for Person and Organisation we will use FifaConnectIdClient from RegistrationFacade
  • Chapter 5.1 contains code-block which shows how to create and execute the request 
  • Mandatory fields for Facility are: Status, LocalName, LocalLanguage, LocalCountry, OrganisationFifaId, OfficialAddress
  • Same as for the Organisation we recommend to provide non-mandatory fields so they can be used by facility deduplication algorithm


Same as for organisation in case of false positive duplicate detection you can use optional force parameter to force register facility.


After facility registration, you can modify its data - chapter 5.3 shows how to perform such operation.

Unlike to Person and Organisation entities, you are not able to Merge/Unmerge Facilities.

Last but not least, a checklist for Facilities.


Sharing a full player's passport with other MAs

In Stage 3 we asked you to build the functionality of sharing player details with other MAs. This is used to allow others to resolve international duplicates. Back in Stage 3, it was only important that the mechanism is set up properly so we asked you to make sure that mandatory information only is present in the message.

Our final recommendation on this topic is that you deliver as much information about the player as you are able to - within the boundaries of FIFA Data Standard of course. Most probably you are almost there and you are only missing a single section called <PlayerRegistration>. We ask you here to list all the history of the player's registrations that you know about. If you don't know about any, you should at least give the current registration from your MA.

The last thing to explain is the OrganisationFIFAId field. Its value should be:

  • ideally FIFA_ID of the Club that player plays/played for (remember we might be talking about historical registrations as well)
  • if you don't have it, then at least FIFA_ID of the Member Association that player plays/played for


Sending more than just mandatory information when responding to requests for person details


As described in Stage 3 of this instruction, there is a set of required fields that you need to provide when responding with a person details. If you open chapter 3.1.1 of SDK documentation, you will see how to set these values in the technology that you use. Basically, it's all about creating and modifying the PersonLocal object, which later on is serialized directly to an XML document. We encourage you to open this class (PersonLocal) and try to explore it, so to get more overview of what you can find there. Same time please find below a list of all not-required fields:

  • LocalFirstName (string)
  • LocalBirthName (string)
  • Photo (instruction of how to create such object can be found in chapter 3.1.1)
  • LocalPersonName (a list of localized person names)
  • NationalIdentifier (a list of unique national person identifiers, e.g. social security number, passport number, or Tax ID)
  • PlayerRegistration (list)
  • TeamOfficialRegistration (list)
  • MatchOfficialRegistration (list)
  • OrganisationOfficialRegistration (list)
  • PersonFIFAId (string)
  • InternationalFirstName (string)
  • InternationalLastName (string)
  • RegionOfBirth (string)
  • LocalSystemMAId


Each registration type (Player, TeamOfficial, etc.) contains only required fields. That means (depending on technology) in order to create an instance of any of them, you will just need to fulfill the constructor's needs or use all possible setter methods.


Players registered by external systems (SystemID)

For more information on this scenario refer to this article: System ID explained.

Note, that some of the example persons listed in Stage 4 chapter, are registered by such an external system - we recommend running tests aimed at being able to differentiate between a duplicate registered by an MA and by an external system.


Transfers / taking over an existing player

This article has been getting longer and longer, so we decided to describe transfers in a separate article.