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:
$ sf sfdmu run --sourceusername source@name.com --targetusername target@name.com
  • Use the following command if you want to import data from CSV files:
$ sf sfdmu run --sourceusername csvfile --targetusername target@name.com
  • Use the following command for export data into CSV files:
$ sf 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 sf 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.

$ sf 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>] [--usesf] [--logfullquery]

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
--usesf, default true [Optional] If set to 'true', forces the Plugin to use the latest Salesforce CLI (sf-cli) commands instead of Salesforce DX CLI (sfdx-cli) commands for deprecated commands. For example, it will use sf org display instead of sfdx force:org:display.

Setting this flag to 'false' will force the Plugin to use the deprecated Salesforce DX CLI (sfdx-cli) commands.

If not set, the Plugin will use the latest Salesforce CLI (sf-cli) commands by default.
This flag is useful when you have both Salesforce CLI (sf-cli) and Salesforce DX CLI (sfdx-cli) installed and you want to force the Plugin to use a specific CLI.
--logfullquery [Optional] Currently, when using the SFDMU plugin for querying data from Salesforce using SOQL, only a shortened version of the query results is displayed. While this is suitable for most scenarios, there are cases where having access to all the selected fields in the query result would be highly beneficial. logfullquery flag, enables the output of all selected fields when querying with SOQL, instead of the default short version.

➦ When this flag is set, the Plugin will still truncate the SOQL part after the FROM keyword if it exceeds a certain length.
➦ This flag affects both stdout and file logs.
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 sf sfdmu run --targetusername MYTARGET

  • All examples are provided with the assumption that you are using the current SF-CLI platform. However, if you are operating under the outdated SFDX-CLI platform, you should use sfdx sfdmu:run in all commands, instead of sf sfdmu run.

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 15th Mar 2024