How to...

Most tasks for customizing io.Connect Desktop can be accomplished by using the extensibility features of the io.Connect installer app. Whether it's changing the interface and behavior of the installer, modifying io.Connect components, substituting default with custom configurations, creating shortcuts, or adding custom resources like icons, splash screen, loaders and more, the installer app offers ways for automating almost all customization processes.

The basic premise of the installer extensibility mode is to repackage the stock io.Connect installer app into a new executable file together with your custom configurations and resources. To accomplish this, you must use the provided basic setup for creating a repackaged installer. Some customizations can be achieved by modifying the extensibility configuration file for the repackaged installer, while others require you to directly modify or replace resources in the provided basic setup.

For descriptions of the files contained in the basic setup and details on how to use it, see the Extensibility Installer Example section.

Extensibility Configuration File

The extensibility features of the io.Connect installer are controlled by an extensibility configuration file. It defines a number of extensibility points, representing stages of the installation flow, each of which can be populated with one or more extensibility items, representing tasks to perform or settings to change.

⚠️ Note that you can also use a limited number of command line arguments with which to control the installation or uninstallation processes. For more details, see the Command Line Arguments section.

The extensibility points and items are listed in the extensibility file using the following structure:

{
    "<extensibility point 1>": [
        {
            "type": "<extensibility item type>",
            "args": {
                "<arg>": <value>,
                ...
            }
        },
        ...
    ],
    "<extensibility point 2>": [
        {
            "type": "<extensibility item type>",
            "args": {
                "<arg>": <value>,
                ...
            }
        },
        ...
    ],
    ...
}

In case of no arguments, an extensibility item can be shortened to just a string with its type:

{
    "startup": [
        {
            "type": "unattended",
            "args": {}
        }
    ]
}

// Can be shortened to:
{
    "startup": [
        "unattended"
    ]
}

All extensibility points are arrays. The table below lists all available extensibility points and the extensibility item types applicable to them:

For a basic extensibility file setup and an example on how to use it to modify the io.Connect installer, see the Extensible Installer Example section.

⚠️ Note that you can also instruct the installer to delete itself after successful installation or uninstallation by using the /deleteself command line argument. Also note that /deleteself can't be specified as an extensibility item in the extensibility configuration file - it can only be used as a command line argument. For all available command line arguments, see the Command Line Arguments section.

Extensibility Points & Items

Each extensibility point represents a stage in the installation or the uninstallation process. Extensibility points are configured using the extensibility items applicable to them.

This section lists all available extensibility points and the extensibility items applicable to them.

⚠️ Note that the "run" and "message" extensibility items can be used in every extensibility point to run a custom script or show a message to the user.

Extensibility Point: "startup"

The "startup" extensibility point accepts the following items:

• "uninstall"

Use to uninstall the product. The installer will start directly from the Uninstall screen.

See also the Uninstallation section.

• "unattended"

Provides a continuous, uninterrupted installation process from the moment the installer is started until the installation succeeds or fails. The user won't be asked to take any action. The installation process can't be completed while certain apps are running - e.g., io.Connect Desktop, or Excel/Word/Outlook, unless the corresponding Application Adapter has been disabled in the "artifacts" extensibility point. By default, an unattended installation will exit with a non-zero exit code when it encounters conflicts, but you can specify options for conflict handling.

See also the Non-Interactive Installation section.

• "hidden"

Provides the same functionality as "unattended", except that the installer is hidden.

• "license"

Use this item to specify a custom license file.

• "logo"

Use this item to specify a custom logo for the installer.

• "banner"

Use this item to specify a custom banner for the installer.

The following is an example configuration for the "startup" extensibility point demonstrating how to supply custom license, logo and banner files:

{
    "startup": [
        // Use a predefined license file.
        {
            "type": "license",
            "args": {
                // Either a path or a URL.
                "file": "license.json"
            }
        },

        // Logo to display in the top-left corner.
        {
            "type": "logo",
            "args": {
                // Either a path or a URL.
                "url": "https://example.com/logo.png",
                // URL to open when the user clicks on the logo.
                "onClick": "https://example.com"
            }
        },

        // Banner during installation.
        {
            "type": "banner",
            "args": {
                // Either a path or a URL.
                "file": "banner.png",
                // URL to open when the user clicks on the banner.
                "onClick": "https://example.com"
            }
        }
    ]
}

