Configuration

System 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.

Dynamic Gateway Port

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.

Gateway Memory Diagnostics

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:

Property Type Description
dump_locaton string Location for dumping the heap memory snapshots. Defaults to "%GLUE-USER-DATA%/heapsnapshots".
dump_prefix string Prefix for the file containing the heap memory snapshots. Files will be named in the format <dump-prefix>.<backup-number>.heapsnapshot. Defaults to "gw".
max_backups number Maximum number of heap memory snapshots that will be saved. Defaults to 10.
memory_limit number Limit for the heap memory size that will trigger heap memory snapshot. Defaults to 1073741824 (1GB).
report_interval number Interval in milliseconds at which the heap memory size will be checked and logged. Defaults to 300000.

The "limits" object has the following properties:

Property Type Description
large_msg_threshold number Maximum size in bytes of messages sent to the io.Connect Gateway that, if exceeded, will trigger a warning in the logs. Useful for detecting apps sending excessively large messages causing the io.Connect Gateway to crash. Defaults to 20000.
max_connections number Limit for the number of simultaneous app connections to the io.Connect Gateway. Unlimited by default.

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

App Stores

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:

Property Type Description
"appDefinitionOverrides" object Valid app definition properties that will override the ones in all app definitions from the app store. Top-level app definition properties can be specified directly in the "appDefinitionOverrides" object. The properties that are found under the "details" top-level key for each app definition type must be specified in a top-level object with the same name as the app type - "window", "exe", "node", "workspaces", "webGroup", "clickonce", "citrix" or "childWindow". Available since io.Connect Desktop 9.1.
"details" object Required. Specific details about the app store.
"isRequired" boolean If true (default), the app store will be required. If the app store can't be retrieved, io.Connect Desktop will throw an error and shut down. If false, io.Connect Desktop will initiate normally, without apps from that store.
"type" string Required. Type of the app store. Must be set to "path" for local path app stores.

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

Property Type Description
"path" string Required. Must point to the local app store. The specified path can be absolute or relative and you can use defined environment variables.

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:

Property Type Description
"appDefinitionOverrides" object Valid app definition properties that will override the ones in all app definitions from the app store. Top-level app definition properties can be specified directly in the "appDefinitionOverrides" object. The properties that are found under the "details" top-level key for each app definition type must be specified in a top-level object with the same name as the app type - "window", "exe", "node", "workspaces", "webGroup", "clickonce", "citrix" or "childWindow". Available since io.Connect Desktop 9.1.
"details" object Required. Specific details about the app store.
"isRequired" boolean If true (default), the app store will be required. If the app store can't be retrieved, io.Connect Desktop will throw an error and shut down. If false, io.Connect Desktop will initiate normally, without apps from that store.
"type" string Required. Type of the app store. Must be set to "rest" for remote app stores.

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

Property Type Description
"auth" string Authentication configuration. Can be one of "no-auth" (default), "negotiate" or "kerberos".
"cacheFolder" string Location to keep the persisted configuration files.
"enablePersistentCache" boolean If true (default), will cache and persist the configuration files locally (e.g., in case of connection interruptions).
"pollInterval" number Interval in milliseconds at which to poll the REST service for updates. Default is 60000.
"proxy" string HTTP proxy to use when fetching data.
"readCacheAfter" number Interval in milliseconds after which to try to read the cache. Default is 30000.
"rejectUnauthorized" boolean If true (default), SSL validation will be enabled for the REST server.
"requestTimeout" number Timeout in milliseconds to wait for a response from the REST server. Default is 20000.
"startRetries" number Number of times io.Connect Desktop will try to connect to the REST server. Default is 5.
"startRetryInterval" number Interval in milliseconds at which io.Connect Desktop will try to connect to the REST server. Default is 10000.
"url" string Required. The URL to the REST service providing the app definitions.

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:

Property Type Description
"appDefinitionOverrides" object Valid app definition properties that will override the ones in all app definitions from the app store. Top-level app definition properties can be specified directly in the "appDefinitionOverrides" object. The properties that are found under the "details" top-level key for each app definition type must be specified in a top-level object with the same name as the app type - "window", "exe", "node", "workspaces", "webGroup", "clickonce", "citrix" or "childWindow". Available since io.Connect Desktop 9.1.
"isRequired" boolean If true (default), the app store will be required. If the app store can't be retrieved, io.Connect Desktop will throw an error and shut down. If false, io.Connect Desktop will initiate normally, without apps from that store.
"type" string Required. Type of the app store. Must be set to "server" for app stores retrieved from io.Manager.

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.

System App Stores

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.

Layouts

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

The "layouts" object has the following properties:

Property Type Description
"restoreDefaultGlobalOnStartup" boolean If true (default), the default Global Layout (if any) will be restored on startup of io.Connect Desktop.
"splash" object Settings for the loading animation displayed when restoring a Layout.
"store" object Settings for the Layout store.

The "splash" object has the following properties:

Property Type Description
"disabled" boolean If true, the Layout loader will be disabled.
"height" number Height in pixels for the Layout loader.
"title" string Title for the Layout loader.
"url" string URL pointing to the location of the Layout loader. Defaults to "file://%GDDIR%/assets/loader/index.html".
"width" number Width in pixels for the Layout loader.

The "store" object has the following properties:

Property Type Description
"rejectUnauthorized" boolean If true (default), SSL validation will be enabled for the REST server. Valid only in "rest" mode.
"restClientAuth" "no-auth" | "negotiate" | "kerberos" Authentication configuration. Defaults to "negotiate". Valid only in "rest" mode.
"restFetchInterval" number Interval in seconds at which to poll the REST service for updates. Default is 60. Valid only in "rest" mode.
"restURL" string URL pointing to the Layout store. Valid only in "rest" mode.
"type" "file" | "rest" | "server" Type of the Layout store. Set to "file" (default) to read Layouts from a local file. Set to "rest" to fetch Layouts from a REST service. Set to "server" to fetch Layouts from io.Manager.

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 Store

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:

Property Type Description
"newDataCheckInterval" number Interval in seconds at which to check for new data from the REST store. Executed only if subscribers are available. Defaults to 1800. Valid only in "rest" mode.
"restClientAuth" "no-auth" | "negotiate" | "kerberos" Authentication configuration. Valid only in "rest" mode.
"restURL" string URL pointing to the app preferences store. Valid only in "rest" mode.
"type" "file" | "rest" | "server" The type of the app preferences store. Set to "file" (default) to read app preferences from a local file. Set to "rest" to fetch app preferences from a REST service. Set to "server" to fetch app preferences from io.Manager.

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.

Splash Screen

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:

Property Type Description
"blockStartup" boolean If true (default), will block startup until the splash screen has loaded.
"disabled" boolean If true, the splash screen will be disabled.
"height" number Height in pixels for the splash screen. Defaults to 233.
"showOnShutdown" boolean If true (default), will show the splash screen when io.Connect Desktop is shutting down.
"timeout" number Interval in milliseconds to wait for the splash screen to load. Defaults to 2000.
"transparent" boolean If true (default), the splash screen background will become transparent.
"url" string URL pointing to the location of the splash screen. Defaults to "file://%GDDIR%/assets/splash/splash.html".
"width" number Width in pixels for the splash screen. Defaults to 350.

Notifications

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:

Property Type Description
"enabled" boolean If true (default), will enable all notifications - notification toasts and notifications in the Notification Panel.
"enableToasts" boolean If true (default), will enable notification toasts.
"placement" object Placement settings for the Notification Panel and the notification toasts. Available since io.Connect Desktop 9.2.
"snooze" object Settings for snoozing notifications. Available since io.Connect Desktop 9.3.
"sourceFilter" object Filter with names of apps that are allowed or not allowed to raise notifications.
"toastExpiry" number Interval in milliseconds after which the notification toasts will be hidden. Defaults to 15000.
"toasts" object Settings for the notification toasts.

The "snooze" object has the following properties:

Property Type Description
"duration" number Interval in milliseconds for which the notifications will be snoozed. Defaults to 600000.
"enabled" boolean If true, will enable snoozing notifications. Defaults to false.

The "placement" object has the following properties:

Property Type Description
"panel" "left" | "right" Sets the position of the Notification Panel on the screen - left or right. Defaults to "right".
"toasts" "top-left" | "top-right" | "bottom-left" | "bottom-right" Sets the position of the notification toasts on the screen - top right, top left, bottom right or bottom left. Defaults to "bottom-right".

The "sourceFilter" object has the following properties:

Property Type Description
"allowed" string[] Names of apps allowed to raise notifications. Defaults to "*".
"blocked" string[] Names of apps not allowed to raise notifications.

The "toasts" object has the following properties:

Property Type Description
"mode" "single" | "stacked" Mode for the notification toasts. Notification toasts can appear individually, or can be stacked together based on a criterion (severity or app that has raised the notification). Defaults to "single".
"stackBy" "severity" | "application" Criterion for stacking the notification toasts. Defaults to "severity".

Dialogs

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:

Property Type Description
"enableDefaultDialogs" object Enable or disable the default io.Connect dialog messages.
"height" number Height in pixels for the io.Connect dialogs.
"transparent" boolean If true, the io.Connect Window containing the dialog will be transparent.
"url" string URL pointing to the location of the io.Connect dialog app.
"width" number Width in pixels for the io.Connect dialogs.

The "enableDefaultDialogs" object has the following properties:

Property Type Description
"preventShutdown" boolean If true (default), will enable the dialog message that appears when io.Connect Desktop is about to shutdown.
"preventWindowClose" boolean If true (default), will enable the dialog message that appears when the user tries to close an io.Connect Window that is programmatically prevented from closing. This dialog will appear also when such window participates in a Layout that is being closed.
"unsavedLayoutChanges" boolean If true (default), will enable the dialog message that appears when the user modifies the current Global Layout and tries to restore another Global Layout. Available since io.Connect Desktop 9.2.

Default Search Provider

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:

Property Type Description
"enabled" boolean If true (default), will enable the default search provider of io.Connect Desktop.
"types" string[] Predefined search types for which the provider will return results. The possible values you can use in the array are "application", "layout", "workspace" and "action". Defaults to ["application", "layout", "workspace", "action"].

App Settings

Title Format

To set a format for the titles of app windows, use the "titleFormat" property of the "applications" top-level key. Use the supported macros - {title} and {instanceIndex}:

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

Title format

The value for the {title} macro is the title specified in the app definition file. The {instanceIndex} macro is the consecutive number of the app instance. It 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.

⚠️ Note that if the app sets the title programmatically through any of the io.Connect APIs, the specified title format will be overridden. For web apps, the window title can be synced with the document title by using the "syncTitleWithDocumentTitle" property of the "windows" top-level key, which will override the specified title format.

Hibernation

To specify whether app instances are to be closed when a Global Layout, a Workspace or a window group is hibernated, 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 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.

Window Management

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

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

Snap to Screen Edges

The "snapToScreenEdges" object has the following properties:

Property Type Description
"distance" number Distance in pixels from the screen edge at which the window will snap to it. The minimum is 5, the maximum is 30. Defaults to 20.
"enabled" boolean If true, will enable snapping windows to the screen edges when the user moves them within the specified distance from the screen edge. Defaults to false.

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:

Property Type Description
"enabled" boolean If true, will enable hardware acceleration for web pages. Defaults to false.

Window Settings

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:

Property Type Description
"enabled" boolean If true, will allow showing the Channel Selector. Defaults to false.
"channelId" string Name of the Channel to which the window will be joined by default when it's started.
"readOnly" boolean If true, the Channel Selector will be visible, but the user won't be able to switch between Channels from it. Defaults to false.
"type" "single" | "directionalSingle" Type of the Channel Selector to show on the io.Connect Windows. A single Channel Selector (default) allows the window to join a single Channel to which it can subscribe and publish data unrestrictedly. A directional single Channel Selector allows the window to join a single Channel, but also enables the user to restrict the window from publishing or from subscribing to the current Channel. Defaults to "single".

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:

Property Type Description
"replace" boolean If true, will replace the existing styles of the web app with the injected ones. This won't affect styles added dynamically after the initial page load. If false, the existing styles will be merged with the injected ones.
"styles" object List of objects describing CSS files that will be injected in the specified order.

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

Property Type Description
"fallback" string URL pointing to a local or a remote CSS file that will be used as a fallback in case the one specified in the "url" property doesn't load.
"timeout" number Interval in milliseconds to wait for the CSS file to load.
"url" string Required. URL pointing to a local or a remote CSS file.

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:

Property Type Description
"command" boolean Valid only for native apps. If true, when the app is saved in a Layout, the command with which it was started will be persisted. If the value of the "command" property in the app definition is changed, when the Layout is restored, the app will be started with the previously persisted command, and not the one in the current app definition.
"env" boolean Valid only for native apps. If true, when the app is saved in a Layout, the environment variables with which it was started will be persisted. If the value of the "env" property in the app definition is changed, when the Layout is restored, the app will be started with the previously persisted environment variables, and not the ones in the current app definition. Available since io.Connect Desktop 9.3.
"parameters" boolean Valid only for native apps. If true, when the app is saved in a Layout, the parameters with which it was started will be persisted. If the value of the "parameters" property in the app definition is changed, when the Layout is restored, the app will be started with the previously persisted parameters, and not the ones in the current app definition.
"title" boolean | string[] Valid only for web apps. If true, the current window title will be saved for all Layout types. Alternatively, you can provide a list of Layout types for which the window title is to be saved. The possible string values are "Global", "Workspace" and "ApplicationDefault". Only for web apps.
"url" boolean | string[] Valid only for web apps. If true, the current window URL will be saved for all Layout types. Alternatively, you can provide a list of Layout types for which the window URL is to be saved. The possible string values are "Global", "Workspace" and "ApplicationDefault".

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

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:

Value Description
"browser" Windows created with window.open() will be opened in the default browser.
"off" Opening windows with window.open() is disabled.
"window" Default. Windows created with window.open() will be opened as io.Connect Windows.

The "nativeWindowOpen" object has the following properties:

Property Type Description
"grouping" object Settings for grouping the newly opened child window with the parent window. The child window can be snapped to any side of the parent window, or can be added to its tab group, provided that both windows are io.Connect tab windows. Available since io.Connect Desktop 9.3.
"mode" string Must be set to "window".
"outlivesOpener" boolean If true, will prevent child windows from being closed when their parent is closed.

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:

Property Type Description
"addToTabGroup" boolean If true, will add the new child window to the tab group of the parent. Valid only when both the parent and the child are io.Connect tab windows.
"snap" boolean If true, the child window will be snapped to the parent window. To specify a relative direction for the snapped window, use the "direction" property of the "snappingOptions" object. If no direction is specified, the child window will be snapped to the right side of the parent window.
"snappingOptions" object Options for snapping the child window to the parent window.

The "snappingOptions" object has the following properties:

Property Type Description
"direction" "right" | "left" | "bottom" | "top" Direction (bottom, top, left or right) for positioning the child window relatively to the parent window. Considered only if "snap" is set to true.

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

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:

Property Type Description
"enabled" boolean If true (default), will enable cascading windows.
"offset" number Offset in pixels for the cascaded window.

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

Sticky Button

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

Feedback Button

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

Clone Button

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.

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:

Property Type Description
"categories" object[] Categorized lists with actions to execute when the user clicks on them.
"enabled" boolean If true (default), will enable the jump list.

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

Property Type Description
"actions" object[] List of actions contained in the category.
"title" string Title of the category to be displayed in the context menu.

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

Property Type Description
"icon" string Icon for the action to be displayed in the context menu. Must point to a local file.
"multiInstanceTitle" string Title of the action to be displayed in the context menu when there are multiple instances with grouped taskbar icons.
"singleInstanceTitle" string Title of the action to be displayed in the context menu when there is a single instance with a single taskbar icon.
"type" string Type of the predefined action to execute.

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:

Property Type Description
"autoOpenDownload" boolean If true, will open the download file after the download is completed. Defaults to false.
"autoOpenPath" boolean If true, will open the folder that contains the downloaded file after the download is completed. Defaults to false.
"autoSave" boolean If true (default), will auto save the file (without asking the user where to save it). If false, a system save dialog will appear.
"enable" boolean If true (default), will enable the window to download files.
"enableDownloadBar" boolean If true (default), a download bar tracking the download progress will appear at the bottom of the window. If false, the download process will be invisible.
"path" string Location where the downloaded file will be saved. Due to security reasons, there are only two possible locations for downloads: the Windows "Temp" or "Downloads" folder. Defaults to "%DownloadsFolder%".

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:

Property Type Description
"defaultFactor" number Default zoom factor within the range of 25 to 500. Avoid negative values. Defaults to 100.
"enabled" boolean If true (default), will enable zooming.
"factors" number[] List of zoom factors to be used when the user zooms in or out of the window. The factors must be in ascending order and may have integer or floating point values. Zooming will only work with factor values within the range of 25 to 500. Avoid passing negative values when setting the zoom factor (via configuration or programmatically), as this will cause unexpected behavior. Defaults to [25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400, 500].
"mouseWheelZoom" boolean If true, will enable zooming with CTRL + mouse scroll. Defaults to false.

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"
        }
    }
}
Property Type Description
"color" boolean If true (default), will print the page in color. Otherwise, in grayscale.
"copies" number The number of copies to print.
"duplexMode" string Setting for duplex printing.
"enabled" boolean If true (default), will enable printing.
"footer" string String that will be printed as a footer on each page.
"pageSize" string The size of the printed page.
"silent" boolean If true, won't ask the user for print settings. Defaults to false.

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
        }
    }
}
Property Type Description
"autoOpenPath" boolean If true, will open automatically the directory where the file was saved. Defaults to false.
"autoSave" boolean If true, will auto save the PDF file. If false, a system dialog will appear asking the user where to save the file. Defaults to false.
"enabled" boolean If true (default), will enable printing to a PDF file.
"fullPath" string The default directory where PDF files will be saved. Defaults to "%DownloadsFolder%".
"pageSize" string The size of the printed page.
"printBackground" boolean If true, will print the page background.
"printSelectionOnly" boolean If true, will print only the currently selected section of the page.
"usePrintShortcutKey" boolean If true, will use CTRL + P by default to print to a PDF file.

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

Citrix Apps

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:

Property Type Description
"launcherArguments" string The command line arguments used to launch published Citrix Virtual Apps. Defaults to "-qlaunch \"$appName$\"".
"launcherModule" string The file name of the Citrix module used to launch published Citrix Virtual Apps. Defaults to "SelfService.exe".
"launcherPath" string Location of the Citrix module used to launch published Citrix Virtual Apps. Defaults to "%ProgramFiles(x86)%/Citrix/ICA Client/SelfServicePlugin".
"launcherSpawnInterval" number Interval in milliseconds at which multiple launcher modules will be spawned. Defaults to 1500.

Issue Reporting

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:

Property Type Description
"attachmentsViewMode" "file" | "category" Defines how the attachments will be displayed in the Feedback Form. Possible values are "file" or "category". If set to "file", all attachable files will be displayed as separate items, otherwise several main categories will be displayed and if the category is selected by the user, all files in it will be attached.
"attachScreenShots" boolean If true, will attach screenshots of all monitors to the issue report.
"folderAttachments" object[] Required. Attachments configuration. For more details, see the Attachments section.
"form" object Object that can be used to specify various properties for the io.Connect Window containing the Feedback Form, or to provide a URL pointing to a custom Feedback app.
"jira" object Required. Jira configuration. For more details, see the Jira section.
"mail" object Required. Email configuration. For more details, see the Email section.

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:

Property Type Description
"enabled" boolean If true, will enable the option to create a Jira ticket when submitting the issue.
"noEnvironment" boolean If true, the ticket "Environment" field won't be set.
"noPriority" boolean If true, the ticket "Priority" field won't be set.
"password" string Required. The password of the user who will create the ticket.
"preferredRole" string Preferred role in the Jira project.
"preferredRoleDescriptor" string Description of the preferred role in the Jira project.
"project" string Required. The name of the project in which the ticket will be created.
"tlsVersion" string Force TLS protocol version, e.g. "TLS1.2".
"url" string Required. Link to the Jira API.
"useProjectLeadAsPreferredAssignee" boolean If true, will assign the ticket to the project lead.
"user" string Required. The username of the user who will create the ticket.

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:

Property Type Description
"allowEditRecipients" boolean If true, the user will be allowed to manually add more recipients.
"bugSubjectPrefix" string Prefix for the email subject when the issue is a bug.
"enabled" boolean If true, will enable the option to send an email when submitting the issue.
"maxAttachmentMB" string The maximum size of the attachments in MB.
"recipients" string[] List of email addresses to which the issue report will be sent.
"reportSubjectPrefix" string Prefix for the email subject when sending feedback.
"zipAttachments" boolean If true, the attachments will be archived.

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:

Property Type Description
"category" string Required. Category for the attached item.
"filter" string Required. Regex filter that will be applied to each file in the folder - e.g., "*.log".
"folderPath" string Required. Path to the folder that will be attached.
"name" string Required. Name for the attachment.
"recursive" boolean If true, will collect and attach all files from all folders located inside the specified folder. Set to false to collect the files only in the specified folder.
"selected" boolean If true, the category (or all files under this category) in the Feedback Form will be selected by default.
"zipFolderPath" string Required. Path in the archived folder.

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:

Property Type Description
"height" number Height in pixels for the Feedback Form.
"showEnvironmentInfo" boolean If true, the Feedback Form will show a field with details about the io.Connect environment.
"transparent" boolean If true, the io.Connect Window containing the Feedback Form will have a transparent background. Available since io.Connect Desktop 9.1.
"url" string URL pointing to the location of the Feedback app. Defaults to "file://%GDDIR%/assets/issue-reporting/index.html".
"width" number Width in pixels for the Feedback Form.

⚠️ 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.

Feedback Form

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.

Download Manager

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:

Property Type Description
"appName" string Name of an io.Connect app, as specified in its definition, to be used as a Download Manager. Defaults to "io-connect-download-manager".
"autoStartOnDownload" boolean If true, the Download Manager app will be started automatically when a download is initiated. Defaults to false.
"shortcut" string Shortcut for starting the Download Manager app. Defaults to "ctrl+j".

Download Manager

About App

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

The "about" object has the following properties:

Property Type Description
"height" number Height in pixels for the About app.
"hideTrademark" boolean Hide the trademark information section in the About app.
"url" string URL pointing to the location of the About app.
"width" number Width in pixels for the About app.

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

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

Hide Trademark

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

Custom About

Folders

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:

Property Type Description
"cache" string Settings for the Electron cache. Defaults to "%LocalAppData%/interop.io/io.Connect Desktop/Cache/%GLUE-ENV%-%GLUE-REGION%/".
"remoteConfig" string Location for storing configuration files for io.Connect Desktop downloaded from remote locations. Defaults to "%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%/remoteConfig".
"userData" string Location for storing user-specific data like app definitions, Layouts, logs, cache and other system information. Accepts an absolute path, or a path relative to the location of the io.Connect Desktop executable file. You can use environment variables. Defaults to "%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%".

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:

Property Type Description
"copy" boolean If true, the Electron cache from the closest previously installed io.Connect Desktop version will be copied and added to the cache files for the upgraded version of io.Connect Desktop. Defaults to false.
"location" string Location for the Electron cache. Accepts an absolute path, or a path relative to the location of the io.Connect Desktop executable file. You can use environment variables. Defaults to "%LocalAppData%/interop.io/io.Connect Desktop/Cache/%GLUE-ENV%-%GLUE-REGION%/".

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

Logging

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 is identical to the log4js-node configuration as described in the log4js-node API documentation.

You can also configure the system logging for io.Connect Desktop. For more details, see the System Logs and the More > APIs > Logging > System Logs sections.

⚠️ 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 each interop-enabled app.

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
  1. Create an index.js file in which import and export the appender:
module.exports = require("@log4js-node/logstash-http");
  1. 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.

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

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:

Property Type Description
"enabled" boolean If true, will enable streaming system log entries. Defaults to false.
"interval" number Interval in seconds at which the log entries will be streamed. Defaults to 120.
"minLevel" "error" | "warn" | "info" The minimum level of the log entries to be streamed. Defaults to "error".

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:

Property Type Description
"moveOldTo" string Absolute path pointing to the location where the log files from the previous session (if any) will be moved on startup of io.Connect Desktop. You can use environment variables. Defaults to "%GLUE-USER-DATA%/logs/archive".
"onStartup" string Specifies how to handle the log files on system startup. Set to "archive" to archive the existing log files. Set to "delete" to delete the existing log files. Set to "keep" (default) to leave the existing log files intact.

Crash Reporter

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:

Property Type Description
"companyName" string Required. The company name to be included in the crash report.
"enabled" boolean Required. If true, the crash reporter will be enabled.
"folderPath" string Required. Location for the crash reporter logging and memory dumps when the output type is set to "local".
"ignoreSystemCrashHandler" boolean If true, crashes generated in the main process won't be forwarded to the system crash handler.
"output" object Required. Output settings for the crash reporter.
"productName" string Required. The product name to be included in the crash report.

The "output" object has the following properties:

Property Type Description
"dumps" object Settings for handling the dump files for crash reports. Available since io.Connect Desktop 9.3.
"backTraceConfig" object Settings for the Backtrace client.
"serverUrl" string URL pointing to the server (or to io.Manager) that will receive the crash report if the output type is set to "server". Required if "type" is set to "server".
"type" "local" | "server" | "backtrace" Type of the crash reporter output. Crash reports can be saved locally, sent to a REST service (including io.Manager), or to a Backtrace server.

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:

Property Type Description
"deleteOnSent" boolean If true, when a dump file is sent, it will be deleted instead of moved to the /sent folder located in the directory containing the dump files.
"limit" number Limit for the number of dump files to keep. On system restart, the oldest files will be deleted until the file limit is met.