Enrich Change Events with Extra Fields

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 Pub/Sub API, CometD (Streaming API), or event relays. 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. Also, because no change event is generated for a hard-deleted record, which is a record deleted from the Recycle Bin, enriched fields aren’t available. If the enriched fields have an empty value, they aren’t included in the event messages in CometD clients and event relays, and are included with null values in Pub/Sub API clients. 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 are 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

Formula fields aren’t supported for enriched fields because they aren’t supported for change events.
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 the individual constituent fields. For example, you can enrich an event with the Lead Name field. The enriched change event contains the constituent fields as part of the Name field, including FirstName, MiddleName, LastName, and Suffix. In CometD clients, all non-empty constituent fields are returned as part of the compound field in the enriched change event. In Pub/Sub API clients, all constituent fields are returned as part of the compound field including the null fields.
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.
You can add up to 10 enriched fields in each channel member. A compound field counts as one field. This allocation is per channel member. For example, if you have a channel with two channel members, the channel can be enriched with 20 fields total, 10 for each channel member.

Note

Select fields to enrich your change event messages by using the PlatformEventChannelMember object in Tooling API or Metadata API.

Change Data Capture Developer Guide

Enrich Change Events with Extra Fields