Configuration

The system configuration of io.Connect Desktop is located in the system.json file in the main configuration folder - %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config. This file allows you to alter system-wide settings for window behavior, app stores, Gateway settings and much more. In most cases, the default configuration settings should suffice.

For more details about the available system configuration properties, see the system configuration and the io.Connect Gateway configuration schemas.

See also the More Features & APIs section of the documentation, as many of the platform features are configured via the system.json file.

The logging configuration for io.Connect Desktop is found in the logger.json file located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config.

⚠️ Note that some of the globally defined properties in the system.json file may be overridden using the respective property definitions in the app definition files.

The following examples demonstrate some of the available system-level settings.

The io.Connect Gateway starts on port 8385 by default. In environments where multiple user sessions run on the same machine (e.g., running io.Connect Desktop as a Citrix Virtual App), using a predefined port won't work, as the first instance of io.Connect Desktop will occupy that port and all other instances won't be able to connect. To avoid this, the io.Connect Gateway can be configured from the "gw" top-level key in the system.json file to choose dynamically a free port on startup.

To configure the io.Connect Gateway to use a random free port, go to the "configuration" object under the "gw" top-level key and set its "port" property to 0:

{
    "gw": {
        "configuration": {
            "port": 0
        }
    }
}

For more details on the available configuration properties for the io.Connect Gateway, see the io.Connect Gateway configuration schema.

The io.Connect Gateway can be configured to take heap memory snapshots when the heap memory exceeds a predefined limit. You can also set limits for the maximum client connections to the io.Connect Gateway and a maximum size of messages sent by apps to the io.Connect Gateway. If the maximum message size is exceeded, a warning in the logs will be triggered, which can help you identify the responsible apps. Use the "memory" and "limits" properties of the "configuration" object under the "gw" top-level key to specify the desired settings.

The following is an example configuration:

{
    "gw": {
        "configuration": {
            "memory": {
                "report_interval": 300000,
                "max_backups": 5,
                "memory_limit": 1073741824,
                "dump_location": "%GLUE-USER-DATA%/heapsnapshots",
                "dump_prefix": "gw"
            },
            "limits": {
                "max_connections": 1000,
                "large_msg_threshold": 524288
            }
        }
    }
}

The "memory" object has the following properties:

The "limits" object has the following properties:

For more details on the available configuration properties for the io.Connect Gateway, see the io.Connect Gateway configuration schema.

To specify app stores with app definitions, use the "appStores" top-level key, which accepts an array of objects defining one or more app stores.

Local

To configure io.Connect Desktop to load app definition files from a local path, set the "type" property of the app store configuration object to "path" and specify a relative or an absolute path to the app definitions. The environment variables set by io.Connect Desktop can also be used as values:

{
    "appStores": [
        {
            "type": "path",
            "details": {
                "path": "./config/apps"
            }
        },
        {
            "type": "path",
            "details": {
                "path": "%GD3-APP-STORE%"
            }
        },
        {
            "type": "path",
            "details": {
                "path": "%GLUE-USER-DATA%/apps"
            }
        }
    ]
}

Each local path app store object has the following properties:

The "details" object for a local path app store has the following properties:

REST

App definitions can also be obtained from remote app stores via a REST service.

To configure a connection to the REST service providing the remote app store, add a new entry to the "appStores" top-level key and set its "type" to "rest":

{
    "appStores": [
        {
            "type": "rest",
            "details": {
                "url": "https://example.com/my-app-store/",
                "auth": "no-auth",
                "pollInterval": 30000,
                "enablePersistentCache": true,
                "cacheFolder": "%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%/configCache/"
            },
            "appDefinitionOverrides": {
                // Overrides for some top-level app definition properties.
                "ignoreSavedLayout": true,
                "allowMultiple": false,
                // Overrides for the properties under the `"details"` top-level key in apps of type `"window"`.
                "window": {
                    "autoInjectAPI": {
                        "enabled": true,
                        "autoInit": {
                            "channels": true
                        }
                    }
                }
            }
        }
    ]
}

Each remote app store object has the following properties:

The "details" object for a remote app store has the following properties:

The remote store must return app definitions in the following response shape:

{
    "applications": [
        // List of app definition objects.
        {}, {}
    ]
}

For details on working with remote app stores compliant with FDC3 App Directory standards, see the FDC3 Compliance section and the FDC3 App Directory documentation.

For a reference implementation of a remote app definitions store, see the Node.js REST Config example that implements the FDC3 App Directory and is compatible with io.Connect Desktop. This basic implementation doesn't take the user into account and returns the same set of data for all requests. For instructions on running the sample server on your machine, see the README file in the repository.

For a .NET implementation of a remote app definitions store, see the .NET REST Config example.

io.Manager

You can also use io.Manager for hosting and retrieving app stores. io.Manager is a complete server-side solution for providing data to io.Connect. To configure io.Connect Desktop to fetch app definitions from io.Manager, set the "type" property of the app store configuration object to "server":

{
    "appStores": [
        {
            "type": "server"
        }
    ]
}

The server app store object has the following properties:

If you are using only io.Manager for retrieving app definitions, you can set the "appStores" key to an empty array. io.Connect Desktop will automatically try to connect to io.Manager using its configuration, and will retrieve the app definitions from it, if any.

