Salesforce Change Data Capture

Overview

Salesforce Change Data Capture publishes a change event every time a record of a Salesforce object is created, updated, deleted or undeleted. This page outlines the parameters that should be included in your listener configuration when setting up a real-time sync with a Salesforce Change Data Capture source. Each listener subscribes to the change events of one object; to sync several objects, configure one listener per object.

How Cinchy applies a change event

A change event carries only the fields that changed, and a delete carries only the record Id. Cinchy reads the full record back from Salesforce before it syncs it, so every mapped column of the target row is written from current Salesforce data, and formula fields can be mapped. This uses your org's daily REST API allocation: one call per batch of changed records, plus a few calls when the listener starts.

Before you start

1. Enable the object for Change Data Capture in your Salesforce org. Cinchy does not enable objects for you, and creates nothing in your org. See Select Objects for Change Notifications.
2. Grant the integration user permission to read every record of the object. Change Data Capture ignores sharing rules and publishes every record, so Salesforce requires View All Records on the object or its equivalent; see Required Permissions. Under the Client Credentials grant this is the Run As user of the External Client App.
3. Set the sync key of your data sync to the destination column that is mapped from Id. A delete event carries only the record Id, so nothing else can match the target row. The listener refuses to start otherwise.

Configuring the sync

All of the configuration parameters and variables for this real-time sync are the same as those outlined in the Salesforce Change Data Capture source documentation. The only difference is that you must also set up your listener configuration as per the next section.

The Listener configuration

info

In Cinchy v5.7+, configuring the listener can be done directly in the Connections UI, however for multiple listener requirements you must still add additional configurations in the Listener Config table.

To set up a stream source, you must set up a Listener configuration. The below table describes the parameters and their relevant descriptions.

Listener Config

The following column parameters can be found in the Listener Config table:

Parameter	Description	Example
Name	Mandatory. Provide a name for your listener config.	real-time sync
Event Connector Type	Mandatory. Select your Connector type from the drop-down menu.
Topic	Mandatory. This field is expecting a JSON formatted value specific to the connector type you are configuring.	See the Topic tab.
Connection Attributes	Mandatory. This field is expecting a JSON formatted value specific to the connector type you are configuring.	See the Connection Attributes tab.
Status	Mandatory. Set to "Enabled" to activate the listener. Leave on "Disabled" until you are ready to start syncing.	Enabled/Disabled
Running Status	Read-only. Shows the current state of the listener as Starting, Running, or Failed. This is automatically managed by the system. For more information, see the Listener status section.	Running
Active	Managed by User/System. Indicates whether the listener is set to retry after failure ("Yes") or has stopped attempting to sync and requires user intervention ("No").	Yes/No
Data Sync Config	Mandatory. This drop-down will list all the data syncs on your platform. Select the one that you want to use for your real-time sync.	CDC Data Sync
Subscription Expires On	Salesforce Stream Sources only. This field is a timestamp that's auto populated when it has successfully subscribed to a topic.
Message	Auto-populated. This field reports errors that occur during the sync.
Auto Offset Reset	Earliest, Latest, None. Determines where to start reading events if there is no last message ID or if it's invalid. Can be adjusted post-configuration. Learn more	Earliest ,Latest, None

Topic

The below table can be used to help create your Topic JSON needed to set up a real-time sync.

Parameter	Description	Example
name	Mandatory. The API name of the change event. For a standard object this is the object name followed by ChangeEvent. For a custom object Salesforce drops the c of __c: the change event of Employee__c is Employee__ChangeEvent.	AccountChangeEvent
channel	Optional. Defaults to /data/{name}, the channel of that one object. Set /data/{ChannelName}__chn to subscribe through a custom channel. The all-objects channel /data/ChangeEvents is not accepted: a listener feeds one data sync and one table.	/data/SalesEvents__chn
entityName	Optional. The object whose changes this listener syncs. Defaults to the object behind name. On a custom channel that carries several objects, events for other objects are skipped.	Account
fields	Optional. The record fields Cinchy reads back from Salesforce for each event. Leave it empty to read every field of the object. If you set it, it must include Id and every column in your data sync's source schema.	["Id", "Name", "Industry", "AnnualRevenue"]

