Configuration

App Definition

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

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 window title and also as a name for the app in the io.Connect launcher. 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 > Overview > Window Modes 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 App",
    "type": "exe",
    "details":{
         "path":"%GDDIR%/../PathToWPFApplication/",
         "command": "WPFApplication.exe",
         "parameters": "param1 param2",
         "width": 400,
         "height": 400
    }
}

⚠️ Note that currently size constraints properties (e.g., "width", "height", "maxWidth", "minHeight", etc.) are only valid for EXE apps that are also registered programmatically as io.Connect Windows.

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 parameters for starting the app, use the "parameters" property.

For more details about the available definition properties for apps of type "exe", 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.

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,
        "appParameters": [
            {
                "name": "p1",
                "value": "customParameter"
            }
        ]
    }
}

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 "appParameters" property is an array of objects defining custom parameters that your app can access at runtime through io.GDStartingContext.ApplicationConfig.Details.AppParameters. Each object sets the "name" and the "value" of a custom parameter.

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:

Property Type Description
"headers" object[] Set of headers that will be added to the request for downloading the script file. Each object in the array must have valid "name" and "value" properties holding the header name and the respective value.
"noCache" boolean If true, the Cache-control: no-cache header will be added.
"url" string The URL to the JavaScript file to be fetched and executed in Node.js.

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.

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:

Property Type Description
"autoStart" boolean If true, the window will be started automatically on io.Connect Desktop startup.
"details" object Use the "hidden" Boolean property of the "details" top-level key to set the window visibility. If true, the window will be invisible.
"hidden" boolean If true, the app won't be available in the io.Connect launcher.
"service" boolean If true, both the "autoStart" top-level key and the "hidden" property of the "details" top-level key will be overridden and set to true. The window will be invisible and will start automatically when io.Connect Desktop is initiated.

⚠️ 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 aren't closed when restoring a Layout.

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 as a first-class citizen 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
    },
    "customProperties": {}
}

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 "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 app definition schema.

Multiple Workspaces Apps

It's possible to use more than one version of the Workspaces App when your various business use-cases demand different Workspaces App designs or functionalities.

Each Workspaces App that you want to use must have a separate configuration file with its "type" property set to "workspaces". You can use the "default" property of the "details" top-level key to specify a default Workspaces app that will handle all Workspaces whose Layouts don't contain information about which Workspaces App to target (or when the targeted Workspaces App is missing) when creating or restoring them.

The following example demonstrates how to define two different Workspaces Apps, the first of which will be the default one:

[
    {
        "title": "Workspaces One",
        "type": "workspaces",
        "name": "workspaces-one",
        "details": {
            "default": true,
            "layouts": [],
            "url": "http://localhost:3000"
        },
        "customProperties": {}
    },
    {
        "title": "Workspaces Two",
        "type": "workspaces",
        "name": "workspaces-two",
        "details": {
            "layouts": [],
            "url": "http://localhost:3001"
        },
        "customProperties": {}
    }
]

Defining Workspace Layouts

Use the "layouts" property of the "details" top-level key to predefine Workspace Layouts that will be loaded automatically when the Workspace App starts:

