Glen Mazza's Weblog

Salesforce Trailhead's Create a Custom Channel and Enrich Change Events tutorial shows how to create new Change Data Capture (CDC) channels providing "enriched" messages, i.e., those having certain fields always present. While CREATE and UNDELETE event messages always provide all non-null fields, UPDATE and DELETE events do not, but event enriching can be used for the latter two cases. For example, in my previous tutorial, it would be more readable to always return the Account Name in update and delete events so it can be logged alongside the Account Salesforce ID. And the tutorial gives an example of creating a custom External Account ID field in Salesforce that can be provided in every message and used to identify an account record in the external system for synchronization.

Some drawbacks/limitations of event enriching:

• It is no longer possible to send multiple changes in one event message (e.g., receiving one message that 100 Salesforce IDs of a given entity had the same field changed to a specific value), as each record will have a separate enriched field value.
• The enriched fields cannot contain elements from other entities beyond their Salesforce ID, so for a Contact message one can get the Contact's Account ID but not properties of the Account such as Name.
• It is more cumbersome to create and modify custom channels having enriched fields than relying on the default behavior from the standard CDC streams. The Salesforce Setup UI lacks this functionality, one instead can work with the Salesforce Postman project (GitHub) making REST calls against either Tooling or Metadata APIs. The Salesforce tutorial effectively shows the process using the former.

I expanded my CDC listener sample from the previous tutorial to allow for reading from a custom channel "CDCSample__chn" instead of the standard AccountChangeEvent. The channels can be switched just by adjusting the configuration file and restarting the application. Unfortunately, I was unable to get the Account "Name" property to always be provided in the message as an enriched field. I tried five or six other Account fields and they all worked fine, I'm not sure what the problem with Name is, whether my error or a Salesforce bug.

Using Salesforce's Postman project and the Trailhead tutorial, below are the commands I ran to create and configure this custom channel. Main thing to keep in mind is that a channel is a holder for message event streams, but not a message stream itself. A channel contains one or more channel members, with each member providing messages on a particular entity. It is also with the channel member that any desired enriched fields are defined.

• Creating the custom Platform Event Channel:

  POST to: {{_endpoint}}/services/data/v{{version}}/tooling/sobjects/PlatformEventChannel
  
  with body:
  {  
    "FullName": "CDCSample__chn",
    "Metadata": {
      "channelType": "data",
      "label": "Custom Channel for Change Data Capture Sample"
    }
  }
  

  There should be a success message giving the Salesforce ID of the new channel. Metadata on the PlatformEventChannel can be queried using the following GET call:

  {{_endpoint}}/services/data/v{{version}}/tooling/query/?q=SELECT Id, FullName FROM PlatformEventChannel WHERE DeveloperName='CDCSample'
  