Besides the regular app stores that usually contain definitions for end user apps, you can define system app stores for critical apps that must be auto started with the platform. The system stores aren't monitored for changes and can be only of type "path" and "rest". To define a system app store, use the "systemAppStores" top-level key, which accepts an array of objects defining one or more system app stores.

The following example demonstrates how to configure a local system app store:

{
    "systemAppStores": [
        {
            "type": "path",
            "details": {
                "path": "./config/system-apps"
            }
        }
    ]
}

For details on how to set the priority of system apps, see the Configuration > Application > Boot Sequence section.

To provide settings for handling Layouts in io.Connect Desktop, use the "layouts" top-level key.

The "layouts" object has the following properties:

The "splash" object has the following properties:

The "store" object has the following properties:

Stores

To specify a Layout store with Layout definitions, use the "store" property of the "layouts" top-level key.

Local

By default, the Layouts are saved to and loaded from a local Layout store located in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/layouts folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO). There you can store, customize and delete your Layout files locally.

To instruct io.Connect Desktop to manage Layouts as local files, set the "type" property of the "store" object to "file":

{
    "layouts" : {
        "store": {
            "type": "file"
        }
    }
}

REST

To configure a connection to the REST service providing the Layout store, set the "type" property of the "store" object to "rest":

{
    "layouts": {
        "store": {
            "type": "rest",
            "restURL": "http://localhost:8004/",
            "restFetchInterval": 20,
            "restClientAuth": "no-auth"
        }
    }
}

The remote store must return Layout definitions in the following response shape:

{
    "layouts": [
        // List of Layout definition objects.
        {}, {}
    ]
}

For a reference implementation of a remote Layout definitions store, see the Node.js REST Config example. The user Layouts are stored in files with the same structure as local Layout files. This basic implementation doesn't take the user into account and returns the same set of data for all users. New Layouts are stored in files using the name of the Layout and there isn't validation for the name. The operation for removing a Layout isn't implemented and just logs to the console. For instructions on running the sample server on your machine, see the README file in the repository.

For a .NET implementation of a remote Layout definitions store, see the .NET REST Config example.

io.Manager

To configure io.Connect Desktop to fetch Layouts from io.Manager, set the "type" property of the "store" to "server":

{
    "layouts" : {
        "store": {
            "type": "server"
        }
    }
}

⚠️ Note that when using io.Manager as a Layout store, Layout files aren't only fetched from the server, but are also saved on the server (e.g., when the user edits and saves an existing Layout).

Default Global Layout

To disable automatic restore of the default Global Layout, set the "restoreDefaultGlobalOnStartup" property to false:

{
    "layouts": {
        "restoreDefaultGlobalOnStartup": false
    }
}

Loader

The default loader for Global Layouts is an HTML file located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/assets/loader which you can replace with your own custom one or edit it directly.

To customize the Layout loader, use the "splash" property of the "layouts" top-level key.

The following example demonstrates how to provide a custom loader and settings for it:

{
    "layouts": {
        "splash": {
            "url": "https://example.com/my-custom-loader/index.html",
            "title": "My Custom Loader",
            "width": 500,
            "height": 300
        }
    }
}

App preferences can be stored locally in a file, or remotely - using a REST service or io.Manager. By default, app preferences are stored locally in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/prefs folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO). To configure io.Connect Desktop where to store app preferences, use the "store" property of the "applicationPreferences" top-level key:

{
    "applicationPreferences": {
        "store": {
            "type": "rest",
            "restURL": "https://my-rest-service.com",
            "restClientAuth": "no-auth",
            "newDataCheckInterval": 2000
        }
    }
}

The "store" object has the following properties:

For a reference implementation of a remote app preferences store, see the Node.js REST Config example. This basic implementation doesn't take the user into account and returns the same set of data for all requests. For instructions on running the sample server on your machine, see the README file in the repository.

To customize the splash screen of io.Connect Desktop, use the "splash" top-level key.

The following example demonstrates how to provide a custom splash screen and settings for it:

{
    "splash": {
        "disabled": false,
        "url": "file://%GDDIR%/assets/custom/splash.html",
        "width": 350,
        "height": 233,
        "blockStartup": true
    }
}

The "splash" object has the following properties:

To specify global notification settings, use the "notifications" top-level key.

The following is an example configuration for notifications:

{
    "notifications": {
        "enabled": true,
        "enableToasts": true,
        "sourceFilter": {
            "allowed": ["*"]
        },
        "toastExpiry": 15000
    }
}

The "notifications" object has the following properties:

The "snooze" object has the following properties:

The "placement" object has the following properties:

The "sourceFilter" object has the following properties:

The "toasts" object has the following properties:

To configure the io.Connect dialogs, use the "dialogs" top-level key.

The following example demonstrates how to provide a URL for a custom dialog app, set default dialog size, and disable the default dialogs for preventing shut down and window close:

{
    "dialogs": {
        "url": "https://my-custom-dialog.com",
        "width": 380,
        "height": 150,
        "enableDefaultDialogs": {
            "preventShutdown": false,
            "preventWindowClose": false
        }
    }
}

The "dialogs" object has the following properties:

The "enableDefaultDialogs" object has the following properties:

io.Connect Desktop has a built-in search provider that returns search results for apps, Workspaces, Layouts and actions. To disable it, or to modify the search types for which it will provide results, use the "searchProvider" top-level key:

The following example demonstrates how to configure the default search provider to return search results only for Workspaces and Layouts:

{
    "searchProvider": {
        "enabled": true,
        "types": ["workspace", "layout"]
    }
}

The "searchProvider" object has the following properties:

Available since io.Connect Desktop 9.6

To enable your apps to register interception handlers, use the "interception" top-level key.

The following example demonstrates how to enable interception for all apps:

{
    "interception": {
        "enabled": true
    }
}

The "interception" object has the following properties:

To allow only specific apps to register interception handlers, use the "applications" property and provide the names of the apps as specified in their respective app definitions:

{
    "interception": {
        "enabled": true,
        "applications": ["my-app", "my-other-app"]
    }
}

Available since io.Connect Desktop 9.6

io.Connect Desktop utilizes the built-in Electron spellchecker which is enabled by default. To provide settings for the spellchecker, use the "spellchecker" top-level key:

{
    "spellchecker": {
        "enabled": true,
        "languages": ["en-US", "fr"],
        "dictionaryDownloadURL": "https://example.com/dictionaries"
    }
}

The "spellchecker" object has the following properties:

Title Format

To set a format for the titles of app instances, use the "titleFormat" property of the "applications" top-level key in the system.json system configuration file of io.Connect Desktop. The supported macros are {title} and {instanceIndex}. The {title} macro will be substituted with the title set in the app definition and the {instanceIndex} macro will be substituted with the consecutive number of the started app instance which is incremented for each new app instance starting from 1. If all instances are closed, the counter is reset. If some instances are closed while others are still running, the counter will continue to increment accordingly:

{
    "applications": {
        "titleFormat": "{title} ({instanceIndex})"
    }
}

⚠️ Note that if the window title is set programmatically via the io.Connect APIs, the specified title format will be overridden. For web apps and Workspaces Apps, the "syncTitleWithDocumentTitle" property will override the specified title format.

Hibernation

To specify whether app instances are to be closed when hibernating Global Layouts, Workspaces or window groups, use the "closeOnHibernate" property of the "applications" top-level key:

{
    "applications": {
        "closeOnHibernate": false
    }
}

By default, this property is set to true. Set to false to prevent the apps participating in the hibernation process to close. This will result in faster display of hibernated apps when resuming Global Layouts, Workspaces or window groups, but won't save as much system resources.

Setting this to false may also be useful if you want to hibernate and resume io.Connect Window groups programmatically, in order to preserve the original group objects and IDs.

You can also configure the hibernation behavior per app, which provides you with flexibility in designing your hibernation strategy. You may choose to close the instances of lightweight apps, as they won't take much time to load, and preserve only the instances of heavy apps during hibernation. This will save the time needed for loading the heavy apps when the user resumes the Layout later, but comes at the expense of higher memory consumption on the user machine.

For details on how to configure hibernation per app, see the Configuration > Application > Hibernation section.

Available since io.Connect Desktop 9.3

Global settings for the internal window management mechanisms are found under the "windowManagement" top-level key in the system.json file of io.Connect Desktop, and with the exception of window group settings, can be overridden per app from the app definition settings.

⚠️ Note that each setting under the "windowManagement" top-level may be valid only for certain app definition types. Window group settings may be valid only for classic groups or only for web groups.

Window Groups

To configure the behavior of window groups, use the "groups" property of the "windowManagement" top-level key.

The "groups" object has the following properties:

Tab Overflow

Available since io.Connect Desktop 9.4

⚠️ Note that this feature is available only for web groups.

Tab overflow allows the extra tabs on the right side of the tab header to be collected in a dropdown menu in their original order instead of becoming smaller and smaller each time a new tab is added to the group. The user can open the menu and select the desired tab (or close a tab directly from the menu). The tabs will be scrolled horizontally and the selected tab will be focused.

To enable tab overflow, use the "overflow" property of the "tabs" object:

{
    "windowManagement": {
        "group": {
            "tabs": {
                "overflow": true
            }
        }
    }
}

Tab Selection

Available since io.Connect Desktop 9.4

⚠️ Note that this feature is available only for web groups.

By default, when the user closes a tab in a window group with multiple tabs, the tab immediately to its left (or immediately to its right, if the closed tab was the first one in the tab group) is automatically focused. You can override this behavior and instruct io.Connect Desktop to focus the tab that was previously selected by the user instead.

To enable focusing the previously selected tab, use the "selectPreviousOnClose" property of the "tabs" object:

{
    "windowManagement": {
        "group": {
            "tabs": {
                "selectPreviousOnClose": true
            }
        }
    }
}

Loading Strategy

Available since io.Connect Desktop 9.4

⚠️ Note that this feature is available only for web groups.

It's possible to specify a loading strategy for restoring tabbed window groups. The available options are to load all apps in the tabs simultaneously, or to load only the visible apps first and then load hidden apps on demand (only when the user clicks on a tab to activate it).

To specify a loading strategy for window groups, use the "loadingStrategy" property of the "tabs" object:

{
    "windowManagement": {
        "group": {
            "tabs": {
                "loadingStrategy": "lazy"
            }
        }
    }
}

