Seed Project

Available since io.Connect Desktop 10.0.4

io.Connect Desktop supports executing custom install and uninstall tasks via command-line triggers, allowing automated execution of scripts and commands during installation and uninstallation processes on both Windows and macOS.

Tasks can copy configuration, register protocols, download resources, clean up data, or back up preferences as part of installation and uninstallation.

On Windows, Squirrel passes installation and uninstallation arguments to the platform automatically. For other deployment methods, including a macOS DMG, invoke the manual triggers from your installation or removal process.

The following command-line arguments trigger task execution:

The --post-install and --pre-uninstall flags can be used if you aren't using a Squirrel-based installer or if you want to manually test the install tasks.

⚠️ Note that on Windows, Squirrel executes the install tasks after the initial installation and again after every update. Write install tasks that can run repeatedly without side effects (e.g., check whether a resource exists before creating it).

To trigger the install tasks manually on Windows, execute:

io-connect-desktop.exe --post-install

To trigger the install tasks manually on macOS, execute:

open -a "io.Connect Desktop" --args --post-install

Install and uninstall tasks are defined in platform-specific JSON configuration files within the /install folder:

• tasks.win32.json defines Windows tasks.
• tasks.darwin.json defines macOS tasks.

The files are read from <installation_location>/install on both operating systems. The <installation_location> placeholder represents the executable folder on Windows and the app bundle Contents folder on macOS.

To add install tasks to your seed project, create the task files in the /modifications/build/iocd/install directory:

modifications/
└── build/
    └── iocd/
        └── install/
            ├── tasks.win32.json  (Windows)
            └── tasks.darwin.json (macOS)

This ensures that the task files are included in your production build.

The task files follow this structure:

{
    "installTasks": [
        {
            "type": "run",
            "args": {
                "filename": "path/to/executable",
                "args": "command line arguments",
                "dir": "working/directory",
                "hide": true,
                "unattended": false,
                "exitCode0": "success",
                "exitCode1": "Custom error message",
                "exitCodeN": "success"
            }
        }
    ],
    "uninstallTasks": [
        {
            "type": "run",
            "args": { /* same structure */ }
        }
    ]
}

Each task has "type": "run" and an "args" object. The "installTasks" and "uninstallTasks" arrays contain the tasks for the corresponding operation.

The "args" object has the following properties:

⚠️ Note that tasks execute sequentially in the order defined. If a task fails with an exit code that isn't mapped to success, execution will stop and subsequent tasks won't run.

Windows Batch Script

The following example demonstrates how to run installation and cleanup scripts on Windows. Place the scripts beside tasks.win32.json in the packaged /install folder:

{
    "installTasks": [
        {
            "type": "run",
            "args": {
                "filename": "cmd.exe",
                "args": "/c copy-resources.bat",
                "hide": true,
                "exitCode0": "success",
                "exitCode1": "Error copying resources."
            }
        }
    ],
    "uninstallTasks": [
        {
            "type": "run",
            "args": {
                "filename": "cmd.exe",
                "args": "/c cleanup.bat",
                "hide": true
            }
        }
    ]
}

macOS Shell Script

The following example demonstrates how to run shell scripts on macOS. Place setup.sh in the packaged /install folder. In this example, cleanup.sh must be available in the explicitly selected /tmp working directory:

{
    "installTasks": [
        {
            "type": "run",
            "args": {
                "filename": "/bin/bash",
                "args": "setup.sh --silent",
                "hide": false
            }
        }
    ],
    "uninstallTasks": [
        {
            "type": "run",
            "args": {
                "filename": "/bin/bash",
                "args": "cleanup.sh",
                "dir": "/tmp"
            }
        }
    ]
}

Custom Exit Code Mapping

You can map specific exit codes to success or custom error messages:

{
    "installTasks": [
        {
            "type": "run",
            "args": {
                "filename": "installer.exe",
                "args": "--verify",
                "exitCode0": "success",
                "exitCode1": "Error validating the installation.",
                "exitCode2": "Error contacting server.",
                "exitCode3": "success",
                "exitCode4": "Network timeout - please retry."
            }
        }
    ]
}

In this example:

• Exit codes 0 and 3 are considered successful.
• Exit codes 1, 2, and 4 will show custom error messages.
• Any other exit code will show a default error message.

The "filename", "args", and "dir" properties support environment variable expansion using the %VAR% syntax. The following Windows example demonstrates paths in a task "args" object:

{
    "args": {
        "filename": "%APPDATA%\\MyCompany\\install-script.bat",
        "dir": "%LOCALAPPDATA%\\MyCompany"
    }
}

Platform Variables

The following environment variables are automatically set by io.Connect Desktop and available for use in all install tasks:

Tasks Not Executing

• Verify that the install/tasks.win32.json (Windows) or install/tasks.darwin.json (macOS) file exists in the correct location.
• Check that the file contains valid JSON.
• Ensure the executable paths are correct and accessible.

Failed Tasks

• Review the install log or the console output for error messages.
• Test the script manually to verify it works.
• Check file permissions (especially on macOS - scripts need execute permission).
• Verify environment variables are correctly expanded.

Silent Installation Failures

• Ensure all tasks have "unattended": true to prevent error dialogs.
• Test each task individually to identify which one is failing.
• Consider adding custom exit code mappings for expected error conditions.

Install Log

Available since io.Connect Desktop 10.4

io.Connect Desktop records the execution of install and uninstall tasks, including the task environment and the output and exit code of each task, in an install.log file:

• On Windows, in %LocalAppData%/interop.io/io.Connect Desktop/UserData/install/install.log.
• On macOS, in ~/Library/Application Support/interop.io/io.Connect Desktop/UserData/install/install.log.

The location doesn't depend on the product name or the configured user data folder.