Start tracking your progress
Trailhead Home
Trailhead Home

Learn Change Data Capture Characteristics

Learning Objectives

After completing this unit, you’ll be able to:

  • Explain which objects change events are available for.
  • List the fields that are returned in the change event header and describe which fields are included in the body for each operation.
  • Create a change event channel name.
  • List the permissions needed for subscribing to change events.

Object Support

Change Data Capture can generate change events for all custom objects defined in your Salesforce org and a subset of standard objects. It supports change events for the most popular standard objects including Account, Contact, Lead, User, Order, OrderItem, Product2, and others.

To receive notifications for record changes, select the custom objects and supported standard objects that you are interested in from the Change Data Capture page in Setup. We go over the steps for selecting objects later in this module.

A Change Event Example

Remember Robert? His consulting client has defined a custom object called Employee__c that is part of a custom HR app that manages employee data. To synchronize employee data in Salesforce to the external HR system, Robert created an app that receives and integrates change events of new and changed employee records. 

Let’s look at an example of an event message that his app receives. It contains the data for a new employee record that a user created in Salesforce. Notice the changeType and entityName field values. 

{
  "schema":"TIOb-jG_qRb2ucSBIdByMA",
  "payload":{
    "ChangeEventHeader":{
      "entityName":"Employee__c",
      "recordIds":[
         "a00xx0000004GvqAAE"
      ],
      "changeType":"CREATE",
      "changeOrigin":"com/salesforce/api/soap/44.0;client=GetCloudy",
      "transactionKey":"00059b44-a6c7-ffa7-af68-8a455868ed30",
      "sequenceNumber":1,
      "isTransactionEnd":true,
      "commitTimestamp":1533160499000,
      "commitUser":"005xx000001SwSiAAK",
      "commitNumber":356619267
   },
   "First_Name__c":"Jane",
   "Last_Name__c":"Smith",
   "Name":"e-100",
   "Tenure__c":2.0,     
   "LastModifiedDate":"2018-08-01T21:54:58Z",
   "OwnerId":"005xx000001SwSiAAK",
   "CreatedById":"005xx000001SwSiAAK",
   "CreatedDate":"2018-08-01T21:54:58Z",
   "LastModifiedById":"005xx000001SwSiAAK",
  },
  "event":{
    "replayId":1
  }
}

The change event example message contains the employee fields first name, last name, and tenure, in addition to system fields like the creation date. For a new record, the event message excludes fields that a user didn’t set. For example, if the user doesn’t populate the tenure field, it would be excluded from the event message. 

The ChangeEventHeader field includes header fields that contain information about the event. A few header fields of note are listed below.

entityName

This field contains the name of the standard or custom object for this record change. In our example, it is Employee__c.

changeType

This field contains the operation that caused the change. For common change events, this field can have one of the following values. 

  • CREATE
  • UPDATE
  • DELETE
  • UNDELETE

In our example, the change event was for a record creation, so the value is CREATE.

changeOrigin

Use this field to detect whether your app initiated the change, so you do not process the change again and potentially avoid a deep cycle of changes. This field contains the Salesforce API and the API client ID that initiated the change, if set by the client. 

In our example, it is com/salesforce/api/soap/44.0;client=GetCloudy, which means that an app with clientID GetCloudy created the Employee record via SOAP API.

Transaction-Related Header Fields

The following header fields contain information about the transaction of the current change. 

  • transactionKey
  • sequenceNumber
  • isTransactionEnd

Use the transaction fields to maintain an accurate replica of your org’s data in another system. The transactionKey field uniquely identifies the transaction that the change is part of. The sequenceNumber field identifies the sequence of the change within a transaction. The sequence number is useful for operations that include multiple steps, such as lead conversion or creating related records in an after insert  Apex trigger. And the isTransactionEnd field indicates whether the change is the last step in the sequence. We recommend that you replicate all the changes in one transaction as a single commit in your system. 