Possible values for the "loadingStrategy" property are "direct" (default) or "lazy".

Ungrouping Windows

Available since io.Connect Desktop 9.4

To enable or disable ungrouping windows when the user holds down the left mouse button on the window header, use the "unlockOnLongMousePress" object:

{
    "windowManagement": {
        "group": {
            "unlockOnLongMousePress": {
                "enabled": true,
                "timeout": 1200,
                "tolerance": 10
            }
        }
    }
}

The "unlockOnLongMousePress" object has the following properties:

Sizing

To configure the behavior for sizing windows and window groups, use the "sizing" property of the "windowManagement" top-level key.

The "sizing" object has the following properties:

Inner Sizing Borders for Window Groups

Available since io.Connect Desktop 9.4

⚠️ Note that this feature is available only for web groups.

The mechanism for controlling the inner borders used for resizing the windows within a window group can be configured. It's possible to select between the default internal mechanism based on native Windows methods and the platform-independent mechanism used in the Web Group App itself. To specify the desired mechanism, use the "groupInnerSizingMode" property of the "sizing" object:

{
    "windowManagement": {
        "sizing": {
            "groupInnerSizingMode": "external"
        }
    }
}

Collapse & Expand

Available since io.Connect Desktop 9.4

⚠️ Note that this feature is available only for classic groups.

To specify the behavior for collapsing and expanding grouped windows, use the "mode" property of the "collapseExpand" object. By default, this property is set to "Single". This means that when you collapse a window in a group, the height and shape of the group may change (depending on where the collapsed window is situated), because the neighboring windows at the bottom of the collapsed window (if any) won't try to compensate the lost group height by expanding. To override this behavior and instruct the io.Connect Windows to try to compensate the height of a collapsed window in a group by expanding, set the "mode" property of the "collapseExpand" object to "Proportional":

{
    "windowManagement": {
        "collapseExpand": {
            "mode": "Proportional"
        }
    }
}

⚠️ Note that depending on the position of the collapsed window within the group structure, it may not always be possible for the neighboring windows to fill the empty space left by collapsing it.

⚠️ Note that when the group is maximized, the neighboring windows will always try to fill in the empty space left by a collapsed window, irrespective of the mode used.

Collapsing a window in a group when using "Single" mode:

Collapsing a window in a group when using "Proportional" mode:

Snapping to Screen Edges

Available since io.Connect Desktop 9.3

⚠️ Note that this property is valid only for apps of type "window".

To configure whether windows should snap to the edges of the screen when the user moves them within a specified distance from a screen edge, use the "snapToScreenEdges" property:

{
    "windowManagement": {
        "snapToScreenEdges": {
            "enabled": true,
            "distance": 30
        }
    }
}

The "snapToScreenEdges" object has the following properties:

For details on how to configure snapping to screen edges per app, see the Configuration > Application > Snapping to Screen Edges section.

Hardware Acceleration

Available since io.Connect Desktop 9.3

⚠️ Note that this property is valid only for apps of type "window".

To enable hardware acceleration for web apps, use the "hardwareAcceleration" property:

{
    "windowManagement": {
        "hardwareAcceleration": {
            "enabled": true
        }
    }
}

The "hardwareAcceleration" object has the following properties:

Global io.Connect Window settings are found under the "windows" top-level key in the system.json file of io.Connect Desktop and can be overridden per app from the app definition settings.

⚠️ Note that each setting under the "windows" top-level may be valid only for certain app definition types.

Channels

Available since io.Connect Desktop 9.3

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce", "childWindow" and "citrix".

To configure the Channel Selector, use the "channelSelector" property:

{
    "windows": {
        "channelSelector": {
            "enabled": true,
            "type": "directionalSingle"
        }
    }
}

The "channelSelector" object has the following properties:

For details on how to configure the Channel Selector per app, see the Configuration > Application > Channels section.

Injecting Styles

Available since io.Connect Desktop 9.3

⚠️ Note that this property is valid only for apps of type "window", "workspaces" and "webGroup".

io.Connect Desktop allows injecting CSS files in your web apps, the Workspaces App and the Web Group App. Styles will be injected after the DOM content has been loaded. You can choose whether to merge the injected styles with the already existing ones, or to replace them entirely.

To define globally CSS files to inject in your apps, use the "injectedStyles" property:

{
    "windows": {
        "injectedStyles": {
            "replace": false,
            "styles": [
                {
                    "url": "https://my-org.com/my-styles.css",
                    "fallback": "https://my-org.com/my-fallback-styles.css",
                    "timeout": 20000
                },
                {
                    "url": "https://my-org.com/my-other-styles.css",
                }
            ]
        }
    }
}

The "injectedStyles" object has the following properties:

Each object in the "styles" array has the following properties:

For details on how to configure injecting styles per app, see the Configuration > Application > Injecting Styles section.

Persisting Data in Layouts

Data for both web and native apps can be persisted when the app is saved in a Layout. For web apps, this includes the current URL and title, and for native apps - the command and the parameters with which the app was started.

Available since io.Connect Desktop 9.2

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce" and "citrix".

To persist data for web and native apps in Layouts, use the "saveInLayout" property.

The "saveInLayout" object has the following properties:

Web Apps

Available since io.Connect Desktop 9.2

