Change Data Capture Developer Guide

Change Data Capture
Keep Your External Data Current with Change Data Capture
Change Event Message Structure
Subscribe to Change Events
Subscription Channels
Compose Streams of Change Data Capture Notifications with Custom Channels
Example Diagrams for Channels and Channel Members
Subscribe with CometD Using the EMP Connector Sample
Enrich Change Events with Extra Fields When Subscribed with CometD (Beta)
Example: Add Event Enrichment Fields with Tooling API
Example: Add Event Enrichment Fields with Metadata API
Example: Delivered Enriched Event Messages
Event Enrichment Considerations
Subscribe with Apex Triggers
High-Level Replication Steps
Security Considerations
Change Event Considerations
Standard Object Notes
Change Events for Fields
Other Types of Change Events: Gap and Overflow Events
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Enrich Change Events with Extra Fields When Subscribed with CometD (Beta)

Change event messages include values for new and changed fields, but sometimes unchanged field values are needed for processing or replicating data. For example, a replication app needs an external ID field to match the record in an external system. You can select which fields to always include in change event messages when those fields are non-empty.

As a beta feature, Change Data Capture Enrichment is a preview and isn’t part of the “Services” under your master subscription agreement with Salesforce. Use this feature at your sole discretion, and make your purchase decisions only on the basis of generally available products and features. Salesforce doesn’t guarantee general availability of this feature within any particular time frame or at all, and we can discontinue it at any time. This feature is for evaluation purposes only, not for production use. It’s offered as is and isn’t supported, and Salesforce has no liability for any harm or damage arising out of or in connection with it. All restrictions, Salesforce reservation of rights, obligations concerning the Services, and terms for related Non-Salesforce Applications and Content apply equally to your use of this feature. You can provide feedback and suggestions for Change Data Capture Enrichment in the Trailblazer Community. For information on enabling this feature in your org, contact Salesforce.

Note

Event enrichment is supported for subscribers that use CometD, such as Streaming API clients or EMP Connector. Fields that you select for enrichment are included in change events for update and delete operations. Enriched fields aren’t included in change events for create and undelete operations because these events contain all the populated fields. If the enriched fields have an empty value, they're not included in the event messages. If the enriched fields are updated to null, they're included in the event as changed fields and not as enriched fields.

The presence of enriched fields in change events might require a change to your client-side parsing code if it expects only changed fields in the event payload. Check your client-side code and modify it if necessary. You can determine which fields changed by using the changedFields header field. For more information, see Change Event Header Fields.

Note

Event enrichment is available for channels that support multiple entities, such as the standard /data/ChangeEvents channel, or custom channels, such as /data/SalesEvents__chn. You can't add enrichment directly to single-entity channels such as /data/<Entity>ChangeEvent. For example, say that you want to add the Account Industry field for enrichment. You can do that to the custom channel, SalesEvents__chn, assuming AccountChangeEvent is a member of that channel. Then, if you subscribe to /data/SalesEvents__chn, the Industry field is included in account change events on that channel. If you subscribe to another channel that is not enriched with this field, such as /data/ChangeEvents, or another custom channel, account change events don't include the Industry field.

We recommend that you configure event enrichment on a custom channel and not the standard /data/ChangeEvents channel. This way, other subscribers that receive change events on the standard channel don't receive unchanged fields that they don't expect. If you create a custom channel and configure event enrichment on it, you isolate the fields sent to only the clients that anticipate those fields. To learn how to create a custom channel, see Compose Streams of Change Data Capture Notifications with Custom Channels.

As part of the fields that a change event object contains, the following field types are supported for enriched fields.

  • Auto Number
  • Checkbox
  • Date, Date/Time, Time
  • Email
  • External Lookup Relationship
  • Hierarchical Relationship on User
  • Lookup Relationship
  • Number
  • Percent
  • Phone (and Fax)
  • Picklist (not Multi-Select)
  • Text
  • URL

Select fields to enrich your change event messages using the PlatformEventChannelMember object in Tooling API or Metadata API. You can select up to 10 fields for a channel member across all channels. Only unique fields are counted across all channels for the same member, so the same field is counted only once. For example, AccountChangeEvent is a member of two channels. It contains five enriched fields on the ChangeEvents channel and four fields on a custom channel, two of which are also on the ChangeEvents channel. The total number of enriched fields that count toward the maximum is seven.