Running.

Table of Contents



Simplest Way to Run the SFDMU ⇧

  • Navigate to the directory containing your export.json file.
  • Execute the following command to perform a direct migration between source and target Salesforce orgs:
$ sf sfdmu run --sourceusername source@name.com --targetusername target@name.com
  • Use this command to import data from CSV files:
$ sf sfdmu run --sourceusername csvfile --targetusername target@name.com
  • Use this command to export data into CSV files:
$ sf sfdmu run --sourceusername source@name.com --targetusername csvfile
Notes:
  • When importing or exporting from/to CSV files, ensure that the files are located in the directory containing the export.json file. The files should be named according to the API name of the respective sObject in your export.json, for example: Account.csv, Contact.csv.
    This naming convention helps in accurately mapping the data to the correct sObjects during the import or export process.

Complete Guide to Running the SFDMU ⇧

Run the SFDMU as an SFDX Plugin ⇧

The quickest way to run the SFDMU is using the sf sfdmu run CLI command, as previously explained.

Below you will find the complete details 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] [--usesf <string>] [--logfullquery] [-u <string>] [--apiversion <string>] [--verbose] [--concise] [--quiet] [--json] [--loglevel <string>]

Available CLI Command flags ⇧

--apiversion [float as string]: Optionally, this flag can override the apiVersion specified in export.json. For instance:

  • Setting it to "60.0" directly specifies the API version, allowing precise control over which version of the Salesforce API the migration will utilize.

--canmodify, -c: Allows silent modifications to the target production organization without preliminary user prompting. This is particularly relevant when the target environment is a production instance (e.g., prod-instance.my.salesforce.com), where the plugin will not request user approval for modifications, thereby streamlining processes. If not set, the user will be prompted to prevent accidental destruction of critical production data. This flag is ignored if the target is not a production Salesforce instance.

--concise: Reduces the verbosity of standard output (stdout), displaying only key messages to streamline the information presented during command execution.

--filelog [number, 0 or 1], default 1: Controls file logging. A setting of 0 completely disables logging, while 1 (the default) enables it, creating a log file for each command executed, facilitating detailed record-keeping of the migration process.

--json: Outputs formatted JSON instead of plain text following command execution. The JSON is both written into a log file and printed in stdout. This output can be suppressed in stdout by the --quiet or --silent flags, but it will still be recorded in the log file, making the logs accessible for further analysis or troubleshooting.

--logfullquery: Enables the full output of all selected fields when querying Salesforce data with SOQL, as opposed to the default shortened version. This detailed output is useful for comprehensive data analysis and troubleshooting. The Plugin will still truncate the SOQL part after the FROM keyword if it exceeds a certain length, and this flag affects both stdout and file logs.

--loglevel, default TRACE: Sets the logging level for this command invocation, controlling the type of messages that are written into the log file. Levels available include:

  • TRACE logs all messages, including stack traces in case of an unhandled exception.
  • DEBUG is the same as INFO.
  • WARN logs only warning messages.
  • ERROR logs only exception messages but does not output stack traces.
  • FATAL is the same as ERROR. This flag allows for detailed control over the verbosity of file logs, independent of stdout settings.

--noprompt, -n: Suppresses user prompts for inputs or confirmations, allowing the command to proceed using default settings. This is especially useful in situations where missing lookup references are detected in object records, preventing interruptions during the migration process.

--nowarnings: Suppresses warning messages in stdout, providing a cleaner and less cluttered output, which can be essential during large-scale migrations where numerous warnings might clutter the view.

--path, -p [directory]: Specifies the directory containing the export.json. If this flag is not provided, the plugin searches the current directory, ensuring that the migration configuration is correctly located and utilized.

--quiet: Suppresses stdout logging while still logging to a file. This option is useful in environments where console output needs to be minimized, such as in automated scripts or where output verbosity could obscure important information.

--silent: Functionally equivalent to --quiet, this flag also suppresses stdout logging, ensuring quiet operation during migration tasks.

--usesf, default true: By default, or when set to 'true', this flag forces the Plugin to use the latest Salesforce CLI (sf-cli) commands instead of Salesforce DX CLI (sfdx-cli) commands for deprecated commands. This ensures the use of the most up-to-date and supported commands, enhancing compatibility and reducing the risk of deprecated functionality issues. If set to 'false', the Plugin will revert to using the older Salesforce DX CLI commands, which may be necessary in environments not yet compatible with the latest updates.

Notes:
  • For MacOS users: If you encounter permission issues, prepend your command with sudo, e.g., $ sudo sf sfdmu run --targetusername MYTARGET.

Run the SFDMU on One Org Only (One-Directional Mode) ⇧

In scenarios where no source org is available and you only need to modify certain records in

the target org, provide only the --targetusername. The target org will act as both source and target.

Records are compared using the specified external ID, but it's reasonable to use the Record Id field as an External ID key.

Run the SFDMU as a Standalone NodeJs Application ⇧

To run SFDMU as a standalone NodeJs application without linking it to the SFDX platform, follow these steps:

# Install Node dependencies
$ npm install

# Compile the source code (only once after cloning the repo)
$ npm run build

# Run SFDMU without debugging
$ ./sfdmu-run.cmd -- --sourceusername source@mail.com --targetusername target@mail.com

# To debug with VSCode, use the following command in VSCode's terminal
$ ./sfdmu-run-debug.cmd -- --sourceusername source@mail.com --targetusername target@mail.com
Notes:
  • It is necessary to install the Salesforce CLI (SF CLI) even if you are running the SFDMU as a standalone Node.js application.
  • After compilation, the JavaScript code can be found in the ./lib/ directory.
  • All SFDMU CLI flags must be used in their full format, for example, --targetusername instead of -u.

Run the SFDMU as a NodeJs Module ⇧

You can also run the plugin programmatically from custom TypeScript/JavaScript code. After compiling the source code as described, you can import the module as shown in the example below:

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

const args: IAppSfdmuRunModuleArgs = {
    argv: [
        "", // The first two elements should always be empty
        "",
        "--path",
        "C:\\PathToExportJson",
        "--sourceusername",
        "source@mymail.com",
        "--targetusername",
        "target@mymail.com",
        "--verbose"
    ]
};

const app = new AppSfdmuRunApp(args);
(async () => await app.runCommand())();
Notes:
  • Installation of the Salesforce CLI (SF CLI) is required even when you incorporate SFDMU as a Node.js module in your own application.
  • The argv array must contain the CLI flags in their full format.
Last updated on 23rd Apr 2024