⚠️ Note that this property is valid only for apps of type "window".

To persist data for web apps in Layouts, use the "saveInLayout" property.

The following example demonstrates how to persist the current URLs of web apps only when they participate in Global Layouts and Workspaces, and how to persist the current window titles of web apps in all types of Layouts:

{
    "windows": {
        "saveInLayout": {
            "url": ["Global", "Workspace"],
            "title": true
        }
    }
}

For details on how to control saving web app data in Layouts per app, see the Configuration > Application > Persisting Data in Layouts > Web Apps section.

Native Apps

Available since io.Connect Desktop 9.2

⚠️ Note that this property is valid only for apps of type "exe", "clickonce" and "citrix".

To persist data for native apps in Layouts, use the "saveInLayout" property.

The following example demonstrates how to persist the command and the parameters with which native apps are started when they are saved in a Layout:

{
    "windows": {
        "saveInLayout": {
            "command": true,
            "parameters": true
        }
    }
}

For details on how to control saving native app data in Layouts per app, see the Configuration > Application > Persisting Data in Layouts > Native Apps section.

Synchronizing App Titles

⚠️ Note that this property is valid only for apps of type "window" and "workspaces".

Titles of web app instances and Workspaces App instances can be synchronized with the document title whenever the document title changes. To specify global settings for the desired behavior, use the "syncTitleWithDocumentTitle" property:

{
    "windows": {
        "syncTitleWithDocumentTitle": true
    }
}

Available since io.Connect Desktop 9.4

The "syncTitleWithDocumentTitle" property also accepts a "preserveCustomTitle" string as a value. If set to "preserveCustomTitle", the window title will be synchronized with the document title until the moment the user or the API sets a custom title for the window. After that, the custom title will be preserved and the window title won't be synchronized with the document title.

{
    "details": {
        "syncTitleWithDocumentTitle": "preserveCustomTitle"
    }
}

For details on how to control the synchronizing behavior for app titles per app, see the Configuration > Application > Synchronizing App Titles section.

Handling the Browser window.open()

⚠️ Note that this property is valid only for apps of type "window".

To control the behavior of the browser window.open() method when opening child windows, use the "nativeWindowOpen" property.

The following example demonstrates how to configure io.Connect Desktop to open windows created with window.open() in the default browser:

{
    "windows": {
        "nativeWindowOpen": "browser"
    }
}

The "nativeWindowOpen" property accepts either a string or an object as a value.

The possible string values for the "nativeWindowOpen" property are:

The "nativeWindowOpen" object has the following properties:

Grouping Windows

Available since io.Connect Desktop 9.3

To group child windows with the parent window when using the browser native window.open() method to open windows as io.Connect Windows, use the "grouping" property of the "nativeWindowOpen" object.

The following example demonstrates how to configure io.Connect Desktop to snap newly opened child windows to the left of the parent window:

{
    "windows": {
        "nativeWindowOpen": {
            "mode": "window",
            "grouping": {
                "snap": true,
                "snappingOptions": {
                    "direction": "left"
                }
            }
        }
    }
}

The "grouping" object has the following properties:

The "snappingOptions" object has the following properties:

Window Options

Available since io.Connect Desktop 9.2

⚠️ Note that this property is valid only for apps of type "window".

To provide options for windows opened as io.Connect Windows via the browser window.open() method (i.e., when "nativeWindowOpen" is set to "window"), use the "nativeWindowOpenOptions" property:

{
    "windows": {
        "nativeWindowOpenOptions": {
            "maxHeight": 500,
            "hasSizeAreas": true
        }
    }
}

For a list of the supported options, see the Capabilities > Windows > Window Management > Handling the Browser window.open() > Window Options section.

For details on how to control the behavior for handling the browser window.open() per app, see the Configuration > Application > Handling the Browser window.open() section.

Cascading Windows

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce", "childWindow" and "citrix".

io.Connect Windows that are instances of the same app can be opened in a cascade. Each new window is offset from the previously opened window by a specified distance:

Cascading windows is enabled by default. To specify offset for the cascaded windows, use the "cascade" property:

{
    "windows": {
        "cascade": {
            "offset": 30
        }
    }
}

The "cascade" object has the following properties:

For details on how to control window cascading per app, see the Configuration > Application > Cascading Windows section.

Group Header

⚠️ Note that this property is valid only for apps of type "window".

To hide the group header globally for all io.Connect web apps, use the "hideGroupHeader" property:

{
    "windows": {
        "hideGroupHeader": true
    }
}

⚠️ Note that this property is valid only for web apps (apps of type "window"). However, if a web app forms a window group with one or more native apps (apps of type "exe"), the group header will be hidden. For details on how to hide the group header individually per web app, see the Configuration > Application > Group Header section. For details on how to hide the group header globally for all types of apps, see the Configuration > io.Connect Windows > io.Connect Window Properties > Group Header section.

For details on how to control the group header visibility programmatically, see the Capabilities > Windows > Window Management section.

Sticky Button

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce", "childWindow" and "citrix".

To show the "Sticky" button on all io.Connect Windows, set the "showStickyButton" property to true:

{
    "windows": {
        "showStickyButton": true
    }
}

For details on how to enable or disable the "Sticky" button per app, see the Configuration > Application > Sticky Button section.

