Reading Time: 9 minutes

Did you know there are subtle differences between designing AsyncAPI specifications for a Salesforce Platform Event vs. a Change Data Capture (CDC) Event?

Design AsyncAPIs with Salesforce Platform Events vs. CDC

When you start designing your AsyncAPI specifications to use the Salesforce Pub/Sub API, it’s important to double-check whether your application will be connecting to a Platform Event or a Change Event. There are some differences that you need to pay attention to in your specifications; we’ll go over them in this article. Let’s start by taking a look at the differences between these concepts in Salesforce.

Platform Event vs. Change Event

Both these events are useful for EDA (Event-Driven Architecture) or real-time processing. However, they both have different setups from the Salesforce side. Taking a look at the official Salesforce documentation and additional information, we can see that some of these differences are mostly about field customization vs. implementation time.

Change Data Capture is the easiest way to set up your Salesforce Objects to send a Change Event every time the object is created, modified, or deleted. The information sent within this event includes the changes performed to each of the object’s fields and some header information from the organization.

Platform Events, on the other hand, can be set up to contain custom fields and data. This, of course, requires extra steps to set up the Object and/or the trigger that will create the Platform Event. You can publish these event messages using flows, Apex, Salesforce APIs, and more.

But how exactly can you know which is which by just taking a look at the message itself? It’s all in the message structures.

Differences in Message structures

Let’s start by reviewing each message structure type to understand the differences better.

Change Event Message structure

The Change Event Message structure contains header fields and record fields. We can see an example below:

In the header, you can find general information like the change type, the change origin, the changed fields, etc. These fields will always be the same, regardless of which Salesforce Object you’re dealing with.

The fields you find in the body, though, will vary depending on the Salesforce Object that triggered the Change Event. These fields can contain either the actual value or a null value, depending on the type of change that was made to the object. This is very important to know for our AsyncAPI specification design since we will have to set up two different types for each of the nullable fields.

Platform Event Message structure

Platform Event Fields, unlike the Change Events, can be completely customized. Because of this, the fields will always vary depending on the setup done on the Salesforce side. You can set it up to contain the same (or different) fields and values from the Salesforce Object. Unlike a Change Event, you can set up the trigger for this Platform Event. For example, you can choose to trigger it only when a new object is created. This is important to consider when designing your AsyncAPI since you will have to double-check which fields the event is publishing to the queue.

Differences in Channel Name

Another important thing to notice when designing your specification is the name of the channel. In other platforms like Anypoint MQ or Kafka, we have been using the name of the queue or topic to set up the channel in the AsyncAPI specification.

In Salesforce, we need the name of the event and to make sure we’re using the correct “path” to access the event in the Salesforce Pub/Sub API.

Change Event Channel

When subscribing to a Change Event, you can actually choose the specific channel you want to receive the events from. For example, you can choose to receive all the available entities from all the objects included in CDC. Or you can choose to only receive the events from one specific entity/object.

Each of these channels need to start with /data/ and end in ChangeEvent. This is the name of the channel you should write on your AsyncAPI specification.

Platform Event Channel

When subscribing to Platform Event Notifications, you need to first retrieve the name of the Platform Event created in Salesforce. After that, you can use the following syntax: 

/event/Event_Name__e

As you can see, the Platform Event channel should start with /event/ and end in __e. Very different from the CDC channel.

Conclusion 

Even though we’re connecting to the same Salesforce Pub/Sub API in our AsyncAPIs, we need to make sure those details match up with the data we’ll be receiving from Salesforce. Just because the server is the same doesn’t mean we’ll have to use the same syntax to define the channel or that the message structure will always be the same.

If you want to see a practical example of the complete differences in the design, head to this GitHub repository and look for the Salesforce Platform Events / Salesforce CDC folders.

Want to learn more about AsyncAPI? Check out the following resources:

Read

Watch