Business Events: Custom payload (I)

The purpose of this article is to talk about the posibility of changing the format or the structure of the JSON that is sent through a Business Event in the least intrusive and more reusable way possible, allowing at all times to use the power and robustness of the Business Event framework.

I am currently participating in a project with a large number of integrations between different tools. In this project, it has been decided to use an Azure Service Bus Queue to manage the different events that each and every one of the tools generates. Due tu this large number of tools and platforms, the format of the messages that are sent by each one had to be homogenized, so that their treatment is as simple as possible, and the decisions can be made based on the content of the message and not in its structure.

As a general rule, the format of the payload of a Business Event is given by the BusinessEventsContract, and we can add new attributes through inheritance, as you can see in this article. Once we serialize the data contract, we get a JSON with a structure similar to the following:

But the JSON format for this project should look something like this:

As you can see, it is about generating a header that will allow us to differentiate the type of event that is being generated through “EventType”, and wrap the original content of our data contract within the “Data” attribute. Due to this need, and assuming that this structure could not be achieved by following the “official steps” to generate a personalized Business Event, we considered the following options:

• Generate a development from scratch to connect to the Azure Service Bus Queue and send the messages in the format we want.
• Try to modify the format of the JSON sent through Business Events without breaking the out of the box functionality.

Obviously, the chosen solution was the second, for several reasons:

• The Business Events framework manages, in a standard way, the connection with all the endpoints, and the configuration that we have to carry out to use them is very simple.
• The Business Events framework has integrated error handling.
• The Business Events framework retries sending messages in case of error.
• It is much more fun trying to solve this problem than generating the connection from scratch.
• In case of problems in the connections, sending messages…, we have the Microsoft support team to help us.

Now that we have decided on the second option, it is time to design a solution that is less intrusive, that ensures that it will continue working after the continuous application and platform updates, and that it is reusable, so that it is very easy to generate new business events that can adapt to it.

For this, and due to the operation of the Business Events framework, we designed a solution divided into two parts:

1. Identify the events that must comply with the new format.

This identification will be made at the moment we generate the event catalog, that is, when the system goes through the different existing business events and creates a record for each one of them in the BusinessEventsTable table.

2. Modify the payload to send abroad.

Sending business events to different endpoints is done in two steps. First (very briefly) a record is created in the BusinessEventsCommitLog table the moment we trigger the sending of the business event (we execute the send() method). This table identifies the type of event as well as its content and, in order to insert the record, the data contract does have to comply with the format defined by the BusinessEventsContract class, so the payload cannot be modified until we arrive at this point. Subsequently, there is a batch process that reads the records in this table and sends them abroad.

In summary, the idea is to modify the content of the JSON just before storing it in this table, leaving the rest of the process to be carried out in a completely standard way.

With this, I think we can already have an idea of what the solution will be to meet this objective. In the next article we will see the technical details of it with the elements that we have to create and extend to carry it out.

This is a solution that I am quite proud of (although surely it can be improved) since, as we will see, once developed, we can generate as many business events as we need in a very simple way so that they comply with the custom format for this project.