Extensibility Point: "styles"

The "style" extensibility point accepts the following items:

• "color"

Use this item to set the color for various components of the installer UI.

See also the Color Scheme section.

Extensibility Point: "context"

The "context" extensibility point accepts the following items:

• "setValue"

Use this item to set various miscellaneous values for installer screen titles, URLs, text, the product name, installation location and more.

For example usage of the "context" extensibility point, see the Installer UI section.

Extensibility Point: "artifacts"

The "artifacts" extensibility point accepts the names of the io.Connect Desktop Artifacts as item types. Each item type can have the following arguments:

The following is an example configuration for the "artifacts" extensibility point demonstrating how to disable the installation of the io.Connect Excel Adapter:

{
    "artifacts": [
        {
            "type": "ExcelV1",
            "args": {
                "remove": true
            }
        }
    ]
}

For a list of the available io.Connect Artifacts, see the Artifacts section.

Extensibility Point: "shortcuts"

The "shortcuts" extensibility point accepts the following items:

• "shortcut"

Use this item to modify or remove predefined shortcuts for io.Connect Artifacts and also create brand new ones.

See also the Shortcuts section.

Extensibility Points: "welcome", "downloadProgress", "packages", "previewAndConfirm", "uninstall"

All these extensibility points represent screens of the installation process and you can use "run" items in them to execute external scripts, or "message" items to show messages to the user.

The following is an example configuration for the "welcome" extensibility point demonstrating how to run a script:

{
    "welcome": [
        {
            // Depending on your purpose, you may run scripts here,
            // or after the installation, in the "done" extensibility point.
            "type": "run",
            "args": {
                // Name of the program to run.
                "filename": "cmd.exe",
                // Command line arguments for the program execution.
                "args": "/c copy-resources.bat",
                // By default, "exitCode0" is success, while any other is an error message, followed by the installer exiting.
                // You can override any code with "success" for success and any other string for an error message.
                // Error messages aren't shown during unattended or hidden installations to avoid stalling.
                "exitCode1": "Error validating the installation.",
                "exitCode2": "Error contacting server.",
                "exitCode3": "success",
                //Other exit codes.

                // Hide the started process.
                "hide": true,

                // Don't hide the installer while the process is running.
                "hideInstaller": false
            }
        }
    ]

    // Other screens: "downloadProgress", "packages", "previewAndConfirm", "uninstall".
}

Extensibility Point: "finalizing"

The "finalizing" extensibility point accepts the following items:

• "gdConfig"

Use this item to supply custom configuration files for io.Connect Desktop.

See also the Overriding Configurations section.

Extensibility Point: "done"

The "done" extensibility point accepts the following items:

• "launchGD"

Use this item to automatically launch io.Connect Desktop after the installation has completed.

See also the Launching section.

• "showGD"

Use this item to automatically open the folder containing the io.Connect Desktop executable file after the installation has completed.

See also the Launching section.

• "exit"

Use this item to exit the installation process with a specified exit code.

See also the Exiting the Installer section.

Extensibility Item: "run"

Executes an external program and waits for it to finish.

Extensibility Item: "message"

Shows a message to the user.

Command Line Arguments

You can pass command line arguments directly to the installer to control the installation or the uninstallation process. Command line arguments can also be combined with using an extensibility configuration file. Most command line arguments are also available as extensibility items.

The following example demonstrates how to instruct the installer to initiate an unattended installation, provide a client key, and specify an extensibility configuration file by using command line arguments:

io-connect-desktop.exe /unattended /clientKey:myValidClientKey /ext:extensibility.json

The following command line arguments are available:

Online & Offline Installers

io.Connect Desktop provides two types of installers: online and offline (or "embedded"). They are identical in functionality, but the online installer downloads the necessary io.Connect Artifacts from the io.Connect CDN, while the embedded installer contains them all as resources. The advantage of this is that the online installer is much smaller, but requires a connection to the Internet and permission to download files. If you encounter networking or permission issues, try the offline installer.

