Configuration

Overview

io.Connect Desktop is highly configurable. You can apply custom system-wide, as well as app-specific settings. Among the configurable features are system settings, app settings, io.Connect Windows, logging and more.

Schemas

The following JSON schemas describe the available options for configuring io.Connect Desktop:

The system configuration schema describes all global platform settings.
The io.Connect Gateway configuration schema describes the "gw" key in the system.json file which contains configuration for the io.Connect Gateway port and more, security, and more.
The app definition schema describes the available settings for defining interop-enabled apps.

9.0 Version Stream

If you are still using the io.Connect Desktop 9.0 version stream, see the following additional schemas:

The io.Connect Windows configuration schema describes the available settings for configuring the global behavior of io.Connect Windows.
The themes configuration schema describes the available settings for configuring the io.Connect themes when using classic groups.

⚠️ Note that a JSON schema for the gilding.json configuration file isn't available.

Location

System Configuration Files

The system.json file containing system-wide settings for io.Connect Desktop is located in the <installation_location>/config folder.

9.0 Version Stream

If you are still using the io.Connect Desktop 9.0 version stream, you can find all configuration files for io.Connect Desktop in the <installation_location>/interop.io/io.Connect Desktop/Desktop/config folder. There you can find the system.json file for system-wide settings, the stickywindows.json file for configuring the default behavior of io.Connect Windows, the themes.json file for configuring the io.Connect Desktop Themes, the channels.json file for configuring the io.Connect Channels, and the logger.json file for configuring the logging for io.Connect Desktop.

App Definition Files

The definitions of the io.Connect Desktop system and demo apps are located in the <installation_location>/config/apps folder.

You can add your own app definition files in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder on Windows and in the ~Library/Application Support/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder on macOS where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO). The /UserData folder is preserved between installations allowing you to keep your custom files in case you decide to upgrade or reinstall io.Connect Desktop.

⚠️ Note that the app definitions are monitored dynamically, which means that it isn't necessary to restart io.Connect Desktop when you modify an app definition. You can also define custom locations for the app definition stores and the /UserData folder via the system.json file.

9.0 Version Stream

If you are still using the io.Connect Desktop 9.0 version stream, you can find the definitions of the io.Connect Desktop system and demo apps in the <installation_location>/interop.io/io.Connect Desktop/Desktop/config/apps folder.

Environment Variables

io.Connect Desktop registers a set of environment variables which you can use in all properties of all configuration files that require a URL or a file path as a value.

⚠️ Note that when specifying URLs or file paths in the io.Connect Desktop configuration files, you can use both io.Connect environment variables and OS environment variables (such as %LocalAppData% on Windows).

ℹ️ For details on how to access environment variables programmatically from your interop-enabled apps, see the Capabilities > More > APIs > Environment Variables section.

Platform Variables

The following table lists the environment variables registered by io.Connect Desktop:

Environment Variable	Description
`DesktopFolder`	Points to the desktop directory for the current user (e.g., `"C:\Users\<username>\Desktop"`).
`DownloadsFolder`	Points to the downloads directory for the current user (e.g., `"C:\Users\<username>\Downloads"`).
`HomeFolder`	Points to the profile directory for the current user (e.g., `"C:\Users\<username>"`).
`IO_CD_APP_DATA_DIR`	Points to `%LocalAppData%` on Windows and to `~/Library/Application Support` on macOS. Available since io.Connect Desktop* 10.0.*
`IO_CD_ASSETS_DIR`	Points to the io.Connect Desktop `<installation_location>/assets` folder. Available since io.Connect Desktop* 10.0.*
`IO_CD_CONFIG_DIR`	Points to the io.Connect Desktop `<installation_location>/config` folder. Available since io.Connect Desktop* 10.0.*
`IO_CD_CRASH_DUMPS_DIR`	Points to the `%LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/crashes` folder on Windows and the `~Library/Application Support/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/crashes` folder on macOS where `<ENV>-<REG>` represents the environment and region of io.Connect Desktop (e.g., `DEMO-INTEROP.IO`). Available since io.Connect Desktop* 10.0.*
`IO_CD_ENV`	The environment in which io.Connect Desktop is running (e.g., `"DEMO"`). Available since io.Connect Desktop* 10.0.*
`IO_CD_LOGS_DIR`	Points to the `%LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/logs` folder on Windows and the `~Library/Application Support/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/logs` folder on macOS where `<ENV>-<REG>` represents the environment and region of io.Connect Desktop (e.g., `DEMO-INTEROP.IO`). Available since io.Connect Desktop* 10.0.*
`IO_CD_REGION`	The region in which io.Connect Desktop is running (e.g., `"INTEROP.IO"`). Available since io.Connect Desktop* 10.0.*
`IO_CD_ROOT_DIR`	Points to the root folder of io.Connect Desktop where the executable file is located. Available since io.Connect Desktop* 10.0.*
`IO_CD_USER_DATA_DIR`	Points to the `%LocalAppData%/interop.io/io.Connect Desktop/UserData` folder on Windows and the `~Library/Application Support/interop.io/io.Connect Desktop/UserData` folder on macOS. Available since io.Connect Desktop* 10.0.*

