sfdx-essentials

2.12.0 • Public • Published

Salesforce DX Essentials

Version Downloads/week Downloads/total codecov Mega-Linter GitHub contributors GitHub stars License PRs Welcome

SFDX ESSENTIALS PLUGIN

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 :)

Commands

Metadata

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)

Migration

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

Package.xml

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)

Permission sets

Command Description
essentials:permissionset:generate Generate permission sets from packageXml file depending on JSON configuration file

SFDX Project

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
essentials:project:count-apex-lines Count apex source lines of filtered files

INSTALLATION

    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

UPGRADE

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

CONTRIBUTE

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 :)

Command details

sfdx 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

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
  - CustomPlatformEvent
  - CustomSettings
  - 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

sfdx essentials:metadata:filter-xml-content

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

sfdx essentials:metadata:uncomment

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

sfdx essentials:mig:add-namespace

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

sfdx essentials:mig:fix-aura-attributes-names

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

sfdx essentials:mig:migrate-object-model

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

sfdx essentials:packagexml:append

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

sfdx essentials:packagexml:sort

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

sfdx essentials:permissionset:generate

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) Generate permission sets log image

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

sfdx essentials:project:change-dependency-version

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

sfdx essentials:project:check-consistency-with-packagexml

Allows to compare the content of a SFDX and the content of one or several (concatenated) package.xml files ( See Example log) Check SFDX project consistency log image

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

sfdx essentials:project:count-apex-lines

Allows to count lines of apex executable code related to filtered items

USAGE
  $ sfdx essentials:project:count-apex-lines

OPTIONS
  -b, --browsingpattern=browsingpattern  Files browsing pattern. Default **/*.cls
  -e, --excludepattern=excludepattern    Regex to exclude patterns
  -f, --folder=folder                    SFDX project folder containing files
  -p, --packagexmls=packagexmls          package.xml files path (separated by commas)
  -s, --sort=sort                        [default: alpha] Sort order: alpha (default), lines, chars
  -v, --verbose                          Verbose
  -w, --weight                           Return also weight (number of chars). Slower and requires Perl
  --noinsight                            Do not send anonymous usage stats

ALIASES
  $ sfdx essentials:count-apex-lines

EXAMPLES
  $ sfdx essentials:project:count-apex-lines -f "./force-app/main/default"
  $ sfdx essentials:project:count-apex-lines -f "./force-app/main/default" -b "**/WsMockV*.cls"
  $ sfdx essentials:project:count-apex-lines -f "./force-app/main/default" -p "./packagexml/package1.xml"
  $ sfdx essentials:project:count-apex-lines -f "./force-app/main/default" -p "./packagexml/package1.xml" -e 
  "(WsBlabla|POC_)"

See code: src/commands/essentials/project/count-apex-lines.ts

Readme

Keywords

Package Sidebar

Install

npm i sfdx-essentials

Weekly Downloads

956

Version

2.12.0

License

GPL-3.0-or-later

Unpacked Size

489 kB

Total Files

79

Last publish

Collaborators

  • nvuillam
  • ntang6