For details on how to use stickiness programmatically, see the Capabilities > Windows > Window Management section.

Feedback Button

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce", "childWindow" and "citrix".

To enable the "Feedback" button globally for all io.Connect Windows, set the "showFeedbackButton" property to true:

{
    "windows": {
        "showFeedbackButton": true
    }
}

For details on how to enable or disable the "Feedback" button per app, see the Configuration > Application > Feedback Button section.

Clone Button

Available since io.Connect Desktop 9.2

⚠️ Note that this feature is available only for web groups.

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce", "childWindow" and "citrix".

To enable the "Clone" button globally for all io.Connect Windows, set the "showCloneButton" property to true:

{
    "windows": {
        "showCloneButton": true
    }
}

For details on how to enable or disable the "Clone" button per app, see the Configuration > Application > Clone Button section.

For details on how to clone windows programmatically, see the Capabilities > Windows > Window Management section.

Context Menu

⚠️ Note that this property is valid only for apps of type "window", "workspaces" and "webGroup".

io.Connect Desktop provides a native right-click context menu available in all io.Connect web apps for which it has been enabled. It provides standard editing actions (select, cut, copy, paste, undo, redo), zoom and spelling options.

Available since io.Connect Desktop 9.4

The native context menu supports three different modes: "Edit" mode, "Edit with Suggestions" mode, and "Selection" mode. Each mode is automatically applied based on whether the text can be edited or only selected. The following demonstrates each of the context modes:

To configure the context menu globally, use the "contextMenu" property:

{
    "windows": {
        "contextMenu": {
            "enabled": true
        }
    }
}

For details on how to configure the context menu per app, see the Configuration > Application > Context Menu section.

Jump List

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce", "childWindow" and "workspaces".

To configure the jump list globally for all io.Connect Windows, use the "jumpList" property:

{
    "windows": {
        "jumpList": {
            "enabled": true,
            "categories": [
                {
                    "title": "Tasks",
                    "actions": [
                        {
                            "icon": "%GDDIR%/assets/images/center.ico",
                            "type": "centerScreen",
                            "singleInstanceTitle": "Center on Primary Screen",
                            "multiInstanceTitle": "Center all on Primary Screen"
                        }
                    ]
                }
            ]
        }
    }
}

The "jumpList" object has the following properties:

Each object in the "categories" array has the following properties:

Each object in the "actions" array has the following properties:

For details on how to configure jump lists per app, see the Configuration > Application > Jump List section.

For details on using jump lists programmatically, see the Capabilities > More > APIs > Jump List section.

Downloads

⚠️ Note that this property is valid only for apps of type "window".

To configure the global behavior of the io.Connect Windows when downloading files, use the "downloadSettings" property:

{
    "windows": {
        "downloadSettings": {
            "autoSave": true,
            "autoOpenPath": false,
            "autoOpenDownload": false,
            "enable": true,
            "enableDownloadBar": true,
            "path": "%DownloadsFolder%"
        }
    }
}

The "downloadSettings" object has the following properties:

For details on how to specify download settings per app, see the Configuration > Application > Downloads section.

For details on using downloads programmatically, see the Capabilities > More > APIs > Downloads and the Capabilities > Windows > Window Management sections.

Zooming

⚠️ Note that this property is valid only for apps of type "window", "workspaces" and "webGroup".

To set the zoom behavior globally for all io.Connect Windows, use the "zoom" property:

{
    "windows": {
        "zoom": {
            "enabled": true,
            "mouseWheelZoom": false,
            "factors": [25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500],
            "defaultFactor": 100
        }
    }
}

The "zoom" object has the following properties:

For details on how to specify zoom settings per app, see the Configuration > Application > Zooming section.

For details on zooming windows programmatically, see the Capabilities > More > APIs > Zooming section.

Printing

⚠️ Note that this property is valid only for apps of type "window".

Use the CTRL + P key combination to print a web page opened in an io.Connect Window. To enable or disable printing, or to configure the default print settings globally, use the "print" property.

The following is an example configuration for printing:

{
    "windows": {
        "print": {
            "enabled": true,
            "silent": true,
            "color": false,
            "copies": 1,
            "footer": "https://my-domain.com/",
            "pageSize": "A4",
            "duplexMode": "longEdge"
        }
    }
}

For more details on all available properties for printing, see the "print" key in the system.json schema.

To enable or disable printing a web page as a PDF file, or to configure the default settings for printing to PDF globally, use the "printToPdfSettings" property.

The following is an example configuration for printing to a PDF file:

{
    "windows": {
        "printToPdfSettings": {
            "enabled": true,
            "autoSave": true,
            "autoOpenPath": true,
            "fullPath": "C:/Users/%USERNAME%/Documents/PDF",
            "usePrintShortcutKey": true,
            "pageSize": "A4",
            "printBackground": true,
            "printSelectionOnly": true
        }
    }
}

For more details on all available properties for printing to a PDF file, see the "printToPdfSettings" key in the system.json schema.

For details on how to specify print settings per app, see the Configuration > Application > Printing section.

For details on how to print web pages programmatically, see the Capabilities > Windows > Window Management section.

Filtering Web Requests

