SFDMU GUI Application.

👉 The Application GitHub repository can be found here: SFDMU GUI App Application Repository

Table of Contents



Overview ⇧

The SFDMU GUI Application assists in creating SFDMU plugin configuration file (export.json) through its simple and intuitive UI.

When is SFDMU GUI Application Useful? ⇧

Beyond the basic setup, the export.json file contains numerous advanced properties useful for creating and executing intricate migration jobs. Consequently, in some situations, the JSON file may become lengthy and challenging to manually edit using standard Notepad.

With this Desktop Application, there’s no need for Notepad and Console. All tasks are performed visually, significantly simplifying migration job management. Effortlessly add or remove organization connections, configure SObjects and fields, and run the Plugin directly from the application.

Supported OS ⇧

The Application is built using the ElectronJS framework.

  • All major OS (Win, Mac OS, Linux) are supported.
  • For Windows, it requires Windows 10 or later.

Installation of the Release Version ⇧

Installing and running the release version of the SFDMU GUI App is a straightforward process.

This guide provides a step-by-step explanation of how to download and install the SFDMU GUI App from GitHub, suitable for users with minimal technical skills.

General Information ⇧

The SFDMU GUI App releases are generated using Electron Forge, with different makers tailored for each operating system:

  • For Windows, releases are created using Squirrel.Windows.
  • For macOS, releases are packaged using Zip.
  • For Linux, packages are available in deb and RPM formats.
  • Only the x64 CPU architecture is supported.

Prerequisites ⇧

Before installing and using the SFDMU GUI App, ensure you have installed the SF CLI.

Installation of Latest Release ⇧

The latest release can be found in the release branch of the SFDMU GUI App GitHub repository.

You can find the MD5 hash sums in the respective .md5 files located in the same repository folder as the setup file.

Step 1. Download ⇧

Download the latest release of the SFDMU GUI App for your operating system:

  • macOS: Access the zip installation file here: macOS x64 setup.
  • Linux (Debian-based systems): Access the deb installation file here: Debian x64 setup.
  • Linux (RPM-based systems): Access the rpm installation file here: RPM x64 setup.
  • Windows: Access the zip file containing the setup executable here: Windows x64 setup.

Step 2. Install ⇧

  1. Click on the file link provided for your operating system to navigate to the download page.
  2. Once on the page, use the download link located at the top right to download the file.
  3. Follow the steps specific to your operating system for installation the application as detailed in Step 4 below.

Installation of Specific Release ⇧

Step 1: Select the Release ⇧

  1. Go to the SFDMU GUI App Repository on GitHub and locate the Releases link in the sidebar.
  2. Click on Releases to view all available versions of the SFDMU GUI App. The latest version always appears at the top of the list.
  3. Select the release you want to install by clicking on the corresponding link to navigate to its page.

Step 2: Select the Release Tag ⇧

  1. On the release page, click on the version's tag (icon resembles a price tag) located at the top of the page. This action opens a page listing all files associated with that release.

Step 3: Download the Setup Files ⇧

In the code files view navigate to the specific subdirectories under dist/ and click Download File for the setup file appropriate for your OS:

  • macOS: Navigate to dist/darwin/x64/ and download the file, e.g., sfdmu-gui-app-darwin-x64-X.X.X.zip.
  • Linux (Debian-based systems): Go to dist/deb/x64/ and download sfdmu-gui-app_X.X.X_amd64.deb.
  • Linux (RPM-based systems): Go to dist/rpm/x64/ and download SFDMU-GUI-App-X.X.X-1.x86_64.rpm.
  • Windows: Go to dist/windows/x64/ and download the zip package, e.g., sfdmu-gui-app-X.X.X Setup.zip.

Step 4: Install the Application ⇧

  • macOS:
  1. Open your Downloads folder and find the .zip file.
  2. Double-click to extract it, revealing the sfdmu-gui-app.app file.
  3. Drag the application to your Applications folder.
  • Linux (Debian-based systems):
  1. Open a terminal.
  2. Navigate to the Downloads directory:
    cd ~/Downloads
  3. Install the package:
    sudo dpkg -i sfdmu-gui-app_X.X.X_amd64.deb
  • Linux (RPM-based systems):
  1. Open a terminal.
  2. Navigate to the Downloads directory:
    cd ~/Downloads
  3. Install the package:
    sudo rpm -i SFDMU-GUI-App-X.X.X-1.x86_64.rpm
  • Windows:
  1. Navigate to the folder where the .zip file was downloaded.
  2. Extract the contents.
  3. Run the file namedsfdmu-gui-app-X.X.X Setup.exe. The installer shows a loader with "SFDMU GUI App installation is in progress...".
  4. After installation, the app will automatically launch and create a new shortcut on your desktop and in the Start menu, typically under the folder "Salesforce.com, inc".

