FolderShare Metadata Type in SFDX

Architectural Overview#

FolderShare represents the explicit access control grants applied to report, dashboard, and document folders in Salesforce. Under Enhanced Folder Sharing, organizations can move beyond coarse public/private folder access to assign granular privileges—specifically View, Edit, and Manage—to specific user constituencies.

In enterprise security architectures, folder sharing must be managed through continuous delivery pipelines to ensure regulatory compliance and strict access tiering. By representing folder access as declarative metadata, security architects ensure that sensitive financial metrics, sales pipeline analytics, and executive dashboards are never exposed to unauthorized personnel when environments are cloned or refreshed.

Directory and File Conventions#

In Salesforce DX source format (apiVersion 68.0), FolderShare elements are embedded directly within the parent folder descriptor XML file (<folderName>-meta.xml).

Key Metadata Fields#

The FolderShare schema specifies the grantee, entity type, and granted privilege level:

Declarative XML and Package Manifest Examples#

Below is a folder metadata file demonstrating multiple declarative FolderShare entries:

<?xml version="1.0" encoding="UTF-8"?>
<Folder xmlns="http://soap.sforce.com/2006/04/metadata">
    <name>Executive Dashboards</name>
    <accessType>Shared</accessType>
    <folderShares>
        <accessLevel>Manage</accessLevel>
        <sharedTo>Global_VP_Role</sharedTo>
        <sharedType>Role</sharedType>
    </folderShares>
    <folderShares>
        <accessLevel>View</accessLevel>
        <sharedTo>Board_Auditors_Group</sharedTo>
        <sharedType>Group</sharedType>
    </folderShares>
    <folderShares>
        <accessLevel>Edit</accessLevel>
        <sharedTo>Sales_Operations_Leads</sharedTo>
        <sharedType>RoleAndSubordinatesInternal</sharedType>
    </folderShares>
</Folder>

Package Manifest (package.xml)#

Because FolderShare is deployed as part of the parent folder or dashboard, it is packaged under the container metadata type:

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

CLI Retrieval and Deployment Commands#

Manage folder sharing definitions via the parent metadata container:

# Retrieve the folder descriptor including all folder shares
sf project retrieve start --metadata "Dashboard:Executive_Dashboards"

# Deploy the updated folder sharing configuration to a target sandbox
sf project deploy start --metadata "Dashboard:Executive_Dashboards"

Architect Best Practices and Gotchas#

• Abstract Target Identifiers: Never use sharedType set to User in repository files. Usernames differ across environments (user@company.com.sandbox), causing deployments to fail. Use Public Groups or Roles instead.
• Role Hierarchy Deletions: If a Role referenced in a FolderShare <sharedTo> tag is removed from the organizational hierarchy, subsequent deployments will fail with missing target errors.
• Subfolder Inheritance: In Salesforce Enhanced Folder Sharing, subfolders inherit permissions from their root parent folder unless explicit overriding permissions are established.

Frequently asked questions

What access levels can be granted through FolderShare metadata?

FolderShare supports View, Edit, and Manage access levels, giving administrators precise granular control over folder content administration.

Why is sharing folders to individual Users discouraged in source-driven development?

User IDs and usernames differ across sandboxes and production orgs, causing deployment failures unless abstracted into Roles, Territories, or Public Groups.

How is FolderShare embedded within the parent Folder metadata definition?

FolderShare records appear as child elements within the parent folder XML file, declaring sharedTo, sharedType, and accessLevel for each share grant.