To instruct io.Connect Desktop to filter web requests, use the "urlFilter" property. Provide a regular expression as a value that will be matched against the URLs for all web requests. Matched URLs will be allowed, all other requests will be blocked and a dialog will be shown to the user informing them that the URL is blocked by the organization.

The following example demonstrates how to allow only web requests for URLs that start with https://:

{
    "windows": {
        "urlFilter": "https://*"
    }
}

User Agent

⚠️ Note that this property is valid only for apps of type "window".

To specify a custom User-Agent request header to be sent when connecting to a server, use the "userAgent" property:

{
    "windows": {
        "userAgent": "custom-user-agent-string"
    }
}

The default system settings for the Citrix Virtual Apps support should work fine in most cases and usually it isn't necessary to make any modifications. If the default settings don't work for your specific environment, use the "citrix" top-level key to provide custom values.

The following configuration contains the default Citrix settings:

{
    "citrix": {
        "launcherPath": "%ProgramFiles(x86)%/Citrix/ICA Client/SelfServicePlugin",
        "launcherModule": "SelfService.exe",
        "launcherArguments": "-qlaunch \"$appName$\"",
        "launcherSpawnInterval": 1500
    }
}

The "citrix" key has the following properties:

To configure the Feedback Form of io.Connect Desktop, use the "issueReporting" top-level key:

{
    "issueReporting": {
        "attachmentsViewMode": "category",
        "jira": {
            "enabled": true,
            "url": "https://jira.my-org.com/rpc/soap/jirasoapservice-v2",
            "user": "user",
            "password": "password",
            "project": "MY_PROJECT"
        },
        "mail": {
            "enabled": true,
            "zipAttachments": true,
            "bugSubjectPrefix": "Error:",
            "reportSubjectPrefix": "Feedback:",
            "recipients": ["support@example.com", "dev-support@example.com"],
            "allowEditRecipients": true,
            "maxAttachmentMB": "10"
        },
        "folderAttachments": [
            {
                "name": "Screenshots",
                "folderPath": "%GLUE-USER-DATA%/logs",
                "zipFolderPath": "io.Connect Desktop/Screenshots",
                "filter": "*.png",
                "category": "Screenshots",
                "selected": false,
                "recursive": true
            },
            {
                "name": "io.Connect Desktop-AppLogs",
                "folderPath": "%GLUE-USER-DATA%/logs",
                "zipFolderPath": "io.Connect Desktop/Logs",
                "filter": "*.log*",
                "category": "App Logs",
                "selected": true,
                "recursive": true
            },
            {
                "name": "io.Connect Desktop-Crashes",
                "folderPath": "%GLUE-USER-DATA%/crashes/reports",
                "zipFolderPath": "io.Connect Desktop/Crashes",
                "filter": "*.dmp",
                "category": "Crashes",
                "recursive": false
            }
        ],
        "form": {
            "width": 350,
            "height": 500
        }
    }
}

The "issueReporting" top-level key has the following properties:

Jira

The configuration for automatically creating a Jira ticket when submitting a Feedback Form is found under the required "jira" property of the "issueReporting" top-level key. It accepts an object with the following properties:

Email

The configuration for automatically sending an email when submitting a Feedback Form is found under the required "mail" property of the "issueReporting" top-level key. It accepts an object with the following properties:

Attachments

The configuration for attaching files when submitting a Feedback Form is found under the required "folderAttachments" property of the "issueReporting" top-level key. It accepts an array of objects, each with the following properties:

Form

To configure the io.Connect Window containing the Feedback Form, use the "form" property of the "issueReporting" top-level key. It accepts an object with the following properties:

⚠️ Note that the "transparent" property will set a transparent background only for the io.Connect Window that contains the Feedback app. To achieve actual transparency, you must also set a transparent background for your app from its styles.

For details on how to enable or disable the "Feedback" button globally or per app, see the Window Settings > Feedback Button and the Configuration > Application > Feedback Button sections respectively.

For details on how to create your custom Feedback app, see the More > Features > Issue Reporting > Extending the Feedback Form section.

Available since io.Connect Desktop 9.2

To configure the Download Manager of io.Connect Desktop, use the "downloadManager" top-level key.

{
    "downloadManager": {
        "autoStartOnDownload": true,
        "shortcut": "ctrl+alt+d"
    }
}

The "downloadManager" object has the following properties:

To customize the About app of io.Connect Desktop, use the "about" top-level key.

The "about" object has the following properties:

To remove the trademark information at the bottom of the page, use the "hideTrademark" property:

{
    "about": {
        "hideTrademark": true
    }
}

You can also change the entire content displayed in the About app and its size by providing a URL to be loaded instead of the default app and specifying the desired width and height.

The following example demonstrates how to modify the size and the content of the About app:

{
    "about": {
        "url": "https://interop.io/",
        "width": 500,
        "height": 500
    }
}

Telemetry data is disabled by default. To enable it, set the "telemetry" top-level key to true:

{
    "telemetry": {
        "enabled": true
    }
}

The "telemetry" object has the following properties:

The "features" object has the following properties:

For details on how to retrieve telemetry data programmatically, see the Capabilities > More > Features > Telemetry Data section.

To configure the location of the system folders of io.Connect Desktop, use the "folders" top-level key.

The "folders" object has the following properties:

The following example demonstrates how to change the location of the folder containing remote configurations for io.Connect Desktop:

{
    "folders": {
        "remoteConfig": "%LocalAppData%/my-configs/%GLUE-ENV%-%GLUE-REGION%/remote"
    }
}

Available since io.Connect Desktop 9.2

The "cache" property accepts also an object with the following properties:

The following example demonstrates how to define a custom location for the Electron cache and instruct io.Connect Desktop to copy the cache from the closest previously installed version:

{
    "folders": {
        "cache": {
            "copy": true,
            "location": "../MyCache/%GLUE-ENV%-%GLUE-REGION%/"
        }
    }
}

Available since io.Connect Desktop 9.5

The "copy" property of the "cache" object accepts also an object with the following properties as a value:

Available since io.Connect Desktop 9.6

The "platformCache" object has the following properties:

The logging configuration for io.Connect Desktop is found in the logger.json file located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config. A JSON schema for 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 defines the log appenders and the categories used by io.Connect Desktop for logging. The available configuration options are described in detail in the log4js-node API documentation.

You can also configure the system logging for io.Connect Desktop by using the "logging" top-level key in the system.json file.

⚠️ Note that io.Connect Desktop also offers a JavaScript Logger API that enables your io.Connect apps to output logs to files or to the console.

Default Configuration

By default, io.Connect Desktop uses two of the core log4js-node appenders - file and multiFile. The file appender is used for logging events related to the io.Connect Desktop app itself, while the multiFile appender is used for logging events related to io.Connect client apps.

The default logging configuration for io.Connect Desktop found in the logger.json can be modified according the specifications laid out in the log4js-node documentation.

Custom Log Appenders

You can add any other log4js-node appenders (core, optional and custom) and categories to the io.Connect Desktop logging configuration.

The following example demonstrates how to add the logstashHTTP optional appender to io.Connect Desktop:

1. Create a directory for the appender and run the following command to install it:

npm install @log4js-node/logstash-http

2. Create an index.js file in which import and export the appender:

module.exports = require("@log4js-node/logstash-http");

3. Add the logstashHTTP appender to the io.Connect Desktop configuration in the logger.json file under the "appenders" top-level key:

{
    "appenders": {
        "logstash": {
            "type": "%GDDIR%/assets/logstash-http",
            "url": "http://localhost:9200/_bulk",
            "application": "My App",
            "logType": "application",
            "logChannel": "node"
        }
    }
}

The "type" property must point to the location of the logstash-http package. You can also use environment variables.

4. Under the "categories" top-level key, define the log event categories for which the log appender will be used:

{
    "categories": {
        "my-custom-category": {
            "appenders": ["logstash"],
            "level": "info"
        }
    }
}

Log Appenders per App

Available since io.Connect Desktop 9.5

By default, io.Connect Desktop uses a multiFile appender named "applications" for logging events related to io.Connect client apps. To define separate log appenders per app, execute the following steps:

1. Define a log appender to be used for your app:

{
    "appenders": {
        "my-app-appender": {
            "type": "file",
            "filename": "%GLUE-USER-DATA%/logs/my-app.log",
            "maxLogSize": 10485760,
            "backups": 5,
            "minLevel": "info",
            "keepFileExt": true,
            "compress": true
        }
    }
}

2. Create a category with the name of your app as defined in its app definition and assign the log appender to it. This will instruct io.Connect Desktop to use the specified log appender for your app:

{
    "categories": {
        "my-app": {
            "appenders": [
                "my-app-appender"
            ],
            "level": "trace"
        }
    }
}

System Logs

To configure the system logging for io.Connect Desktop, use the "logging" top-level key in the system.json file.

Streaming

You can configure io.Connect Desktop to stream the system logs so that they can be consumed by your apps. To specify the log streaming configuration, use the "streaming" property of the "logging" top-level key:

{
    "logging": {
        "streaming": {
            "enabled": true,
            "minLevel": "warn",
            "interval": 60
        }
    }
}

The "streaming" object has the following properties:

For details on how to consume the system logs, see the More > APIs > Logging > System Logs section.

Log Files

Available since io.Connect Desktop 9.3

To specify settings for handling the system log files, use the "files" property of the "logging" top-level key:

{
    "logging": {
        "files": {
            "onStartup": "archive",
            "moveOldTo": "%LocalAppData%/my-org/logs"
        }
    }
}

The "files" object has the following properties:

⚠️ Note that by design the gilding.log file won't be archived or deleted.

To configure io.Connect Desktop how to handle system crash reports, use the "crashReporter" top-level key. You can enable or disable crash reporter logging, define metadata to be included in the crash reports, and also provide output settings for the reports:

{
    "crashReporter": {
        "enabled": true,
        "folderPath": "%LocalAppData%/my-org/crashes",
        "companyName": "My Org",
        "productName": "My Product",
        "output": {
            "type": "local"
        }
    }
}

The "crashReporter" object has the following properties:

The "output" object has the following properties:

Available since io.Connect Desktop 9.3

To instruct io.Connect Desktop how to handle the dump files from the crash reporter, use the "dumps" property of the "output" object under the "crashReporter" top-level key:

{
    "crashReporter": {
        "output": {
            "dumps": {
                "deleteOnSent": true,
                "limit": 10
            }
        }
    }
}

The "dumps" object has the following properties: