Configuration

The definition of an app is a JSON file which allows the app to be accessible to the user from the io.Connect launcher. It consists of base properties which are common for all types of apps, and type-specific properties located under the "details" top-level key in the app definition. The required properties for all types of apps are "name", "type" and "details".

The custom user app definitions should be stored in the %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/apps folder, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO). The files at this location won't be erased or overwritten in case you upgrade your version of io.Connect Desktop.

The definition files of the demo apps that come with the io.Connect Desktop installer are located in the %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config/apps folder.

For more details about the available app definition properties, see the app definition schema.

For details on how to retrieve app definitions at runtime, see the Capabilities > App Management > JavaScript > Retrieving App Definitions section.

For details on how to manage app definitions at runtime, see the Capabilities > App Management > JavaScript > Managing App Definitions section.

Window

Apps of type "window" are web apps which run in an io.Connect Window.

The following is an example definition of a web app:

{
    "name":"my-app",
    "title":"My App",
    "icon": "https://example.com/icon.ico",
    "type": "window",
    "details":{
        "url":"https://example.com",
        "mode": "tab",
        "width": 400,
        "height": 400
    }
}

The "name", "type" and "url" properties are required and "type" must be set to "window". The "url" property points to the location of the web app.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and also as a window title if the web app doesn't have a document title.

The "mode" property defines the mode for the io.Connect Window - "flat" (default), "tab", "html" or "frameless".

For more details about the different window modes, see the Capabilities > Windows > Window Management section.

The supported formats for the app icon are ICO, PNG, APNG and JPG.

For more details about the available definition properties for apps of type "window", see the app definition schema.

Exe

Apps of type "exe" are native apps that can be executed by your OS.

The following is an example definition of a native app:

{
    "name": "my-exe-app",
    "title": "My EXE App",
    "type": "exe",
    "details": {
         "path": "%GDDIR%/../PathToWPFApplication/",
         "command": "WPFApplication.exe",
         "parameters": "param1 param2",
         "width": 400,
         "height": 400
    }
}

The "name", "type" and "path" properties are required and "type" must be set to "exe". The "path" property points to the app working directory. The "command" property accepts the actual command to execute - the EXE file name. To specify command line arguments for starting the app, use the "parameters" property.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title.

⚠️ Note that currently size constraints properties (e.g., "width", "height", "maxWidth", "minHeight", etc.) are only valid for native apps that are also registered programmatically as io.Connect Windows. For details on registering native apps as io.Connect Windows, see the respective sections for .NET, Java, VBA, Delphi and C++.

Available since io.Connect Desktop 9.3

To specify environment variables for the app, use the "env" property of the "details" top-level key:

{
    "details":{
        "env": {
            "myEnvVar": "myEnvVar",
            "myOtherEnvVar": "myOtherEnvVar"
        }
    }
}

For more details about the available definition properties for apps of type "exe", see the app definition schema.

Child Windows

Apps of type "childWindow" are child windows of native apps (i.e., children of apps of type "exe").

The following is an example definition of a child window of a native app:

{
    "name":"my-child-app",
    "title":"My Child App",
    "type": "childWindow",
    "details":{
         "owner":"my-exe-app",
         "width": 400,
         "height": 400
    }
}

The "name", "type" and "owner" properties are required and "type" must be set to "childWindow". The "owner" property must be set to the name of the parent app as specified in its definition.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title.

⚠️ Note that currently size constraints properties (e.g., "width", "height", "maxWidth", "minHeight", etc.) are only valid for native apps that are also registered programmatically as io.Connect Windows. For details on registering native apps as io.Connect Windows, see the respective sections for .NET, Java, VBA, Delphi and C++.

For more details about the available definition properties for apps of type "childWindow", see the app definition schema.

Batch file

Batch files are defined as apps of type "exe" and can be included as io.Connect Desktop apps.

The following is an example definition of a batch file:

{
    "title":"My Batch File",
    "name":"my-batch-file",
    "type": "exe",
    "details":{
         "path":"%GDDIR%/../PathToMyBatchFile/",
         "command": "my-batch-file.bat",
         "parameters": "param1 param2",
         "width": 400,
         "height": 400
    }
}

The "name", "type" and "path" properties are required and "type" must be set to "exe". The "path" property points to the app working directory. The "command" property accepts the actual command to execute - the BAT file name. To specify command line parameters for starting the app, use the "parameters" property.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title.

For more details about the available definition properties for apps of type "exe", see the app definition schema.

ClickOnce

ClickOnce apps can be installed by and run in io.Connect Desktop.

The following is an example definition of a ClickOnce app:

{
    "title": "My ClickOnce App",
    "type": "clickonce",
    "name": "my-clickonce-app",
    "details": {
        "url": "https://example.com/my-clickonce-app.application",
        "width": 1000,
        "height": 400
    }
}