To use any of the environment variables in the io.Connect Desktop configuration files, wrap it with % symbols. The following example demonstrates using environment variables to specify a location for storing user-specific data per environment and region via the system.json system configuration file of io.Connect Desktop:

{
    "folders": {
        "userData": "%IO_CD_ROOT_DIR%/my-data/UserData/%IO_CD_ENV%-%IO_CD_REGION%"
    }
}

Currently, the following legacy environment variables are also supported. It's highly recommended to migrate to the environment variables introduced in io.Connect Desktop 10.0 as the legacy environment variables may be removed in a future version:

Environment Variable	Description
`GDDIR`	Set to the root directory where the io.Connect Desktop executable file is located (e.g., `"C:\Users\<username>\AppData\Local\interop.io\io.Connect Desktop\Desktop"`).
`GLUE_ENV`	Set to the environment in which io.Connect Desktop is running (e.g., `"DEMO"`).
`GLUE_REGION`	Set to the region in which io.Connect Desktop is running (e.g., `"INTEROP.IO"`).
`GLUE_USER_DATA`	Set to the location of the `/UserData` folder of io.Connect Desktop (e.g., `"C:\Users\<username>\AppData\Local\interop.io\io.Connect Desktop\UserData\DEMO-INTEROP.IO"`).

Available since io.Connect Desktop 9.7.1

For testing and PoC purposes, you can set the IO_CD_BASIC_AUTH_USERNAME and IO_CD_BASIC_AUTH_PASSWORD environment variables with default username and password to be used for authentication. If these variables are set, io.Connect Desktop will extract their values and pass them to the login screen displayed by the SSO app and to all interop-enabled apps that require basic authentication. The username and password fields will be prepopulated with the extracted values and the user will be automatically authenticated.

The following example demonstrates setting the IO_CD_BASIC_AUTH_USERNAME and IO_CD_BASIC_AUTH_PASSWORD environment variables for the io.Connect platform process:

set "IO_CD_BASIC_AUTH_USERNAME=my-username" && set "IO_CD_BASIC_AUTH_PASSWORD=my-password" && io-connect-desktop.exe

Custom Variables

⚠️ Note that this section is relevant only for the io.Connect Desktop 9.0 version stream. The described functionalities aren't currently available in the io.Connect Desktop 10.0 version stream, but are planned to be added to the system configuration settings in a future release.

The gilding.json configuration file of io.Connect Desktop allows you to define your own custom environment variables that will be registered by the platform on startup. These variables can be used throughout all other configuration files (e.g., in the system configuration or in app definitions).

To define a custom environment variable, use the "set" property of the "envVars" top-level key in the gilding.json file. It accepts an object with key/value pairs holding the names and the values of the environment variables to register.

The following example demonstrates registering environment variables that hold different app URLs for the different environments and regions in which the app will run:

{
    "envVars": {
        "set": {
            "MY_APP_PROD": "https://my-app.com",
            "MY_APP_DEV": "https://dev.my-app.com"
        }
    }
}

Using the custom environment variables in an app definition:

{
    "name":"my-app",
    "title":"My App",
    "icon": "https://%MY_APP_PROD%/icon.ico",
    "type": "window",
    "details":{
        "url":"%MY_APP_DEV%/index.html"
    }
}