DocumentChecklistSettings Metadata in SFDX

Overview#

The DocumentChecklistSettings metadata type represents the org-wide configuration settings for Document Checklist Items (Setup > Feature Settings > Document Checklist Settings).

Architecturally, DocumentChecklistItem records act as structured placeholders between a parent business record (such as an Account, Opportunity, ResidentialLoanApplication, or Case) and an uploaded Salesforce File (ContentDocument). DocumentChecklistSettings governs what happens to the underlying ContentDocument and ContentVersion data model when a customer or back-office reviewer uploads a replacement file to an existing checklist item.

Directory and File Suffix Reference#

Key Metadata Fields#

Declarative XML, Scratch Org, and Package.xml Examples#

1. Settings Metadata File (DocumentChecklist.settings-meta.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<DocumentChecklistSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <newFileVersion>true</newFileVersion>
</DocumentChecklistSettings>

2. Scratch Org Definition (config/project-scratch-def.json)#

Include documentChecklistSettings in your scratch org definition so automated Apex tests verifying ContentVersion counts on DocumentChecklistItem behave identically to production:

{
  "orgName": "Enterprise Document Checklist Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "documentChecklistSettings": {
      "newFileVersion": true
    }
  }
}

3. Package Manifest (package.xml)#

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

4. SFDX CLI Commands#

# Retrieve DocumentChecklistSettings from the target org
sf project retrieve start --metadata Settings:DocumentChecklist

# Deploy DocumentChecklistSettings to the target org
sf project deploy start --metadata Settings:DocumentChecklist

Architect Best Practices and Gotchas#

• Impact on ContentVersion Triggers and Integration IDs: When newFileVersion is true, the ContentDocumentId linked to the DocumentChecklistItem remains constant across re-uploads, while ContentVersion.VersionNumber increments (1, 2, 3). If you integrate Salesforce Files with an external Enterprise Content Management (ECM) system like Box, SharePoint, or AWS S3, enabling newFileVersion prevents orphaned file records in your external storage bucket.
• Storage Consumption Trade-off: Because newFileVersion: true retains all historical versions under the same ContentDocument, every rejected and re-uploaded PDF continues to count against the org’s File Storage allocation until older versions are archived or purged.
• Experience Cloud Collaborator Permissions: When external Experience Cloud users upload a new version to an existing ContentDocument (newFileVersion: true), verify that their ContentDocumentLink.ShareType (V vs C) and PermissionSet permissions allow uploading a new version of a file they own or collaborate on.

Frequently asked questions

What does the newFileVersion boolean field in DocumentChecklistSettings control?

When newFileVersion is set to true, uploading a replacement file to a DocumentChecklistItem creates a new ContentVersion under the existing ContentDocument instead of creating a separate ContentDocument record.

How is DocumentChecklistSettings referenced in package.xml?

Like all org-wide settings metadata types, it is referenced under the Settings type name with a members value of DocumentChecklist, corresponding to the DocumentChecklist.settings-meta.xml file.

Why should regulated industries enable newFileVersion in DocumentChecklistSettings?

Enabling newFileVersion preserves a complete, tamper-evident version history on a single ContentDocument record when applicants re-upload corrected KYC or underwriting documents, simplifying compliance audits.

Can DocumentChecklistSettings be configured in a scratch org definition file?

Yes. You can include documentChecklistSettings with newFileVersion set to true inside the settings block of project-scratch-def.json so scratch orgs match production file versioning behavior.