📢 Attention Salesforce Certified Trailblazers! Maintain your credentials and link your Trailhead and Webassessor accounts by April 19th. Learn more.
close

Subscribe to an Event Channel

Learning Objectives

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

  • Enable objects for change event notifications in the Change Data Capture page.
  • Use EMP Connector to subscribe to a change event channel.
  • Generate change event notifications by making updates in Salesforce.

Now that you’ve learned the basics of Change Data Capture, let’s get hands-on by generating some changes in Salesforce and receiving change events. For this section, we’re going to be creating and modifying an employee record. 

Create the Employee Custom Object

Before we can start this exercise we need to define the Employee custom object. The first step is creating the custom object. You can follow along in your Trailhead Playground or Developer Edition org. To access your Trailhead Playground, click Launch at the bottom of this page.

  1. In Setup, click the Object Manager tab, and then select Create > Custom Object.
  2. Enter the following values.

Label: Employee

Plural Label: Employees

(If available, select Starts with vowel sound.)

Object Name: Employee

Record Name: Employee Name

3. Select Launch New Custom Tab Wizard after saving this custom object.

4. Click Save.

5. In the New Custom Object Tab page, select the Building tab for the tab style.

6. Click Next > Next > Save.

7. Click Fields & Relationships.

8. Follow the field wizard to create these three fields:

Data Type: Text, Field Label: Last Name, Field Name: Last_Name, Length: 50, Required: Yes

Data Type: Text, Field Label: First Name, Field Name: First_Name, Length: 50

Data Type: Number, Field Label: Tenure, Length: 18, Decimal Places: 0, Field Name: Tenure

Enable the Employee Object for Change Notifications 

Before you can receive change notifications, you need to select the objects you’re interested in. Otherwise, even if you subscribe to the right channel, you won’t receive any notifications. In this section, we select the Employee custom object to listen to Employee record changes.

  1. From Setup, enter Change Data Capture in the Quick Find box, and click Change Data Capture.
  2. In Available Entities, select Employee (Employee__c) and click the > arrow.
  3. Click Save.

The Change Data Capture page

Subscribe Using EMP Connector

In this unit, you use EMP Connector to subscribe to change events for the Employee records and receive notifications. EMP Connector is an open-source sample tool that subscribes to streaming channels using Streaming API and CometD. EMP Connector is a thin wrapper around the CometD library and is implemented in Java. The tool subscribes to a channel, receives notifications, and prints them out to the console. It also supports replaying events with durable streaming. 

 

Note

Note

EMP Connector is a free, open-source, community-supported tool. Salesforce provides this tool as an example of how to subscribe to events using CometD. To contribute to the EMP Connector project with your own enhancements, submit pull requests to the repository at https://github.com/forcedotcom/EMP-Connector.

Prerequisites

Steps

To get a local copy of the EMP-Connector GitHub repository:

$ git clone  https://github.com/forcedotcom/EMP-Connector.git

To build the EMP-Connector tool:

$ cd EMP-Connector

$ mvn clean package

The generated JAR file includes the connector and the LoginExample functionality. The shaded JAR contains all the dependencies for the connector, so you don’t have to download them separately. The JAR file has a -phat Maven classifier. 

To run EMP Connector against your Developer Edition or Trailhead Playground org, type this command and supply your Trailhead Playground org or Salesforce org login credentials and the channel to subscribe to. In this example, the channel is /data/ChangeEvents.

$ java -jar target/emp-connector-0.0.1-SNAPSHOT-phat.jar <username> <password> /data/Employee__ChangeEvent

Once you subscribe the EMP-Connector tool to the channel for Employee__c, any changes to Employee records or creation of new records generates notifications that the tool prints to the console.

Create an Employee Record

Let’s make a few record changes so that we receive some change event notifications. First, create an employee record. 

  1. In App Launcher, click Employees.
  2. Click New.
  3. Populate the following fields.
    • Employee Name: e-100
    • Last Name: Smith
    • First Name: Patricia
  4. Click Save.

When you save the employee record, a change notification displays in the console, as follows.

{  
  "schema":"TIOb-jG_qRb2ucSBIdByMA",
  "payload":{
    "LastModifiedDate":"2018-09-20T21:30:06Z",
    "OwnerId":"005B0000004xULvIAM",
    "CreatedById":"005B0000004xULvIAM",
    "ChangeEventHeader":{
      "isTransactionEnd":true,
      "commitNumber":10341190291016,
      "commitUser":"005B0000004xULvIAM",
      "sequenceNumber":1,
      "entityName":"Employee__c",
      "changeType":"CREATE",
      "changeOrigin":"com/salesforce/api/soap/44.0;client=SfdcInternalAPI/",
      "transactionKey":"000861b9-2218-2464-9404-c16b0e2fee71",
      "commitTimestamp":1537479006000,
      "recordIds":[
          "a00B00000098x4aIAA"
      ]
    },
    "CreatedDate":"2018-09-20T21:30:06Z",
    "First_Name__c":"Patricia",
    "LastModifiedById":"005B0000004xULvIAM",
    "Name":"e-100",
    "Last_Name__c":"Smith"
  },
  "event":{
      "replayId":16907794
  }
}

