Subscribe to Change Events Using an Apex Trigger

Asynchronous Apex Triggers for Change Events 

You can subscribe to change events on the Lightning Platform using Apex triggers. The change event trigger fires when one or a batch of change events is received. Unlike object triggers, change event triggers run asynchronously after the database transaction is completed. The  asynchronous execution makes change event triggers ideal for processing resource-intensive business logic while keeping transaction-based logic in the object trigger. By decoupling the processing of changes, change event triggers can help reduce transaction processing time.

Define a change event trigger with the after insert keyword on the change event using this format.

trigger TriggerName on ChangeEventName (after insert) {
}

ChangeEventName is the name of the change event, such as AccountChangeEvent, or for the employee custom object, Employee__ChangeEvent.

Change event triggers share these characteristics with platform event triggers.

• They run under the Automated Process entity. As such, debug logs for the trigger are created by the Automated Process entity, and system fields, such as CreatedById and OwnerId, reference Automated Process.
• They are subject to Apex synchronous governor limits.
• They have a maximum batch size of 2,000 event messages (the number of items in Trigger.New).

Apex Change Event Record and Header Fields

Because fields in a change event message are statically defined, just like in any other Apex type, all record fields are present. Unlike change events received in external CometD apps, Apex change event messages can contain empty (null) fields. Unchanged fields are null, and so are fields that are explicitly set to null in an update. 

To figure out which fields were modified, use the changedFields header field. It contains a list of record fields that were changed in an update operation.

Note

The changedFields header field is available for Apex change event triggers saved using API version 47.0 or later.

Create a Change Event Trigger

Adding a change event trigger is as straightforward as adding a trigger for a Salesforce object. You create a trigger on the change event associated with the Employee custom object that you created previously using the Developer Console. The system creates the change event object, Employee__ChangeEvent, when you create a custom object. 

1. To open the Developer Console:
   1. Click the quick access menu ( ).
   2. Click Developer Console.
2. In the Developer Console, select File | New | Apex Trigger.
3. In the Name field, enter a name for the trigger: EmployeeChangeTrigger.
4. From the dropdown, select the change event object for the Employee custom object: Employee__ChangeEvent. The trigger is created with the after insert keyword.
5. Replace the default content with the following code.

trigger EmployeeChangeTrigger on Employee__ChangeEvent (after insert) {
  List<Task> tasks = new List<Task>();
  
  // Iterate through each event message.
  for (Employee__ChangeEvent event : Trigger.New) {
    // Get some event header fields
    EventBus.ChangeEventHeader header = event.ChangeEventHeader;
    System.debug('Received change event for ' +
      header.entityName +
      ' for the ' + header.changeType + ' operation.');
    // For update operations, we can get a list of changed fields
    if (header.changetype == 'UPDATE') {
        System.debug('List of all changed fields:');
        for (String field : header.changedFields) {
            if (null == event.get(field)) {
                System.debug('Deleted field value (set to null): ' + field);
            } else {
                System.debug('Changed field value: ' + field + '. New Value: '
                    + event.get(field));
            }
        }
    }
    // Get record fields and display only if not null.
    System.debug('Some Employee record field values from the change event:');
    if (event.First_Name__c != null) {
      System.debug('First Name: ' + event.First_Name__c);
    }
    if (event.Last_Name__c != null) {
      System.debug('Last Name: ' + event.Last_Name__c);
    }
    if (event.Name != null) {
      System.debug('Name: ' + event.Name);
    }
    if (event.Tenure__c != null) {
      System.debug('Tenure: ' + event.Tenure__c);
    }
    // Create a followup task
    Task tk = new Task();
    tk.Subject = 'Follow up on employee record(s): ' +
    header.recordIds;
    tk.OwnerId = header.CommitUser;
    tasks.add(tk);
  }
  // Insert all tasks in bulk.
  if (tasks.size() > 0) {
    insert tasks;
  }
}

This change event trigger iterates through each received change event message in Trigger.New. For each event, the trigger gets a few header fields. If the operation is an update, the trigger also gets the list of fields that were changed by accessing the changedFields header value. Next, the trigger displays record field values if not null. Finally, it  creates a follow-up task for new Employee records.

Note

From the user interface, you can create change event triggers from the Developer Console only. Change event objects aren't listed in Object Manager in Lightning Experience, or in Setup in Salesforce Classic. 

Verify Change Event Trigger Execution

Now let’s verify manually that the trigger is working. To receive event messages in the trigger, enable the object first on the Change Data Capture page in Setup. In a previous step, you already enabled notifications for Employee, so you can skip that step here. Because debug logs are created under the Automated Process entity, enable debug logs in Setup for this entity for logs to be collected.

1. To open Setup in a new tab, click the quick access menu ( ), then click Setup.
2. From Setup, enter Debug Logs in the Quick Find box, then select Debug Logs.
3. Click New.
4. For Traced Entity Type, select Automated Process.
5. Select the time period to collect logs for and the debug level.
6. Click Save.