If you choose not to use a transaction-based replication process, your replicated data might not be complete if your subscription stops. For example, if your subscription stops in the middle of an event stream for one transaction, only part of the transaction’s changes are replicated in your system.

Event Replay ID Field

The last part of the event message contains a field called replayId. This field contains an ID for the event message that you can use to replay past events for up to 3 days. We won’t cover replaying events in this module. For more information, check out the Resources section.

Fields Included in the Body of an Event Message

The fields that Salesforce includes in an event message depend on the operation performed.

Create

For a new record, the event message body includes all non-empty fields along with system fields such as the CreatedDate and OwnerId fields.

Update

For an updated record, the body includes only the changed fields. It includes empty fields only if they were updated to an empty value (null). It also includes the LastModifiedDate system field. The body includes the LastModifiedById field only if it has changed—if the user who modified the record is different than the previous user who saved it.

Delete

For a deleted record, the body doesn’t include any fields or system fields.

Undelete

For undeleted records, the body includes all non-empty fields from the original record, in addition to system fields. 

For example, if a user creates an Employee__c record with partial fields populated (LastName__c and Name), the corresponding event message body contains the following fields: LastName__c, Name, and system fields. The empty fields aren’t included in the message.

Order of Fields in the Event Message

The order of the fields in the JSON event message is not guaranteed. The order follows the underlying Avro schema that change events are based on. When an event is expanded into JSON format, the order of the fields might not match the schema depending on the client used to receive the event.

Subscribing to an Event Channel 

Now that you know what a change event message looks like, let’s find out how to receive the change events. Salesforce offers multiple ways to subscribe to a change event channel. For apps external to Salesforce, you can use Streaming API, or tools and libraries based on CometD, an open-source library that simulates push technology. Streaming API provides a subscription mechanism based on CometD. 

To receive instant notifications of Salesforce data changes in an app that is running on the Lightning Platform, you can use the lightning:empApi Lightning component. 

You indicate which events your app is interested in getting by subscribing it to a channel. Your streaming app receives events in real time whenever a change occurs in Salesforce. 

If you would like to build your own app using Streaming API, check out the Streaming API Developer Guide. The guide includes code examples for subscribing using CometD. To build a Lightning Platform app using lightning:empApi, check out the lightning:empApi Lightning Component documentation. 

To keep things simple, we won’t go into the details of building an app with Streaming API or the lightning:empApi Lightning component. Instead, in the next unit, you learn how to use an open-source sample tool, EMP Connector, to subscribe to a channel and receive events.  

Subscription Channels

This table shows you how to specify the subscription channel corresponding to the records you’re interested in capturing changes for.

Subscribe to change events for:
Channel
Example
All objects
/data/ChangeEvents
N/A
A standard object
/data/<Standard_Object_Name>ChangeEvent
For accounts, the channel is: /data/AccountChangeEvent
A custom object
/data/<Custom_Object_Name>__ChangeEvent
For Employee__c records, the channel is: /data/Employee__ChangeEvent

Required User Permissions

Change Data Capture ignores sharing settings and sends change events for all records of a Salesforce object. To receive change events, the subscribed user must have one or more permissions depending on the channel that is subscribed to. The following table outlines the required permissions per channel. 

Channel
Required Permission
/data/ChangeEvents
View All Data
AND
View All Users
/data/UserChangeEvent
View All Users
/data/<Standard_Object_Name>ChangeEvent
Or
/data/<Custom_Object_Name>__ChangeEvent
View All for the object
OR
View All Data

Some standard objects don’t have the View All permission, such as Task and Event. In this case, the View All Data permission is required.

For example, to capture change events for the Employee__c custom object, the subscribed user must have the View All permission on Employee__c.

User permissions are enforced when the user subscribes to a channel. If the user has insufficient permissions, the user can’t subscribe to the channel and an error is returned. For more information about user permissions, see the Salesforce Help article View All and Modify All Permissions Overview.

Field-Level Security

Change Data Capture respects your org’s field-level security settings. Delivered events contain only the fields that a subscribed user is allowed to view. 

Resources

retargeting