Example: Add Event Enrichment Fields with Tooling API

To add event enrichment fields, use the PlatformEventChannelMember Tooling API object, and specify the fields, the channel, and channel member.

To carry out similar steps in Trailhead and earn a badge, check out Create a Custom Channel and Enrich Change Events.

Note

If the channel member you’re enriching is part of a custom channel, create the custom channel first, as shown in this example. You can skip this step if using the ChangeEvents standard channel, or if you created the custom channel earlier.

Make a POST request to this REST endpoint:

1/services/data/v68.0/tooling/sobjects/PlatformEventChannel

Request body for the custom channel:

1{
2  "FullName": "SalesEvents__chn",
3  "Metadata": {
4    "channelType": "data",
5    "label": "Custom Channel for Sales App"
6  }
7}

To add enrichment fields, perform a REST request that creates a PlatformEventChannelMember component by using Tooling API. In this example, the component contains three enriched fields in the enrichedFields array for AccountChangeEvent on the SalesEvents custom channel. Before you create this channel member, create a custom Text(20) field for Account with the label External Account ID.

Make a POST request to this REST endpoint (API version 51.0 or later is supported for enrichment fields):

1/services/data/v68.0/tooling/sobjects/PlatformEventChannelMember

Request body with enrichment fields added in a channel member:

1{
2  "FullName": "SalesEvents_AccountChangeEvent",
3  "Metadata": {
4    "enrichedFields": [
5      {
6        "name": "External_Account_ID__c"
7      },
8      {
9        "name": "Industry"
10      },
11      {
12        "name": "BillingAddress"
13      }
14    ],
15    "eventChannel": "SalesEvents__chn",
16    "selectedEntity": "AccountChangeEvent"
17  }
18}

Query Enriched Fields

To find out which channel members and fields you configured, query the EnrichedField object in Tooling API. For example, this query returns the selected enriched field and the channel member ID.

1SELECT ChannelMemberId,Field FROM EnrichedField ORDER BY ChannelMemberId

You can perform a query using the Query Editor in the Developer Console and by checking Use Tooling API. For more information, see Developer Console Query Editor in Salesforce Help.

Alternatively, you can run a query using REST API. Perform a GET request to the following URI. The URI includes the query with spaces replaced with +.

1/services/data/v68.0/tooling/query/?q=SELECT+ChannelMemberId,Field+FROM+EnrichedField+ORDER+BY+ChannelMemberId

In these query results, the rows returned are for the same channel member. They contain these enriched fields: Industry, the External_Account_ID__c custom field, whose value is an ID, and BillingAddress.

ChannelMemberId	Field
0v8RM00000000JsYAI	Industry
0v8RM00000000JsYAI	00NRM000001gEx32AE
0v8RM00000000JsYAI	BillingAddress

Update a Channel Member with Enriched Fields

If there’s an existing channel member for the same selected entity and channel, you can’t create a duplicate channel member with a POST request. Instead, update the channel member with a PATCH request. Alternatively, you can delete the channel member and recreate it with the enriched fields.

To update a channel member, follow these steps.

If you’re using a custom channel, get the channel ID by running this query:
1SELECT Id FROM PlatformEventChannel WHERE DeveloperName=Channel_Name
DeveloperName doesn’t contain the __chn suffix of a custom channel name. For example, for the SalesEvents__chn channel, the query would be:
1SELECT Id FROM PlatformEventChannel WHERE DeveloperName='SalesEvents'

Get the channel member ID with this Tooling API query. For a custom channel, replace Channel_ID with the ID you got in the previous step, or for the standard ChangeEvents channel, replace Channel_ID with ChangeEvents. Replace EntityChangeEvent with the selected entity name.

1SELECT Id,DeveloperName,EventChannel,SelectedEntity FROM PlatformEventChannelMember 
2    WHERE EventChannel='Channel_ID' AND SelectedEntity='EntityChangeEvent'

For example, for AccountChangeEvent on custom channel ID 0YLRM00000000434AA, the query looks as follows.

1SELECT Id,DeveloperName,EventChannel,SelectedEntity FROM PlatformEventChannelMember WHERE EventChannel='0YLRM00000000434AA' AND SelectedEntity='AccountChangeEvent'

Or for the standard ChangeEvents channel, the full URI would be:

1SELECT Id,DeveloperName,EventChannel,SelectedEntity FROM PlatformEventChannelMember 
2    WHERE EventChannel='ChangeEvents' AND SelectedEntity='AccountChangeEvent'

Make a PATCH request to this URI and append the channel member ID you got in the previous step.
1/services/data/v68.0/tooling/sobjects/PlatformEventChannelMember/Channel_Member_ID
In the request body, include the JSON definition of the channel member. For example, to update AccountChangeEvent on the channel member ID of 0v8RM00000000JsYAI and set the enriched fields to be the Phone field only, make a PATCH request to this URI:
1/services/data/v68.0/tooling/sobjects/PlatformEventChannelMember/0v8RM00000000JsYAI
With this request body:
1{ 2 "FullName": "SalesEvents_chn_AccountChangeEvent", 3 "Metadata": { 4 "enrichedFields": [ 5 { 6 "name": "Phone" 7 } 8 ], 9 "eventChannel": "SalesEvents__chn", 10 "selectedEntity": "AccountChangeEvent" 11 } 12}
If the channel member was previously configured with enriched fields, the update clears them and replaces them with the fields specified in the request body. This example specifies only one enriched field, the Phone field. If the channel member didn’t contain enriched fields, the update adds the specified enriched fields.

For PATCH requests, include the full definition of a PlatformEventChannelMember. Partial definitions with only the enriched fields aren’t supported.

See Also