SFDMU GUI Application.

Table of Contents



Overview ⇧

The SFDMU GUI Application assists in creating SFDMU plugin configuration files through its simple and intuitive UI.

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

When is this 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 of the SFDMU GUI App ⇧

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

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.

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.

Prerequisites ⇧

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

Step 1: Select the Release ⇧

All releases can be found in the "release" branch of the SFDMU GUI App GitHub repository.

  1. Go to the SFDMU GUI App repository page 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): ⇧

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

  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 ⇧

  • Find sfdmu-gui-app.app in your Applications folder and double-click to open.

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.

Managing of The Application Source Code ⇧

This guide outlines the steps to install the source code of the application across various operating systems. It is primarily intended for developers who wish to modify the original source code.

Prerequisites ⇧

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

Installation on Windows ⇧

On Windows-based machines, Electron requires Python and Visual C++ components to run.

Prerequisites ⇧

  1. Visual Studio Community: If you don't have it installed, download and install the free version of Visual Studio Community Edition. Only the Visual C++ Desktop Development components are required. Visual Studio Community Edition

    Alternatively, you can install the windows-build-tools via npm:

    npm install --global windows-build-tools

  2. Python: Install the latest version of Python and ensure to mark "Add Python to PATH" during installation. Download Python

Installation Steps ⇧

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

npm install --global node-gyp

Step 2: Clone the repository:

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

Step 3: Navigate to the project directory:

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

Step 4: Install project dependencies:

npm install

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

npm run build

Step 6: Run the application without debugging:

npm start

Note: Installation 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.

Installation Steps ⇧

  1. Clone the repository:

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

  2. Navigate to the project directory:

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

  3. Install project dependencies:

    npm install

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

    npm run build

  5. Run the application:

    npm start

Upgrading ⇧

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

Upgrade Steps ⇧

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

  2. Pull the latest changes:

    git pull

  3. Install any updated project dependencies:

    npm install

  4. Build the project:

    npm run build

  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.

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.

Compiled JavaScript Files ⇧

Below is the structure and descriptions of the compiled JavaScript files of the application. These files are the minimal set required to run the application without needing to compile the source TypeScript code.

.
├── /css                -> contains CSS files for styling the application UI
├── /i18n               -> holds files for translating the UI into different languages
├── /js                 -> contains compiled application files
├── /libs               -> holds library files the application depends on
├── /themes             -> contains themes for customizing the application's appearance
├── /views              -> holds view templates or components for the application
├── about.html          -> contains information about the application
├── index.html          -> main HTML file, the entry point to the application
├── splash.html         -> used to create a splash screen for the application
└── package.json        -> manages project metadata and dependencies

Application Configuration and Usage ⇧

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 ⇧

Below are the default parameters along with their respective purposes. You can edit this file to alter the application's behavior. Changes will take effect after the application is restarted.

app-config.json

{
    "appConfig": {
        // The name of the folder to hold all application data: 
        // database file, configuration files, migration data, etc. 
        "dataRoot": "sfdmu-gui-app",
        
        // Full path to the dataRoot folder.
        // Example: if you set appRoot = "C:\\MyScripts",
        // the final path to app data will be:
        // "C:\\MyScripts\\sfdmu-gui-app"
        // Leave this field blank to let the Application use
        // the standard user Documents directory as appRoot.
        // So the final path to the app data will be:
        // [Documents Folder]\\sfdmu-gui-app
        "appRoot": "",
        
        // The filename of the database file.
        // Allows keeping multiple databases with different names in the same directory.
        "databaseFilename": "db.json",
        
        // Available languages for the Application UI.
        // Translate application texts (see help below) and add your preferred languages here.
        // These languages will be available upon the next application start.
        "locales": [
            "en", "he", "ru", "es", "fr", "de", "it", "ar"
        ],
        
        // Default application locale on the first start of the Application.
        "defaultLocale": "en",
        
        // Fallback language used when specific text is not translated in the current language.
        "fallbackLocale": "en",
        
        // Enable automatic backup of the latest database file on each Application start.
        // Backup is always created in the db_backup folder (relative to the folder specified by dataRoot).
        "backupOnApplicationStart": true,
        
        // If > 0, the application will backup the database file automatically every N minutes.
        // Backup is made silently in the background.
        // Backup file format: db-backup-yyyy-MM-dd-HH-mm-ss.json
        // Setting this parameter to 0 will disable the automatic backup feature.
        "backupEveryNMinutes": 5,
        
        // Use the latest @salesforce/cli instead of the deprecated sfdx-cli
        // for running Salesforce DX using the command line.
        // Example: To get a list of available locally SFDX orgs, it will use the command:
        // "sf org list" instead of "sfdx force:org:list".
        "useSfCliCommands": true,
        
        // Name of the active UI theme.
        // To see available themes, list inner directories in ./themes.
        "theme": "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 the appConfig section:

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

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 appConfig section 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 detailed logs for all events, actions, and issues.
  • Logs are stored in the log subdirectory within the specified dataRoot folder.
  • Logs are automatically rotated and archived every two weeks to maintain organization.

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

  • Within the application, each step of the migration wizard requires that all configuration issues be resolved before moving to the next step. To identify a configuration issue, hover your mouse over the orange warning rectangle to view the tooltip.

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

Last updated on 27th Apr 2024