Update an Employee Record

Next, let’s update the record we just created by adding a value to the Tenure field and then modifying the first name. 

  1. In the employee record detail page, click Edit.
  2. Change the First Name field to Trish.
  3. For Tenure, enter 3.
  4. Click Save.

Updating the employee record generates the following change event message. Notice that the change event contains only the new and modified fields, in addition to header fields.

{
  "schema":"TIOb-jG_qRb2ucSBIdByMA",
  "payload":{
    "LastModifiedDate":"2018-09-20T21:31:08Z",
    "ChangeEventHeader":{
        "isTransactionEnd":true,
      "commitNumber":10341190536560,
      "commitUser":"005B0000004xULvIAM",
      "sequenceNumber":1,
      "entityName":"Employee__c",
      "changeType":"UPDATE",
      "changeOrigin":"com/salesforce/api/soap/44.0;client=SfdcInternalAPI/",
      "transactionKey":"000861c7-a3cb-f5bf-8c8a-a5e3cf9b8278",
      "commitTimestamp":1537479068000,
      "recordIds":[
        "a00B00000098x4aIAA"
      ]
    },
    "First_Name__c":"Trish",
    "Tenure__c":3.0
  },
  "event":{
      "replayId":16907799
  }
}

Delete an Employee Record

Now let’s see what happens when we delete the employee record. 

  1. In Trish’s detail page, select Delete from the dropdown menu.
  2. Click Delete in the confirmation popup.

The deletion results in the following event message. Change events for deletions don’t contain record or system fields.

{
  "schema":"TIOb-jG_qRb2ucSBIdByMA",
  "payload":{
      "ChangeEventHeader":{
        "isTransactionEnd":true,
      "commitNumber":10341190702886,
      "commitUser":"005B0000004xULvIAM",
      "sequenceNumber":1,
      "entityName":"Employee__c",
      "changeType":"DELETE",
      "changeOrigin":"com/salesforce/api/soap/44.0;client=SfdcInternalAPI/",
      "transactionKey":"000861d2-b189-aa52-d7f6-4a635aa1ce03",
      "commitTimestamp":1537479116000,
      "recordIds":[
          "a00B00000098x4aIAA"
      ]
    }
  },
  "event":{
    "replayId":16907802
  }
}

Undelete an Employee Record

When you delete a record, it is “soft deleted” and can be restored within a certain time limit. Because in the Lightning user interface there is no page to restore a record, we restore the record through Apex.

  1. Click the quick access menu ( Setup gear icon), and select Developer Console.
  2. In the Developer Console, click Debug and select Open Execute Anonymous Window.
  3. In the new window, enter the following and replace the ID placeholder with the ID value returned in the recordIds header field. You can find the recordIds field in the change event message you received after deleting the record in the previous step.
Employee__c record = [SELECT Id,Name FROM Employee__c WHERE Id='ID_Placeholder' ALL ROWS];
undelete record;
  1. Click Execute.

The undeletion results in the following event message. The change event for an undeleted record contains fields from the original record.

{
  "schema":"TIOb-jG_qRb2ucSBIdByMA",
  "payload":{
    "LastModifiedDate":"2018-09-20T21:52:27Z",
    "OwnerId":"005B0000004xULvIAM",
    "CreatedById":"005B0000004xULvIAM",
    "ChangeEventHeader":{
        "isTransactionEnd":true,
      "commitNumber":10341195374106,
      "commitUser":"005B0000004xULvIAM",
      "sequenceNumber":1,
      "entityName":"Employee__c",
      "changeType":"UNDELETE",
      "changeOrigin":"com/salesforce/api/soap/44.0;client=devconsole",
      "transactionKey":"000a9934-32e1-ed11-a74d-8c735d12841c",
      "commitTimestamp":1537480347000,
      "recordIds":[
          "a00B00000098x4aIAA"
      ]
    },
    "CreatedDate":"2018-09-20T21:30:06Z",
    "First_Name__c":"Trish",
    "LastModifiedById":"005B0000004xULvIAM",
    "Tenure__c":3.0,
    "Name":"e-100",
    "Last_Name__c":"Smith"
  },
  "event":{
      "replayId":16908128
  }
}

Resources

retargeting