Salesforce logSalesforce

Pages

Change Event Triggers

Because change events are based on platform events, they share characteristics for subscription with Apex platform event triggers. Also, change event messages in triggers contain header and record fields, and some additional fields not present in JSON event messages.

A change event trigger:

  • Is an after-insert trigger (defined with the after insert keyword)? It fires after the change event message is published.

    For example, this empty trigger definition is for the Account standard object.

    trigger AccountChangeEventTrigger on AccountChangeEvent (after insert) {
    
    }

    And this empty trigger definition is for the Employee__c custom object.

    trigger EmployeeChangeEventTrigger on Employee__ChangeEvent (after insert) {
    
    }
  • Runs under the Automated Process entity. As a result:
    • Debug logs corresponding to the trigger execution are created by Automated Process. The logs aren't available in the Developer Console's log tab, except for Apex tests. Set up a trace flag entity for the Automated Process entity on the Debug Logs page in Setup.
    • The system fields of records that the trigger processes, such as CreatedById and LastModifiedById, also reference the Automated Process entity.
  • Executes asynchronously outside the Apex transaction that published the change event.
  • Is subject to Apex synchronous governor limits.
  • Has a maximum batch size of 2,000 event messages.

To override a change event trigger’s default running user and batch size, use PlatformEventSubscriberConfig in Tooling API or Metadata API. PlatformEventSubscriberConfig also configures platform event triggers. For more information, see Configure the User and Batch Size for Your Platform Event Trigger in the Platform Events Developer Guide.

Apex Change Event Message Fields

Each change event captured in the trigger contains header and record fields. Fields in a change event message are statically defined, just like in any other Apex type. As a result, all record fields are present in the change event message, whether changed or not. Unchanged fields are null in the Apex change event message. For details, see Change Event Body Fields.

To obtain a header field, access the ChangeEventHeader field on the event object. For example, this code snippet gets the change event header and writes two header field values to the debug log.

EventBus.ChangeEventHeader header = event.ChangeEventHeader;
String changeEntity = header.entityName;
String changeOperation = header.changeType;

All header fields are provided in the EventBus.ChangeEventHeader Apex class. For more information, see ChangeEventHeader Class in the Apex Developer Guide. The Apex class also contains these two headers, which aren’t present in JSON event messages.

nulledfields
Contains the names of fields whose values were changed to null in an update operation. Use this field in Apex change event messages to determine if a field was changed to null in an update and isn’t an unchanged field.

Starting in API version 47.0, the changedfields header is present in Apex and JSON event messages. It contains all fields that were changed in an update operation, whether populated or set to null.

Note

difffields
Contains the names of fields whose values are sent as a unified diff because they contain large text values.