The "name", "type" and "url" properties are required and "type" must be set to "clickonce". The "url" property points to the physical location where the ClickOnce app is deployed and from where it will be installed on the user machine.

The value of the "title" property will be used as a name for the app in the io.Connect launcher and as a window title.

For more details about the available definition properties for apps of type "clickonce", see the app definition schema.

Node.js

io.Connect Desktop supports both locally and remotely hosted apps running in a Node.js environment. It's also possible to specify different Node.js versions for the different apps.

Local Apps

The following is an example definition of a local Node.js app:

{
    "name": "node-server",
    "type": "node",
    "service": true,
    "details": {
        "path": "%GDDIR%/PathToMyServer/index.js",
        "nodeVersion": "16.13.2",
        "showConsole": true
    }
}

The "name", "type" and "path" properties are required and "type" must be set to "node". The "path" property points to a JavaScript file that io.Connect Desktop will execute in a Node.js environment.

Use the "nodeVersion" property to specify a Node.js version for the app.

For more details on how to name and where to place the different Node.js versions, see the Using Different Node.js Versions section.

For more details about the available definition properties for apps of type "node", see the app definition schema.

Remote Apps

⚠️ Note that remotely hosted Node.js apps are subject to certain restrictions when participating in an io.Connect environment. io.Connect Desktop will fetch and execute only the file specified in the app definition, so your remote app must be bundled into a single file and must not depend on any packages with native code that can't be bundled with it.

The following is an example definition of a remote Node.js app:

{
    "name": "node-server",
    "type": "node",
    "service": true,
    "details": {
        "remote": {
            "url": "https://example.com/node-server/bundled.js",
            "noCache": true
        },
        "showConsole": true
    }
}

The "name", "type" and "url" properties are required and "type" must be set to "node". The "url" property points to a single bundled JavaScript file that io.Connect Desktop will fetch and execute in a Node.js environment.

The "service" property can be used to specify that this is a service app and shouldn't be closed when saving and restoring a Layout. The "showConsole" property can be used to specify whether the Node.js console should be visible or not.

The "remote" object has the following properties:

For more details about the available definition properties for apps of type "node", see the app definition schema.

Using Different Node.js Versions

io.Connect Desktop comes with a default Node.js version, but also allows you to specify a Node.js version per app using the "nodeVersion" property of the app definition. The default Node.js environment is named node.exe and is located in the %LocalAppData%/interop.io/io.Connect Desktop/Desktop/assets/node folder. The default path to the Node.js environment is specified using the "nodePath" top-level key in the system.json system configuration file of io.Connect Desktop. All additional Node.js executable files must be placed in the same specified folder and their names must be in the format node-[version].exe (e.g., node-16.13.2.exe), in order for io.Connect Desktop to be able to find the correct version for each Node.js app.

Using io.Connect APIs in a Node.js App

Node.js apps are fully-featured io.Connect clients, so you can use all io.Connect APIs in them.

The only thing to keep in mind when using the Window Management API in a Node.js app is that the io.windows.my() method by design won't work (will return undefined).

Service Window

Service windows are a specific usage of an app of type "window", "exe" or "node". They can provide data and enhance other apps throughout the io.Connect Desktop life cycle. The service window is defined as an app that is hidden and may be auto started when io.Connect Desktop is initiated.

There are different ways to configure a service window, depending on whether you want the window to be automatically started when io.Connect Desktop is initiated. Use a combination of the following top-level app definition properties to specify whether the window should be automatically started, invisible, or hidden from the io.Connect launcher:

⚠️ Note that when using the "service" property, it's pointless to use the "autoStart" top-level key and the "hidden" property of the "details" top-level key, because the "service" property will override any values you may set for them.

The following example demonstrates how to use the "service" and "hidden" top-level keys to configure a service window that will start automatically, will be invisible and hidden from the io.Connect launcher:

{
    "name": "service-window",
    "type": "window",
    "service": true,
    "hidden": true,
    "details": {
        "url": "https://example.com/my-service-window",
    }
}

The "name", "type" and "url" properties are required and "type" must be set to "window". The "url" property points to the location of the web app.

The following example demonstrates how to use the "hidden" and "autoStart" top-level keys and the "hidden" property of the "details" top-level key to configure a service window that will be hidden from the io.Connect launcher, won't start automatically and will be invisible:

{
    "name": "service-window",
    "type": "window",
    "hidden": true,
    "autoStart": false,
    "details": {
        "url": "https://example.com/my-service-window",
        "hidden": true
    }
}

The "hidden" property in the "details" object will make the window invisible, while the "hidden" top-level key will hide the app from the io.Connect launcher so that it won't be accessible to the user.

⚠️ Note that service windows don't participate in Layouts.

Citrix App