Both types of installer can be used interchangeably to create online and offline repackaged installers respectively. In fact, you could repackage both and let your deployment team or users decide which one to use.

The following sections describe how to customize various elements of the installer UI. As explained in previous sections, some customizations can be achieved by modifying the extensibility configuration file for the repackaged installer, while others require you to directly modify or replace resources in the provided basic setup for creating a repackaged installer.

For descriptions of the files contained in the basic setup for creating a repackaged io.Connect installer and details on how to use it, see the Extensible Installer Example section.

Icon

To change the icon of the repackaged installer, replace the provided icon file in the extensible installer example keeping the file name the same.

Extraction Text

To change the title and text in the preliminary dialog of the repackaged installer, modify the Title and BeginPrompt arguments in the config.txt file of the extensible installer example:

Title="My Custom Installer"
BeginPrompt="Do you want to install My Custom Product?"

Product Name & Version

To change the product name displayed in the installer, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "ProductName",
                "value": "Custom Product"
            }
        }
    ]
}

See also Extensibility Point: "context".

To add a custom suffix to the product version, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "VersionSuffix",
                "value": "custom-suffix"
            }
        }
    ]
}

See also Extensibility Point: "context".

⚠️ Note that some deployment frameworks may determine the installation or update eligibility status of the installed products by checking the uninstall information (product name and version) inside the Windows registry. Using a custom product name and proper versioning when repackaging io.Connect Desktop can help avoid potential conflicts related to detecting that information. For instance, multiple users may install the product manually leading to the uninstallation information being written in the Windows registry hives of multiple users. This may cause interference with the software installation detection mechanism of the deployment framework. Using a custom product name for installations pushed centrally by a deployment framework will help avoid such conflicts. Using a properly incremented versioning suffix when you need to repackage the same version of io.Connect Desktop with custom artifacts that are often changed or updated will help avoid potential issues caused by duplicate versions detected by the deployment framework in the Windows registry.

Window Title

To change the title of the installer window, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "WindowName",
                "value": "My Custom Product Installer"
            }
        }
    ]
}

See also Extensibility Point: "context".

Screen Icon

To change the icon of the installer screen, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "Icon",
                "value": "icon.ico"
            }
        }
    ]
}

See also Extensibility Point: "context".

Logo

To change the logo in the top left of the installer screen, use the "startup" extensibility point:

{
    "startup": [
        {
            "type": "logo",
            "args": {
                "file": "logo.png",
                "onClick": "https://example.com"
            }
        }
    ]
}

See also Extensibility Point: "startup".

Color Scheme

To change the color of an installer component, use the "styles" extensibility point. Pass the name of the component and the desired color a hexadecimal value. The supported installer components are:

• "Background"
• "ButtonBackground"
• "Caret"
• "CheckboxDisabled"
• "ControlsDisabled"
• "DisabledColor"
• "Foreground"
• "Highlight"
• "Hyperlink"
• "ItemSelected"
• "LoginBoxBackground"
• "LoginBoxForeground"
• "TextBoxBackground"
• "TextBoxForeground"
• "TreeViewHover"
• "Warning"

The following is an example configuration for the "styles" extensibility point demonstrating how to change the background and foreground colors for the installer screens:

{
    "styles": [
        {
            "type": "color",
            "args": {
                "name": "Background",
                "value": "#000000"
            }
        },
        {
            "type": "color",
            "args": {
                "name": "Foreground",
                "value": "#ffffff"
            }
        }
    ]
}

See also Extensibility Point: "styles".

Welcome Screen Text

To change the text of the initial screen of the installer, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "WelcomeScreenParagraphs",
                "value": "My Custom Product"
            }
        }
    ]
}

See also Extensibility Point: "context".

Custom Install Button

To disable the "Custom Install" button in the installer, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "AllowCustomInstall",
                "value": false
            }
        }
    ]
}

See also Extensibility Point: "context".

Artifacts Screen

Title

