Change Data Capture Developer Guide

Change Data Capture
Keep Your External Data Current with Change Data Capture
Change Event Message Structure
Merged Change Events
Other Types of Change Events: Gap and Overflow Events
Subscribe to Change Events
Change Event Storage and Delivery
Subscription Channels
Compose Streams of Change Data Capture Notifications with Custom Channels
Example Diagrams for Channels and Channel Members
High-Level Replication Steps
Subscribe with Pub/Sub API
Subscribe with CometD Using the EMP Connector Sample
Get Compound Fields in Change Events
Enrich Change Events with Extra Fields When Subscribed with CometD or Pub/Sub API
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
Monitor Change Event Publishing and Delivery Usage
Security Considerations
Change Event Considerations
Standard Object Notes
Change Events for Fields
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 or Pub/Sub API

Change event messages include values for new and changed fields, but sometimes unchanged field values are needed for processing or replicating data. For example, use enrichment when your app needs an external ID field for matching records in an external system. Or always include a field that provides important information about the changed record. You can select any field whose type is supported.

Event enrichment is supported for subscribers that use CometD, such as Streaming API clients or EMP Connector, or Pub/Sub API. 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 aren’t 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.

If your client-side parsing code expects only changed fields in the event payload, the presence of enriched fields can require a change to the code. 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 ChangeEventHeader 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 isn’t 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, these field types are supported for enriched fields.

  • Address
  • Auto Number
  • Checkbox
  • Currency
  • Date, Date/Time, Time
  • Email
  • External Lookup Relationship
  • Geolocation
  • Hierarchical Relationship on User
  • Lookup Relationship
  • Master-Detail Relationship
  • Name
  • Number
  • Percent
  • Phone (and Fax)
  • Picklist
  • Roll-Up Summary
  • Text
  • TextArea
  • URL
  • Only the TextArea field type is supported and not TextArea (Long), TextArea (Rich), or TextArea (Encrypted).
  • Compound fields, such as Name, Address, and Geolocation fields are supported for enriched fields. You can specify an entire compound field for enrichment but not directly the individual constituent fields. All non-empty constituent fields are returned as part of the compound field in the enriched change event. For example, you can enrich an event with the Lead Name field. The enriched change event contains the non-empty constituent fields as part of the Name field, including FirstName, MiddleName, LastName, and Suffix.
  • For a relationship field, you can select only the field as an enriched field. You can’t traverse the fields on the related object. The enriched change event contains the ID of the related record. For example, to enrich a contact change event with the ID of the related account, select the Account relationship field as the name of the enriched field for ContactChangeEvent, and not Account.Name. For custom relationship fields, specify the relationship field name with the __c suffix, such as RelField__c.

Note

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 selected object across all channels. A compound field counts as one field. Only unique fields are counted across all channels for the same object, 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.