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
Subscribe with CometD Using the EMP Connector Sample
Enrich Change Events When Subscribed with CometD (Pilot)
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 When Subscribed with CometD (Pilot)

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.

We provide Change Data Capture Enrichment to selected customers through a pilot program that requires agreement to specific terms and conditions. To be nominated to participate in the program, contact Salesforce. Pilot programs are subject to change, and we can’t guarantee acceptance. Change Data Capture Enrichment isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features. You can provide feedback and suggestions for Change Data Capture Enrichment in the Trailblazer Community.

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 enabled Change Data Capture entities. All types of operations are supported including create, update, delete, and undelete operations. 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

Compound fields aren't supported, such as Address and geolocation fields or the Name field on Lead and Contact.

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.