PlatformEventChannel

Represents a channel that you can subscribe to in order to receive a stream of events. In API version 46.0 and earlier, it is the default standard channel for change data capture events. In API version 47.0 and later, it is a custom channel for change data capture events.

The default standard channel corresponds to the entity selection in the Change Data Capture page in Setup. A custom channel is a channel that you define using this metadata type. Starting in API version 47.0, the channel doesn’t contain the selected entities, which are represented each by PlatformEventChannelMember.

This type extends Metadata and inherits its fields.

PlatformEventChannel components have the suffix .platformEventChannel and are stored in the platformEventChannels folder.

Introduced in API version 45.0.

You must have the Customize Application permission to deploy and retrieve this type.

• Type: PlatformEventChannel​SelectedEntity[]
• Required: No
• Description: Removed. A list of event names of entities, including standard and custom objects, selected for Change Data Capture notifications.

• Type: PlatformEventChannelType (enumeration of type string)
• Required: Yes
• Description: Required. The channel type.
• Possible values:
  • data — Change Data Capture channel corresponding to the selected entities.
  • event — A channel that contains platform events.

• Type: PlatformEventChannelEventType (enumeration of type string)
• Required: No
• Introduced: API version 61.0
• Description: The type of events that the channel can hold. A channel can hold only one type of events. Use this field to optionally specify a specific type of events for a channel in combination with the channelType field.
• Possible values:
  • custom — The channel contains custom platform events. This value is valid with the channelType of event.
  • data — The channel contains change data capture events. This value is valid with the channelType of data.
  • monitoring — The channel contains Real-Time Event Monitoring events. This value is valid with the channelType of event.
  • standard — Reserved for internal use.

• Type: string
• Required: Yes
• Description: Required. The channel label.

• Type: string
• Required: Yes
• Description: Required. The event name of an entity selected for Change Data Capture notifications. For example, for the Account standard object, the name is AccountChangeEvent, or for a custom object MyObject__c, the name is MyObject__ChangeEvent.

The PlatformEventChannel component contains the label of the custom channel and the channel type.

1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
3    <channelType>data</channelType>
4    <label>Custom Channel for Sales Events</label>
5</PlatformEventChannel>

This package.xml references the previous definition. The custom channel name is SalesEvents__chn.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>SalesEvents__chn</members>
5        <name>PlatformEventChannel</name>
6    </types>
7    <version>68.0</version>
8</Package>

The createMetadata() and deleteMetadata() calls aren’t supported with the PlatformEventChannel metadata type.

In API version 47.0 and later, you can’t deploy or retrieve the ChangeEvents standard channel.

You can’t delete the ChangeEvents standard channel with destructiveChanges.xml, but you can delete channel members using the PlatformEventChannelMember type with destructiveChanges.xml.

You can delete a custom channel with destructiveChanges.xml. If you delete a custom channel, all its member PlatformEventChannelMember components are also deleted.

You can update only the fullName field and the label field of a PlatformEventChannel component.

To deploy or retrieve all custom channels, specify the wildcard character * (asterisk) in the <members> field.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>*</members>
5        <name>PlatformEventChannel</name>
6    </types>
7    <version>68.0</version>
8</Package>

The channelMembers field of the PlatformEventChannel type is removed in API version 47.0 and later. As a result, PlatformEventChannel components created in prior versions can’t be deployed using a later API version but you can deploy them in the same API version they were created with.

To deploy a custom channel component using API version 47.0 and later, upgrade the PlatformEventChannel definition by removing the <channelMembers> fields. For the ChangeEvents standard channel, it can’t be deployed or retrieved, so delete the PlatformEventChannel definition file.

For example, if you had custom channel called SalesEvents__chn, this could be your custom channel definition in API version 46.0.

1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
3 <channelMembers>
4 <selectedEntity>AccountChangeEvent</selectedEntity>
5 </channelMembers>
6 <channelMembers>
7 <selectedEntity>ContactChangeEvent</selectedEntity>
8 </channelMembers>
9 <channelType>data</channelType>
10 <label>Sales Events</label>
11</PlatformEventChannel>

To upgrade to version 47.0 or later, you would replace the custom channel definition with this definition, which doesn’t contain any channel members.

1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
3 <channelType>data</channelType>
4 <label>SalesEvents__chn</label>
5</PlatformEventChannel>

For each channel member that is part of either a custom or the standard ChangeEvents channel, add a PlatformEventChannelMember metadata component. Also, in the package.xml file, reference both the PlatformEventChannel and PlatformEventChannelMember components.

For example, this PlatformEventChannelMember component is for the AccountChangeEvent member.

1<?xml version="1.0" encoding="UTF-8"?>
2<PlatformEventChannelMember xmlns="http://soap.sforce.com/2006/04/metadata">
3 <eventChannel>SalesEvents__chn</eventChannel>
4 <selectedEntity>AccountChangeEvent</selectedEntity>
5</PlatformEventChannelMember>

For more information, see PlatformEventChannelMember.

For an example of a custom channel that holds custom platform events and Real-Time Event Monitoring events, see Group Platform Events into One Stream with a Custom Channel in the Platform Events Developer Guide.