To change the title displayed in the Artifacts screen, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "DownloadScreenTitle",
                "value": "Custom Screen Title"
            }
        }
    ]
}

Banner

To change the banner displayed in the Artifacts screen, use the "startup" extensibility point:

{
    "startup": [
        {
            "type": "banner",
            "args": {
                "file": "banner.png",
                "onClick": "https://example.com"
            }
        }
    ]
}

See also Extensibility Point: "context" and Extensibility Point: "startup".

Final Screen

Title

To change the title displayed in the Final screen, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "DoneScreenTitle",
                "value": "Custom Screen Title"
            }
        }
    ]
}

Text

To add additional text under the buttons in the Final screen, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "DoneScreenDetails",
                "value": "Custom Text"
            }
        }
    ]
}

To change the text size, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "DoneScreenDetailsFontSize",
                "value": 15
            }
        }
    ]
}

Documentation Link

To change the documentation link in the Final screen, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "DocumentationUrl",
                "value": "https://example.com"
            }
        }
    ]
}

Support Link

To change the support link in the Final screen, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "SupportEmailOrUrl",
                "value": "https://example.com"
            }
        }
    ]
}

See also Extensibility Point: "context".

Uninstall Screen

To change the title displayed in the Uninstall screen, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "UninstallScreenTitle",
                "value": "Custom Screen Title"
            }
        }
    ]
}

See also Extensibility Point: "context".

Location

To change the default installation location, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "Path",
                "value": "%ProgramFiles%/MyCustomProduct"
            }
        }
    ]
}

In an interactive installation, the user can select a custom path using the "Custom Install" button. To reference the final installation location in your custom scripts, use the %INSTALL_PATH% environment variable.

⚠️ Note that specific permission or filesystem virtualization setups may cause permission or performance issues if you try to install in a protected location, network drive, etc.

See also Extensibility Point: "context".

Non-Interactive Installation

The installation process can be unattended or hidden altogether. In unattended mode, no user interaction is necessary, but the installer screens are still visible. The hidden mode provides the same functionality as the unattended mode, except that the installer screens aren't visible. To run the installer in unattended or hidden mode, either run the executable file with the /unattended or /hidden command line arguments respectively, or specify the desired mode in the extensibility configuration file for the installer:

// Unattended installation.
{
    "startup": [
        "unattended"
    ]
}

// Hidden installation.
{
    "startup": [
        "hidden"
    ]
}

⚠️ Note that for unattended installations, you must provide your client key as described in Client Key. Also, your extensibility configuration file must be a valid JSON. Otherwise, the installer will enter interactive installation mode which may lead to the installation process waiting indefinitely for user input. To avoid this, you can use the /unattended command line argument in combination with your extensibility file, which will make sure that the installation process will enter non-interactive mode even in cases of an invalid JSON file.

By default, an unattended installation will exit with a non-zero exit code when it encounters conflicts, but you can specify options for conflict handling.

To show a message box for the user to dismiss, set the "conflictHandling" argument to "ask":

{
    "startup": [
        {
            "type": "hidden",
            "args": {
                // Show a message box to the user in case of conflicts.
                "conflictHandling": "ask"
            }
        }
    ]
}

⚠️ Note that using "ask" may stall the installation if no user is present.

To try resuming the installation a specified number of times at a specified interval, set the "conflictHandling" argument to "retry":

{
    "startup": [
        {
            "type": "hidden",
            "args": {
                // Try resuming the installation in case of conflicts.
                "conflictHandling": "retry",
                // Retry at an interval of 1000 ms.
                "waitMs": 1000,
                // Retry 10 times.
                "retries": 10
            }
        }
    ]
}

⚠️ Note that you can also instruct the installer to delete itself after successful installation by using the /deleteself command line argument. Also note that /deleteself can't be specified as an extensibility item in the extensibility configuration file - it can only be used as a command line argument. For all available command line arguments, see the Command Line Arguments section.

⚠️ Note that the installation process can't be completed while certain apps are running - e.g., io.Connect Desktop, or Excel/Word/Outlook, unless the corresponding Application Adapter has been disabled in the "artifacts" extensibility point.