Running the Installed Application ⇧

  • macOS:

    1. Open a Terminal window.

    2. Execute the following command to run the application:

      /Applications/sfdmu-gui-app.app/Contents/MacOS/sfdmu-gui-app

  • Linux: For both Debian and RPM-based systems, search for SFDMU GUI App in your application menu and launch it.

  • Windows: After installation, the app typically starts automatically. For subsequent launches, find the SFDMU GUI App shortcut on your desktop or search for it in the Start menu under "Salesforce.com, inc".

Uninstallation and Upgrades ⇧

Uninstalling the App ⇧

  • macOS: Drag the app from the Applications folder to the Trash.
  • Linux (Debian-based): Use the command sudo apt-get remove sfdmu-gui-app.
  • Linux (RPM-based): Use the command sudo rpm -e SFDMU-GUI-App.
  • Windows: Go to Control Panel > Uninstall a program. Locate the SFDMU GUI App, right-click on it, and then select Uninstall.

Upgrading the App ⇧

When a new version is available, repeat the download and installation steps.

For Linux and Windows, the new installation will overwrite the previous version. For macOS, you may first need to delete the previous version from the Applications folder before installing the new one.

Installation of the Source Code ⇧

This guide details how to install the application's source code on various operating systems.

It is intended for developers who wish to modify the original source code or prefer to run the application directly from the source, bypassing the release setup process.

Prerequisites  ⇧

Ensure you have installed Node.Js, Git and SF CLI before using the source code of the SFDMU GUI App.

Installation on Windows ⇧

For Windows machines, installing Electron necessitates specific components like Python and Visual C++.

Step 1: Complete the following prerequisites: ⇧

  1. Visual Studio Community: Install only the Visual C++ Desktop Development components from the free version of Visual Studio Community Edition, if not already installed. Visual Studio Community Edition

    Alternatively, use npm to install windows-build-tools:

    npm install --global windows-build-tools

  2. Python: Download and install the latest version of Python, ensuring "Add Python to PATH" is selected during the installation process. Download Python

Step 2: Open the Command Prompt and install node-gyp globally: ⇧ 

npm install --global node-gyp

Step 3: Clone the repository: ⇧ 

git clone https://github.com/forcedotcom/SFDX-Data-Move-Utility-Desktop-App.git

Step 4: Navigate to the project directory: ⇧ 

cd SFDX-Data-Move-Utility-Desktop-App

Step 5: Install project dependencies: ⇧ 

npm install

Step 6: Optionally, build the project (omit if you have downloaded a pre-compiled version): ⇧ 

npm run build

Step 7: Run the application without debugging: ⇧ 

npm start
Notes:

Installation of the source code for Windows can be problematic due to version compatibility issues between VC++ build tools, Python, and Electron. If you encounter issues, please consult relevant forums for solutions.

Installation on macOS and Linux ⇧

Installation on macOS and Linux is straightforward and generally executes without issues.

Step 1. Clone the repository: ⇧ 

git clone https://github.com/forcedotcom/SFDX-Data-Move-Utility-Desktop-App.git

Step 2. Navigate to the project directory: ⇧ 

cd SFDX-Data-Move-Utility-Desktop-App

Step 3. Install project dependencies: ⇧ 

npm install

Step 4. Optionally, build the project (omit if you have downloaded a pre-compiled version): ⇧ 

npm run build

Step 5. Run the application: ⇧ 

npm start

Upgrading ⇧

Upgrading the application is streamlined once the initial installation is complete.

Step 1. Navigate to the project directory where the repository is cloned. ⇧

Step 2. Pull the latest changes: ⇧ 

git pull

Step 3. Install any updated project dependencies: ⇧ 

npm install

Step 4. Build the project: ⇧ 

npm run build

Step 5. Run the application: ⇧ 

npm start

Debugging ⇧

To debug the source code, it's necessary to have the entire source code cloned and installed locally.

Start the Debug Session ⇧

To start debugging the application, ensure the application's source code is installed as previously described, then execute the following command in a terminal window:

npm run debug

This command compiles the source code and initiates the debug session.

Notes:
  • You can set breakpoints directly in the source code to debug the Electron host context.
  • To debug the browser context code, use the client-side debugger available in the Developer Tools of the Chromium browser. These tools will be displayed alongside the main application view when the application is running in debug mode.

Application Configuration ⇧

The application utilizes the app-config.json file, located in the standard Documents folder (the exact location depends on the OS) under the "sfdmu-gui-app" directory.

This file is automatically generated when the application is launched for the first time on a device. Once created, the file remains unchanged unless manually modified to meet specific requirements.

Configuration File Description ⇧

The configuration file, app-config.json, contains several settings to customize the behavior of an application. Changes to this file will take effect after the application is restarted.

Configuration File Properties ⇧

Below is the default app-config.json file and detailed description of each property in the JSON configuration:

{
    "dataRoot": "sfdmu-gui-app",
    "appRoot": "",
    "databaseFilename": "db.json",
    "locales": [
        "en", "he", "ru", "es", "fr", "de", "it", "ar"
    ],
    "defaultLocale": "en",
    "fallbackLocale": "en",
    "backupOnApplicationStart": true,
    "backupEveryNMinutes": 5,
    "useSfCliCommands": true,
    "theme": "cosmo"
}

