@dxatscale/sfpowerscripts v21.1.0

sfpowerscripts

Simple wrappers around sfdx commands to help set up CI/CD quickly. These commands are universal and may be used on any automation platform, as long as a shell process is available for executing the commands.

Installation

The SFDX CLI and sfpowerkit plugin are required for this plugin to work. If you have not already done so, please install both of these before continuing.

To install the sfpowerscripts plugin, run the following command:

$ sfdx plugins:install @dxatscale/sfpowerscripts

For automated installations as part of a CI process or Dockerfile:

$ echo 'y' | sfdx plugins:install @dxatscale/sfpowerscripts

Usage

$ sfdx sfpowerscripts:COMMAND
running command...

$ sfdx --help sfpowerscripts:[COMMAND]
USAGE
  $ sfdx sfpowerscripts:COMMAND
OPTIONS
  -flag Description
EXAMPLE
  Output variable:

...

Output variables

Many of the commands listed below will output variables which may be consumed as inputs to other tasks. The output variables are written to an environment file .env in a key=value format. A readVars.sh helper script is included as part of this package that can be used to read the values stored in the .env file and export them as environment variables.

One method of making the helper script globally invocable, is to install the NPM module as follows:

  $ npm install -g @dxatscale/sfpowerscripts

The script is then invocable as source readVars from the command-line.

If you're using a Docker image as part of your build process, you could also COPY the script into the image and link it to $PATH.

The following code snippet is an example of how output variables may be used.

$ sfdx sfpowerscripts:CreateDeltaPackage -n mypackage -r 61635fb -t 3cf01b9 -v 1.2.10 -b
$ source readVars
$ sfdx sfpowerscripts:DeploySource -u scratchorg --sourcedir ${sfpowerscripts_delta_package_path} -c

Reference name

Commands that output variables optionally accept a --refname flag that prefixes output variables with a user-specified string. The prefix is intended as a variable namespace that allows the same command to be invoked multiple times without overwriting the output variables.

$ sfdx sfpowerscripts:CreateUnlockedPackage --refname core -n core_package -b -x -v DevHub
$ sfdx sfpowerscripts:CreateUnlockedPackage --refname utility -n utility_package -b -x -v Devhub

$ source readVars
$ echo $core_sfpowerscripts_package_version_id
  04t2v000007X2YRAA0
$ echo $utility_sfpowerscripts_package_version_id
  04t2v000007X2YWAA0

Commands

• sfpowerscripts:AnalyzeWithPMD
• sfpowerscripts:CreateDeltaPackage
• sfpowerscripts:CreateSourcePackage
• sfpowerscripts:CreateUnlockedPackage
• sfpowerscripts:DeployDestructiveManifest
• sfpowerscripts:DeploySource
• sfpowerscripts:ExportSource
• sfpowerscripts:IncrementBuildNumber
• sfpowerscripts:InstallUnlockedPackage
• sfpowerscripts:TriggerApexTest
• sfpowerscripts:ValidateApexCoverage

sfpowerscripts:AnalyzeWithPMD

This task is used to run a static analysis of the apex classes and triggers using PMD. Please ensure that the SFDX CLI and sfpowerkit plugin are installed before using this task.

