SFDMU GUI Application.

Table of Contents



Overview ⇧

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

  • 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-11, Mac OS Ventura 3.5, and Ubuntu 22.04.3.

Installation ⇧

First Installation on Your Device ⇧

Installation on Windows ⇧

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

Skip steps which are already done in your case.

Step 1.

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/

Alternatively, you can install the windows-build-tools package using the following command:

npm install --global windows-build-tools

Step 2.

Install the latest Python (during the installation, mark "Add Python to PATH" when prompted): https://www.python.org/downloads/

Step 3.

Open the Command window and run the following commands:

# 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 version of the application as described below)
npm run build

# Run the Application.
npm start

Installation on LINUX ⇧

The 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 version of the application as described below)
npm run build

# Run the Application.
npm start

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

Upgrading ⇧

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:

# Go into the project directory where the repo is cloned and pull the latest changes
git pull

# Install project dependencies as they can be modified during the latest deploy
npm install

# Build the project
npm run build

# Run the Application.
npm start

Application Versions ⇧

The latest major version of the Application is Version 4.

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

Improvements in Version 4 ⇧

  • 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 a 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 ⇧

There is one breaking change compared to the previous version:

  • The App has transitioned from using user accounts to Workspaces. Consequently, the local database file (db.json) now adopts a new format. This means configurations created for versions 3.X.X are no longer directly compatible with the Application. However, there's no need for concern :) You can effortlessly import any export.json file generated in the previous application version and continue editing it seamlessly.

Other Changes from Version 3 ⇧

Version 4 of the App is built on a foundation very similar to that of the previous version, particularly in terms of UX/UI. Below are some points we suggest you pay attention to:

  • More informative warnings about configuration issues. To understand the issue, hover your mouse over the orange warning rectangle to view the tooltip.
  • You cannot proceed to the next step until all configuration issues in the current step are resolved.
  • Unlike the previous version, this version now supports multiple ObjectSets. Therefore, when you create a new configuration, also create a new ObjectSet and then start adding objects to it.
  • In this app, the configuration controls are grouped by functionality, which is why the CSV-FILE source/target option is removed from the connection step, as it's not relevant in this context. Therefore, to select a CSV file as the source/target, do this in the Preview step: simply switch to the Command Line Setup tab and select the data source and data target there.

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,
        
        // 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.

Notes:
  • 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 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.
Last updated on 23rd Apr 2024