@ds-sfdc/sfparty

Why use sfparty?

Salesforce metadata is typically stored in large XML files, which can take some effort to work with. These XML files are hard to read, challenging to diff, and can lead to conflicts and corrupted XML when merging. sfparty is a utility that improves the developer and DevOps experience by splitting Salesforce metadata XML files into smaller YAML or JSON parts. This makes it much easier to understand and manage the metadata and eliminates the risk of conflicts and corrupted XML. Additionally, sfparty's ability to combine these parts back into XML files makes it an ideal solution for CI/CD needs. It allows for easy version control and streamlined deployment processes.

Install

npm i -g @ds-sfdc/sfparty

NPM Installation Issues

command not found: sfparty
sfparty is an executable that is meant to be installed globally.

EACCESS: permission denied There are several options on how to resolve the NPM EACCESS issue.The simplest way if you can is to use sudo

sudo npm i -g @ds-sfdc/sfparty

Depending on your system, you may have some issues installing sfparty using NPM. These are typically file system permission issues. Here are some links to various articles with suggestions on how to resolve the issue.

Fixing npm permission issue
Always use sudo to install global packages
Use npm config instead of using chown or chmod

Commands

Split

sfparty split

Combine

sfparty combine

Update

sfparty update

Options

-y, --type     type(s) of metadata to process
-n, --name     name of metadata file  
-f, --format   format to use yaml (default) or json
-s, --source   package directory path specified in sfdx-project.json  
-t, --target   target path to directory to create yaml/json files  
-g, --git      combine files based on git commits
-h, --help     Show help  
-v, --version  Show version

Combine Options

The following options are available when using the combine command:

git

-g, --git      process files based on git commits. This option does not require a value.

Git Options

The following options are available when using the combine command:

-a, --append      append package and destructive package instead of overwriting.
-l, --delta       when possible create delta metadata files for CI/CD deployment.
-p, --package     path to your change package XML file.
-x, --destructive path to your destructive change package XML file.

Examples

Custom Labels

sfparty split --type=label

Permission Set

sfparty split --type=permset
sfparty split --type=permset --name="My Permission Set"

Profile

sfparty split --type=profile
sfparty split --type=profile --name="My Profile"

Workflow

sfparty split --type=workflow
sfparty split --type=workflow --name="Workflow"

Multiple Types

sfparty split --type="workflow,label"

Source Directory

The source directory will use your default package folder as specified in the sfdx-project.json file, and therefore must be executed from your Salesforce project directory. It will create the main/default folders if they do not exist.

{
    "packageDirectories": [
        {
            "path": "force-app",
            "default": true
        },
        {
            "path": "my-package"
        }
    ],
    "namespace": "",
    "sfdcLoginUrl": "https://login.salesforce.com",
    "sourceApiVersion": "56.0"
}

sfparty split --source="my-package"

Target Directory

The source directory will use your default package folder as specified in the sfdx-project.json file, and append -party to the end. For example, if the default source path is force-app, then the default target directory will be force-app-party unless otherwise specified. The target does not need to be specified in the sfdx-project.json, however the combine command will not work on folders that are not specified in the sfdx-project.json.

sfparty split --target="test"

Husky Git Hooks

If you are using a git hook utility such as husky, you can add a post-merge hook to automate running the combine command whenever you execute a merge or git pull command.

post-merge

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

sfparty combine --git

CI/CD

sfparty is meant to be a supplemental addition to your CI/CD process. Your pipeline should already build out a package.xml and destructiveChanges.xml. When sfparty runs it will do a git diff and append changes to the files. You can use a utility like sfdx-git-delta to build out the package.

Command:
sfparty combine --git

Required:  
-g, --git         process files based on git commits. This option does not require a value.

Optional:  
-a, --append      append package and destructive package instead of overwriting.
-l, --delta       when possible create delta metadata files for CI/CD deployment.
-p, --package     path to your change package XML file.
-x, --destructive path to your destructive change package XML file.

Example

Previous Commit to Current

sfparty combine --git=HEAD~1..HEAD --append --delta --package=deploy/package.xml --destructive=deploy/destructiveChanges/destructiveChanges.xml

Previous Commit to Current and output to different target directory

The default target is the package file specified in the sfdx-project.json file. You can use the --target parameter if you want the files to be created in a different location. sfparty will create the /main/default/* directories accordingly.

sfparty combine --git=HEAD~1..HEAD --append --delta --package=deploy/package.xml --destructive=deploy/destructiveChanges/destructiveChanges.xml --target=deployDir/force-app