This plugin was written to make it easier for developers (and admins!) to help analyze and clean up their Salesforce org metadata. Initial functionality is focused on permission based metadata which are particularly painful to compare and merge because of their size and complexity. This project has also absorbed and enhanced part of the functionality of another project: sfdx-hydrate. This project made it very easy to create a package.xml file without relying on 3rd party hosted tools. Supported metadata types for compare functionality are listed below. Contributions and requests/ideas are welcomed.
| Type | Notes |
|---|---|
| PermissionSet | |
| Profile | |
| SharingRules |
- Install the SDFX CLI.
- Clone the repository:
git clone [email protected]:mikesimps/sfdx-collate.git - Install npm modules:
npm install - Link the plugin:
sfdx plugins:link .
- Install plugin:
sfdx plugins:install sfdx-collate
Clone the sample gist:
git clone [email protected]:6427ea434581058a14fd3b084b87a5ff.git
Move into directory:
cd 6427ea434581058a14fd3b084b87a5ff/
Make script executable:
chmod +x ./sfdx-collate-permissionsets.sh
Generate examples:
./sfdx-collate-permissionsets.sh
OR Run a specific example:
sfdx collate:compare:files -p PermissionSet1.xml -s PermissionSet2.xml > permissionset_default.csvOutput as a CSV for easy editing. When using the build command, it blindly uses whatever values are in the final column which means you can overwrite it with whatever you need.
| field | purpose |
|---|---|
| obj | the metadata file type being compared |
| key | the unique value for each row in the file |
| primary | the xml property value (between the tags) for the primary file |
| secondary | the xml property value (between the tags) for the secondary file |
| final | the value that will be used in the build process, set depending on mode used |
| change | Match - exact match in key and value Add - key did not exist in one of the files Update - keys were matched, but values are different |
| mode | output |
|---|---|
| full | (default) include all items from both files final value is set to primary if it exists |
| diff | only include items that are different (adds or updates) final value is set to primary if it exists, otherwise secondary |
| exact | only includes items where keys and values match exactly final value is set to primary |
| inner | only includes items where keys match, but values can be different final value is set to primary |
The command requires a shorthand of sfdxAlias.APIName which is then parsed. For Profiles that have spaces in their names, you will have to escape the name when passing it. For example My Profile Name would be:
... -p myorg.My\ Profile\ Name -s ...
For Standard Profile you must use their API names which are not intuitive.
| Profile Name | Profile fullName (api name) |
|---|---|
| System Administrator | Admin |
| Standard User | Standard |
Full List of Standard Profile API Names: Here
An example config file is defined below. The "quickfilter" array lets you specify a list of metadata types that will be included in the output. You can have the xml output formatted by setting the "formatxml" to true.
Note: commandline parameters will override what is in the config file
//config.json
{
"quickFilters": ["Report",
"Dashboard",
"ReportType"
],
"apiVersion": "40.0",
"excludeManaged": "true",
"targetDir": ".",
"skipcleanup": "false",
"dxFormat": "false"
}sfdx-collate collate:compare:api -t <string> -p <string> -s <string> [-m <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]sfdx-collate collate:compare:build -f <string> [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]sfdx-collate collate:compare:files -p <string> -s <string> [-m <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]sfdx-collate collate:fetch:packagexml [-c <string>] [-q <string>] [-x] [-u <string>] [--apiversion <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
sfdx-collate collate:compare:api -t <string> -p <string> -s <string> [-m <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
Compares two metadatafiles. Currently only PermissionSet files are supported.
USAGE
$ sfdx-collate collate:compare:api -t <string> -p <string> -s <string> [-m <string>] [--json] [--loglevel
trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
OPTIONS
-m, --mode=full|inner|exact|diff What comparison values should be
returned
-p, --primary=primary (required) sfdxAlias.apiName of
primary metadata file
-s, --secondary=secondary (required) sfdxAlias.apiName of
secondary metadata file
-t, --metadatatype=PermissionSet|Profile|SharingRules (required) The metadata type to be
compared
--json format output as json
--loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL) [default: warn] logging level for
this command invocation
EXAMPLE
$ sfdx collate:compare:api --metadataType PermissionSet --primary uat.All_Users --secondary prod.All_Users --mode full
"obj","key","primary","secondary","final","change"
...
See code: src/commands/collate/compare/api.ts
sfdx-collate collate:compare:build -f <string> [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
Generate metadata file from a csv list of comparisons. The csv can be generated using the collate:compare:files command and expects a specific format.
USAGE
$ sfdx-collate collate:compare:build -f <string> [--json] [--loglevel
trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
OPTIONS
-f, --file=file (required) Path to csv comparison
file
--json format output as json
--loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL) [default: warn] logging level for
this command invocation
EXAMPLE
$ sfdx collate:compare:build --file directory/comparison.csv
See code: src/commands/collate/compare/build.ts
sfdx-collate collate:compare:files -p <string> -s <string> [-m <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
Compares two metadatafiles. Currently only PermissionSet files are supported.
USAGE
$ sfdx-collate collate:compare:files -p <string> -s <string> [-m <string>] [--json] [--loglevel
trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
OPTIONS
-m, --mode=full|inner|exact|diff What comparison values should be
returned
-p, --primary=primary (required) Path to primary file
-s, --secondary=secondary (required) Path to secondary file
--json format output as json
--loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL) [default: warn] logging level for
this command invocation
EXAMPLE
$ sfdx collate:compare:files --primary directory/file1.xml --secondary directory/file2.xml --mode full
"obj","key","primary","secondary","final","change"
...
See code: src/commands/collate/compare/files.ts
sfdx-collate collate:fetch:packagexml [-c <string>] [-q <string>] [-x] [-u <string>] [--apiversion <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
Create a package.xml file from a target org
USAGE
$ sfdx-collate collate:fetch:packagexml [-c <string>] [-q <string>] [-x] [-u <string>] [--apiversion <string>]
[--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
OPTIONS
-c, --config=config Configuration file to help make
pulling metadata more scriptable
-q, --quickfilter=quickfilter CSV list of metadata types to filter
-u, --targetusername=targetusername username or alias for the target
org; overrides default target org
-x, --excludemanaged Exclude managed packages (and
related items) from output
--apiversion=apiversion override the api version used for
api requests made by this command
--json format output as json
--loglevel=(trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL) [default: warn] logging level for
this command invocation
EXAMPLE
$ sfdx collate:fetch:packagexml --targetusername [email protected]
<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">...</Package>
See code: src/commands/collate/fetch/packagexml.ts