We recommend using Metadata API as part of the application lifecycle management process to develop, test, deploy, and release your apps to production. If you want to create the channel and filter expression, we recommend that you use Tooling API with REST.
| User Permissions Needed | |
|---|
| To deploy and retrieve metadata types: | Customize Application |
| To update metadata types: | Modify Metadata Through Metadata API Functions |
| To use Metadata API: | API Enabled |
Create a channel and channel member in Metadata API using API version 56.0 or later.
To create a channel and channel member with Metadata API, you can use tools such as Visual Studio Code with the Salesforce Extension pack or Salesforce CLI. For more information, see Metadata API Developer Tools and Quick Start: Metadata API in the Metadata API Developer Guide.
The steps are based on a custom channel. We recommend using a custom channel instead of the standard channel so that the filtered stream is isolated from the standard event stream and subscribers expect the stream to be filtered. You can alternatively use the ChangeEvents standard channel. If you do so, you can skip the custom channel definition, and for the PlatformEventChannelMember definition, adjust the file name and use this eventChannel value: <eventChannel>ChangeEvents</eventChannel>.
This sample custom channel definition is for the FilteredChannel__chn channel. The file name is FilteredChannel__chn.platformEventChannel.
1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
3 <channelType>data</channelType>
4 <label>My Custom Filtered Channel</label>
5</PlatformEventChannel>
Next, add a channel member. This channel member specifies the enriched fields of Industry and NumberOfEmployees, the filter expression, and the selected entity of AccountChangeEvent. The file name is FilteredChannel_chn_AccountChangeEvent.platformEventChannelMember.
1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannelMember xmlns="http://soap.sforce.com/2006/04/metadata">
3 <eventChannel>FilteredChannel__chn</eventChannel>
4 <filterExpression><![CDATA[Industry='Agriculture' AND NumberOfEmployees>1000]]></filterExpression>
5 <selectedEntity>AccountChangeEvent</selectedEntity>
6</PlatformEventChannelMember>
If the filter expression contains the < and & special characters, they aren’t allowed in XML data in their literal form. Escape those characters as < and &, or enclose the entire filter expression value within the <![CDATA[...]]> section. Although no special characters are present in the previous example, <![CDATA[...]]> is included for convenience. For more information, see CData sections in the Extensible Markup Language (XML) specification.
If your Salesforce org has a namespace, prepend the namespace prefix to each field used in filterExpression and the selectedEntity value in the PlatformEventChannelMember request body. For example, if the namespace is ns, the request body in this example becomes:
1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannelMember xmlns="http://soap.sforce.com/2006/04/metadata">
3 <eventChannel>FilteredChannel__chn</eventChannel>
4 <filterExpression><![CDATA[ns__Industry='Agriculture' AND ns__NumberOfEmployees>1000]]></filterExpression>
5 <selectedEntity>AccountChangeEvent</selectedEntity>
6</PlatformEventChannelMember>
This package.xml file references the channel and channel member.
1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3 <types>
4 <members>FilteredChannel__chn</members>
5 <name>PlatformEventChannel</name>
6 </types>
7 <types>
8 <members>FilteredChannel_chn_AccountChangeEvent</members>
9 <name>PlatformEventChannelMember</name>
10 </types>
11 <version>68.0</version>
12</Package>
To update a filter expression, redeploy the package with an updated value for the filterExpression field in the PlatformEventChannelMember component. You can update only the filter expression and enriched fields of a channel member. All other fields aren’t updateable.
You can add another filter on another change event by adding a channel member to the same channel. For example, to filter lead change events, add a second channel member for the FilteredChannel__chn channel. In this member, specify selectedEntity as LeadChangeEvent, and specify the filter expression and enriched fields. This PlatformEventChannelMember definition is an example component with a file name of FilteredChannel_chn_LeadChangeEvent.platformEventChannelMember.
1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannelMember xmlns="http://soap.sforce.com/2006/04/metadata">
3 <eventChannel>FilteredChannel__chn</eventChannel>
4 <filterExpression><![CDATA[AnnualRevenue>1000000]]></filterExpression>
5 <selectedEntity>LeadChangeEvent</selectedEntity>
6</PlatformEventChannelMember>
This package.xml file references both channel members.
1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3 <types>
4 <members>FilteredChannel__chn</members>
5 <name>PlatformEventChannel</name>
6 </types>
7 <types>
8 <members>FilteredChannel_chn_AccountChangeEvent</members>
9 <members>FilteredChannel_chn_LeadChangeEvent</members>
10 <name>PlatformEventChannelMember</name>
11 </types>
12 <version>68.0</version>
13</Package>
See Also
j