Leave the Debug Logs Setup page open, since you’ll come back to it in a minute. Next, make some changes in Salesforce to fire the change event trigger. Create an Employee record and then update it.

1. In a new tab, click the App Launcher ( ), then click Employees.
2. Click New.
3. Populate the following fields.
   • Employee Name: e-200
   • Last Name: Smith
   • First Name: Joseph
   • Tenure: 1
4. Click Save.
5. In the employee record detail page, click Edit.
6. Change the First Name field to Joe.
7. Delete the value for Tenure.
8. Click Save.
9. Switch to the Debug Logs tab and refresh the browser.
10. To view the debug logs corresponding to the record creation, click View next to the second log in the list (logs are ordered by most recent first). The output of the System.debug statements looks similar to the following.

...|DEBUG|Received change event for Employee__c for the CREATE operation.
...|DEBUG|Some Employee record field values from the change event:
...|DEBUG|First Name: Joseph
...|DEBUG|Last Name: Smith
...|DEBUG|Name: e-200
...|DEBUG|Tenure: 1.0

11. To view the debug logs corresponding to the record update, click View next to the first log in the list. The output of the System.debug statements looks similar to the following. Because the system updates the LastModifiedDate field when the record is updated, this field is listed as part of the changed fields.

...|DEBUG|Received change event for Employee__c for the UPDATE operation.
...|DEBUG|List of all changed fields:
...|DEBUG|Changed field value: LastModifiedDate. New Value: 2019-09-26 20:53:29
...|DEBUG|Changed field value: First_Name__c. New Value: Matt
...|DEBUG|Deleted field value (set to null): Tenure__c
...|DEBUG|Some Employee record field values from the change event:
...|DEBUG|First Name: Matt

Testing the Change Event Trigger

Before you can package or deploy Apex change event triggers to production, you must provide Apex tests and sufficient code coverage. 

To ensure that Salesforce record changes in a test method fire change event triggers, enable all entities for Change Data Capture by calling Test.enableChangeDataCapture() at the beginning of the test. This method enables all entities only for the test and doesn't affect the Change Data Capture entity selections for the org.

Test.enableChangeDataCapture();

After enabling Change Data Capture, perform some DML operations and then call the Test.getEventBus().deliver() method. The method delivers the event messages from the test event bus to the corresponding change event trigger and causes the trigger to fire.

Test.getEventBus().deliver();

Create and Run a Test for the Trigger

The test method in the class creates an Employee test record and updates the record. Each of these operations fires the trigger on the Employee change event. The test ensures the trigger execution by querying the task created and verifying the count of tasks.

When running the test class in the Developer Console, the debug logs are available in the Logs tab. For Apex tests, there is no need to set up debug logs in Setup for the Automated Process entity.

To create the test class:

1. In the Developer Console, select File | New | Apex Class.
2. In the Name field, enter a name for the trigger: TestEmployeeChangeTrigger.
3. Replace the default content with the following code.

@isTest
public class TestEmployeeChangeTrigger {
  @isTest static void testCreateAndUpdateEmployee() {
    // Enable all Change Data Capture entities for notifications.
    Test.enableChangeDataCapture();
    // Insert an Employee test record
    insert new Employee__c(Name='e-101',
      First_Name__c='Astro',
      Last_Name__c='Test',
      Tenure__c=1);
    // Call deliver to fire the trigger and deliver the test change event.
    Test.getEventBus().deliver();
    // VERIFICATIONS
    // Check that the change event trigger created a task.
    Task[] taskList = [SELECT Id,Subject FROM Task];
    System.assertEquals(1, taskList.size(),
      'The change event trigger did not create the expected task.');
    // Update employee record
    Employee__c[] empRecords = [SELECT Id,OwnerId,First_Name__c,Tenure__c FROM Employee__c];
    // There is only one test record, so get the first one
    Employee__c emp = empRecords[0];
    // Debug
    System.debug('Retrieved employee record: ' + emp);
    // Update one field and empty another
    emp.First_Name__c = 'Codey';
    emp.Tenure__c = null;
    update emp;
    // Call deliver to fire the trigger for the update operation.
    Test.getEventBus().deliver();
    // VERIFICATIONS
    // Check that the change event trigger created a task.
    // We should have two tasks now, including one from the first trigger invocation.
    Task[] taskList2 = [SELECT Id,Subject FROM Task];
    System.assertEquals(2, taskList2.size(),
      'The change event trigger did not create the expected task.');
  }
}  

4. Click Run Test. After the test finishes execution, the Tests tab shows the status of the test run.
5. Click the Tests tab and expand the Overall Code Coverage pane. The code coverage for EmployeeChangeTrigger is at 100%, which is the result of running this test.