App Management
Overview
The App Management API provides a way to manage io.Connect Desktop apps. It offers abstractions for:
- App - a program as a logical entity, registered in io.Connect Desktop with some metadata (name, description, icon, etc.) and with all the configuration needed to spawn one or more instances of it. The App Management API provides facilities for retrieving app metadata and for detecting when an app is started.
For details on how to define and configure an app, see the Developers > Configuration > Application section.
- Instance - a running copy of an app. The App Management API provides facilities for starting and stopping app instances and tracking app-related events.
![](../../../images/app-management/app-management.gif)
App Stores
io.Connect Desktop can obtain app definitions from a local store, from a remote REST service, or from io.Manager. To specify app stores with app definitions, use the "appStores"
top-level key in the system.json
system configuration file of io.Connect Desktop, located in %LocalAppData%/interop.io/io.Connect Desktop/Desktop/config
. It accepts an array of objects defining one or more app stores.
In the standard io.Connect Desktop deployment model, app definitions aren't stored locally on the user machine, but are served remotely. If io.Connect Desktop is configured to use a remote app store, it will poll it periodically and discover new app definitions. The store implementation is usually connected to an entitlement system based on which different users can have different apps or versions of the same app. In effect, io.Connect Desktop lets users run multiple versions of the same app simultaneously and allows for seamless forward/backward app rolling.
⚠️ Note that io.Connect Desktop respects the FDC3 standards and can retrieve standard io.Connect, as well as FDC3-compliant app definitions. For more details on working with FDC3-compliant apps, see the FDC3 Compliance section, the FDC3 App Directory documentation and the FDC3 Application schema.
![](../../../images/app-management/app-stores.png)
Local
To configure io.Connect Desktop to load app definition files from a local path, set the "type"
property of the app store configuration object to "path"
and specify a relative or an absolute path to the app definitions. The environment variables set by io.Connect Desktop can also be used as values:
{
"appStores": [
{
"type": "path",
"details": {
"path": "./config/apps"
}
},
{
"type": "path",
"details": {
"path": "%GD3-APP-STORE%"
}
},
{
"type": "path",
"details": {
"path": "%GLUE-USER-DATA%/apps"
}
}
]
}
Each local path app store object has the following properties:
Property | Type | Description |
---|---|---|
"appDefinitionOverrides" |
object |
Valid app definition properties that will override the ones in all app definitions from the app store. Top-level app definition properties can be specified directly in the "appDefinitionOverrides" object. The properties that are found under the "details" top-level key for each app definition type must be specified in a top-level object with the same name as the app type - "window" , "exe" , "node" , "workspaces" , "webGroup" , "clickonce" , "citrix" or "childWindow" . Available since io.Connect Desktop 9.1. |
"details" |
object |
Required. Specific details about the app store. |
"isRequired" |
boolean |
If true (default), the app store will be required. If the app store can't be retrieved, io.Connect Desktop will throw an error and shut down. If false , io.Connect Desktop will initiate normally, without apps from that store. |
"type" |
string |
Required. Type of the app store. Must be set to "path" for local path app stores. |
The "details"
object for a local path app store has the following properties:
Property | Type | Description |
---|---|---|
"path" |
string |
Required. Must point to the local app store. The specified path can be absolute or relative and you can use defined environment variables. |
REST
App definitions can also be obtained from remote app stores via a REST service.
To configure a connection to the REST service providing the remote app store, add a new entry to the "appStores"
top-level key in the system.json
file and set its "type"
to "rest"
:
{
"appStores": [
{
"type": "rest",
"details": {
"url": "https://example.com/my-app-store/",
"auth": "no-auth",
"pollInterval": 30000,
"enablePersistentCache": true,
"cacheFolder": "%LocalAppData%/interop.io/io.Connect Desktop/UserData/%GLUE-ENV%-%GLUE-REGION%/configCache/"
},
"appDefinitionOverrides": {
// Overrides for some top-level app definition properties.
"ignoreSavedLayout": true,
"allowMultiple": false,
// Overrides for the properties under the `"details"` top-level key in apps of type `"window"`.
"window": {
"autoInjectAPI": {
"enabled": true,
"autoInit": {
"channels": true
}
}
}
}
}
]
}
Each remote app store object has the following properties:
Property | Type | Description |
---|---|---|
"appDefinitionOverrides" |
object |
Valid app definition properties that will override the ones in all app definitions from the app store. Top-level app definition properties can be specified directly in the "appDefinitionOverrides" object. The properties that are found under the "details" top-level key for each app definition type must be specified in a top-level object with the same name as the app type - "window" , "exe" , "node" , "workspaces" , "webGroup" , "clickonce" , "citrix" or "childWindow" . Available since io.Connect Desktop 9.1. |
"details" |
object |
Required. Specific details about the app store. |
"isRequired" |
boolean |
If true (default), the app store will be required. If the app store can't be retrieved, io.Connect Desktop will throw an error and shut down. If false , io.Connect Desktop will initiate normally, without apps from that store. |
"type" |
string |
Required. Type of the app store. Must be set to "rest" for remote app stores. |
The "details"
object for a remote app store has the following properties:
Property | Type | Description |
---|---|---|
"auth" |
string |
Authentication configuration. Can be one of "no-auth" (default), "negotiate" or "kerberos" . |
"cacheFolder" |
string |
Location the persisted configuration files. |
"enablePersistentCache" |
boolean |
If true (default), will cache and persist the configuration files locally (e.g., in case of connection interruptions). |
"pollInterval" |
number |
Interval in milliseconds at which to poll the REST service for updates. Default is 60000 . |
"proxy" |
string |
HTTP proxy to use when fetching data. |
"readCacheAfter" |
number |
Interval in milliseconds after which to try to read the cache. Default is 30000 . |
"rejectUnauthorized" |
boolean |
If true (default), SSL validation will be enabled for the REST server. |
"requestTimeout" |
number |
Timeout in milliseconds to wait for a response from the REST server. Default is 20000 . |
"startRetries" |
number |
Number of times io.Connect Desktop will try to connect to the REST server. Default is 5 . |
"startRetryInterval" |
number |
Interval in milliseconds at which io.Connect Desktop will try to connect to the REST server. Default is 10000 . |
"url" |
string |
Required. The URL to the REST service providing the app definitions. |
The remote store must return app definitions in the following response shape:
{
"applications": [
// List of app definition objects.
{}, {}
]
}
For details on working with remote app stores compliant with FDC3 App Directory standards, see the FDC3 Compliance section and the FDC3 App Directory documentation.
For a reference implementation of a remote app definitions store, see the Node.js REST Config example that implements the FDC3 App Directory and is compatible with io.Connect Desktop. This basic implementation doesn't take the user into account and returns the same set of data for all requests. For instructions on running the sample server on your machine, see the README file in the repository.
For a .NET implementation of a remote app definitions store, see the .NET REST Config example.
io.Manager
You can also use io.Manager for hosting and retrieving app stores. io.Manager is a complete server-side solution for providing data to io.Connect. To configure io.Connect Desktop to fetch app definitions from io.Manager, set the "type"
property of the app store configuration object to "server"
:
{
"appStores": [
{
"type": "server"
}
]
}
The server app store object has the following properties:
Property | Type | Description |
---|---|---|
"appDefinitionOverrides" |
object |
Valid app definition properties that will override the ones in all app definitions from the app store. Top-level app definition properties can be specified directly in the "appDefinitionOverrides" object. The properties that are found under the "details" top-level key for each app definition type must be specified in a top-level object with the same name as the app type - "window" , "exe" , "node" , "workspaces" , "webGroup" , "clickonce" , "citrix" or "childWindow" . Available since io.Connect Desktop 9.1. |
"isRequired" |
boolean |
If true (default), the app store will be required. If the app store can't be retrieved, io.Connect Desktop will throw an error and shut down. If false , io.Connect Desktop will initiate normally, without apps from that store. |
"type" |
string |
Required. Type of the app store. Must be set to "server" for app stores retrieved from io.Manager. |
If you are using only io.Manager for retrieving app definitions, you can set the "appStores"
key to an empty array. io.Connect Desktop will automatically try to connect to io.Manager using its configuration, and will retrieve the app definitions from it, if any.
System App Stores
Besides the regular app stores that usually contain definitions for end user apps, you can define system app stores for critical apps that must be auto started with the platform. The system stores aren't monitored for changes and can be only of type "path"
and "rest"
. To define a system app store, use the "systemAppStores"
top-level key in the system.json
file, which accepts an array of objects defining one or more system app stores.
The following example demonstrates how to configure a local system app store:
{
"systemAppStores": [
{
"type": "path",
"details": {
"path": "./config/system-apps"
}
}
]
}
For details on how to set the priority of system apps, see the Configuration > Application > Boot Sequence section.