Run the migration job.

There are three ways to run the SFDMU Plugin.


Run the SFDMU as a Sfdx Plugin.

The default way to run the Plugin is using the stadnard sfdx command, as below.

In this case you need either to clone the repository locally and to perform sfdx plugins:link or install the Plugin globally without downloading the source code with the command sfdx plugins:install sfdmu.

Then you can run the migration job:

$ sfdx sfdmu:run [-s <string>] [-u <string>] [-p <directory>] [-c <string>] [--silent] [--version] [--filelog] [--noprompt] [--canmodify <string>] [--nowarnings] [--apiversion <string>] [--verbose] [--concise] [--quiet] [--json] [--loglevel trace|debug|info|warn|error|fatal|TRACE|DEBUG|INFO|WARN|ERROR|FATAL]

Available flags:

Flag Description
--sourceusername, -s [string] The username/alias of the source salesforce org to take the data from it.
As mentioned above the credentials can be explicitly set in the [orgs] section of the export.json, or you can specify the username of the organization, that is previously connected using standard sfdx force:auth:web:login command.

"--sourceusername csvfile" will import records from previously created CSV files into the target Org.
The CSV files must exist in the same directory as the export.json file.
Use --targetusername csvfile parameter (see below) to create these files from the source records.
--targetusername, -u [string] The username/alias of the target salesforce org where to put the data.

--targetusername csvfile will export records from the source org into CSV files. Each SObject will be stored in separated 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] Disable logging - show only success/errors. Suppress stdout output. if --filelog is specified the plugin will still log into file.
--silent [Optional] The same as --quiet flag. Disable logging - show only success/errors. Suppress stdout output. if --filelog is specified the plugin will still log into file.
--apiversion [float as string] [Optional] If specified, overrides the apiVersion parameter of the export.json file. Used for all api requests made by this command. Example value: "47.0"
--concise [Optional] Display only short messages, that are highly important for understanding the progress of the execution.
--filelog [Optional] In addition stdout/stderr this flag will turn on logging into .log file. Each command run will create separated log file inside /log subdirectory related to the working export.json file.
A verbosity control is disabled for log files: all messages will be logged, even --quite flag was specified.
If specified, overrides the fileLog parameter of the export.json file.
--json [Optional] Return formatted json instead of text to stdout as a result of the command execution.
Json result will also contain extended information as start time, end time, time elapsed etc.
--noprompt [Optional] Flag to skip all prompting for more inputs or confirmation. Command will continue using the default options.
--nowarnings [Optional] Flag to suppress output of all warning messages to stdout.
--canmodify, -c [Optional] Allows modification of target production environment without preliminary prompting the user about it.
When production environment is set as the Target and this flag is set to the target DOMAIN 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] Display all command messages and errors.
--apiversion [Optional] Display the current installed version of the plugin.
--loglevel [Optional, default: info] logging level for this command invocation.
Notes:
- This flag affects only the console output. The log messages will be written to the log file in any case.
- TRACE prints all messages including debug trace.
- DEBUG is the same as INFO
- WARN flag is not supported and is the same as INFO
- ERROR prints only errors but will not output the debug trace
- FATAL is the same as ERROR

Run the SFDMU to modify the target org data 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's quite correct 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 Tool as a standalone NodeJs application. Meaning, that in order to run the migration job you don't have to link the Plugin to the sfdx platform.

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 

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

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 Sa Oct 2022