See also Extensibility Point: "startup".

When uninstalling io.Connect Desktop, the following must be taken into account:

• The uninstallation process must be performed with the same user that was used for the installation process.
• If the installation was performed using an offline installer, it must be present or redeployed on the target machine to be able perform the uninstallation.
• If using the "unattended" or "hidden" option for the uninstallation, both the product and the associated user data will be removed. An option for preserving the user data is available only during an interactive uninstallation.
• If the installation was modified by using custom scripts to create files or shortcuts outside the installation directory, these won't be removed. To remove them, you can use the extensibility file to specify custom scripts to run during the uninstallation.

To instruct the installer to uninstall io.Connect Desktop, use the "startup" extensibility point and provide the "uninstall" extensibility item:

{
    "startup": [
        "uninstall"
    ]
}

During uninstall, you can also use all extensibility items described in the Non-Interactive Installation section. The following example demonstrates how to perform an unattended uninstall, specify options for conflict handling, and run a custom script during the Uninstall screen:

// Unattended uninstallation.
{
    "startup": [
        // Instruct the installer to uninstall the product.
        "uninstall",
        {
            "type": "unattended",
            "args": {
                // Try resuming the uninstallation in case of conflicts.
                "conflictHandling": "retry",
                // Retry at an interval of 1000 ms.
                "waitMs": 1000,
                // Retry 10 times.
                "retries": 10
            }
        }
    ],

    // Options for the Uninstall screen.
    "uninstall": [
        {
            "type": "run",
            "args": {
                "filename": "cmd.exe",
                "args": "/c delete-custom-resources.bat"
            }
        }
    ]
}

⚠️ Note that you can also instruct the installer to delete itself after successful uninstallation by using the /deleteself command line argument. Also note that /deleteself can't be specified as an extensibility item in the extensibility configuration file - it can only be used as a command line argument. For all available command line arguments, see the Command Line Arguments section.

See also Extensibility Point: "startup".

To create or modify shortcuts, use the "shortcuts" extensibility point. The following example demonstrates how to create three shortcuts: two shortcuts to the io.Connect Desktop executable file with command line arguments specifying override configurations for running io.Connect Desktop in different environments, and one shortcut to the official interop.io site. The two shortcuts to io.Connect Desktop will be created on the desktop and in the Windows Start Menu, and the icons for them will be copied from the repackaged installer to the folder containing the "Desktop" artifact. The shortcut to the interop.io site will be created only on the desktop and will use the logo.ico file located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/assets/images as its icon.

{
    "shortcuts": [
        {
            "type": "shortcut",
            "args": {
                "artifact": "Desktop",
                "icon": "copy:icon.ico",
                "filename": "My Custom Product DEV",
                "desktop": true,
                "startMenu": true,
                "description": "Start My Custom Product in DEV environment.",
                "targetArguments": "-- config=config/system.json configOverrides config0=config/system-override-DEV.json"
            }
        },
        {
            "type": "shortcut",
            "args": {
                "artifact": "Desktop",
                "icon": "copy:icon.ico",
                "filename": "My Custom Product UAT",
                "desktop": true,
                "startMenu": true,
                "description": "Start My Custom Product in UAT environment.",
                "targetArguments": "-- config=config/system.json configOverrides config0=config/system-override-UAT.json"
            }
        },
        {
            "type": "shortcut",
            "args": {
                "target": "https://interop.io",
                "filename": "interop.io Official Site",
                "description": "Open the interop.io official site",
                "icon": "io.Connect Desktop/Desktop/assets/images/logo.ico",
                "startMenu": false,
                "desktop": true
            }
        }
    ]
}

⚠️ Note that Windows Explorer sometimes fails to show the proper icon after packaging due to icon caching. If the installer icon seems not to be updated, select a different Explorer view (e.g., switch to "Details" or "Tiles") to see the updated icon.

See also Extensibility Point: "shortcuts".

To specify a custom name for the Windows Start Menu folder, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "StartMenuFolderName",
                "value": "Custom Folder Name"
            }
        }
    ]
}

