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, io.Connect Themes, logging and more.

Schemas

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

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

⚠️ Note that a JSON schema for the logging configuration found in the logger.json file isn't available, as the io.Connect Desktop logging mechanism is based on log4js-node. The logging configuration provided in the logger.json file is identical to the log4js-node configuration as described in the log4js-node API documentation.

Location

System Configuration Files

All configuration files for io.Connect Desktop are located 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.

This folder also contains a gilding.json configuration file used for configuring the gilding executable file, which is a thin wrapper around the actual io.Connect Desktop executable. It can be used to define settings for fetching remote configurations for io.Connect Desktop or for defining custom environment variables.

App Definition Files

The <installation_location>/interop.io/io.Connect Desktop/Desktop/config/apps folder contains the definition files for the demo apps bundled with the io.Connect Desktop installer.

You can add your own app definition files in the <installation_location>/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO). This 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 at runtime, 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 using the system.json file.

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

It's also possible to define your own custom environment variables via the gilding.json configuration file of io.Connect Desktop, enabling you to use them throughout all other configuration files.

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 Set to the desktop directory for the current user (e.g., "C:\Users\<username>\Desktop").
DownloadsFolder Set to the downloads directory for the current user (e.g., "C:\Users\<username>\Downloads").
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").
HomeFolder Set to the profile directory for the current user (e.g., "C:\Users\<username>").

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": "%GDDIR%/my-data/UserData/%GLUE_ENV%-%GLUE_REGION%"
    }
}

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

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"
    }
}