Salesforce DX Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
How Salesforce Developer Experience (DX) Tooling Changes the Way You Work
Provide Developers Access to Salesforce DX Tools
Project Setup
Sample Repository on GitHub
Create a Salesforce DX Project
Salesforce DX Project Structure and Source Format
Decomposed Metadata Types
How to Exclude Source When Syncing
Create a Salesforce DX Project from Existing Source
Convert Files in Metadata Format to Source Format
Salesforce DX Usernames and Orgs
Link a Namespace to a Dev Hub Org
Salesforce DX Project Configuration
Multiple Package Directories
Replace Strings in Code Before Deploying or Packaging
Authorization
Metadata Coverage
Scratch Orgs
Sandboxes
Track Changes Between Your Project and Org
Work with Data
Development
Build and Release Your App
Unlocked Packages
Continuous Integration
Troubleshoot Salesforce DX
Limitations for Salesforce DX
PDF

Decomposed Metadata Types

Decomposition refers to splitting a single, often large, metadata XML file into smaller XML files based on its subtypes. The result is referred to as source format. By default, a Salesforce DX project always decomposes custom objects and custom object translations. You can also optionally specify that other metadata types, such as permission sets and custom labels, be decomposed.

Start Decomposing the Optional Metadata Types (Beta)

The Salesforce DX project file (sfdx-project.json) determines which of the optional metadata types are decomposed. But don't update it manually. Rather, run the project convert source-behavior Salesforce CLI command which updates the project file for you, and also breaks up the associated metadata file XML into smaller files.

Decomposition of permission sets, custom labels, sharing rules, and workflows is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

Note

Before you begin, commit all your DX project source files to your version control system. Committing the files ensures that you can easily see what changed in your project. You can also revert the changes if necessary.

  1. Open a terminal or command prompt and change to your Salesforce DX project directory.
  2. Optionally execute a dry run of the CLI command to display what it does before it actually changes your DX project. For example, to dry run the decomposition of permission sets, run this command: 
    sf project convert source-behavior --behavior decomposePermissionSetBeta2 --dry-run
    See this table for the --behavior values for the other metadata types you can optionally decompose.
  3. When you're ready to update your DX project, run the same command but without the --dry-run flag: 
    sf project convert source-behavior --behavior decomposePermissionSetBeta2

    If your default org is enabled for source tracking, the CLI command returns an error. This error is expected, because decomposing your local metadata causes the source tracking system to get out of sync with the org. Follow the directions in the error message and try again.

  4. If you deleted your default org, recreate it and deploy your local source.

When the project convert source-behavior command finishes, your sfdx-project.json file is updated to always decompose permission sets, or whatever type you specified. The existing source files in your local package directories are converted into the new decomposed format. You can now deploy and retrieve your metadata as usual.

If you change your mind and don't want to decompose the optional types, revert the changes made by the project convert source-behavior and recreate your source-tracking orgs.

This table provides the list of metadata types that are decomposed by default, and the types that you can optionally decompose. For optional metadata types, the table also shows the corresponding --behavior flag value.

Metadata Type Value of --behavior Flag Details About the Source Format Structure
CustomObject Not needed; type is decomposed by default. Custom Objects
CustomObjectTranslation Not needed; type is decomposed by default. Custom Object Translations
CustomLabels decomposeCustomLabelsBeta2 Custom Labels (Beta)
PermissionSet decomposePermissionSetBeta2 Permission Sets (Beta)
SharingRules decomposeSharingRulesBeta Sharing Rules (Beta)
Workflow decomposeWorkflowBeta Workflows (Beta)

Source Format Structure of Decomposed Metadata Types

This section provides details about how the decomposed metadata types are broken down into their local source format structure.

Decomposition of the optional metadata types (custom labels, permission sets, sharing rules, and workflows) is a pilot or beta service that is subject to the Beta Services Terms at Agreements - Salesforce.com or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the Product Terms Directory. Use of this pilot or beta service is at the Customer's sole discretion.

Note

Custom Objects

Custom objects are decomposed by default.

When you convert from metadata format to source format, your custom objects are placed in the <package-directory>/main/default/objects directory. Each object has its own subdirectory that reflects the type of custom object. Some parts of the custom objects are extracted into in these subdirectories:

  • businessProcesses
  • compactLayouts
  • fields
  • fieldSets
  • indexes
  • listViews
  • recordTypes
  • sharingReasons
  • validationRules
  • webLinks

The parts of the custom object that aren’t extracted are placed in a <object-name>.object-meta.xml file.

Custom Object Translations

Custom object translations are decomposed by default.

Custom object translations reside in the <package-directory>/main/default/objectTranslations directory, each in their own subdirectory named after the custom object translation. Custom object translations and field translations are extracted into their own files within the custom object translation’s directory.

  • For field names, <field_name>.fieldTranslation-meta.xml

  • For object names, <object_name>.objectTranslation-meta.xml

The remaining pieces of the custom object translation that aren’t field translations are placed in a file called <objectTranslation-name>.objectTranslation-meta.xml.

See Salesforce Help: Translation Workbench for more information.

Custom Labels (Beta)

Custom labels aren’t decomposed by default; you must specifically configure your DX project to decompose them. See Start Decomposing the Optional Metadata Types (Beta) for details.

By default, all custom labels for your entire org are contained in a single file called CustomLabels.labels-meta.xml that resides in the <package-directory>/labels directory. Each package directory can have its own CustomLabels.labels-meta.xml file.

If you choose to decompose custom labels, individual CustomLabel components appear one time in a dedicated *.label-meta.xml source file. The name of each *.label-meta.xml source file is derived from the fullName of the CustomLabel component it contains. This example shows four custom label files in the default package directory.

Custom labels decomposed source structure

You can further organize custom labels in your DX project, as long as you follow these guidelines:

  • All *.label-meta.xml source files must be contained by a labels source directory.
  • You can create a labels source directory in each of your multiple package directories in your DX project.
  • You can create subdirectories of the labels source directory to further organize your *.label-meta.xml files.

Here are some examples of different ways you can organize custom labels.

Custom labels organized outside the default package directory
Custom labels organized using a subdirectory
Custom labels organized in multiple package directories and subdirectories

Permission Sets (Beta)

Permission sets aren’t decomposed by default; you must specifically configure your DX project to decompose them. See Start Decomposing the Optional Metadata Types (Beta) for details.

By default, all permission sets are contained in a single file called <permission-set-name>.permissionset-meta.xml that resides in the <package-directory>/main/default/permissionsets directory.

If you choose to decompose permission sets, they’re still stored in the top-level <package-directory>/main/default/permissionsets directory. This graphic shows how a sample permission set called MyPermSet is then decomposed into its smaller XML files.

Permission set source structure

Here are some highlights about the decomposition:

  • The decomposed files for a specific permission set are contained in a subdirectory named the same as the permission set, MyPermSet in our example.
  • The specific permission set directory contains a single file called <Name>.permissionset-meta.xml file, where <Name> is the directory name. This XML file contains information such as the permission set label, description, and license. In our example, the file is called MyPermSet.permissionset-meta.xml.
  • The objectSettings directory consolidates object-related permissions and settings into a single file for each object, with name <ObjectName>.objectSettings-meta.xml.
  • The remaining permissions and settings are in focused files with a category-specific extension, such as MyPermSet.applicationVisibilities-meta.xml or MyPermSet.flowAccesses-meta.xml.

Sharing Rules (Beta)

Sharing rules aren’t decomposed by default; you must specifically configure your DX project to decompose them. See Start Decomposing the Optional Metadata Types (Beta) for details.

By default, all sharing rules for an object are contained in a file called <object-name>.sharingRules-meta.xml that resides in the <package directory>/main/default/sharingRules directory. The object-name refers to the object to which the sharing rule applies.

If you choose to decompose sharing rules, they’re still stored in the top-level <package directory>/main/default/sharingRules directory. But the sharing rules are grouped into subdirectories with the same name as the object that the sharing rule is associated with. Within this object subdirectory, parts of the sharing rule are extracted into these subdirectories.

  • sharingCriteriaRules
  • sharingGuestRules
  • sharingOwnerRules
  • sharingTerritoryRules

The parts of the sharing rule that aren’t extracted are placed in a <object-name>.sharingRules-meta.xml file.

Workflows (Beta)

Workflows aren’t decomposed by default; you must specifically configure your DX project to decompose them. See Start Decomposing the Optional Metadata Types (Beta) for details.

By default, all workflows for an object are contained in a file called <object-name>.workflow-meta.xml that resides in the <package directory>/main/default/workflows directory. The object-name refers to the object to which the workflow applies.

If you choose to decompose workflows, they’re still stored in the top-level <package directory>/main/default/workflows directory. But the workflows are grouped into subdirectories with the same name as the object that the workflow is associated with. Within this object subdirectory, parts of the workflow are extracted into these subdirectories.

  • workflowAlerts
  • workflowFieldUpdates
  • workflowKnowledgePublishes
  • workflowOutboundMessages
  • workflowRules
  • workflowSends
  • workflowTasks

The parts of the workflow that aren’t extracted are placed in a <object-name>.workflow-meta.xml file.