{
    "details": {
        "layouts": [
            // Standard Workspace Layout definition.
            {
                "children": [
                    {
                        "type": "column",
                        "children": [
                            {
                                "type": "group",
                                "children": [
                                    {
                                        "type": "window",
                                        "appName": "clientlist"
                                    }
                                ]
                            },
                            {
                                "type": "group",
                                "children": [
                                    {
                                        "type": "window",
                                        "appName": "clientportfolio"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            },

            // Or a simpler Workspace Layout definition for an already existing Workspace Layout.
            {
                "layoutName": "My Workspace"
            }
        ]
    }
}

Use the "config" property of the standard Workspace Layout object or the "restoreConfig" property of the simpler object to pass context to the Workspace or to hide or show its tab header:

{
    "details": {
        "layouts": [
            // Standard Workspace Layout definition.
            {
                "children": [],
                "config": {
                    "noTabHeader": true,
                    "context": { "io" : 42 }
                }
            },

            // Or a simpler Workspace Layout definition for an already existing Workspace Layout.
            {
                "layoutName": "My Workspace",
                "restoreConfig": {
                    "noTabHeader": true,
                    "context": { "io" : 42 }
                }
            }
        ]
    }
}

Hiding the Workspace tab header with the "noTabHeader" property prevents the user from manipulating the Workspace through the UI and allows for the Workspace to be controlled entirely through API calls. For instance, a Workspace may be tied programmatically to certain logic designed to manage its state without any user interaction.

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",
    "title": "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.

App Default Layout

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
}

Grouping Apps

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

App Grouping

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

Excluding & Including Apps in Workspaces

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.

Keywords

Use the "keywords" top-level key 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:

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

Accessing the list of app keywords:

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

Boot Sequence

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:

Property Type Description
"priority" number Number determining the priority with which the system app will be started at the specified stage of the boot sequence of the platform. The greater the number, the greater the priority of the app. You can use decimal numbers to allow for more flexibility when reordering the boot sequence. Apps with the same priority will be started simultaneously. Set to 0 for lowest priority.
"stage" "core" | "pre-sso" | "post-sso" | "user" Boot sequence stage at which to start the system app.
"timeout" number Interval in milliseconds to wait for the system app to initialize.
"waitForInitialization" boolean Specifies whether the platform must wait for the app to initialize before continuing the boot sequence.

Stages

⚠️ Note that the boot sequence stages have different limitations in related to which types of apps you can start in it, access to the io.Connect APIs and the user identity. You should take these 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:

Stage Description
"core" This is the initial stage in which all critical system apps of io.Connect Desktop (e.g., io.Connect Gateway, HTTP servers) and the ones defined in the system app stores are started. At this stage, apps don't yet have access to the io.Connect APIs and the user identity, and only apps of type "exe" and "node" can be started.
"pre-sso" At this stage, apps will have access to the io.Connect APIs, but not the user identity, and apps of type "window" can be started too. This means that at this stage you can initialize apps that require the io.Connect APIs, but don't need the specific set of app definitions and Layouts for the current user in order to function properly. Apps started at this stage must be defined in system app stores or in memory.
"post-sso" At this stage, apps will have access to both the io.Connect APIs and the user identity. Apps started at this stage must be defined in system app stores or in memory and will run before the auto started apps from the regular user-specific app stores.
"user" At this stage, apps defined in the regular user-specific app stores and apps from the in memory store will be started. Available since io.Connect Desktop 9.2.

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:

Value Description
"appSignal" The app must explicitly send a signal to the platform that the necessary initialization has been completed.
"interopReady" The platform will be automatically signaled when the Interop library has been fully initialized. Default for apps defined in regular user-specific app stores.
"no" The platform won't wait for the app to initialize before continuing the boot sequence. Default for apps defined in system app stores.

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

To send a signal from your app that it has been fully initialized, you must invoke the already registered by the platform "T42.GD.Execute" Interop method and pass the "signal-app-ready" command as an argument:

const methodName = "T42.GD.Execute";
const args = { command: "signal-app-ready" };

await io.interop.invoke(methodName, args);

Remote Archived Apps

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 "assets" top-level key.

The "assets" object has the following properties:

Property Type Description
"headers" object[] Array of objects, each with required "name" and "value" properties, defining the headers that will be added to the request for downloading the archived app.
"noCache" boolean If true, the Cache-Control: no-cache header will be added.
"src" string URL pointing to the location of the archived app that will be downloaded and extracted.

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.

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.

Web Apps

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

To persist the current URLs and titles of web apps when a Layout is saved (App Default, Global Layouts, or Workspaces), use the "saveCurrentUrlInLayout" and "saveCurrentTitleInLayout" properties of the "details" top-level key respectively. Both accept either a Boolean value, or an array of strings specifying the Layout types for which the data will be persisted. The possible string values are "ApplicationDefault", "Global", and "Workspace". Persisting the current URL of a web app allows users to automatically restore its last saved navigation state.

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": {
        "saveCurrentUrlInLayout": ["Global", "Workspace"],
        "saveCurrentTitleInLayout": true
    }
}

Available since io.Connect Desktop 9.2

To persist data for web apps in Layouts, it's now recommended to 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:

Property Type Description
"title" boolean | string[] 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".
"url" boolean | string[] 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".

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:

Property Type Description
"command" boolean 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.
"parameters" boolean 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.

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

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 object value for the "nativeWindowOpen" property has the following properties:

Property Type Description
"mode" string Must be set to "window".
"outlivesOpener" boolean If true, will prevent child windows from being closed when their parent is closed.

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.

Reload Options

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:

Property Type Description
"maxAttempts" number Maximum number of times to attempt reloading the window.
"timeout" number Interval in milliseconds at which to attempt to reload the window.

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:

Property Type Description
"allowed" string Regular expression that will be matched against the URL when the window navigates. If the new URL doesn't match the expression, navigation will be blocked.

Opening New Windows

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:

Property Type Description
"allowed" string Regular expression that will be matched against the URL when opening a new window from the current app. If the URL doesn't match the expression, opening the new window will be blocked.

Background Throttling

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

Cascading Windows

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce" 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 of the "details" top-level key:

{
    "details": {
        "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 configure window cascading globally, see the Configuration > System > Window Settings > Cascading Windows section.

Placement

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

Property Accepts Description
"bottom" number | string Bottom margin for the placed window. Use a number to define the value in pixels, or use a string to define the value in pixels or in percentage of the screen - e.g., "10px" or "10%".
"display" string The identifying number of the monitor (e.g., "1", "2", "3" or "main").
"height" number | string Defines the window height. Use a number to define the value in pixels, or use a string to define the value in pixels or in percentage of the screen - e.g., "10px" or "10%".
"horizontalAlignment" "left" | "right" | "center" | "stretch" Defines a horizontal alignment configuration. If "verticalAlignment" is set, then "horizontalAlignment" will default to "stretch".
"left" number | string Left margin for the placed window. Use a number to define the value in pixels, or use a string to define the value in pixels or in percentage of the screen - e.g., "10px" or "10%".
"right" number | string Right margin for the placed window. Use a number to define the value in pixels, or use a string to define the value in pixels or in percentage of the screen - e.g., "10px" or "10%".
"snapped" boolean Required. If true, the io.Connect Window will remain snapped to the specified screen position even in cases of resolution changes, window visibility changes or when the app virtualization window hosting the io.Connect Window has been resized. However, this doesn't include any API calls or manual user interaction which affect the window placement or bounds. If false, the window will be positioned at the specified screen location only once when created.
"top" number | string Top margin for the placed window. Use a number to define the value in pixels, or use a string to define the value in pixels or in percentage of the screen - e.g., "10px" or "10%".
"verticalAlignment" "top" | "bottom" | "center" | "stretch" Defines a vertical alignment configuration. If "horizontalAlignment" is set, then "verticalAlignment" will default to "stretch".
"width" number | string Defines the window width. Use a number to define the value in pixels, or use a string to define the value in pixels or in percentage of the screen - e.g., "10px" or "10%".

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

Docking

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.

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:

Property Accepts Description
"allowedPositions" string[] Allowed positions for docking the app. Available positions are "top", "bottom", "left", and "right". Defaults to ["top", "bottom"]
"claimScreenArea" boolean If true, the app will claim the area it occupies on the screen when docked, in effect, reducing the working area of the screen.
"enabled" boolean If true, docking will be enabled for the app.
"height" number Height in pixels for the app when docked at the top or the bottom screen edge.
"initialPosition" "top" | "bottom" | "left" | "right" Initial docking position for the app.
"width" number Width in pixels for the app when docked at the left or the right screen edge.

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

Group Header

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

Sticky Group

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

Sticky Button

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

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

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

Sticky Button

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.

Feedback Button

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

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

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

Feedback Button

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.

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" and "citrix".

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

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

Clone Button

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.

Collapse & Expand

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

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

Collapse Expand

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

Jump List

⚠️ Note that this property is valid only for apps of type "window", "exe", "clickonce" 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:

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

Downloads

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

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

Zooming

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

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 globally, see the Configuration > System > Window Settings > 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 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"
        }
    }
}
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 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
        }
    }
}
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 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.

User Agent

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

Resizing Areas

⚠️ 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 now 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
    }
}

Frameless Window Resizing

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

Sending POST Data & Uploading Files

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

To upload files or send POST data from web apps, 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"
                }
            ]
        }
    }
}

For more details on the available options, see the "urlLoadOptions" property in the application.json schema.

Configuration Validator

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.