Running.


Table of Contents



Simplest way to run the SFDMU.

  • Go to the directory where your export.json is located.
  • Use the following command to run a direct migration between source and target salesforce orgs:
$ sfdx sfdmu:run --sourceusername source@name.com --targetusername target@name.com
  • Use the following command if you want to import data from CSV files:
$ sfdx sfdmu:run --sourceusername csvfile --targetusername target@name.com
  • Use the following command for export data into CSV files:
$ sfdx sfdmu:run --sourceusername source@name.com --targetusername csvfile

Complete guide to running the SFDMU.

Run the SFDMU as a Sfdx Plugin.

The most quick way to run the SFDMU is using the sfdx sfdmu:run CLI command, as we've already explained before.

Find below the complete information about the format of the sfdmu:run command.

Full format of the CLI command.

$ sfdx sfdmu:run [-s <string>] [-p <directory>] [--silent] [-v] [-l <integer>] [-n] [-w] [-c <string>] [-m] [-u <string>] [--apiversion <string>] [--verbose] [--concise] [--quiet] [--json] [--loglevel <string>]

Available command flags.

Flag Description
--sourceusername, -s [string] ➦ The username/alias of the Source to import the data from it.

➦ If orgs section exists in the export.json, the credentials data will be extracted from this section based on the user name.
--sourceusername csvfile will export records from the previously created CSV files to the target org.
➦ The CSV files must present in the same directory as the export.json file.
--targetusername, -u [string] The username/alias of the Target to export the data to it.

If orgs section exists in the export.json, the credentials data will be extracted from this section based on the user name.
--targetusername csvfile will export records from the source org to CSV files. Each sObject will be stored in a separated CSV.
➦ The Plugin creates target CSV files in the same directory as the export.json file.
--path, -p [directory] [Optional] Absolute or relative path to the directory that contains working export.json file. If not provided, the Plugin will try to search for the file in the current directory.
--quiet [Optional] Supresses stdout logging. The Plugin will still log into file.
--silent [Optional] The same as the --quiet.
--apiversion [float as string] [Optional] If specified, overrides the apiVersion global property of the export.json file.

➦ Used for all api requests made by this command.
➦ Example value: "47.0"
--concise [Optional] Low stdout verbosity.

➦ Only messages, that seem to be important for understanding the progress of the execution, are printed to the stdout.
--filelog [number, 0 or 1], default 1 [Optional] Turns on/off file logging feature.

The available values are:
0 - completelly turns off file logging, log files are never created.
1 (default value) - the file logging is turned on, each command invocation creates its own log file.
--json [Optional] Outputs formatted json instead of text as a result of the command invocation.

➦ The json is printed once after the command invocation is fully completed.
➦ The same json is written into the file and printed in the stdout. The log file then contains well-formatted json content and can be used by any json parsers.
--quiet/--silent flags prevent outputting of json to the stdout. The json will still be written into log file.
--noprompt [Optional] Flag to suppress asking for user's inputs or confirmation. The command will continue using the default prompt/input option without pause the execution.
--nowarnings [Optional] Flag to suppress output of all warning messages to stdout.
--canmodify, -c [Optional] Flag to allow modification of target Production org sillently without preliminary prompting the user about it.

➦ When production environment is set as the Target and this flag is set to the target instance name (for example: prod-instance.my.salesforce.com), the Plugin will not ask the user for the approval to make modifications, otherwise the user will be prompted to prevent the critical production data from destroying by accident.
➦ This flag is ignored when the Target is other than production salesforce instance.
--verbose [Optional] High stdout verbosity.

➦ All messages are printed to the stdout.
--apiversion [Optional] Displays the current installed version of the Plugin.
--loglevel, default TRACE [Optional] Logging level for this command invocation. Which type of messages should be written into the log file.

➦ This flag control only file logs. The stdout logging is controlled only by --silent, --quiet, --concise and --verbose flags
All log messages (filtered by level of the message) are always written into log file (this corresponds to the --verbose verbosity of the stdout logging).
The available log levels are:
TRACE logs all messages, including stack trace in case of unhandled exception.
DEBUG is the same as INFO
WARN logs only warning messages.
ERROR logs only exeption messages, but unlike TRACE it will not output stack trace
FATAL is the same as ERROR
Notes:
  • If no --concise and --verbose flag added, the SFDMU uses a "normal" verbosity. It's a medium verbosity level, less messages than --verbose, but much more detailed than --concise.

  • When running the SFDMU on MacOS you can sometimes run into a permission issue. If so, just prepend your CLI command with "sudo", e.g.:

$ sudo sfdx sfdmu:run --targetusername MYTARGET

Run the SFDMU on one org only (one-directional mode).

Sometimes you have no the source org and want to only modify certain records in the target org.

For that you can provide only the --targetusername flag with the desired target org username and omit the --sourceusername. In this case, the target org will become the source org as well .

The data will be downloaded from the org, transformed as necessary (for example using the Anonymization feature), then uploaded back to the same org.

Note, that in the one-directional mode, the records are still being compared using the specified external id. Despite this, because the same org is used in the both ends, it would be quite reasonable to use the Record Id field as an External ID key for all objects in your export json.

Run the SFDMU as a standalone NodeJs application.

Alternatively you can run the the SFDMU as a standalone NodeJs application. It's meaning, that in order to run the migration job in this mode, you don't have to link the Plugin to the SFDX platform.

How to run?

Clone the SFDMU source code, then run the following CLI commands:

# Install Node dependencies
$ npm install

# Compile the source code (perform this step only once you have cloned the repo).
$ npm run build

# Perform the following command to run the SFDMU without debugging.
$ ./sfdmu-run.cmd -- --sourceusername source@mail.com --targetusername target@mail.com

# If you want to debug the source with VSCode, perform the following command from the VSCode's Terminal.
$ ./sfdmu-run-debug.cmd -- --sourceusername source@mail.com --targetusername target@mail.com
Notes:
  • After the compilation has done, the compiled Js code resides in the ./lib/ directory.

  • You can provide all SFDMU CLI flags listed above, but they should be spelled in the FULL format only, for example --targetusernme instead of -u, --path instead of -p, etc.

Run the SFDMU as a NodeJs module.

Also there is an option to run the Plugin programmatically from the custom TS/JS code.

Clone the source code and perform the following commands:

# Install Node dependencies
$ npm install

# Compile the source code (perform this step only once you have cloned the repo).
$ npm run build

Then after the compilation is done, upon the requirements, you can import the file ./src/modules/app/SfdmuRunModule as a TS module or the file ./lib/modules/app/SfdmuRunModule as a JS module.

How to run?

Find below the example of TS code which imports and runs the SFDMU as a JS module (this is the content of the file sfdmu_run_module_demo.ts, incuded in the SFDMU repository).

import IAppSfdmuRunModuleArgs from "./modules/app/IAppSfdmuRunModuleArgs";
import AppSfdmuRunApp from "./modules/app/appSfdmuRunApp";

const args: IAppSfdmuRunModuleArgs = {
    argv: [
         // The 2 first members of the array should always be empty
    "",
    "",

    // list of the CLI flags
    "--path",
    "C:\\PathToExportJson",
    "--sourceusername",
    "source@mymail.com",
    "--targetusername",
    "target@mymail.com",
    "--verbose"
    ]
};

const app = new AppSfdmuRunApp(args);
(async () => await app.runCommand())();
Notes:
  • As already mentioned above, the argv array should include the SFDMU CLI flags in the FULL format only.
Last updated on 29th Jan 2023