Example Topic JSON

{
  "name": "AccountChangeEvent",
  "channel": "/data/AccountChangeEvent",
  "entityName": "Account",
  "fields": []
}

Connection Attributes

The Connection Attributes JSON is the same as for the Salesforce Platform Event listener: GrantType of password or client_credentials, ClientId, ClientSecret, InstanceAuthUrl, and for the password grant Username and Password.

Use client_credentials for new listeners. Salesforce is retiring the username-password flow, and the client credentials flow is only served from your org's My Domain host.

{
 "GrantType": "client_credentials",
 "ClientId": "Bn8UmtiLydmYQV6//qCL5dqfNUMhqchdk959hu0XXgauGMYAmYoyWN8FD+voGuMwGyJa7onrc60q1Hu6QFsQXHVA==",
 "ClientSecret": "DyU1hqde3cWwkPOwK97T6rzwqv6t3bgQeCGq/fUx+tKI=",
 "InstanceAuthUrl": "https://mydomain.my.salesforce.com/services/oauth2/token"
}

Auto Offset Reset

Value	What the listener does
Earliest	Reads every change event Salesforce still retains (72 hours), then new events.
Latest	Reads new events only. This is the usual setting.
None	The listener does not start.

The listener records the replay ID of the last event it processed and resumes from it after a restart or a disconnection. Auto Offset Reset only applies when there is no recorded replay ID, or when the recorded one has aged out of the retention window.

What the listener checks when it starts

The listener validates its configuration before it subscribes and sets the Listener Config Message to the reason when a check fails:

• The name is a change event API name and the channel, if set, is a single-object or custom Change Data Capture channel.
• The data sync's sync key is the single destination column mapped from the Id source column.
• If fields is set, it includes Id and covers every column in the data sync's source schema.
• The change event exists in the org, and the object is enabled for Change Data Capture. If it is not, the message says so.

Behaviour to know

• Gap events. Occasionally Salesforce cannot include a record's field values in a change event and sends a gap event instead. Cinchy reads the affected records back by Id and syncs them; a warning is written to the listener log.
• Overflow. When one Salesforce transaction changes more than 100,000 records of an object, Salesforce publishes the first 100,000 changes and a single overflow event for the rest. The listener moves to Failed and asks you to run a batch sync of that object. Re-enable the listener after the batch sync; it resumes after the overflow event, so nothing is replayed twice.
• Daily API allocation. If Salesforce refuses a request because the org has spent its daily REST allocation, the listener moves to Failed with that message. Re-enable it once the allocation resets. If the outage lasted longer than 72 hours, run a batch sync and set Auto Offset Reset to Latest.
• Delivery allocation. Salesforce caps the number of change and platform events it delivers per rolling 24 hours. The cap depends on your edition and is counted per subscriber; see Change Data Capture allocations. Two listener configurations on the same channel count twice. Monitor usage in Salesforce Setup.
• Ordering. Events are applied one record at a time in the order Salesforce published them. Changes that Salesforce made in one transaction are not applied as one transaction in Cinchy.

Moving an existing Push Topic sync

1. Enable the object for Change Data Capture in Salesforce.
2. Set the sync key of the data sync to the destination column mapped from Id. If the sync is keyed on another field, it must stay on the Push Topic.
3. Move any filtering from the Push Topic's SOQL WHERE clause into the data sync, either as a post-extraction filter or on the target side.
4. Disable the Push Topic listener.
5. Create the Change Data Capture listener with Auto Offset Reset set to Latest and enable it.
6. Run a batch sync of the object with the Salesforce object (Bulk API) source to catch anything that changed between the two listeners. Both paths upsert, so an overlap is harmless.

The Push Topic itself stays in your org until you delete it; Cinchy does not remove it.