Toolbox for Salesforce DX to provide some very helpful additional features to base sfdx commands.
SFDX Essentials commands are focused on DevOps, but not only (cleaning, sources consistency check ...)
Easy to integrate in a CD/CI process (Jenkins Pipeline,CircleCI...)
See CHANGELOG
Any question, problem or enhancement request ? Ask here :)
Command | Description |
---|---|
essentials:metadata:filter-from-packagexml | Filter metadatas generated from a SFDX Project in order to be able to deploy only part of them on an org |
essentials:metadata:filter-xml-content | Filter content of metadatas (XML) in order to be able to deploy only part of them on an org |
sfdx essentials:metadata:uncomment | Uncomment lines in sfdx/md files (useful to manage @Deprecated annotations with managed packages) |
Command | Description |
---|---|
essentials:mig:fix-aura-attributes-names | Replace reserved lightning attribute names in lightning components and apex classes ( if you named a lightning attribute like a custom apex class, since Summer 18 you simply can not generate a managed package again) |
essentials:mig:migrate-object-model | Migrate sources from an object model to a new object model |
essentials:mig:add-namespace | Update SFDX sources to add a namespace on references to items described in a package.xml file |
Command | Description |
---|---|
essentials:packagexml:append | Append content of a package.xml files into a single one |
essentials:packagexml:sort | Reorder alphabetically the content of package.xml file(s) |
Command | Description |
---|---|
essentials:permissionset:generate | Generate permission sets from packageXml file depending on JSON configuration file |
Command | Description |
---|---|
essentials:project:change-dependency-version | Replace other managed packages dependency version number ( very useful when you build a managed package over another managed package, like Financial Services Cloud ) |
essentials:project:check-consistency-with-packagexml | Check consistency between a SFDX project files and package.xml files |
sfdx plugins:install sfdx-essentials
-
Windows users: sfdx plugin generator is bugged on windows (hardcode call of linux rm instruction) , so you may use Git Bash to run this code ( at least while it installs the plugin dependencies )
-
CI Users: As the plugin is not signed, to install it from a Dockerfile or a script:
echo 'y' | sfdx plugins:install sfdx-essentials
Its seems that sfdx plugins:update
does not always work, in that case , uninstall then reinstall the plugin
sfdx plugins:uninstall sfdx-essentials
sfdx plugins:install sfdx-essentials
Contributions are very welcome, please run npm run lint:fix and npm run test before making a new PR
- Fork the repo and clone it on your computer
- To debug, run
$ sfdx plugins:link
or use$ NODE_OPTIONS=--inspect-brk bin/run yourcommand
- Now your calls to sfdx essentials are performed on your local sources
- Once your code is ready, documented and linted, please make a pull request :)
sfdx essentials:metadata:filter-from-packagexml
sfdx essentials:metadata:filter-xml-content
sfdx essentials:metadata:uncomment
sfdx essentials:mig:add-namespace
sfdx essentials:mig:fix-aura-attributes-names
sfdx essentials:mig:migrate-object-model
sfdx essentials:packagexml:append
sfdx essentials:packagexml:sort
sfdx essentials:permissionset:generate
sfdx essentials:project:change-dependency-version
sfdx essentials:project:check-consistency-with-packagexml
Filter metadatas generated from a SFDX Project in order to be able to deploy only part of them on an org
USAGE
$ sfdx essentials:metadata:filter-from-packagexml
OPTIONS
-i, --inputfolder=inputfolder Input folder (default: "." )
-o, --outputfolder=outputfolder Output folder (default: filteredMetadatas)
-p, --packagexml=packagexml package.xml file path
-s, --silent Silent logs when no error
-v, --verbose Verbose
--noinsight Do not send anonymous usage stats
DESCRIPTION
This can help if you need to deploy only part of the result of sfdx force:source:convert into a org, by filtering the
result (usually in mdapi_output_dir) to keep only the items referenced in your own package.xml file
WARNING: This version does not support all the metadata types yet, please contribute if you are in a hurry :)
Package.xml types currently managed:
- ApexClass
- ApexComponent
- ApexPage
- ApexTrigger
- ApprovalProcess
- AuraDefinitionBundle
- AuthProvider
- BusinessProcess
- ContentAsset
- CustomApplication
- CustomField
- CustomLabel
- CustomMetadata
- CustomObject
- CustomObjectTranslation
- CustomPermission
- CustomSite
- CustomTab
- Document
- EmailTemplate
- EscalationRules
- FlexiPage
- Flow
- FieldSet
- GlobalValueSet
- GlobalValueSetTranslation
- HomePageLayout
- ListView
- LightningComponentBundle
- Layout
- NamedCredential
- Network
- NetworkBranding
- PermissionSet
- Profile
- Queue
- QuickAction
- RecordType
- RemoteSiteSetting
- Report
- SiteDotCom
- StandardValueSet
- StandardValueSetTranslation
- StaticResource
- Translations
- ValidationRule
- WebLink
- Workflow
ALIASES
$ sfdx essentials:filter-metadatas
EXAMPLES
$ sfdx essentials:metadata:filter-from-packagexml -p myPackage.xml
$ sfdx essentials:metadata:filter-from-packagexml -i md_api_output_dir -p myPackage.xml -o md_api_filtered_output_dir
$ sfdx force:source:convert -d tmp/deployDemoQuali/
sfdx essentials:metadata:filter-from-packagexml -i tmp/deployDemoQuali/ -p myPackage.xml -o
tmp/deployDemoQualiFiltered/
sfdx force:mdapi:deploy -d tmp/deployDemoQualiFiltered/ -w 60 -u DemoQuali
See code: src/commands/essentials/metadata/filter-from-packagexml.ts
Filter content of metadatas (XML) in order to be able to deploy only part of them on an org (See Example configuration)
USAGE
$ sfdx essentials:metadata:filter-xml-content
OPTIONS
-c, --configFile=configFile Config JSON file path
-i, --inputfolder=inputfolder Input folder (default: "." )
-o, --outputfolder=outputfolder Output folder (default: parentFolder + _xml_content_filtered)
--noinsight Do not send anonymous usage stats
DESCRIPTION
When you perform deployments from one org to another, the features activated in the target org may not fit the content
of the sfdx/metadata files extracted from the source org.
You may need to filter some elements in the XML files, for example in the Profiles
This script requires a filter-config.json file
ALIASES
$ sfdx essentials:filter-xml-content
EXAMPLES
sfdx essentials:filter-xml-content -i "./mdapi_output"
sfdx essentials:filter-xml-content -i "retrieveUnpackaged"
See code: src/commands/essentials/metadata/filter-xml-content.ts
Uncomment lines in sfdx/md files (useful to manage @Deprecated annotations with managed packages)
USAGE
$ sfdx essentials:metadata:uncomment
OPTIONS
-f, --folder=folder SFDX project folder containing files
-k, --uncommentKey=uncommentKey Uncomment key (default: SFDX_ESSENTIALS_UNCOMMENT)
-v, --verbose Verbose
--noinsight Do not send anonymous usage stats
DESCRIPTION
Uncomment desired lines just before making a deployment
Once you flagged a packaged method as **@Deprecated** , you can not deploy it in an org not used for generating a
managed package
Before :
// @Deprecated SFDX_ESSENTIALS_UNCOMMENT
global static List<OrgDebugOption__c> setDebugOption() {
return null;
}
After :
@Deprecated // Uncommented by sfdx essentials:uncomment (https://github.com/nvuillam/sfdx-essentials)
global static List<OrgDebugOption__c> setDebugOption() {
return null;
}
ALIASES
$ sfdx essentials:uncomment
EXAMPLE
$ sfdx essentials:metadata:uncomment --folder "./Projects/DevRootSource/tmp/deployPackagingDxcDevFiltered"
--uncommentKey "SFDX_ESSENTIALS_UNCOMMENT_DxcDev_"
See code: src/commands/essentials/metadata/uncomment.ts
Migrate sources from an object model to a new object model (See Example configuration)
USAGE
$ sfdx essentials:mig:add-namespace
OPTIONS
-e, --excludeExpressionList=excludeExpressionList List of expressions to ignore. ex: **/node_modules/**
-f, --fetchExpressionList=fetchExpressionList Fetch expression list. Let default if you dont know. ex:
./aura/**/*.js,./aura/**/*.cmp,./classes/*.cls,./objects/*/fields/*
.xml,./objects/*/recordTypes/*.xml,./triggers/*.trigger,./permissio
nsets/*.xml,./profiles/*.xml,./staticresources/*.json
-i, --inputFolder=inputFolder Input folder (default: "." )
-l, --labelsfile=labelsfile Path to CustomLabel.labels-meta.xml
-n, --namespace=namespace (required) Namespace string
-p, --packagexml=packagexml (required) Path to package.xml file
-v, --verbose Verbose
--noinsight Do not send anonymous usage stats
DESCRIPTION
Use this command if you need to replace a SObject by another one in all your sfdx sources
ALIASES
$ sfdx essentials:migrate-object-model
EXAMPLES
$ essentials:mig:add-namespace -n DxcOemDev -p "../../somefolder/package.xml"
$ essentials:mig:add-namespace -n DxcOemDev -i "C:/Work/git/some-client-project/Projects/DevRootSource"
--fetchExpressionList="**/*.apex,**/*.json" -p
"C:/Work/git/DXCO4SF_Sources_OEM_ST/Config/packageXml/package_DevRoot_Managed.xml"
$ essentials:mig:add-namespace -n DxcOemDev -e "**/www*" -p "../../somefolder/package.xml"
See code: src/commands/essentials/mig/add-namespace.ts
Replace reserved lightning attribute names in lightning components and apex classes
USAGE
$ sfdx essentials:mig:fix-aura-attributes-names
OPTIONS
-f, --folder=folder SFDX project folder containing files
--noinsight Do not send anonymous usage stats
DESCRIPTION
If you named a lightning attribute like a custom apex class, since Summer 18 you simply can not generate a managed
package again.
This command lists all custom apex classes and custom objects names , then replaces all their references in lightning
components and also in apex classes with their camelCase version.
Ex : MyClass_x attribute would be renamed myClassX
ALIASES
$ sfdx essentials:fix-lightning-attribute-names
EXAMPLE
sfdx essentials:mig:fix-aura-attributes-names
See code: src/commands/essentials/mig/fix-aura-attributes-names.ts
Migrate sources from an object model to a new object model (See Example configuration)
USAGE
$ sfdx essentials:mig:migrate-object-model
OPTIONS
-c, --configFile=configFile JSON config file
-d, --[no-]deleteFiles Delete files with deprecated references
-f, --fetchExpressionList=fetchExpressionList Fetch expression list. Let default if you dont know. ex:
/aura/**/*.js,./aura/**/*.cmp,./classes/*.cls,./objects/*/fields/*.xml,
./objects/*/recordTypes/*.xml,./triggers/*.trigger,./permissionsets/*.x
ml,./profiles/*.xml,./staticresources/*.json
-i, --inputFolder=inputFolder Input folder (default: "." )
-k, --[no-]deleteFilesExpr Delete files matching expression
-r, --[no-]replaceExpressions Replace expressions using fetchExpressionList
-s, --[no-]copySfdxProjectFolder Copy sfdx project files after process
-v, --verbose Verbose
--noinsight Do not send anonymous usage stats
DESCRIPTION
Use this command if you need to replace a SObject by another one in all your sfdx sources
ALIASES
$ sfdx essentials:migrate-object-model
EXAMPLES
$ sfdx essentials:mig:migrate-object-model -c "./config/migrate-object-model-config.json"
$ sfdx essentials:mig:migrate-object-model -c migration/config-to-oem.json -i Config/packageXml --fetchExpressionList
"./package*.xml" --no-deleteFiles --no-deleteFilesExpr --no-copySfdxProjectFolder
See code: src/commands/essentials/mig/migrate-object-model.ts
Append content of a package.xml files into a single one
USAGE
$ sfdx essentials:packagexml:append
OPTIONS
-o, --outputfile=outputfile package.xml output file
-p, --packagexmls=packagexmls package.xml files path (separated by commas)
-v, --verbose Verbose
--noinsight Do not send anonymous usage stats
DESCRIPTION
API version number of the result file will be the same than in the first package.xml file sent as argument
EXAMPLE
sfdx essentials:packagexml:append -p
"./Config/packageXml/package_DevRoot_Managed.xml,./Config/packageXml/package_DevRoot_Demo.xml,./Config/packageXml/pack
age_DevRoot_Scratch.xml" -o "./Config/packageXml/package_for_new_scratch_org.xml"
See code: src/commands/essentials/packagexml/append.ts
Developers have the bad habit to input package.xml files in a non-alphabetical order. Use this command to reorder alphabetically your package.xml files !
USAGE
$ sfdx essentials:packagexml:sort
OPTIONS
-p, --packagexml=packagexml package.xml file path (or a folder containing package.xml files)
--noinsight Do not send anonymous usage stats
ALIASES
$ sfdx essentials:order-package-xml
$ sfdx essentials:packagexml:reorder
EXAMPLES
$ sfdx essentials:packagexml:sort -p "./Config/packageXml/package.xml"
$ sfdx essentials:packagexml:sort -p "./Config/packageXml"
See code: src/commands/essentials/packagexml/sort.ts
Generate permission sets in XML format used for SFDX project from package.xml file depending on JSON configuration file (See Example configuration and Example log)
USAGE
$ sfdx essentials:permissionset:generate
OPTIONS
-c, --configfile=configfile config.json file
-f, --sfdxSourcesFolder=sfdxSourcesFolder SFDX Sources folder (used to filter required and masterDetail fields)
-o, --outputfolder=outputfolder [default: .] Output folder (default: "." )
-p, --packagexml=packagexml package.xml file path
-s, --nameSuffix=nameSuffix Name suffix for generated permission sets
-v, --verbose Verbose
--noinsight Do not send anonymous usage stats
ALIASES
$ sfdx essentials:generate-permission-sets
EXAMPLES
$ sfdx essentials:permissionset:generate -c "./Config/generate-permission-sets.json" -p
"./Config/packageXml/package_DevRoot_Managed.xml" -f "./Projects/DevRootSource/force-app/main/default" -o
"./Projects/DevRootSource/force-app/main/default/permissionsets"
$ sfdx essentials:permissionset:generate -c "./Config/generate-permission-sets.json" -p
"./Config/packageXml/package_DevRoot_xDemo.xml" -f "./Projects/DevRootSource/force-app/main/default" --nameSuffix
Custom -o "./Projects/DevRootSource/force-app/main/default/permissionsets"
See code: src/commands/essentials/permissionset/generate.ts
Allows to change an external package dependency version, or update api version
USAGE
$ sfdx essentials:project:change-dependency-version
OPTIONS
-a, --apiversion=apiversion If sent, updates api version
-f, --folder=folder SFDX project folder containing files
-j, --majorversion=majorversion Major version
-m, --minorversion=minorversion Minor version
-n, --namespace=namespace Namespace of the managed package
-r, --remove Verbose
-v, --verbose Verbose
--noinsight Do not send anonymous usage stats
DESCRIPTION
Can also :
- remove package dependencies if --namespace and --remove arguments are sent
- update API version
ALIASES
$ sfdx essentials:change-dependency-version
$ sfdx essentials:change-api-version
$ sfdx essentials:project:change-api-version
EXAMPLES
$ sfdx essentials:project:change-dependency-version -n FinServ -j 214 -m 7
$ sfdx essentials:project:change-dependency-version -n FinServ -r
$ sfdx essentials:project:change-dependency-version -a 47.0
See code: src/commands/essentials/project/change-dependency-version.ts
Allows to compare the content of a SFDX and the content of one or several (concatenated) package.xml files ( See Example log)
USAGE
$ sfdx essentials:project:check-consistency-with-packagexml
OPTIONS
-c, --chatty Chatty logs
-d, --ignoreDuplicateTypes=ignoreDuplicateTypes List of types to ignore while checking for duplicates in package.xml
files
-f, --failIfError Script failing if errors are founds
-i, --inputfolder=inputfolder SFDX Project folder (default: "." )
-j, --jsonLogging JSON logs
-p, --packageXmlList=packageXmlList List of package.xml files path
--noinsight Do not send anonymous usage stats
DESCRIPTION
This will output a table with the number of elements :
- Existing in both SFDX Project files and package.xml file(s)
- Existing only in SFDX Project files
- Existing only in package.xml file(s)
ALIASES
$ sfdx essentials:check-sfdx-project-consistency
EXAMPLE
$ sfdx essentials:project:check-consistency-with-packagexml -p
"./Config/packageXml/package_DevRoot_Managed.xml,./Config/packageXml/package_DevRoot_xDemo.xml" -i
"./Projects/DevRootSource/force-app/main/default" -d "Document,EmailTemplate" --failIfError
See code: src/commands/essentials/project/check-consistency-with-packagexml.ts