USAGE
  $ sfdx sfpowerscripts:AnalyzeWithPMD [--sourcedir <string>] [--ruleset <string>] [--rulesetpath <string>] [--format
  <string>] [-o <string>] [--version <string>] [-b] [-d <string>] [--refname <string>] [--json] [--loglevel
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -b, --istobreakbuild                                                               Enable this option if the build
                                                                                     should be reported as failure if 1
                                                                                     or more critical defects are
                                                                                     reported during the analysis

  -d, --projectdir=projectdir                                                        The project directory should
                                                                                     contain a sfdx-project.json for
                                                                                     this command to succeed

  -o, --outputpath=outputpath                                                        The file to which the output for
                                                                                     static analysis will be written

  --format=text|textcolor|csv|emacs|summaryhtml|html|xml|xslt|yahtml|vbhtml|textpad  [default: text]
                                                                                     https://pmd.github.io/latest/pmd_us
                                                                                     erdocs_cli_reference.html#available
                                                                                     -report-formats

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

  --refname=refname                                                                  Reference name to be prefixed to
                                                                                     output variables

  --ruleset=sfpowerkit|Custom                                                        [default: sfpowerkit] Inbuilt is
                                                                                     the default ruleset that comes with
                                                                                     the task, If you choose custom,
                                                                                     please provide the path to the
                                                                                     ruleset

  --rulesetpath=rulesetpath                                                          The path to the ruleset if you are
                                                                                     utilizing your own ruleset

  --sourcedir=sourcedir                                                              The directory that is to be analzed
                                                                                     using PMD, If omitted default
                                                                                     project diretory as mentioned in
                                                                                     sfdx-project.json will be used

  --version=version                                                                  [default: 6.22.0] The version of
                                                                                     PMD to be used for static analysis

EXAMPLE
  $ sfdx sfpowerscripts:AnalyzeWithPMD -b
  Output variable:
  sfpowerscripts_pmd_output_path
  <refname>_sfpowerscripts_pmd_output_path

See code: lib/commands/sfpowerscripts/AnalyzeWithPMD.js

sfpowerscripts:CreateDeltaPackage

This task is used to create a delta package between two commits and bundle the created delta as as a deployable artifact. Please ensure that the SFDX CLI and sfpowerkit plugin are installed before using this task.

USAGE
  $ sfdx sfpowerscripts:CreateDeltaPackage -n <string> -r <string> -v <string> [-t <string>] [-b] [-d <string>] [-x]
  [--bypassdirectories <string>] [--onlydifffor <string>] [--refname <string>] [--json] [--loglevel
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -b, --buildartifactenabled                                                        Create a build artifact, so that
                                                                                    this pipeline can be consumed by a
                                                                                    release pipeline

  -d, --projectdir=projectdir                                                       The project directory should contain
                                                                                    a sfdx-project.json for this command
                                                                                    to succeed

  -n, --package=package                                                             (required) The name of the package

  -r, --revisionfrom=revisionfrom                                                   (required) Provide the full SHA
                                                                                    Commit ID, from where the diff
                                                                                    should start generating

  -t, --revisionto=revisionto                                                       If not set, the head commit ID of
                                                                                    the current branch is used

  -v, --versionname=versionname                                                     (required) Provide a meaningful name
                                                                                    such as the default value, so this
                                                                                    artifact can be identified in the
                                                                                    release

  -x, --generatedestructivemanifest                                                 Check this option to generate a
                                                                                    destructive manifest to be deployed

  --bypassdirectories=bypassdirectories                                             Ignore a comma seperated list of
                                                                                    directories that need to be ignored
                                                                                    while a diff is generated

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

  --onlydifffor=onlydifffor                                                         Generate a comma seperated list of
                                                                                    directories that the diff should be
                                                                                    generated, Create a
                                                                                    sfdx-project.json to support
                                                                                    deployment

  --refname=refname                                                                 Reference name to be prefixed to
                                                                                    output variables

EXAMPLE
  $ sfdx sfpowerscripts:CreateDeltaPackage -n packagename -r 61635fb -t 3cf01b9 -v 1.2.10 -b
  Output variable:
  sfpowerscripts_delta_package_path
  <refname>_sfpowerscripts_delta_package_path
  sfpowerscripts_artifact_metadata_directory
  <refname>_sfpowerscripts_artifact_metadata_directory

See code: lib/commands/sfpowerscripts/CreateDeltaPackage.js

sfpowerscripts:CreateSourcePackage

This task simulates a packaging experience similar to unlocked packaging, just by writing the commit id to an artifact. It is basically to help with the release pipelines.

USAGE
  $ sfdx sfpowerscripts:CreateSourcePackage -n <string> -v <string> [--refname <string>] [--json] [--loglevel
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -n, --package=package
      (required) The name of the package

  -v, --versionnumber=versionnumber
      (required) The format is major.minor.patch.buildnumber . This will override the build number mentioned in the
      sfdx-project.json, Try considering the use of Increment Version Number task before this task

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

  --refname=refname
      Reference name to be prefixed to output variables

EXAMPLE
  $ sfdx sfpowerscripts:CreateSourcePackage -n packagename -v 1.5.10
  Output variable:
  sfpowerscripts_artifact_metadata_directory
  <refname>_sfpowerscripts_artifact_metadata_directory

See code: lib/commands/sfpowerscripts/CreateSourcePackage.js

sfpowerscripts:CreateUnlockedPackage

Creates a new package version. Utilize this task in a package build for DX Unlocked Package.

USAGE
  $ sfdx sfpowerscripts:CreateUnlockedPackage -n <string> [-b] [-k <string> | -x] [-v <string>] [--versionnumber
  <string>] [-f <string>] [-d <string>] [--enablecoverage] [-s] [--tag <string>] [--waittime <string>] [--refname
  <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -b, --buildartifactenabled
      Create a build artifact, so that this pipeline can be consumed by a release pipeline

  -d, --projectdir=projectdir
      The project directory should contain a sfdx-project.json for this command to succeed

  -f, --configfilepath=configfilepath
      [default: config/project-scratch-def.json] Path in the current project directory containing  config file for the
      packaging org

  -k, --installationkey=installationkey
      Installation key for this package

  -n, --package=package
      (required) ID (starts with 0Ho) or alias of the package to create a version of

  -s, --isvalidationtobeskipped
      Skips validation of dependencies, package ancestors, and metadata during package version creation. Skipping
      validation reduces the time it takes to create a new package version, but package versions created without
      validation can’t be promoted.

  -v, --devhubalias=devhubalias
      [default: HubOrg] Provide the alias of the devhub previously authenticated, default value is HubOrg if using the
      Authenticate Devhub task

  -x, --installationkeybypass
      Bypass the requirement for having an installation key for this version of the package

  --enablecoverage
      Please note this command takes a longer time to compute, activating this on every packaging build might not
      necessary

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

  --refname=refname
      Reference name to be prefixed to output variables

  --tag=tag
      the package version's tag

  --versionnumber=versionnumber
      The format is major.minor.patch.buildnumber . This will override the build number mentioned in the
      sfdx-project.json, Try considering the use of Increment Version Number task before this task

  --waittime=waittime
      [default: 120] wait time for command to finish in minutes

EXAMPLE
  $ sfdx sfpowerscripts:CreateUnlockedPackage -n packagealias -b -x -v HubOrg --tag tagname
  Output variable:
  sfpowerscripts_package_version_id
  <refname>_sfpowerscripts_package_version_id
  sfpowerscripts_artifact_metadata_directory
  <refname>_sfpowerscripts_artifact_metadata_directory

See code: lib/commands/sfpowerscripts/CreateUnlockedPackage.js

sfpowerscripts:DeployDestructiveManifest

Delete components in org according to destructive manifest - an empty package.xml will be automatically created, Read more about the task at https://sfpowerscripts.com/tasks/deployment-tasks/deploy-destructive-maifest-to-an-org/

USAGE
  $ sfdx sfpowerscripts:DeployDestructiveManifest [-u <string>] [-m <string>] [-t <string>] [-f <string>] [--json]
  [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -f, --destructivemanifestfilepath=destructivemanifestfilepath
      The location to the xml file which contains the destructive changes

  -m, --method=Text|FilePath
      [default: Text] If text is specified, add the members in the next field, if URL, pass in the location of the
      destructiveChanges.xml such as the raw git url

  -t, --destructivemanifesttext=destructivemanifesttext
      Type in the destructive manifest, follow the instructions,
      https://developer.salesforce.com/docs/atlas.en-us.daas.meta/daas/daas_destructive_changes.htm

  -u, --targetorg=targetorg
      [default: scratchorg] Alias or username of the target org where the code should be deployed

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

EXAMPLES
  $ sfdx sfpowerscripts:DeployDestructiveManifest -u scratchorg -m Text -t "<?xml version="1.0" encoding="UTF-8"?>
  <Package
  xmlns="http://soap.sforce.com/2006/04/metadata"><types><members>myobject__c</members><name>CustomObject</name></types>
  </Package>"

See code: lib/commands/sfpowerscripts/DeployDestructiveManifest.js

sfpowerscripts:DeploySource

Deploy source to org using mdapi based deploy (converts source to mdapi and use mdapi deployment).

USAGE
  $ sfdx sfpowerscripts:DeploySource [-u <string>] [-d <string>] [--sourcedir <string>] [--waittime <string>] [-c] [-f
  <string>] [-l <string>] [--specifiedtests <string>] [--apextestsuite <string>] [-b] [--refname <string>] [--json]
  [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -b, --istobreakbuildifempty
      Uncheck this field, to allow for empty folders not to break build, useful in the case of pre/post step uniformity
      across projects

  -c, --checkonly
      Validate a deployment, but don't save to the org, Use this for Stage 1/2 CI Run's

  -d, --projectdir=projectdir
      The  directory should contain a sfdx-project.json for this command to succeed

  -f, --validationignore=validationignore
      [default: .forceignore] Validation only deployment has issues with certain metadata such as apexttestsuite, create a
      different file similar to .forceignore and use it during validate only deployment

  -l, --testlevel=NoTestRun|RunSpecifiedTests|RunApexTestSuite|RunLocalTests|RunAllTestsInOrg
      [default: NoTestRun] The test level of the test that need to be executed when the code is to be deployed

  -u, --targetorg=targetorg
      [default: scratchorg] Alias or username of the target org where the code should be deployed

  --apextestsuite=apextestsuite
      Name of the Apex Test Suite that needs to be executed during this deployment

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

  --refname=refname
      Reference name to be prefixed to output variables

  --sourcedir=sourcedir
      [default: force-app] The source directory to be deployed

  --specifiedtests=specifiedtests
      Specify a comma seperated values of Apex Test that need to be executed during this deployment

  --waittime=waittime
      [default: 20] wait time for command to finish in minutes

EXAMPLE
  $ sfdx sfpowerscripts:DeploySource -u scratchorg --sourcedir force-app -c
  Output variable:
  sfpowerkit_deploysource_id
  <refname_sfpowerkit_deploysource_id

See code: lib/commands/sfpowerscripts/DeploySource.js

sfpowerscripts:ExportSource

Export source from any org for storing to backup or further analysis. Please ensure that the SFDX CLI and sfpowerkit plugin are installed before using this task.

USAGE
  $ sfdx sfpowerscripts:ExportSource [-u <string>] [-d <string>] [--quickfilter <string>] [-x] [-e] [--refname <string>]
  [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -d, --sourcedir=sourcedir                                                         [default: metadata] The directory to
                                                                                    which the source should be exported
                                                                                    to

  -e, --isunzipenabled                                                              Unzip the exported metadata/source
                                                                                    from the zip into the provided
                                                                                    folder

  -u, --targetorg=targetorg                                                         [default: scratchorg] Alias or
                                                                                    username of the target org where
                                                                                    metadata is to be retrieved

  -x, --ismanagedpackagestobeexcluded                                               Exclude managed package components
                                                                                    from the export

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

  --quickfilter=quickfilter                                                         Comma separated values  of metadata
                                                                                    type, member or file names to be
                                                                                    excluded while building the manifest

  --refname=refname                                                                 Reference name to be prefixed to
                                                                                    output variables

EXAMPLE
  $ sfdx sfpowerscripts:ExportSource -u scratchorg -d metadata -x -e
  Output variable:
  sfpowerscripts_exportedsource_zip_path
  <refname>_sfpowerscripts_exportedsource_zip_path

See code: lib/commands/sfpowerscripts/ExportSource.js

sfpowerscripts:IncrementBuildNumber

Increment the selected version counter by one and adds a commit to to your repository. This task does not push the change to the repository. If a push to the repository is required, include a step after the package is created to push this commit to the repository.

Please note this task skips all the options if it figures a .NEXT in the build number for an unlocked package

USAGE
  $ sfdx sfpowerscripts:IncrementBuildNumber [--segment <string>] [-a -r <string>] [-n <string>] [-d <string>] [-c]
  [--refname <string>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -a, --appendbuildnumber
      Set the build segment of the version number to the build number rather than incremenenting

  -c, --commitchanges
      Mark this if you want to commit the sfdx-project json to the repository, Please note this will not push to the repo
      only commits in the local checked out repo, You would need to have a push to the repo at the end of the packaging
      task if everything is successfull

  -d, --projectdir=projectdir
      The directory should contain a sfdx-project.json for this command to succeed

  -n, --package=package
      The name of the package of which the version need to be incremented,If not specified the default package is utilized

  -r, --runnumber=runnumber
      The build number of the CI pipeline, usually available through an environment variable

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

  --refname=refname
      Reference name to be prefixed to output variables

  --segment=Major|Minor|Patch|BuildNumber
      [default: BuildNumber] Select the segment of the version

EXAMPLE
  $ sfdx IncrementBuildNumber --segment BuildNumber -n packagename -c
  Output variable:
  sfpowerscripts_incremented_project_version
  <refname>_sfpowerscripts_incremented_project_version

See code: lib/commands/sfpowerscripts/IncrementBuildNumber.js

sfpowerscripts:InstallUnlockedPackage

Installs an unlocked package using sfpowerscripts metadata.

USAGE
  $ sfdx sfpowerscripts:InstallUnlockedPackage [-n <string>] [-u <string>] [-v <string> | -i] [-k <string>] [-a]
  [--securitytype <string>] [--upgradetype <string>] [--waittime <string>] [--publishwaittime <string>] [--json]
  [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -a, --apexcompileonlypackage                                                      Each package installation triggers a
                                                                                    compilation of apex, flag to trigger
                                                                                    compilation of package only

  -i, --packageinstalledfrom                                                        automatically retrieve the version
                                                                                    ID of the package to be installed,
                                                                                    from the build artifact

  -k, --installationkey=installationkey                                             installation key for key-protected
                                                                                    package

  -n, --package=package                                                             Name of the package to be installed

  -u, --envname=envname                                                             Alias/User Name of the target
                                                                                    environment

  -v, --packageversionid=packageversionid                                           manually input package version Id of
                                                                                    the package to be installed

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

  --publishwaittime=publishwaittime                                                 [default: 10] number of minutes to
                                                                                    wait for subscriber package version
                                                                                    ID to become available in the target
                                                                                    org

  --securitytype=AllUsers|AdminsOnly                                                [default: AllUsers] Select the
                                                                                    security access for the package
                                                                                    installation

  --upgradetype=DeprecateOnly|Mixed|Delete                                          [default: Mixed] the upgrade type
                                                                                    for the package installation

  --waittime=waittime                                                               [default: 120] wait time for command
                                                                                    to finish in minutes

EXAMPLE
  $ sfdx InstallUnlockedPackage -n packagename -u sandboxalias -i

See code: lib/commands/sfpowerscripts/InstallUnlockedPackage.js

sfpowerscripts:TriggerApexTest

Triggers an asynchronous apex unit test in an org. Please ensure that the SFDX CLI and sfpowerkit plugin are installed before using this task.

USAGE
  $ sfdx sfpowerscripts:TriggerApexTest [-u <string>] [-l <string>] [-s] [--specifiedtests <string>] [--apextestsuite
  <string>] [--waittime <string>] [--json] [--loglevel
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -l, --testlevel=RunSpecifiedTests|RunApexTestSuite|RunLocalTests|RunAllTestsInOrg  [default: RunLocalTests] The test
                                                                                     level of the test that need to be
                                                                                     executed when the code is to be
                                                                                     deployed

  -s, --synchronous                                                                  Select an option if the tests are
                                                                                     to be run synchronously

  -u, --targetorg=targetorg                                                          [default: scratchorg] username or
                                                                                     alias for the target org; overrides
                                                                                     default target org

  --apextestsuite=apextestsuite                                                      comma-separated list of Apex test
                                                                                     suite names to run

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

  --specifiedtests=specifiedtests                                                    comma-separated list of Apex test
                                                                                     class names or IDs and, if
                                                                                     applicable, test methods to run

  --waittime=waittime                                                                [default: 60] wait time for command
                                                                                     to finish in minutes

EXAMPLE
  $ sfdx TriggerApexTest -u scratchorg -l RunLocalTests -s

See code: lib/commands/sfpowerscripts/TriggerApexTest.js

sfpowerscripts:ValidateApexCoverage

Validates apex test coverage in the org. Please ensure that the SFDX CLI and sfpowerkit plugin are installed before using this task.

USAGE
  $ sfdx sfpowerscripts:ValidateApexCoverage -t <string> [-u <string>] [--json] [--loglevel
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -t, --testcoverage=testcoverage                                                   (required) The percentage of test
                                                                                    coverage for apex clasess, that
                                                                                    should be as per the last test run
                                                                                    status

  -u, --targetorg=targetorg                                                         [default: scratchorg] Alias or
                                                                                    username of the target org

  --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 sfpowerscripts:ValidateApexCoverage -u scratchorg -t 80

See code: lib/commands/sfpowerscripts/ValidateApexCoverage.js