To opt out of creating a Start Menu folder, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "CreateStartMenuEntries",
                "value": false
            }
        }
    ]
}

See also Extensibility Point: "context".

To change the publisher name displayed in the Control Panel "Uninstall or change a program" menu, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "UninstallPublisher",
                "value": "My Company Name"
            }
        }
    ]
}

To change the icon displayed in the Control Panel "Uninstall or change a program" menu, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "UninstallDisplayIcon",
                "value": "icon.ico"
            }
        }
    ]
}

See also Extensibility Point: "context".

The following is a list of the names of the available io.Connect Desktop Artifacts:

Required:

• "Desktop"

io.Connect SDKs:

• "ioJS"
• "ioOfficeJS"
• ".Net"
• "Java"
• "COMv1"
• "COMv2"

Application Adapters:

• "ExcelV1"
• "ExcelV2"
• "Word"
• "Outlook"
• "Fidessa"
• "Bloomberg"
• "BloombergV3"
• "BloombergBridgeV2MDFOnly"
• "SalesforceConnectorSandboxConfig"

Dev Tools:

• "DevToolsLauncher"
• "InteropViewer"
• "ContextViewer"
• "AppMonitor"
• "PerfReport"

io.Connect Demos:

• "EnterpriseDemos"
• "LocalDemos"

Other:

• "GTF"
• "GnsDesktopManager"

⚠️ Note that depending on your license for io.Connect Desktop, some of these artifacts may not be available in your installer.

To make an artifact required, to select it by the default, or to remove it from the installation, use the "artifacts" extensibility point. The following example demonstrates how to make the Excel Adapter required, how to remove the Word Adapter from the installation and how to select by default the Outlook Adapter:

{
    "artifacts": [
        {
            "type": "ExcelV1",
            "args": {
                "required": true
            }
        },
        {
            "type": "Word",
            "args": {
                "remove": true
            }
        },
        {
            "type": "Word",
            "args": {
                "checkedByDefault": true
            }
        }
    ]
}

See also Extensibility Point: "context".

To run a custom script at any installation stage, use the "run" extensibility item. The following example demonstrates how to run a script for copying custom resources after the installation has completed:

{
    "done": [
        {
            "type": "run",
            "args": {
                // Name of the program to run.
                "filename": "cmd.exe",
                // Command line arguments for the program execution.
                "args": "/c copy-resources.bat",
                // By default, "exitCode0" is success, while any other is an error message, followed by the installer exiting.
                // You can override any code with "success" for success and any other string for an error message.
                // Error messages aren't shown during unattended or hidden installations to avoid stalling.
                "exitCode1": "Error validating the installation.",
                "exitCode2": "Error contacting server.",
                "exitCode3": "success",
                //Other exit codes.

                // Hide the started process.
                "hide": true,

                // Don't hide the installer while the process is running.
                "hideInstaller": false
            }
        }
    ]
}

In an interactive installation, the user can select a custom path using the "Custom Install" button. To reference the final installation location in your custom scripts, use the %INSTALL_PATH% environment variable. The following example demonstrates how to copy an entire custom /splash directory to the respective /splash directory in the io.Connect Desktop installation folder (e.g., %LocalAppData%/interop.io/io.Connect Desktop/Desktop/assets/splash) using the xcopy command:

xcopy /E splash "%INSTALL_PATH%\io.Connect Desktop\Desktop\assets\splash"

See also Extensibility Item: "run".

To specify the client key received from the io.Connect support team, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "ClientKey",
                "value": "my-custom-client-key"
            }
        }
    ]
}

See also Extensibility Point: "context".

Overriding Configurations

