SFDMU GUI Application.

This application assists in creating SFDMU plugin configuration files through its simple and intuitive UI.

Visit the Application repository at the following link:

SFDMU GUI App Application Repository

Table of Contents



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 org connections, configure SObjects and fields, and run the Plugin directly from the application.

Installation. ⇧

First installation on your device. ⇧

Installation on Windows. ⇧

The Application is built using the ElectronJs framework.

On Windows-based machines, Electron requires Python and VC++ components to be installed to run.

The optimal choice is to install Visual Studio Community for this purpose (if it's possible) or you can try to download and install windows-build-tools (npm install --global windows-build-tools) but in most cases it does not work correctly.

Thus, the installation requires additional prerequisites and becomes more complex compared to UNIX-based machines.

Below are the typical steps to install the Application.

In the majority of cases, Electron (and the application) starts working correctly after these steps are completed. However, exceptions may occur rarely. In such cases, we suggest referring to the developer forums to search for possible solutions.

Skip steps which are already done in your case.

# If you don't have Visual Studio installed yet, 
# install the free version of Visual Studio Community Edition 
# (only the VC++ Desktop Development components are required)
https://visualstudio.microsoft.com/vs/community/

# Install the latest Python (mark Add Python to PATH)
https://www.python.org/downloads/

# In the Console, install node-gyp
npm install --global node-gyp

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

# Go into the project directory.
cd SFDX-Data-Move-Utility-Desktop-App

# Install project dependencies
npm install

# Build the project (omit if you've downloaded a compiled verison of the application as described below)
npm run build

# Run the Application.
npm start

Installation on LINUX ⇧

Installation of the Application on LINUX machines is quite simple.

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

# Go into the project directory.
cd SFDX-Data-Move-Utility-Desktop-App

# Install project dependencies
npm install

# Build the project (omit if you've downloaded a compiled verison of the application as described below)
npm run build

# Run the Application.
npm start

# CAUTION!
# On Ubuntu you may encounter the following error:
# /home/.../node_modules/electron/dist/electron exited with signal SIGSEGV
# This indicates a segmentation fault when trying to run Electron, and may require additional troubleshooting.

Additional installations ⇧

Once you have already installed the Application on your device and ensured the Electron framework is functioning properly, subsequent upgrades and installations of the Application become much simpler and are consistent across all OS types.

To upgrade or install, open a Console or Terminal window and type the following commands:

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

# Go into the project directory.
cd SFDX-Data-Move-Utility-Desktop-App

# Install project dependencies
npm install

# Build the project
npm run build

# Run the Application.
npm start

Supported OS ⇧

  • Normally all major OS (Win, Mac OS, Linux) are supported.
  • For Windows it requires Windows 10 or later.
  • The application was successfully tested on Windows 10, Mac OS Ventura 3.5 and Ubuntu 22.04.3

Application versions ⇧

The latest major version of the Application is v4.X.X.

The Application's code has been thoroughly refactored, introducing several breaking changes compared to earlier 3.X.X versions.

If you have previously used the SFDMU GUI App, please review the list of improvements and breaking changes below before transitioning to version 4.

Improvements ⇧

  • Built on the latest version of the ElectronJs framework

  • Added detailed logging for enhanced bug detection.

  • Added automatic backup to prevent accidental loss of data.

  • Enhanced UI for better user interaction

  • Equipped with tools to manage all the latest parameters of the SFDMU export.json

  • Supports multiple object sets.

  • Ability to import a raw export.json file, which is parsed and converted to a configuration for further editing.

  • Augmented org metadata and script issue detection

  • Offers multilingual support and can be easily translated to any language

  • Supports multiple UI themes for personalized experience

  • Integrated with the SFDMU Help Center for contextual assistance

  • The Application can be configured using a dedicated section in the export.json file.

Breaking changes from Version 3.X.X ⇧

  • The local database file (db.json) now has a new format. As a result, configurations created for versions 3.X.X are no longer compatible as is from the Application interface. However, there’s no need to worry. You can easily import any export.json file created in the previous application version and continue editing it seamlessly.

    Caution! Since the new version is not compatible with the older db.json file, using it will cause the application to crash. We recommend archiving the old database file and removing it from the working directory before running the new version.

  • The Application no longer displays the login screen (prompting users to enter a username/password upon startup). Given that the application always runs only on the same client computer, this feature felt unnecessary. Instead, the new version introduces Workspaces, which can contain an unlimited number of export.json file configurations. Now, each Workspace in the new version acts similarly to a different user in the old version, each capable of holding multiple configurations and user settings.

Application configuration ⇧

The Application utilizes the appConfig section of the package.json file for setup and customization of application behavior.

Below are the parameters and their respective purposes.

package.json

{
    // ... Other settings

    "appConfig": {

        // The name of the folder to hold all application data: 
        //   database file, configuration files, migration data, etc. 
        "dataRoot": "SFDMU-GUI-APP-DATA",
        
        // 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-DATA"
        // Leave this field blank to let the Application use
        // the standard user Documents directory as appRoot.
        "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,
        
        // sfdmu:run command (reserved for further implementation)
        "sfdmuRunCommand": "sfdmu:run",
        
        // Name of the active UI theme.
        // To see available themes, list inner directories in ./themes.
        "theme": "cosmo"
  }
}

Project directory structure ⇧

Starting from version 4, the Application project boasts a clean and organized folder structure.

Distribution files ⇧

If you only need to run the compiled application without accessing the source code and without the need for compilation, you can download only these files and folders. Proceed with the installation steps as described above, omitting the build phase, and run the application.

This will allow you to use the application without dealing with the source code or the build process.

Below is the structure and descriptions for the distribution files of the application:

.
├── /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
├── LICENSE.md  		-> contains the license agreement for the application
├── README.md   		-> provides information and instructions about the application
├── CODE_OF_CONDUCT.md	-> outlines expected behavior and consequences for violations.
└── package.json 		-> manages project metadata and dependencies

Project source code ⇧

If you wish to debug the Application, it's necessary to download and use the entire release of the Project.

The src directory holds the organized source code, partitioned by purpose for improved modularity.

Below are instructions on how to debug the project.

Debugging ⇧

To debug the Application, proceed with the following steps:

  1. Install the Application source.
  2. Open the Application source folder in the developer IDE (for example, VSCode).
  3. Run the following command in the Terminal:
npm run debug

This command will compile the source code and initiate the debug session.

Note: You can set breakpoints directly in the source code when executing the Electron host context code. To debug the browser context code, use the client-side debugger available in the Developer Tools of the Chromium browser. These tools will be shown alongside the main view in the Application window when the application is running.

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
    ],

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

Last updated on 13th Nov 2023