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.

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 ⇧

--sourceusername, -s: ⇧

Optionally, this CLI flag specifies the username for the source Salesforce organization in a data migration process. It can override the sourceUsername setting in export.json. For example:

  • Using --sourceusername "source@example.com" sets the username for the source org, enabling the SFDMU tool to connect and interact with the specified Salesforce environment for data extraction.
  • Using --sourceusername csvfile sets CSV files as the data source, allowing to import data from CSV files instead of Salesforce organization.

--targetusername, -u: ⇧

This mandatory CLI flag specifies the username for the target Salesforce organization or sets the target to CSV files in a data migration process. It can override the targetUsername setting in export.json. For example:

  • Using --targetusername "target@example.com" sets the username for the target org, enabling the SFDMU tool to connect and interact with the specified Salesforce environment for data import.
  • Using --targetusername csvfile sets the data target to export into CSV files instead of a Salesforce organization, allowing data to be output in a structured file format for storage or further processing.

--apiversion: ⇧

Type: 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.

--filelog, -l: ⇧

Type: 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: ⇧

Type: String, 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, -w: ⇧

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: ⇧

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.

--verbose: ⇧

This CLI flag activates verbose logging for the SFDMU tool, providing detailed output about the migration process. It is useful for debugging and understanding the intricacies of how data is handled during the migration.

Enabling verbose mode helps users closely monitor and troubleshoot their data migrations, offering insights into the flow and any potential adjustments needed to optimize the process.

--concise: ⇧

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

--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: ⇧

Type: String, 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.

Example to set the SFDMU to operate using old-fashion SFDX-CLI: 

sf sfdmu run -s source@example.com -u target@example.com --usesf false

--simulation, -m: ⇧

This CLI flag enables a simulation mode in the SFDMU tool, allowing users to run a migration process without actually performing any data changes in the Salesforce organizations or files involved.

It is particularly useful for testing migration configurations and understanding the behavior of the tool under specific conditions before committing to a real operation.

--version, -v: ⇧

This CLI flag, when used with the SFDMU tool, displays the current installed version of the software.

Additional 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 1st May 2024