KnowledgeSettings Metadata Type in SFDX

Architectural Overview#

The KnowledgeSettings metadata type controls foundational configuration and feature activation for Salesforce Lightning Knowledge. In enterprise customer support operations, technical documentation, agent case deflection, and self-service community portals revolve around curated knowledge articles.

Architecturally, KnowledgeSettings is an essential foundational setting: deploying it provisions the consolidated standard Knowledge__kav object (or custom article types in Classic Knowledge), article versioning tables, translation workflows, and case-to-article deflection triggers. Without configuring KnowledgeSettings, downstream deployments containing custom fields on Knowledge__kav, Knowledge-dependent Flexipages, or article sharing rules will fail during metadata compilation.

Directory and File Conventions#

In Salesforce DX source format, KnowledgeSettings is stored as a single XML file in the settings directory:

Key Metadata Fields#

The XML schema for KnowledgeSettings contains switches governing language configuration, voting, and article lifecycles:

Declarative XML and Package Manifest Examples#

Source XML (Knowledge.settings-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<KnowledgeSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableKnowledge>true</enableKnowledge>
    <enableLightningKnowledge>true</enableLightningKnowledge>
    <defaultLanguage>en_US</defaultLanguage>
    <enableArticleVoting>true</enableArticleVoting>
    <showArticleSummariesCustomerPortal>true</showArticleSummariesCustomerPortal>
</KnowledgeSettings>

Package Manifest (package.xml)#

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

Retrieval and Deployment#

To retrieve KnowledgeSettings via the Salesforce CLI:

# Retrieve settings directly
sf project retrieve start --metadata Settings:Knowledge

# Retrieve using manifest
sf project retrieve start --manifest manifest/package.xml

To deploy KnowledgeSettings to a target environment:

# Deploy to service sandbox
sf project deploy start \
  --metadata Settings:Knowledge \
  --target-org service-uat \
  --wait 10

Senior Architect Deployment Best Practices and Gotchas#

Dependency Sequencing in CI/CD Pipelines#

Deploy Knowledge.settings-meta.xml in the initial settings phase of automated pipeline deployments. The Knowledge__kav object does not exist until Knowledge is enabled:

1. Phase 1: Settings:Knowledge (provisions Knowledge__kav).
2. Phase 2: Custom fields, record types, and validation rules on Knowledge__kav.
3. Phase 3: FlexiPages, layouts, and Experience Cloud components referencing Knowledge.

Scratch Org Automation#

In CI/CD pipelines that dynamically spin up scratch orgs, configure both the features and settings blocks in project-scratch-def.json:

{
  "orgName": "Service Cloud Knowledge CI Org",
  "edition": "Enterprise",
  "features": ["Knowledge"],
  "settings": {
    "knowledgeSettings": {
      "enableKnowledge": true,
      "enableLightningKnowledge": true,
      "defaultLanguage": "en_US"
    }
  }
}

Frequently asked questions

What does KnowledgeSettings configure in Salesforce?

It configures Lightning Knowledge enablement, multi-language publishing, article voting, archiving, and case deflection rules.

Where is KnowledgeSettings stored in an SFDX project?

It is stored under force-app/main/default/settings as Knowledge.settings-meta.xml and retrieved as Settings:Knowledge.

Can Knowledge be disabled once enabled via KnowledgeSettings?

No, enabling Lightning Knowledge is a one-way irreversible architectural operation in Salesforce production and sandbox orgs.

How do scratch orgs enable Lightning Knowledge in CI/CD?

By adding Knowledge to the features array and configuring knowledgeSettings with enableKnowledge set to true in project-scratch-def.json.