• Creating a PlatformEventChannelMember in the PlatformEventChannel. Here I'm choosing three fields to always appear.

  POST to {{_endpoint}}/services/data/v{{version}}/tooling/sobjects/PlatformEventChannelMember
  
  {
    "FullName": "CDCSample_chn_AccountChangeEvent",
    "Metadata": {
      "enrichedFields": [
        {
          "name": "Industry"
        },
        {
          "name": "Name"
        },
        {
          "name": "TickerSymbol"
        }
      ],
      "eventChannel": "CDCSample__chn",
      "selectedEntity": "AccountChangeEvent"
    }
  }
  

  The success message provides the ID for the Channel Member, whose details can be later queried with a GET similar to the following:

  {{_endpoint}}/services/data/v{{version}}/tooling/sobjects/PlatformEventChannelMember/0v85e0000004Cl7AAE
  

  Sample output:

  {
      "attributes": {
          "type": "PlatformEventChannelMember",
          "url": "/services/data/v51.0/tooling/sobjects/PlatformEventChannelMember/0v85e0000004Cl7AAE"
      },
      "Id": "0v85e0000004Cl7AAE",
      "IsDeleted": false,
      "DeveloperName": "CDCSample_chn_AccountChangeEvent",
      "Language": "en_US",
      "MasterLabel": "AccountChangeEvent",
      "NamespacePrefix": null,
      "ManageableState": "unmanaged",
      "CreatedDate": "2021-05-15T16:01:21.000+0000",
      "CreatedById": "0055e000000nMxcAAE",
      "LastModifiedDate": "2021-05-19T10:27:59.000+0000",
      "LastModifiedById": "0055e000000nMxcAAE",
      "SystemModstamp": "2021-05-19T10:27:59.000+0000",
      "FullName": "CDCSample_chn_AccountChangeEvent",
      "Metadata": {
          "enrichedFields": [
              {
                  "name": "Industry"
              },
              {
                  "name": "Name"
              },
              {
                  "name": "TickerSymbol"
              }
          ],
          "eventChannel": "CDCSample__chn",
          "selectedEntity": "AccountChangeEvent",
          "urls": null
      },
      "EventChannel": "0YL5e0000008OIAGA2",
      "SelectedEntity": "AccountChangeEvent"
  }
  

  Above query provides the enriched fields, but for links to them specifically, this query can be used:

  {{_endpoint}}/services/data/v{{version}}/tooling/query/?q=SELECT Id,ChannelMemberId,Field FROM EnrichedField ORDER BY ChannelMemberId
  

• Keep this tutorial page handy for whenever it is needed to adjust the enriched fields of a platform event channel member. It involves PATCH requests to the endpoint originally used to create the stream.

Update July 2021: Added a sample platform event processor to the Github project in support of the Platform Event tutorial.

Change Data Capture (also known as change events) in Salesforce refers to a special type of platform event in which messaging events are created based on changes to records of specified Salesforce entities like Account or Contact. Events are marked by a specific change type--CREATE, UPDATE, DELETE, UNDELETE (with additional "Gap" events when the creation of events are not possible)--allowing the subscriber to react appropriately. In Salesforce Trailhead, they are covered in the latter half of the Design Event-Driven Apps for Real-Time Integration trail. Note to some degree you can also "enrich" the messages with always-to-be-provided fields helpful for processing, see the Trailhead tutorial for more information. Enrichment does carry a risk however of having multiple messages with the same ReplayID.

I added a Spring Boot Salesforce Event Listener sample to Github that shows how change events to the Account entity can be captured and logged. To use, first create a Salesforce connected app and from the Change Data Capture screen in Salesforce Setup enable messages from the Account entity. Then rename and configure the CDC Listener application.properties~template file as explained in that file. The application can then be run as any other Spring Boot app, e.g., from IntelliJ IDEA or via command-line using gradle bootRun. Any changes you make to Accounts will result in logged output from the CDC Listener. For the purposes of this sample the CDC Listener presently reports on changes to just three Account fields--name (a String), rating (an enum), and number of employees (an int). However, it is easy to modify the AccountCDCEvent.Payload class to include whatever Account fields desired.

Sample output while editing accounts:

n.g.c.processor.AccountCDCProcessor : Account added: 0015e000002pK7EAAU, name Glen's First Account, employee count 12, rating Hot
n.g.c.processor.AccountCDCProcessor : Account updated: 0015e000002pK7EAAU: Rating to Warm 
n.g.c.processor.AccountCDCProcessor : Account updated: 0015e000002pK7EAAU: Num employees to 15 Rating to null 
n.g.c.processor.AccountCDCProcessor : Account added: 0015e000002pNwUAAU, name Glen's Second Account, employee count 50, rating Hot
n.g.c.processor.AccountCDCProcessor : Account deleted: 0015e000002pNwUAAU
n.g.c.processor.AccountCDCProcessor : Account undeleted: 0015e000002pNwUAAU, name Glen's Second Account, employee count 50, rating Hot

For production, the potential for Gap events will need to be handled, see the Salesforce documentation for suggested strategies.