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 your profile image in the upper-right-hand corner, click Hands-on Orgs, then click the username of the org you want to launch.

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, then click New.

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.

Subscribe Using EMP Connector

Next, we show you how to generate and subscribe to change events for Employee records using EMP Connector. In this section, we provide the steps for generating and receiving change events so you can see examples of change events. You don’t need to follow the steps to complete this badge. You can refer to the steps when you use EMP Connector for subscribing to change events later.

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

• Git: See Git Downloads.
• Apache Maven: This example uses Apache Maven to build the EMP Connector project. Download and install it from https://maven.apache.org/index.html.
• Java Development Kit 8 or later: See Java Downloads.
• A Developer Edition org or your Trailhead Playground org. For more information about how to get the username and password for your Trailhead Playground org, see Get Your Trailhead Playground Username and Password unit in the Trailhead Playground Management module.
• If you have not set up a range of trusted IP addresses for your org, you need a security token that you append to your password. For more information, see Reset Your Security Token and Set Trusted IP Ranges for Your Organization.

Steps

1. To get a local copy of the EMP-Connector GitHub repository:
   • $ git clone  https://github.com/forcedotcom/EMP-Connector.git
2. To build the EMP-Connector tool:
   • $ cd EMP-Connector
   • $ mvn clean package
   • The mvn command generates JAR files in the target folder in the EMP-Connector project directory. The generated JAR file,  target/emp-connector-0.0.1-SNAPSHOT-phat.jar, includes the connector and the LoginExample functionality. The JAR contains all the dependencies for the connector, so you don’t have to download them separately.
3. 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/Employee__ChangeEvent.
   • $ java -jar target/emp-connector-0.0.1-SNAPSHOT-phat.jar <username> <password> /data/Employee__ChangeEvent

• You have to append a security token to your password if you haven't set up a trusted IP address range for your org. For more information, see the Prerequisites section.
• The command line interprets some characters to have a special function. If your password includes special characters, enclose it within single quotes so it is passed in as a literal string. For example, on macOS and Unix-based systems, some of the special characters that need to be included within quotes are !, \, and $.

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. From the App Launcher ( ), find and select 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": "-pszPCNGMHqUPU1ftkjxEA",
  "payload": {
    "LastModifiedDate": "2019-09-25T20:36:12.000Z",
    "OwnerId": "005RM000001vI4mYAE",
    "CreatedById": "005RM000001vI4mYAE",
    "ChangeEventHeader": {
      "commitNumber": 65840604581,
      "commitUser": "005RM000001vI4mYAE",
      "sequenceNumber": 1,
      "entityName": "Employee__c",
      "changeType": "CREATE",
      "changedFields": [],
      "changeOrigin": "com/salesforce/api/soap/47.0;client=SfdcInternalAPI/",
      "transactionKey": "00051d2e-a65a-3e97-03fc-cdf4e16d5d3c",
      "commitTimestamp": 1569443772000,
      "recordIds": [
        "a00RM0000004ICTYA2"
      ]
    },
    "CreatedDate": "2019-09-25T20:36:12.000Z",
    "First_Name__c": "Patricia",
    "LastModifiedById": "005RM000001vI4mYAE",
    "Name": "e-100",
    "Last_Name__c": "Smith"
  },
  "event": {
    "replayId": 15053
  }
}

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": "-pszPCNGMHqUPU1ftkjxEA",
  "payload": {
    "LastModifiedDate": "2019-09-25T20:38:11.000Z",
    "ChangeEventHeader": {
      "commitNumber": 65840825286,
      "commitUser": "005RM000001vI4mYAE",
      "sequenceNumber": 1,
      "entityName": "Employee__c",
      "changeType": "UPDATE",
      "changedFields": [
        "LastModifiedDate",
        "First_Name__c",
        "Tenure__c"
      ],
      "changeOrigin": "com/salesforce/api/soap/47.0;client=SfdcInternalAPI/",
      "transactionKey": "00051d4a-7640-5b8c-c6d1-b8db4ce4cf2f",
      "commitTimestamp": 1569443892000,
      "recordIds": [
        "a00RM0000004ICTYA2"
      ]
    },
    "First_Name__c": "Trish",
    "Tenure__c": 3.0
  },
  "event": {
    "replayId": 15054
  }
}

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": "-pszPCNGMHqUPU1ftkjxEA",
  "payload": {
    "ChangeEventHeader": {
      "commitNumber": 65841052769,
      "commitUser": "005RM000001vI4mYAE",
      "sequenceNumber": 1,
      "entityName": "Employee__c",
      "changeType": "DELETE",
      "changedFields": [],
      "changeOrigin": "com/salesforce/api/soap/47.0;client=SfdcInternalAPI/",
      "transactionKey": "00051d67-b628-09dc-15a0-05101183b4d1",
      "commitTimestamp": 1569444019000,
      "recordIds": [
        "a00RM0000004ICTYA2"
      ]
    }
  },
  "event": {
    "replayId": 15055
  }
}

Undelete an Employee Record

When you delete a record, it is “soft deleted” and can be restored within a certain time limit. Let's restore the record through Apex.

1. Click the quick access menu ( ), 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 deleted record.

{
  "schema": "-pszPCNGMHqUPU1ftkjxEA",
  "payload": {
    "LastModifiedDate": "2019-09-25T20:43:31.000Z",
    "OwnerId": "005RM000001vI4mYAE",
    "CreatedById": "005RM000001vI4mYAE",
    "ChangeEventHeader": {
      "commitNumber": 65841428802,
      "commitUser": "005RM000001vI4mYAE",
      "sequenceNumber": 1,
      "entityName": "Employee__c",
      "changeType": "UNDELETE",
      "changedFields": [],
      "changeOrigin": "com/salesforce/api/soap/47.0;client=devconsole",
      "transactionKey": "00051d9a-2fd0-e4de-a8e6-09f68b7ca54c",
      "commitTimestamp": 1569444212000,
      "recordIds": [
        "a00RM0000004ICTYA2"
      ]
    },
    "CreatedDate": "2019-09-25T20:36:12.000Z",
    "First_Name__c": "Trish",
    "LastModifiedById": "005RM000001vI4mYAE",
    "Tenure__c": 3.0,
    "Name": "e-100",
    "Last_Name__c": "Smith"
  },
  "event": {
    "replayId": 15056
  }
}

Resources

• Streaming API Developer Guide: Subscribe to and Replay Events Using a Java Client (EMP Connector)
• GitHub: EMP-Connector GitHub Repo
• Change Data Capture Developer Guide