Also see:
- Sending over person details via Service Bus for more business explanation of  communication via the Service Bus.


This article explains the concept of custom messaging and shows how to utilize Connect Service Bus SDK to successfully communicate with other Member Associations and/or systems.

You will not need this article during a standard integration with Connect ID Service, as all the message types (e.g. PersonDetailsRequest) and methods for communication have been predefined. 

If you, however, want to exchange a new type of message with another MA[s], for whatever purpose (e.g. exchange a digital match report), this article is a must-read.

Connect Service Bus is part of the FIFA Connect Service allowing to exchange messages between different parties in secure manner. Except for predefined message types (PersonDetails, PersonDetailsRequest) each system is able to send messages of their own types. As for any built-in message type, sender can choose if they wish to encrypt the data prior to sending.


Before sending a message sender and receiver have to agree on:

  • Message Action Type - text based identifier of the type of a message e.g. PersonDetails, TmsAddPlayer, etc.
  • Message content - format of the data known to each party (XML or JSON are recommended).
  • Message properties - optional metadata related to the message content/type. 

Additionally, each party has to prepare the code to send/receive data in the new format.

Please note, that although not required, it is highly recommended to add 'correlationId' property. This helps in tracking and troubleshooting communication issues (refer to the article about troubleshooting Clearing House messages). Without this property, pinpointing problems can be difficult.


For 'correlationId' property to function correctly, the sender should assign it a unique value, such as a GUID or UUID. When replying to the message (like sending a confirmation), the receiver should carry over the same 'correlationId' and include it in their response's properties.


Example 1

Consider a scenario when Member Association A wants to send messages of custom type to Member Association B. Both Member Associations use .NET SDK.


1.1 Data format
Both parties agreed on the following format:

  • Message Action Type: MatchReport
  • Message Content: XML formed data e.g.
<?xml version="1.0" encoding="ISO-8859-1"?>
<TransferData>
    <body>Random content</body>
</TransferData>
  • Message properties: information about the format of data (dataFormat, XML)

Additionally they agreed to encrypt their communication.


1.2 Sender implementation

Sender has to prepare the message and use ConnectServiceBusClient, which can be retrieved from RegistrationFacade. In order to send a message you need to know the ID of the recipient organisation.

// Prepare message contents
var message = @"<?xml version=""1.0"" encoding=""ISO-8859-1""?><MatchReport><body>Random content</body></MatchReport>";
var messageBytes = Encoding.UTF8.GetBytes(message);
var metadataProperties = new Dictionary<string, string> { 
  { "dataFormat", "XML" }, 
  { "correlationId", Guid.NewGuid().ToString() } 
};
const string messageType = "MatchReport";

// Send message
var recipientId = "Id of recipient organisation";
await registrationFacade.ServiceBusClient.Send(recipientId, messageBytes, messageType, metadataProperties);

1.3 Recipient implementation

In order to receive a custom message, you need to configure a background listener (refer to chapter 2.4.2 Message handlers from the SDK documenation). The listener needs to be passed in a message handler that is responsible for handling a specific message type:

// Replace:
// var listener = registrationFacade.ConfigureListener(personDetailsProvider);
// in your existing code with:
var listener = registrationFacade.ConfigureListener(personDetailsProvider, new[]
{
     new MatchReportMessageHandler()
});

class MatchReportMessageHandler : IMessageHandler
{
  private const string SupportedNotificationType = "MatchReport";

  public bool CanHandle(string messageType)
  {
    return messageType == SupportedNotificationType;
  }

  public void Handle(string messageType, Message message)
  {
    var metadata = message.Properties;
    var bytes = message.Content;
    // your logic here...
  }

  public override string ToString() => this.FullNameWithMessageType(SupportedNotificationType);
}


When responding with another message, reuse the correlationId from received metadata. Do not generate a new correlationId. Example of Handle method:

public void Handle(string messageType, Message message)
{
    var metadata = message.Properties;
    var bytes = message.Content;
    // your logic here...
    
    // response:
    var recipient = message.ReplyTo;
    var messageContent = @"<?xml version=""1.0"" encoding=""ISO-8859-1""?><MatchReportReceived />";
    var messageBytes = Encoding.UTF8.GetBytes(messageContent);
    var metadataProperties = new Dictionary<string, string> { 
       { "dataFormat", "XML" }, 
       { "correlationId", metadata["correlationId"] } 
    };
    const string replyMessageType = "MatchReportReceived";

    registrationFacade.ServiceBusClient.Send(recipient, messageBytes, replyMessageType, metadataProperties).GetAwaiter().GetResult();
}