Add a Channel Member and Configure Change Event Enrichment

You’ve set up a custom channel. Now, you use this custom channel to enable change event notifications for Account and to configure event enrichment.

What Is Event Enrichment?

Event enrichment lets you include unchanged fields in change events to facilitate data processing and replication. For example, use enrichment when your app needs an external ID field for matching records in an external system. Or if you want to always include a field that provides important information about a changed record.

You can select any field whose type is supported. Non-empty enriched fields are included in change event messages for update and delete operations. A field that you enrich the change event with is an enriched event field, or enriched field, for short. Event enrichment is available for channels that support multiple entities, such as the standard /data/ChangeEvents channel, or custom channels. Event enrichment is available for CometD and Pub/Sub API subscribers but not for Apex triggers because Apex triggers don't support multi-entity channels. You add enriched fields as part of a channel member.

For more information about event enrichment, see Enrich Change Events with Extra Fields and Event Enrichment Considerations in the Change Data Capture Developer Guide.

Sales Integration App Example Scenario

The integration app synchronizes Salesforce account record data changes with an ERP system that’s external to Salesforce. The app receives change events for account record changes and synchronizes the changes to the external data store. To better synchronize the changes, the events are enriched with extra fields that are always present when non-empty: External_Account_ID__c and Industry. The integration app uses the External_Account_ID__c field to match the Salesforce record with the record in the external data store. Also, the app uses the Industry field to make related changes in the external system.

Event enrichment scenario for the Employee object and the HR app.

Create a Custom Account Field

One of the enriched fields you set up is a custom field on Account, so create it first before proceeding to the next step.

In Setup, click the Object Manager tab, and then click Account.
In Fields & Relationships, click New.
Follow the field wizard to create this field:
1. Data Type: Text
2. Field Label: External Account ID
3. Length: 10
4. External ID: Enabled

Enable Notifications and Add Enriched Fields

You add PlatformEventChannelMember to both enable change event notifications for Account and to add enriched fields. The notifications enablement is done through the selectedEntity field and the enriched fields are added in the enrichedFields array. The enriched fields are External_Account_ID__c and Industry.

If you’re still on the PlatformEventChannel request page in Postman from step 1, stay on the same page and replace PlatformEventChannel at the end of the URI with PlatformEventChannelMember. Otherwise, perform these steps:
1. Under Tooling, click POST Post Tooling sObject.
2. In the new tab that opens for this request, replace the :SOBJECT_API_NAME placeholder in the URI with PlatformEventChannelMember. The resulting URI is: {{_endpoint}}/services/data/v{{version}}/tooling/sobjects/PlatformEventChannelMember
Click Body and ensure that raw and JSON options are selected.

Replace the body with this JSON body.

{
  "FullName": "SalesEvents_chn_AccountChangeEvent",
  "Metadata": {
    "enrichedFields": [
      {
        "name": "External_Account_ID__c"
      },
      {
        "name": "Industry"
      }
    ],
    "eventChannel": "SalesEvents__chn",
    "selectedEntity": "AccountChangeEvent"
  }
}

Click Send.
Verify that the response status is 201 Created.

The response returns the ID of the new custom channel, which looks similar to this.

{
    "id": "0v8B0000000TNa7IAG",
    "success": true,
    "errors": [],
    "warnings": [],
    "infos": []
}

This image shows the request and response returned in Postman.

Send a POST request in Postman to configure event enrichment.

In this example, the selectedEntity is the Account object. The format of the selectedEntity for standard objects is <Object>ChangeEvent. For custom objects, the format is <Object>__ChangeEvent.

If the PlatformEventChannelMember already exists for the channel and the selectedEntity, you can’t overwrite it. You can update the channel member with a PATCH request, or delete it and create it again to add enriched fields. You learn how to perform an update in this project.

Query Enriched Fields

A handy Tooling API object, EnrichedField, lets you verify the enriched fields that are configured on a channel and a channel member. You can query EnrichedField with Tooling API using a REST API tool.

In Postman, under Tooling, select GET Tooling Query.
In the Params tab, add this value to the row for q: SELECT Id,ChannelMemberId,Field FROM EnrichedField ORDER BY ChannelMemberId. The full URI looks as follows: {{_endpoint}}/services/data/v{{version}}/tooling/query/?q=SELECT Id,ChannelMemberId,Field FROM EnrichedField ORDER BY ChannelMemberId
Click Send.

The returned response looks similar to the following example. The returned size of 2 means there are two enriched fields. Each enriched field is listed in the records array and has a channel member ID, which corresponds to the member you created in the previous step. The enriched field name is returned in Field. You can see the Industry field name listed. For the custom field, Field contains the field ID and not the name.

{
  "size": 2,
  "totalSize": 2,
  "done": true,
  "queryLocator": null,
  "entityTypeName": "EnrichedField",
  "records": [
    {
      "attributes": {
        "type": "EnrichedField",
        "url": "/services/data/v51.0/tooling/sobjects/EnrichedField/0dzB00000004C9sIAE"
      },
      "Id": "0dzB00000004C9sIAE",
      "ChannelMemberId": "0v8B0000000TNa7IAG",
      "Field": "Industry"
    },
    {
      "attributes": {
        "type": "EnrichedField",
        "url": "/services/data/v51.0/tooling/sobjects/EnrichedField/0dzB00000004C9rIAE"
      },
      "Id": "0dzB00000004C9rIAE",
      "ChannelMemberId": "0v8B0000000TNa7IAG",
      "Field": "00NB0000008cpevMAA"
    }
  ]
}

For custom fields, the field name is returned as an ID. In this example, it is: "Field": "00NB0000008cpevMAA". You can retrieve the corresponding field name by performing a Tooling API query on CustomField. For example, the following tooling query returns the field name in DeveloperName for the specified field ID: SELECT Id,DeveloperName FROM CustomField WHERE Id='<field_Id>'. If you replace <field_Id> with the Field ID value returned in the EnrichedField query, the name retrieved in DeveloperName is "External_Account_ID".

Alternatively, you can run the query in the Developer Console’s Query Editor and check the Use Tooling API option. For more information, see Developer Console Query Editor in Salesforce Help.