sfdx-isv/territory-management-toolkit

The Territory Management Toolkit (TM-Tools) is a Salesforce CLI Plugin that provides tools for simplifying the migration of a Salesforce org from Territory Management (TM1) to Enterprise Territory Management (TM2).

TM-Tools Plugin for the Salesforce CLI

A plugin for the Salesforce CLI that makes it easy to migrate from Territory Management (TM1) to Enterprise Territory Management (TM2) by creating a structured, multi-step environment to automate the extraction, transformation, and deployment/load of metadata and data from TM1 to TM2.

Installation

Installing the TM-Tools Plugin is easy if you have already installed the Salesforce CLI.

Open a terminal window (command prompt) and enter the following:

$ sfdx plugins:install territory-management-toolkit

You should see something similar to this:

Important Notes:

1. The command sfdx plugins:install pulls the plugin source code directly from the territory-management-toolkit package, hosted by NPM
2. The TM-Tools Plugin has not been digitially signed (yet), so you will need to acknowledge the warning to continue the installation

Available Commands

• sfdx tmtools:tm1:analyze [-d <directory>] [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
• sfdx tmtools:tm1:clean -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
• sfdx tmtools:tm1:extract [-s <directory>] [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
• sfdx tmtools:tm1:transform -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
• sfdx tmtools:tm2:deploy -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
• sfdx tmtools:tm2:deploysharing -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]
• sfdx tmtools:tm2:load -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

sfdx tmtools:tm1:analyze [-d <directory>] [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Analyze Territory Management (TM1) config in a connected org

USAGE
  $ sfdx tmtools:tm1:analyze [-d <directory>] [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] 
  [--falcondebugdepth <number>] [--json] [--loglevel 
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -d, --outputdir=outputdir                                                         [default: .] Directory to store TM1
                                                                                    analysis report

  --falcondebug=falcondebug                                                         [default: ] List of debug namespaces
                                                                                    which should render output

  --falcondebugdepth=falcondebugdepth                                               [default: 2] Sets the depth of
                                                                                    object inspection when debug output
                                                                                    is displayed

  --falcondebugerror                                                                Display extended information for
                                                                                    uncaught Errors

  --falcondebugsuccess                                                              Display extended information upon
                                                                                    successful command completion

  --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 tmtools:tm1:analyze
  $ sfdx tmtools:tm1:analyze -d ~/output-directory

See code: src/commands/tmtools/tm1/analyze.ts

sfdx tmtools:tm1:clean -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Given the location of a TM1 Transformation report (tm1-transformation.json), removes stale TM1 config from the target org.

USAGE
  $ sfdx tmtools:tm1:clean -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] 
  [--falcondebugdepth <number>] [--json] [--loglevel 
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -s, --sourcedir=sourcedir                                                         (required) [default: .] Directory
                                                                                    that contains a
                                                                                    tm1-transformation.json file.
                                                                                    Defaults to . (current directory) if
                                                                                    not specified.

  --falcondebug=falcondebug                                                         [default: ] List of debug namespaces
                                                                                    which should render output

  --falcondebugdepth=falcondebugdepth                                               [default: 2] Sets the depth of
                                                                                    object inspection when debug output
                                                                                    is displayed

  --falcondebugerror                                                                Display extended information for
                                                                                    uncaught Errors

  --falcondebugsuccess                                                              Display extended information upon
                                                                                    successful command completion

  --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 tmtools:tm1:clean
  $ sfdx tmtools:tm1:clean -s ~/tm1-transformation-report-directory

See code: src/commands/tmtools/tm1/clean.ts

sfdx tmtools:tm1:extract [-s <directory>] [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Given the location of a TM1 Analysis file (tm1-analysis.json), extracts all TM1 config (data & metadata) from the associated org and saves it locally.

USAGE
  $ sfdx tmtools:tm1:extract [-s <directory>] [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] 
  [--falcondebugdepth <number>] [--json] [--loglevel 
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -s, --sourcedir=sourcedir                                                         [default: .] Directory that contains
                                                                                    a tm1-analysis.json file. Defaults
                                                                                    to . (current directory) if not
                                                                                    specified.

  --falcondebug=falcondebug                                                         [default: ] List of debug namespaces
                                                                                    which should render output

  --falcondebugdepth=falcondebugdepth                                               [default: 2] Sets the depth of
                                                                                    object inspection when debug output
                                                                                    is displayed

  --falcondebugerror                                                                Display extended information for
                                                                                    uncaught Errors

  --falcondebugsuccess                                                              Display extended information upon
                                                                                    successful command completion

  --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 tmtools:tm1:extract
  $ sfdx tmtools:tm1:extract -s ~/tm1-analysis-report-directory

See code: src/commands/tmtools/tm1/extract.ts

sfdx tmtools:tm1:transform -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Transforms locally stored TM1 data and metadata into bundles that can be deployed back into the source org once Enterprise Territory Management (TM2) is activated.

USAGE
  $ sfdx tmtools:tm1:transform -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] 
  [--falcondebugdepth <number>] [--json] [--loglevel 
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -s, --sourcedir=sourcedir                                                         (required) [default: .] Directory
                                                                                    that contains a tm1-extraction.json
                                                                                    file. Defaults to . (current
                                                                                    directory) if not specified.

  --falcondebug=falcondebug                                                         [default: ] List of debug namespaces
                                                                                    which should render output

  --falcondebugdepth=falcondebugdepth                                               [default: 2] Sets the depth of
                                                                                    object inspection when debug output
                                                                                    is displayed

  --falcondebugerror                                                                Display extended information for
                                                                                    uncaught Errors

  --falcondebugsuccess                                                              Display extended information upon
                                                                                    successful command completion

  --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 tmtools:tm1:transform
  $ sfdx tmtools:tm1:transform -s ~/tm1-extraction-report-directory

See code: src/commands/tmtools/tm1/transform.ts

sfdx tmtools:tm2:deploy -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Given the location of a TM1 Transformation report (tm1-transformation.json), deploys TM2 metadata to the target org.

USAGE
  $ sfdx tmtools:tm2:deploy -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] 
  [--falcondebugdepth <number>] [--json] [--loglevel 
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -s, --sourcedir=sourcedir                                                         (required) [default: .] Directory
                                                                                    that contains a
                                                                                    tm1-transformation.json file.
                                                                                    Defaults to . (current directory) if
                                                                                    not specified.

  --falcondebug=falcondebug                                                         [default: ] List of debug namespaces
                                                                                    which should render output

  --falcondebugdepth=falcondebugdepth                                               [default: 2] Sets the depth of
                                                                                    object inspection when debug output
                                                                                    is displayed

  --falcondebugerror                                                                Display extended information for
                                                                                    uncaught Errors

  --falcondebugsuccess                                                              Display extended information upon
                                                                                    successful command completion

  --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 tmtools:tm2:deploy
  $ sfdx tmtools:tm2:deploy -s ~/tm1-transformation-report-directory

See code: src/commands/tmtools/tm2/deploy.ts

sfdx tmtools:tm2:deploysharing -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Given the location of a TM2 Deployment report (tm2-deployment.json), deploys TM2 sharing rules into the target org. Requires the migrated Territor Model to be in the 'Active' state.

USAGE
  $ sfdx tmtools:tm2:deploysharing -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] 
  [--falcondebugdepth <number>] [--json] [--loglevel 
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -s, --sourcedir=sourcedir                                                         (required) [default: .] Directory
                                                                                    that contains a tm1-deployment.json
                                                                                    file. Defaults to . (current
                                                                                    directory) if not specified.

  --falcondebug=falcondebug                                                         [default: ] List of debug namespaces
                                                                                    which should render output

  --falcondebugdepth=falcondebugdepth                                               [default: 2] Sets the depth of
                                                                                    object inspection when debug output
                                                                                    is displayed

  --falcondebugerror                                                                Display extended information for
                                                                                    uncaught Errors

  --falcondebugsuccess                                                              Display extended information upon
                                                                                    successful command completion

  --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 tmtools:tm2:deploysharing
  $ sfdx tmtools:tm2:deploysharing -s ~/tm2-deployment-report-directory

See code: src/commands/tmtools/tm2/deploysharing.ts

sfdx tmtools:tm2:load -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] [--falcondebugdepth <number>] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Given the location of a TM2 Deployment report (tm2-deployment.json), loads TM2 data into the target org using the Bulk API.

USAGE
  $ sfdx tmtools:tm2:load -s <directory> [--falcondebug <array>] [--falcondebugerror] [--falcondebugsuccess] 
  [--falcondebugdepth <number>] [--json] [--loglevel 
  trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

OPTIONS
  -s, --sourcedir=sourcedir                                                         (required) [default: .] Directory
                                                                                    that contains a tm1-deployment.json
                                                                                    file. Defaults to . (current
                                                                                    directory) if not specified.

  --falcondebug=falcondebug                                                         [default: ] List of debug namespaces
                                                                                    which should render output

  --falcondebugdepth=falcondebugdepth                                               [default: 2] Sets the depth of
                                                                                    object inspection when debug output
                                                                                    is displayed

  --falcondebugerror                                                                Display extended information for
                                                                                    uncaught Errors

  --falcondebugsuccess                                                              Display extended information upon
                                                                                    successful command completion

  --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 tmtools:tm2:load
  $ sfdx tmtools:tm2:load -s ~/tm2-deployment-report-directory

See code: src/commands/tmtools/tm2/load.ts

Questions/Comments

To report bugs or request new features, create an issue in this repository.

Acknowledgements

• This plugin was created by Vivek M. Chawla LinkedIn | Twitter
• Key portions have been adopted from the SFDX-Falcon Plugin

License

The TM-Tools Plugin is made available under the MIT License - see the LICENSE file for details.