ChannelLayout Metadata Type for Knowledge

Architectural Overview#

In Salesforce Service Cloud with Lightning Knowledge (Knowledge__kav), a single Knowledge article often contains both customer-facing content (such as Summary and Resolution__c) and internal-only agent notes (such as Internal_Escalation_Steps__c). When a support agent clicks Insert Article into Email or shares an article in a social/chat channel, the ChannelLayout metadata type dictates exactly which fields are included for that specific channel and article Record Type.

Architecting ChannelLayout properly is critical for data loss prevention (DLP): if an internal troubleshooting field is accidentally added to the Email channel layout, agents inserting an article into a customer email will inadvertently copy internal notes into the outbound message body.

Directory Location and File Suffix#

In Salesforce DX projects, ChannelLayout components are stored in the channelLayouts directory.

Key Metadata Fields#

The ChannelLayout metadata type includes the following elements in API version 68.0 (Winter ’27):

Declarative Metadata Example#

The following ChannelLayout configures the FAQ record type on Knowledge__kav so that inserting an FAQ article into an Email includes only Title, Summary, and Public_Answer__c, while excluding attached files and internal notes.

<?xml version="1.0" encoding="UTF-8"?>
<ChannelLayout xmlns="http://soap.sforce.com/2006/04/metadata">
    <doesExcludeFiles>true</doesExcludeFiles>
    <enabledChannels>Email</enabledChannels>
    <label>FAQ Customer Email Channel Layout</label>
    <layoutItems>
        <field>Title</field>
    </layoutItems>
    <layoutItems>
        <field>Summary</field>
    </layoutItems>
    <layoutItems>
        <field>Public_Answer__c</field>
    </layoutItems>
    <recordType>FAQ</recordType>
</ChannelLayout>

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Knowledge__kav-FAQ_Email_Channel</members>
        <name>ChannelLayout</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval and Deployment#

Retrieve and deploy ChannelLayout definitions using the sf CLI:

# Retrieve all ChannelLayout definitions in the org
sf project retrieve start --metadata ChannelLayout

# Deploy a specific Knowledge ChannelLayout
sf project deploy start --metadata "ChannelLayout:Knowledge__kav-FAQ_Email_Channel"

Architect Best Practices and Gotchas#

• Deploy Knowledge Schema First: Ensure Knowledge__kav CustomField components (Public_Answer__c) and RecordType definitions (FAQ) are included in the deployment manifest whenever deploying ChannelLayout files.
• File Attachment Governance: Set <doesExcludeFiles>true</doesExcludeFiles> on external email channel layouts if Knowledge articles contain internal PDFs or large media attachments that could exceed outbound email size limits.

Frequently asked questions

What problem does ChannelLayout solve in Salesforce Knowledge?

It determines which fields from a Knowledge article record type are inserted or displayed when an agent shares the article content into an email, social post, or chat conversation, preventing internal-only fields from leaking to customers.

How are ChannelLayout files named in an SFDX repository?

ChannelLayout file names use the prefix of the Knowledge object and record type or layout name, such as Knowledge__kav-FAQ_Channel_Layout.channelLayout-meta.xml inside the channelLayouts directory.

Can ChannelLayout restrict field visibility without Field-Level Security?

ChannelLayout controls which fields are rendered in communication channels like Email, but architects must still enforce Field-Level Security via PermissionSet and Profile for external Experience Cloud users.

What prerequisite must be enabled before deploying ChannelLayout metadata?

Lightning Knowledge must be enabled in the target org and the referenced Knowledge__kav custom fields and recordTypes must exist.