dataRoot ⇧

Specifies the name of the folder intended to hold all application data such as the database file, configuration files, migration data, etc. Default value is "sfdmu-gui-app".

appRoot ⇧

Indicates the full path to the dataRoot folder. If left blank, the application defaults to using the standard user Documents directory. Example paths are shown in the configuration for both specified and default settings.

databaseFilename ⇧

Defines the filename of the database file. This allows for the maintenance of multiple databases with different names within the same directory. The default filename is "db.json".

locales ⇧

Lists the available languages for the Application UI. Languages added here will be available from the next start of the application.

defaultLocale ⇧

Sets the default application locale upon the first start of the Application. Default is "en".

fallbackLocale ⇧

Specifies a fallback language to be used when certain texts are not translated in the current language. Default is "en".

backupOnApplicationStart ⇧

Enables automatic backup of the database file each time the Application starts. The backup is always created in the db_backup folder relative to the dataRoot.

backupEveryNMinutes ⇧

If greater than 0, this setting enables automatic backup of the database file at specified intervals, in minutes. A setting of 0 disables this feature. The backup files are named in the format: db-backup-yyyy-MM-dd-HH-mm-ss.json.

useSfCliCommands ⇧

Allows the application to use the latest @salesforce/cli commands instead of the deprecated sfdx-cli commands for running Salesforce DX from the command line. This setting is particularly useful for users transitioning to new CLI tools.

theme ⇧

Specifies the name of the active UI theme. To view available themes, users can list the directories within the ./themes folder. Default theme set is "cosmo".

Translation ⇧

The Application UI can easily be translated into any language.

Currently, the Application is shipped with translations in English, German, Spanish, French, Hebrew, Arabic, Russian, and Italian.

Translation is done in the standard i18n format using JSON files located in the ./i18n directory.

To translate the Application:

  1. Add a new file named [locale].json to the ./i18n directory, for example, to translate to Japanese, add ./i18n/ja.json.
  2. Translate all keys from the English version, which is the base language for the Application.

After the file is ready, add a new value to the array of locales in app-config.json file:

"locales": [
      "en",
      "he",
      "ru",
      "es",
      "fr",
      "de",
      "it",
      "ar",
      "ja"    // <- translated to Japanese
    ],
Notes:

  • You can add or change translation only for the Application running as a source code.

  • If you want to improve the existing translation or provide translation to other languages, please submit a PR. Your support is highly appreciated! :)

Theming ⇧

You can easily switch between UI themes, allowing you to customize the look and feel of the Application according to your own taste.

The application is supplied with 26 built-in themes.

To switch between themes, simply set the theme property in the app-config.json file to the desired UI theme.

To find the available theme names:

  1. Open the folder ./themes.
  2. Write one of the folder names from this folder as a theme name in the theme property.

The theme will be switched after the next application start.

Logging ⇧

  • The application provides comprehensive logs for all events, actions, and issues.
  • Logs are stored in the log subdirectory located at [appRoot]/[dataRoot]/logs. For example, based on the default configuration in app-config.json, the log files are located in the [Documents Folder]/sfdmu-gui-app/logs/.
  • The format for log filenames is: yyyy-MM-dd-HH.log.
  • Logs are automatically rotated and archived into zip files every two weeks to conserve disk space.
  • The log file includes detailed information on all application events, which is essential for debugging. When reporting issues about the GUI App, please attach these logs as they help in identifying and resolving bugs. Before submitting, ensure that all sensitive information has been removed from the log files.

Backup ⇧

  • The Application conducts automatic database file backups. Backups are performed silently in the background and are consistently stored in the db_backup folder relative to the dataRoot folder.
  • Adjust backupEveryNMinutes in app-config.json to set the backup interval. A setting of 5 triggers backups every 5 minutes.
  • Backups are saved in the format db-backup-yyyy-MM-dd-HH-mm-ss.json.
  • Set backupEveryNMinutes to 0 to disable automatic backups.
  • Enable backupOnApplicationStart for backups at each application start.

Additional Notes ⇧

  • The final selection of the data source and target, including the option to use CSV files as either, should not be made during the Connection step but rather during the Preview step. Simply click on the "Command Line Setup" tab on the Preview page and use the dropdown selectors to choose your desired data source and target.
    Contrastingly, the Connection step allows you to select only Salesforce orgs, enabling you to set up the export.json configuration based on the metadata available in these organizations.

  • Since the release version of the SFDMU GUI App is stored in the Git repository using LFS, simply downloading the .zip or tar.gz files attached to the release is insufficient.
    Instead, you must download the appropriate setup file directly from the tagged codebase as described above.

  • Starting with v4.4.4, the application will use a dedicated configuration file, app-config.json, located in the Documents/sfdmu-gui-app folder. If you have customized settings in the export.json file (which held application settings in previous versions), please manually transfer the appConfig section to app-config.json after the first run of version 4.4.4 or later, when the default version of this file is created.

Last updated on 24th May 2024