A Citrix Virtual App can be defined as an io.Connect app just like any other app. It can participate in the io.Connect environment alongside all other interop-enabled apps and use all io.Connect functionalities. Citrix apps must be defined with type "citrix" and the "name" property of the "details" top-level key must be set with the exact published name of the Citrix app. Use the "parameters" property of the "details" top-level key to pass command line arguments for starting the app.

The following is an example definition of a Citrix app:

{
    "title": "Client List - Citrix",
    "type": "citrix",
    "name": "clientlist-citrix",
    "details": {
        "name": "Client List",
        "parameters": "--mode=3 --clients=http://localhost:22060/clients",
        "left": 100,
        "top": 100,
        "width": 600,
        "height": 700
    }
}

For details on how to configure Citrix apps globally, see the Configuration > System > Citrix Apps section.

For more details about the available definition properties for apps of type "citrix", see the app definition schema.

Workspaces App

Workspaces Apps are web apps of type "workspaces" that can host io.Connect Workspaces.

io.Connect Desktop comes with a Workspaces UI app and a definition file for it named workspaces.json and located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config/apps. If you are creating your custom Workspaces App, make sure to modify or replace this file with your own definition file, or delete it if your app definitions are stored at another location.

The following is an example definition of a Workspaces App:

{
    "title": "Workspaces UI",
    "type": "workspaces",
    "name": "workspaces-demo",
    "icon": "http://localhost:22080/resources/icons/workspaces.ico",
    "details": {
        "layouts": [],
        "url": "http://localhost:3000",
        "updateFrameConstraints": false,
        "framePool": 4
    }
}

The "type" and "name" top-level properties are required and "type" must be set to "workspaces". The "url" and "layouts" properties in the "details" object are optional. Use "url" to specify where the app is hosted, otherwise it will default to the Workspaces App template distributed with io.Connect Desktop. Use the "layouts" property to define Workspace Layouts that will be loaded on startup of the Workspaces App.

The value of the "title" property will be used as a name for the app in the io.Connect launcher.

The "updateFrameConstraints" property by default is set to true, which means that the Frame is restricted to the constraints of the Workspace and the elements inside it. Set to false if you don't want to prevent the user from resizing your custom Workspaces App beyond the constraints of its content.

The "framePool" property can be used to specify how many semi-initialized Frames (3 by default) will be cached in order to provide a smoother experience when dragging out a Workspace from an existing Frame. The higher the number, the higher the memory consumption; the lower the number, the higher the risk of rejection due to an empty pool when dragging out a Workspace.

For more details about the available definition properties for apps of type "workspaces", see the Capabilities > Windows > Workspaces section and the app definition schema.

Web Group App

A Web Group App is a web app used in io.Connect Desktop for handling io.Connect web groups. It's "type" property must be set to "webGroup".

⚠️ Note that, by default, io.Connect Desktop will search for a registered app with the name "web-group-application" and if one is available, will use it. If no such app is found, the first available app definition of type "webGroup" will be used. io.Connect Desktop expects only one app definition for a Web Group App - i.e., one configuration file with "type" property set to "webGroup". If multiple Web Group App definitions are present, the first one will be used.

io.Connect Desktop comes with a Web Group App and a definition file for it named webGroup.json and located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config/apps. If you are creating your custom Web Group App, make sure to modify or replace this file with your own definition file, or delete it, if your app definitions are stored at another location.

The following is an example definition of a Web Group App:

{
    "name": "web-group-app",
    "type": "webGroup",
    "hidden": true,
    "details": {
        "url": "http://localhost:3000/",
        "autoOpenDevTools": true,
        "preloadScripts": ["https://example.com/my-script.js"],
        "pool": {
            "min": 5
        }
    }
}

The "url" property is required and must point to the location of your custom Web Group App.

Use the "autoOpenDevTools" property to automatically open the Chrome Dev Tools (disabled by default) when debugging your Web Group App.

Use the "preloadScripts" property to specify a list of URLs pointing to scripts that will be loaded and executed before loading the Web Group App.

Use the "pool" property to specify the minimum number of cached Web Group App instances (3 by default) used for improving group performance and user experience. The higher the number, the more memory will be consumed; the lower the number, the higher the chance to experience delay during web group operations.

The "hidden" property is set to true in order to hide the Web Group App from the io.Connect launcher, because this is a service app used directly by io.Connect Desktop to handle io.Connect Window groups.

io.Connect Desktop is configured to use the Floating Toolbar as a default shell app. To replace it with your own shell app, or to define an additional shell app, use the "shell" top-level key:

{
    "shell": true
}

To start your shell app automatically with the io.Connect framework, use the "autoStart" top-level key:

{
    "autoStart": true
}

If you want to disable the embedded shell app (the default io.Connect launcher) in order to use your own shell app, you must set to false the "useEmbeddedShell" top-level key in the system.json system configuration file of io.Connect Desktop:

// In `system.json`.
{
    "useEmbeddedShell": false
}

You may also consider providing settings for running multiple instances of your shell app, defining your shell app as critical for the io.Connect platform, disabling the default system buttons, providing placement or docking settings, enabling jump lists, allowing users to pin your shell app to the taskbar, ignoring the App Default Layout, providing zoom settings, custom properties, and more.

The following is an example definition of a shell app:

{
    "title": "My Shell App",
    "type": "window",
    "name": "my-shell-app",
    "shell": true,
    "autoStart": true,
    "allowMultiple": false,
    "ignoreSavedLayout": true,
    "details": {
        "url": "https://my-shell-app.com",
        "mode": "frameless",
        "allowClose": false,
        "allowMaximize": false,
        "allowMinimize": false,
        "allowCollapse": false,
        "zoom": {
            "enabled": false
        },
        "taskbar": {
            "allowPin": true
        },
        "jumpList": {
            "enabled": true
        }
    },
    "customProperties": {
        "myCustomProp": 42
    }
}

The App Default Layout contains information about:

• the last saved window bounds - size and location;
• the window state - maximized, minimized or normal and whether it's collapsed;
• the default window context;

When an app is started for the first time by io.Connect Desktop, the size and the location of the app window are determined by the bounds set in the app definition file (or by the default bounds, if none are specified in the app definition). When the user moves or resizes the app window and closes it, the new bounds are automatically saved as an App Default Layout and the next time the app is started, its window will be loaded using these bounds.

Sometimes, it may be necessary to bypass the App Default Layout - e.g., if somehow the app window has been saved outside the visible monitor area, or you simply want your app to always start with certain bounds, state or context despite the user interactions.

To bypass the App Default Layout only once, press and hold the SHIFT key and click on the app in the io.Connect launcher to start it.

To instruct io.Connect Desktop to always ignore the App Default Layout for your app, use the "ignoreSavedLayout" top-level key in the app definition file:

{
    "ignoreSavedLayout": true
}

It's possible to define custom properties for your app in order to use them at runtime via the App Management API for specific UI or internal operations. To define custom properties, use the "customProperties" top-level key:

{
    "customProperties": {
        "myCustomProp": "forty-two",
        "myOtherCustomProp": 42
    }
}

For details on how to access the custom properties at runtime, see the Capabilities > App Management section.

Apps can be grouped in folders and subfolders in the io.Connect launcher via configuration:

To group apps in folders or subfolders, use the "customProperties" top-level key in the app definition file. Use / to specify subfolders:

{
    "name":"ClientList",
    "title":"Client List",
    "icon": "http://localhost:22080/resources/icons/logo.ico",
    "type": "window",
    "customProperties": {
        "folder": "Clients/Corporate"
    },
    "details":{
         "url":"http://localhost:3000/client-list"
    }
}

To control whether an app will be available in the Workspace "Add App" menu (the dropdown that appears when you click the "+" button to add an app), use the "includeInWorkspaces" property of the "customProperties" top-level key in your app definition:

{
    "customProperties": {
        "includeInWorkspaces": true
    }
}

By default, this property is set to false, which means that by default apps aren't visible in the "Add App" dropdown menu of the Workspaces App.

To prevent an app from participating in Workspaces, set the "allowWorkspaceDrop" top-level key in the app definition to false:

{
    "allowWorkspaceDrop": false
}

By default, this property is set to true, which means that by default users are able to drag and drop apps in a Workspace.

By default, multiple instances of an io.Connect app can be started. To prevent users from starting multiple instances of an app, use the "allowMultiple" top-level key:

{
    "allowMultiple": false
}

To specify whether an app instance is to be closed when hibernating Global Layouts, Workspaces or window groups, use the "closeOnHibernate" top-level key:

{
    "closeOnHibernate": false
}

By default, this property is set to true. Set to false to prevent the app 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 on a global system level, 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 globally, see the Configuration > System > App Settings > Hibernation section.

To specify a list of keywords for the app, which can be accessed through the JavaScript App Management API and used for filtering and searching for apps, use the "keywords" top-level key:

{
    "keywords": ["keyword1", "keyword2"]
}

Accessing the list of app keywords:

const keywords = io.appManager.application("MyApp").keywords;

The boot sequence of io.Connect Desktop is divided into four stages executed in the following order: "core" stage, "pre-sso" stage, "post-sso" stage and "user" stage. You can configure your system or regular user apps to start at the desired stage with the desired priority. You can also specify whether io.Connect Desktop must wait for the app to initialize before continuing the boot sequence.

To specify the priority with which an app will be started in the boot sequence of the io.Connect Desktop platform, use the "runPriority" top-level key. It accepts either an object or a number as a value.

The "runPriority" object has the following properties:

Stages