To instruct the installer whether to delete all default system configuration files before writing your custom ones, or to delete only the ones you are replacing, use the "finalizing" extensibility point. The supplied custom configuration files must be in a ZIP archive (archive the files directly, don't place them in a containing folder). The following example demonstrates how to provide a ZIP file with custom configuration files and merge them with the default ones:

{
    "finalizing": [
        {
            "type": "gdConfig",
            "args": {
                "file": "custom-config.zip",
                // If `true`, all default system configuration files will be deleted before your custom files are written.
                // In this case, you must supply all necessary configuration files for io.Connect Desktop to function properly.
                "wipe": true
            }
        }
    ]
}

⚠️ Note that this can also be achieved by using the "run" extensibility item to execute your custom script for copying custom resources to the respective io.Connect Desktop folders. For more details, see the Custom Scripts section.

See also Extensibility Point: "finalizing".

Launching

After the installation has completed, you can instruct the installer to automatically launch io.Connect Desktop or open the folder containing the io.Connect Desktop executable file. You can also specify command line arguments when launching io.Connect Desktop.

The following example demonstrates how to automatically start io.Connect Desktop with specified command line arguments after installation by using the "context" and "done" extensibility points:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "LaunchGDArgs",
                "value": "command-line-arguments"
            }
        }
    ],

    "done": [
        "launchGD"
    ]
}

⚠️ Note that the specified command line arguments will be used even if you let the user decide whether to launch io.Connect Desktop after installation.

The following example demonstrates how to open the folder containing the io.Connect Desktop executable file after installation:

{
    "done": [
        "showGD"
    ]
}

See also Extensibility Point: "context" and Extensibility Point: "done".

Exiting the Installer

To instruct the installer to exit automatically after installation, use the "done" extensibility point:

{
    "done": [
        // Exit from the Final screen without the user having to click a button.
        {
            "type": "exit",
            "args": {
                "exitCode": 0
            }
        }
    ]
}

See also Extensibility Point: "done".

As a final step of preparing your custom installer, you have to sign the resulting executable with an Authenticode signing certificate. This is necessary to prevent Windows or antivirus software warnings.

This section will provide you with a basic setup for creating a custom repackaged installer and will give you a step-by-step example of how to use an extensibility configuration file to package custom resources and control the installation process.

Download the basic setup for a custom installer. Use it to test how the custom installer works, to tweak the setting, add your own files and, ultimately, create your own custom installer.

Basic Setup Files

The basic setup for creating a custom installer contains the following files and folders:

Guide

In this step-by-step guide you will be creating a custom io.Connect Desktop installer with the following additions and changes:

• adding custom logo, banner and icon for the installer screens;

• setting which io.Connect Artifacts to be required or removed during the installation;

• customizing the title and text of the installer windows;

• setting the foreground and background colors for the installer screens;

• creating a custom shortcut;

• installing io.Connect Desktop with a custom system configuration in order to setup io.Connect Desktop to retrieve app definitions from a REST service;

You must have a running REST service from which to retrieve app definitions. For testing purposes, you can use the Node.js REST Configuration Example.

• running a custom script that will copy a resource to an io.Connect Desktop folder after installation;

• showing a message to the user;

• opening the folder containing the io.Connect Desktop executable file after the installation has completed;

Follow these steps to create the customized installer:

1. Navigate to the directory where you have downloaded the sfx-installer-example.zip and extract the files in it.

2. Copy your io.Connect Desktop installer to the /custom-installer-files directory and rename it to io-connect-installer.exe.

You can download a trial version of io.Connect Desktop from here.

3. Custom logo, banner and icon

For convenience, the /custom-installer-files folder already contains example custom files for the installer logo, banner and icon, but you can replace them with your own files.

Open the extensibility.json file and in the "startup" extensibility point add the following configuration for the logo and the banner:

{
    "startup": [
        {
            "type": "logo",
            "args": {
                "file": "logo.png",
                "onClick": "https://example.com"
            }
        },
        {
            "type": "banner",
            "args": {
                "file": "banner.png",
                "onClick": "https://example.com"
            }
        }
    ]
}

Use the "onClick" property to specify a URL to open when the user clicks on the banner or the logo, or skip it if you don't want clicking on the banner or the logo to open a web page.

Go to the "context" extensibility point and add the following configuration for the icon:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "Icon",
                "value": "icon.ico"
            }
        }
    ]
}

4. Requiring and removing io.Connect artifacts

To make some of the io.Connect Artifacts required or to remove them from the installation, use the "artifacts" extensibility point. Add the following configuration to make the "ExcelV1" artifact required and remove the "Word" artifact from the installation:

{
    "artifacts": [
        {
            "type": "ExcelV1",
            "args": {
                "required": true
            }
        },
        {
            "type": "Word",
            "args": {
                "remove": true
            }
        }
    ]
}

To check that this configuration is in effect, click on the "Custom Install" button during the installation and look for the specified artifacts.

5. Changing the installation window title and text

To change the default installer window name and the text that is shown when installing the io.Connect components, use the "context" extensibility point:

{
    "context": [
        {
            "type": "setValue",
            "args": {
                "name": "WindowName",
                "value": "Custom io.Connect Installer"
            }
        },
        {
            "type": "setValue",
            "args": {
                "name": "DownloadScreenTitle",
                "value": "Installing components..."
            }
        }
    ]
}

6. Changing the colors of the installer screens

To change the foreground and background color of the installer screens, use the "styles" extensibility point. Add the following configuration to change the background color to black and the foreground color to white:

{
    "styles": [
        {
            "type": "color",
            "args": {
                "name": "Background",
                "value": "#000000"
            }
        },
        {
            "type": "color",
            "args": {
                "name": "Foreground",
                "value": "#ffffff"
            }
        }
    ]
}

7. Creating a custom shortcut

To define a custom shortcut to be created during installation, use the "shortcuts" extensibility point. Add the following configuration to create a shortcut to the official interop.io site on the desktop, but not in the Windows Start menu:

{
    "shortcuts": [
        {
            "type": "shortcut",
            "args": {
                "target": "https://interop.io",
                "filename": "interop.io Official Site",
                "description": "Open the interop.io official site",
                "icon": "io.Connect Desktop/Desktop/assets/images/icon.ico",
                "startMenu": false,
                "desktop": true
            }
        }
    ]
}

The shortcut will use the provided custom icon file for its icon. This icon file will be copied in a later step to the io.Connect Desktop folder specified here.

8. Custom system configuration file

Use the default system.json file of io.Connect Desktop located in the %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config folder as a basis for your custom system configuration. Get the system.json from a previous installation of io.Connect Desktop and modify the "appStores" top-level array to configure io.Connect Desktop to retrieve app definitions from a REST service:

{
    "appStores": [
        {
            "type": "rest",
            "details": {
                // URL to your remote app store.
                "url": "http://localhost:8004/apps/",
            }
        }
    ]
}

Archive the customized system.json file as a ZIP file named system.zip - archive the file directly, don't place it in a containing folder. Place the system.zip file in the /custom-installer-files folder.

Use the "finalizing" extensibility point to instruct the installer to replace the default system.json file of io.Connect Desktop with your custom one. The "wipe" property is set to false in order to prevent the installer from deleting all other necessary configuration files:

{
    "finalizing": [
        {
            "type": "gdConfig",
            "args": {
                "file": "system.zip",
                "wipe": false
            }
        }
    ]
}

9. Copying a custom resource

The custom icon.ico file must be copied to the %LocalAppData%/interop.io/io.Connect Desktop/Desktop/assets/images directory so that the previously created custom shortcut can use it as its icon. Use the "done" extensibility point to run the custom copy-resources.bat script after the installation has completed:

{
    "done": [
        {
            "type": "run",
            "args": {
                "filename": "cmd.exe",
                "args": "/c copy-resources.bat"
            }
        }
    ]
}

10. Showing a message to the user

To show a custom message for completed installation, use the "done" extensibility point:

{
    "done": [
        {
            "type": "message",
            "args": {
                "title": "Installation Completed",
                "text": "io.Connect Desktop installed successfully!"
            }
        }
    ]
}

11. Opening the folder containing the executable file

To instruct the installer to open the folder containing the io.Connect Desktop executable file, use the "done" extensibility point:

{
    "done": [
        "showGD"
    ]
}

12. Go back to the root folder and start the produce-sfx-installer.bat script to produce the repackaged installer file. The output installer is named sfx-installer.exe.

13. Run sfx-installer.exe to install the product and test the customizations.

⚠️ Note that the SFX installer should be Authenticode signed to prevent false alerts from Windows or antivirus software.