⚠️ Note that the boot sequence stages have different limitations related to which types of apps you can start in a stage, and to having access to the io.Connect APIs and the user identity. You should take this into account when configuring the boot sequence options for your apps, depending on the role of the app in your system and what functionality or information it requires to initialize properly.

The following boot sequence stages are available:

For details on how to define system app stores, see the Configuration > System > System App Stores section.

The following example demonstrates how to set the boot sequence priority of an app that will be started with high priority in the "pre-sso" stage:

{
    "runPriority": {
        "stage": "pre-sso",
        "priority": 100
    }
}

The "runPriority" property can also be set with a number. In this case, the default is 0 and the app can be started only at the "core" stage.

Waiting for App Initialization

When setting the boot sequence for apps, you can use the "waitForInitialization" property to specify whether the io.Connect platform must wait for the app to initialize before continuing the boot sequence:

{
    "runPriority": {
        "stage": "pre-sso",
        "priority": 100,
        "waitForInitialization": true
    }
}

Available since io.Connect Desktop 9.2

In addition to a boolean value, the "waitForInitialization" property accepts also the following string values:

The following example demonstrates how to configure an app to be started at the "user" stage and to instruct the platform to wait for an explicit signal from the app that it's initialization has been completed:

{
    "runPriority": {
        "stage": "user",
        "priority": 101,
        "waitForInitialization": "appSignal"
    }
}

For details on how to send a signal to io.Connect Desktop that your app has been initialized, see the Capabilities > More > Features > Boot Sequence section.

For details on how to receive a signal from io.Connect Desktop when a batch of apps with the same run priority starts and completes loading, see the Capabilities > More > Features > Boot Sequence section.

io.Connect Desktop can download, unarchive and run archived web or native apps hosted at a remote location. To specify the location of your archived app and headers for the request, use the "asset" top-level key.

The "asset" object has the following properties:

The following example demonstrates how to define the location of a remote archived web app, specify headers for the request, include the Cache-Control: no-cache header, and define the app entry point:

{
    "name": "my-archived-web-app",
    "type": "window",
    "asset": {
        "src": "https://example.com/my-archived-web-app.zip",
        "headers": [
            {
                "name": "header-name",
                "value": "header-value"
            }
        ],
        "noCache": true
    },
    "details": {
        "url": "$ASSET_LOCATION$/home.html"
    }
}

⚠️ Note that if you don't specify an entry point for your web app in the "url" property, io.Connect Desktop will try to access it via an index.html file.

The following example demonstrates how to define the location of a remote archived native app:

{
    "name": "my-archived-native-app",
    "type": "exe",
    "asset": {
        "src": "http://example.com/my-archived-native-app.zip"
    },
    "details": {
        "command": "MyArchivedNativeApp.exe",
        "path": "$ASSET_LOCATION$"
    }
}

The default location for downloading remote apps is %LocalAppData%/interop.io/io.Connect Desktop/UserData/<ENV>-<REG>/remoteApps/<app-name>, where <ENV>-<REG> represents the environment and region of io.Connect Desktop (e.g., DEMO-INTEROP.IO) and <app-name> is the name of the app as defined in its configuration. You can use the $ASSET_LOCATION$ macro pointing to the default location of the extracted app when defining the "path" or the "url" property of your app, depending on its type.

For details on specifying locations for the system folders of io.Connect Desktop, see the Developers > Configuration > System section.

Available since io.Connect Desktop 9.5

Executing JavaScript code within the context of the current or another io.Connect Window is disabled by default. To enable it, set the "allowScriptExecution" top-level key to true:

{
    "allowScriptExecution": true
}

For details on how to execute JavaScript code within the context of the current or another io.Connect Window, see the Capabilities > Windows > Window Management section.

Available since io.Connect Desktop 9.6

You can define an app as critical for the io.Connect Desktop platform. If a critical app fails to load, the platform will shutdown and display an error message. To define an app as critical, set the "critical" top-level key to true:

{
    "critical": true
}

Channel Selector

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 of the "details" top-level key:

{
    "details": {
        "channelSelector": {
            "enabled": true,
            "type": "single",
            "channelId": "Black"
        }
    }
}

The "channelSelector" object has the following properties:

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

⚠️ Note that the "allowChannels", "channelId" and "readOnlyChannelSelector" properties found under the "details" top-level key have been deprecated. To provide settings for the Channel Selector in your apps, use the "channelSelector" object instead.

For details on how to configure the Channel Selector globally, see the Configuration > System > Window Settings > Channels section.

Inheriting Channels

Available since io.Connect Desktop 9.3

To make apps opened from your app inherit its current Channel, use the "childrenInheritChannel" top-level property. It accepts a Boolean value or a list of app names specifying the child apps that will inherit the current Channel:

{
    "childrenInheritChannel": true
}

// Or:

{
    "childrenInheritChannel": ["my-app", "my-other-app"]
}

⚠️ Note that if the definition of the child app contains a "channelId" property, it will be joined to the Channel specified in its definition and not to the current Channel of the parent.

Preload Scripts

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

To specify preload scripts per app, use the "preloadScripts" property of the "details" top-level key:

{
    "details": {
        "preloadScripts": {
            "scripts": [
                "https://my-domain.com/my-script.js",
                "https://my-domain.com/my-other-script.js"
            ],
            "useBase64PreloadScripts": false
        }
    }
}

The "preloadScripts" property accepts as a value a list of preload script URLs, or an object with the following properties:

The "useBase64PreloadScripts" property allows you to control how io.Connect Desktop will import preload scripts. To improve this behavior, it's recommended to set the "useBase64PreloadScripts" property to false.

Available since io.Connect Desktop 9.1

The "scripts" property of the configuration object for the "preloadScripts" key accepts also an array of objects which you can use to specify detailed settings for the preload scripts:

{
    "details": {
        "preloadScripts": {
            "scripts": [
                {
                    "url": "https://my-domain.com/my-script.js",
                    "fallback": "https://my-domain.com/my-fallback-script.js",
                    "timeout": 5000
                },
                {
                    "url": "https://my-domain.com/my-other-script.js",
                    "fallback": "https://my-domain.com/my-other-fallback-script.js",
                    "timeout": 5000
                }
            ],
            "useBase64PreloadScripts": false
        }
    }
}

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

For details on how to configure preload scripts globally, see the Configuration > System > Window Settings > Preload Scripts section.

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 CSS files to inject in your app, use the "injectedStyles" property of the "details" top-level key:

{
    "details": {
        "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 globally, see the Configuration > System > Window Settings > Injecting Styles section.

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.

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 of the "details" top-level key.

The following example demonstrates how to persist the current URL of the web app only when it participates in Global Layouts and Workspaces, and how to persist its current window title in all types of Layouts:

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

The "saveInLayout" object has the following properties:

For details on how to control saving web app data in Layouts globally, see the Configuration > System > Window Settings > 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 of the "details" top-level key.

The following example demonstrates how to persist the command and the parameters with which the app was started when it's saved in a Layout:

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

The "saveInLayout" object has the following properties:

For details on how to control saving native app data in Layouts globally, see the Configuration > System > Window Settings > Persisting Data in Layouts > Native Apps section.

⚠️ 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 settings per app, use the "syncTitleWithDocumentTitle" property of the "details" top-level key:

{
    "details": {
        "syncTitleWithDocumentTitle": false
    }
}

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 globally, see the Configuration > System > Window Settings > Synchronizing App Titles section.

⚠️ 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 of the "details" top-level key:

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

{
    "details": {
        "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:

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 of the "details" top-level key:

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

For a list of the supported options, see the Capabilities > Windows > Window Management section.

For details on how to control the behavior for handling the browser window.open() globally, see the Configuration > System > Window Settings > Handling the Browser window.open() section.

Available since io.Connect Desktop 9.2

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

io.Connect Desktop can try to reload web apps in case of load failure. To specify options for reloading an app, use the "reloadOptions" property of the "details" top-level key:

{
    "details": {
        "reloadOptions": {
            "maxAttempts": 5,
            "timeout": 2000
        }
    }
}

The "reloadOptions" object has the following properties:

Available since io.Connect Desktop 9.2

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

To specify navigation settings for the current window, use the "navigation" property of the "details" top-level key:

{
    "details": {
        "navigation": {
            "allowed": "^https:\/\/(www\\.)?my-org\\.com\\/"
        }
    }
}

The "navigation" object has the following properties:

Available since io.Connect Desktop 9.2

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

To specify settings for for opening new windows from the current window, use the "windowOpen" property of the "details" top-level key:

{
    "details": {
        "windowOpen": {
            "allowed": "^https:\/\/(www\\.)?my-org\\.com\\/"
        }
    }
}

The "windowOpen" object has the following properties:

Available since io.Connect Desktop 9.2

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

Animations and timers for web apps running in the background can be throttled. Background throttling is enabled by default. To disable it, use the "backgroundThrottling" property of the "details" top-level key:

{
    "details": {
        "backgroundThrottling": false
    }
}

Available since io.Connect Desktop 9.3

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

To configure whether the app window should snap to the edges of the screen when the user moves it within a specified distance from a screen edge, use the "snapToScreenEdges" property of the "details" top-level key:

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

The "snapToScreenEdges" object has the following properties:

For details on how to configure snapping to screen edges globally, see the Configuration > System > Window Management > Snapping to Screen Edges section.

⚠️ 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 of the "details" top-level key:

{
    "details": {
        "cascade": {
            "offset": 30
        }
    }
}

The "cascade" object has the following properties:

For details on how to configure window cascading globally, see the Configuration > System > Window Settings > Cascading Windows section.

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

The placement settings allow an io.Connect Window to occupy a specific position on the screen. This position can be set only once - initially, on window creation, or can be kept throughout the entire lifetime of the window. The placement feature solves the problem of reacting adequately to changes of the screen resolution or the size of the app virtualization window hosting the io.Connect Window, ensuring that the io.Connect Window always stays at the desired screen position and with the desired dimensions. This is especially useful if you are developing a toolbar or a notifications panel that shouldn't be resized by the users and must always stay at the same position on the screen.

To specify window placement settings, use the "placement" property of the "details" top-level key. The following example demonstrates how to place a window at the top center of the screen. The window will be 50 pixels high, its width will be 30% of the screen width, and there will be a 10 pixel margin between the top edge of the screen and the top of the window:

{
    "details": {
        "placement": {
            "snapped": true,
            "verticalAlignment": "top",
            "horizontalAlignment": "center",
            "height": 50,
            "width": "30%",
            "top": 10
        }
    }
}

The "placement" object has the following properties:

⚠️ Note that in order for the bounds specified in the placement settings to be respected when the app is restarted, you must set the "ignoreSavedLayout" top-level key to true, otherwise the App Default Layout, in which the last known bounds of the window are recorded, will take precedence when restoring the window.

For details on how to specify placement settings programmatically, see the Capabilities > Windows > Window Management section.

Available since io.Connect Desktop 9.1

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

io.Connect Windows can be docked to a specified edge on the screen. Docking is supported only for HTML and frameless windows.

⚠️ Note that if you want to dock your window, it's strongly recommended to define it as a frameless window instead of an HTML one. The implementation for supporting frameless windows is much more lightweight and is less likely to cause issues with special window functionalities like docking.

⚠️ Note that by design docked windows don't participate in Global Layouts.

Docking is disabled by default. To enable it and to specify docking placement settings, use the "docking" property of the "details" top-level key. The following example demonstrates how to allow docking for a frameless window at the top and the left of the screen. It will have an initial docking position, specific height when docked at the top and width when docked at the left, and will claim the screen area it occupies:

{
    "details": {
        "mode": "frameless",
        "docking": {
            "enabled": true,
            "claimScreenArea": true,
            "initialPosition": "top",
            "allowedPositions": [ "top", "left"],
            "height": 80,
            "width": 80
        }
    }
}

The "docking" object has the following properties:

For details on how to specify docking placement settings programmatically, see the Capabilities > Windows > Window Management section.

Available since io.Connect Desktop 9.5

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

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

To make your tab window pinned, use the "isPinned" property of the "details" top-level key:

{
    "details": {
        "isPinned": true
    }
}

For details on how to pin and unpin tab windows programmatically, see the Capabilities > Windows > Window Management section.

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

To hide the group header of apps when they form a window group, use the "hideGroupHeader" property of the "details" top-level key:

{
    "details": {
        "hideGroupHeader": true
    }
}

⚠️ Note that this property is valid only for web apps (apps of type "window"). If a web app with a "hideGroupHeader" property set to true forms a window group with one or more web apps with a "hideGroupHeader" property set to false, or 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 globally for web apps, see the Configuration > System > Window Settings > 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.

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

To create groups of windows that will stick only to each other, but not to other windows that don't have the same sticky group, use the "stickyGroup" property of the "details" top-level key:

{
    "details": {
        "stickyGroup": "my-sticky-group"
    }
}

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

⚠️ Note that the standard system buttons aren't available for frameless windows.

The standard system buttons "Minimize", "Maximize", and "Close" are enabled by default for all for io.Connect Windows. To disable any of the standard system buttons, use the "allowMinimize", "allowMaximize", and "allowClose" properties of the "details" top-level key:

{
    "details": {
        "allowClose": false
    }
}

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

⚠️ Note that the "Collapse & Expand" button isn't available for frameless windows.

io.Connect Windows can be collapsed and expanded, including when in a window group:

By default, the button for collapsing and expanding windows is disabled. To enable it, use the "allowCollapse" property of the "details" top-level key:

{
    "details": {
        "allowCollapse": true
    }
}

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

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

To hide the "Close" button displayed on the window tab, use the "allowTabClose" property of the "details" top-level key:

{
    "details": {
        "mode": "tab",
        "allowTabClose": false
    }
}

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

⚠️ Note that the "Sticky" button isn't available for frameless windows.

To enable the "Sticky" button for an app, set the "showStickyButton" property of the "details" top-level key to true:

{
    "details": {
        "showStickyButton": true
    }
}

For details on how to enable or disable the "Sticky" button globally, see the Configuration > System > Window Settings > Sticky Button section.

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

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

⚠️ Note that the "Feedback" button isn't available for frameless windows.

To enable the "Feedback" button for an app, set the "showFeedbackButton" property of the "details" top-level key to true:

{
    "details": {
        "showFeedbackButton": true
    }
}

Use the "supportEmails" top-level key to specify the emails of the app owners. The email addresses defined in this property will be added to the Feedback Form if it has been triggered from that app:

{
    "supportEmails": ["app.owner1@example.com", "app.owner2@example.com"]
}

For details on how to enable or disable the "Feedback" button globally, see the Configuration > System > Window Settings > Feedback Button section.

Available since io.Connect Desktop 9.2

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

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

⚠️ Note that the "Clone" button isn't available for frameless windows.

To enable the "Clone" button for an app, set the "showCloneButton" property of the "details" top-level key to true:

{
    "details": {
        "showCloneButton": true
    }
}

For details on how to enable or disable the "Clone" button globally, see the Configuration > System > Window Settings > Clone Button section.

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

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

Combining Icons

To specify how the taskbar icons of your apps will be combined when the Windows taskbar is set to combine icons, use the "combineIcons" property of the "taskbar" object under the "details" top-level key:

{
    "details": {
        "taskbar": {
            "combineIcons": "sameApp"
        }
    }
}

The "combineIcons" property accepts as a value "sameIcon" (default), "sameApp", or "never". If set to "sameIcon", will combine the icons of all instance of all apps that use the same taskbar icon. If set to "sameApp", will combine only the icons of instances of the same app. If set to "never", the icons of io.Connect apps won't be combined in the taskbar.

Pinning Shell Apps

To allow a shell app to be pinned to the Windows taskbar, use the "allowPin" property of the "taskbar" object under the "details" top-level key:

{
    "details": {
        "taskbar": {
            "allowPin": true
        }
    }
}

⚠️ 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 per app, use the "contextMenu" property of the "details" top-level key:

{
    "details": {
        "contextMenu": {
            "enabled": false
        }
    }
}

For details on how to configure the context menu globally, see the Configuration > System > Window Settings > Context Menu section.

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

To configure the jump list for an app, use the "jumpList" property of the "details" top-level key:

{
    "details": {
        "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 globally, see the Configuration > System > Window Settings > Jump List section.

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

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

To configure the behavior of an app when downloading files, use the "downloadSettings" property of the "details" top-level key:

{
    "details": {
        "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 globally, see the Configuration > System > Window Settings > Downloads section.

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

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

To set the zoom behavior of an app, use the "zoom" property of the "details" top-level key:

{
    "details": {
        "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 globally, see the Configuration > System > Window Settings > Zooming section.

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

⚠️ 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 for an app, use the "print" property of the "details" top-level key.

The following is an example configuration for printing:

{
    "details": {
        "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 for an app, use the "printToPdfSettings" property of the "details" top-level key.

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

{
    "details": {
        "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 globally, see the Configuration > System > Window Settings > Printing section.

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

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

To specify on app level a custom User-Agent request header to be sent when connecting to a server, use the "userAgent" property of the "details" top-level key:

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

For details on how to control the custom User-Agent request header globally, see the Configuration > System > Window Settings > User Agent section.

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

Resizing io.Connect Windows in HTML mode can be enabled or disabled by using the "hasSizeAreas" property of the "details" top-level key:

{
    "name": "My App",
    "type": "window",
    "details": {
        "url": "https://my-app.com",
        "mode": "html",
        "hasSizeAreas": false
    }
}

Available since io.Connect Desktop 9.1

The "hasSizeAreas" property can be used for all io.Connect Window modes. This allows you to add resizing areas even to the io.Connect frameless windows so that the user can resize them manually:

{
    "name": "My App",
    "type": "window",
    "details": {
        "url": "https://my-app.com",
        "mode": "frameless",
        "hasSizeAreas": true
    }
}

⚠️ Note that, by default, "hasSizeAreas" is set to true for flat, tab and HTML windows, and to false for frameless windows.

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

To upload files, send POST data from web apps, or specify other options for loading the app URL, use the "urlLoadOptions" property of the "details" top-level key:

{
    "details": {
        "urlLoadOptions": {
            "extraHeaders": "Content-Type: application/x-www-form-urlencoded",
            "postData": [
                {
                    "type": "base64",
                    "data": "base64-encoded-string"
                }
            ]
        }
    }
}

The "urlLoadOptions" object has the following properties:

A free io.Connect Configuration Validator tool is available and you can install it as a Visual Studio Code extension. The validator tool has several functionalities:

• Performs real time validation of JSON files on save or change of the active editor.
• Can generate template configurations for different types of io.Connect apps - "window", "exe", "node" and Service Windows.
• Can deploy (copy) the created configuration to a specified app definition folder.

For more detailed information, see the README file of the io.Connect Configuration Validator.