Apps

6.16.3

⚠️ Note that the Apps API is still an experimental feature. This means that it may have hidden issues and may be subject to changes in future releases.

The Apps API is designed to replace the legacy App Management API accessible via the io.appManager object. The legacy App Management API is still supported, but will be entirely removed in a future release. It's highly recommended to migrate to the new Apps API.

The Apps API provides a modern, fully asynchronous 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 Apps API provides facilities for retrieving app metadata and for detecting when an app is started.
Instance - a running copy of an app. The Apps API provides facilities for starting/stopping app instances and tracking app-related events.

The Apps API is accessible via the io.apps object.

Available since io.Connect Desktop 10.0.

Description

Apps API.

Properties

Property	Type	Description
instances	InstanceManager	Object that can be used for managing running app instances.
my	My	Provides access to the current app instance.
registry	AppRegistry	Object that that can be used for managing app definitions.

Description

Describes the argument received by the callback function for handling the app added event.

Properties

Property	Type	Default	Required	Description
app	ApplicationCore			Describes the app that has been added to the environment.

Description

Object with key/value pairs describing the updated app properties and their new values.

Description

Options for selecting or filtering apps.

Properties

Property	Type	Default	Required	Description
includeDefinition	boolean	false		If `true`, the app definition will be included in the result.
includeInstances	boolean	true		If `true`, all currently available app instances will be included in the result.

Description

Filter for retrieving apps.

Properties

Property	Type	Default	Description
customProperties	Record<string, any>		Custom properties as specified in the respective app definition.
includeDefinition	boolean	false	If `true`, the app definition will be included in the result.
includeInstances	boolean	true	If `true`, all currently available app instances will be included in the result.
isFdc3Definition	boolean		If `true`, the result will include only FDC3 app definitions.
isHidden	boolean		If `true`, the result will include only apps that are specified as hidden in their app definitions.
isInMemory	boolean		If `true`, the result will include only apps from the in-memory app store.
keywords	string[]		Array of keywords as specified in the respective app definitions.
names	string[]		Array of app names as specified in the respective app definitions.
types	AppType[]		Array of app types as specified in the respective app definitions.

Description

Describes an app.

Properties

Property	Type	Description
allowMultiple	boolean	Flag indicating whether multiple instances of the app are allowed.
autoStart	boolean	Flag indicating whether the app will be auto started on platform startup.
customProperties	Record<string, any>	Provides access to the custom properties specified in the app definition if such exist.
definition	Definition	Provides access to the entire app definition.
description	string	Description of the app.
fdc3	Record<string, any>	Provides access to the FDC3 app definition if this is an FDC3 app.
icon	string	Icon URL or the icon of the app in Base64 format.
iconURL	string	URL of the app icon.
instances	ApplicationInstance[]	Array of objects describing all currently available app instances.
isHidden	boolean	Flag indicating whether the app is running as a hidden window.
isInMemory	boolean	Flag indicating whether the app is part of the in-memory store.
isShell	boolean	Flag indicating whether the app is a shell app for the platform.
keywords	string[]	Keywords for the app.
name	string	Name of the app.
title	string	Title of the app.
type	AppType	Type of the app.
version	string	Version of the app.

Description

Describes the basic properties of an app.

Properties

Property	Type	Description
allowMultiple	boolean	Flag indicating whether multiple instances of the app are allowed.
autoStart	boolean	Flag indicating whether the app will be auto started on platform startup.
description	string	Description of the app.
icon	string	Icon URL or the icon of the app in Base64 format.
iconURL	string	URL of the app icon.
isHidden	boolean	Flag indicating whether the app is running as a hidden window.
isInMemory	boolean	Flag indicating whether the app is part of the in-memory store.
isShell	boolean	Flag indicating whether the app is a shell app for the platform.
keywords	string[]	Keywords for the app.
name	string	Name of the app.
title	string	Title of the app.
type	AppType	Type of the app.
version	string	Version of the app.

Description

Describes an app instance.

Properties

Property	Type	Description
appName	string	Name of the app as specified in its definition to which the instance belongs.
id	string	ID of the app instance.
interopInstance	Instance	Provides access to the Interop instance of the current app instance.
pid	number	Process ID of the current app instance.
startedAt	Date	Timestamp of when the app instance was started.
startedBy	StartedByInfo	Describes how the current app instance was started and provides details about the app that started it.

Description

Object that can be used for managing app definitions.

Properties

Property	Type	Default	Required	Description
inMemory	InMemoryStore			Object that can be used for handling app definitions dynamically.

has
onAdded

onRemoved
onUpdated

getmethod

Signature

(options: GetAppOptions) => Promise<Application>

Description

Retrieves an app by name.

Parameters

Name	Type	Required	Description
options	GetAppOptions		Options for retrieving the app.

getManymethod

Signature

(filter?: AppFilter) => Promise<Application[]>

Description

Retrieves all available apps. You can also provide an optional filter to refine the result.

Parameters

Name	Type	Required	Description
filter	AppFilter		Filter for retrieving apps.

hasmethod

Signature

(name: string) => Promise<boolean>

Description

Checks if an app exists in the app registry.

Parameters

Name	Type	Required	Description
name	string		The name of the app to check.

onAddedmethod

Signature

(handler: AppEventHandler<AppAddedEvent>) => Promise<UnsubscribeFunction>

Description

Notifies when an app has been registered in the environment. Returns an unsubscribe function.

Parameters

Name	Type	Required	Description
handler	AppEventHandler<AppAddedEvent>		Callback function for handling the event. Receives as an argument an object describing the added app.

onRemovedmethod

Signature

(handler: AppEventHandler<AppRemovedEvent>) => Promise<UnsubscribeFunction>

Description

Notifies when an app has been removed from the environment. Returns an unsubscribe function.

Parameters

Name	Type	Required	Description
handler	AppEventHandler<AppRemovedEvent>		Callback function for handling the event. Receives as an argument the name of the removed app.

onUpdatedmethod

Signature

(handler: AppEventHandler<AppUpdatedEvent>) => Promise<UnsubscribeFunction>

Description

Notifies when an app has been updated. Returns an unsubscribe function.

Parameters

Name	Type	Required	Description
handler	AppEventHandler<AppUpdatedEvent>		Callback function for handling the event. Receives as an argument an object describing the updated app and the new values of the updated app properties.

Description

Describes the argument received by the callback function for handling the app removed event.

Properties

Property	Type	Default	Required	Description
appName	string			The name of the app that has been removed from the environment.

Description

Options for selecting apps.

Properties

Property	Type	Default	Required	Description
name	string			Name of the app as specified in its app definition.

Description

Describes the argument received by the callback function for handling the app updated event.

Properties

Property	Type	Default	Required	Description
app	ApplicationCore			Describes the app that has been updated.
changes	AppChangeSet			Object with key/value pairs describing the updated app properties and their new values.

Description

Options for clearing all app definitions from the in-memory store.

Properties

Property	Type	Default	Required	Description
stopAllInstances	boolean	false		If `true`, all currently running instances of all apps from the in-memory store will be stopped.

Description

App definition object. All available app definition properties are described in the application.json JSON schema of io.Connect Desktop.

Description

Options for retrieving apps.

Properties

Property	Type	Default	Description
includeDefinition	boolean	false	If `true`, the app definition will be included in the result.
includeInstances	boolean	true	If `true`, all currently available app instances will be included in the result.
name	string		Name of the app as specified in its app definition.

Description

Describes the result from importing app definitions at runtime.

Properties

Property	Type	Default	Required	Description
errors	{ app: string; error: string; }[]			Array of objects describing any errors from importing the app definitions.
imported	string[]			Array of names of the successfully imported apps as specified in their definitions.

Description

Object that can be used for handling app definitions dynamically. The described methods operate only on in-memory app definitions.

Methods

clear
has

import
remove

clearmethod

Signature

(options?: ClearAppsOptions) => Promise<void>

Description

Clears all app definitions from the in-memory store.

Parameters

Name	Type	Required	Description
options	ClearAppsOptions		Options for clearing app definitions.

hasmethod

Signature

(name: string) => Promise<boolean>

Description

Checks if an app definition is available in the in-memory store.

Parameters

Name	Type	Required	Description
name	string		The name of the app for whose definition to check.

importmethod

Signature

(definitions: Definition[], mode?: "replace" | "merge") => Promise<ImportResult>

Description

Imports the provided collection of app definitions.

Parameters

Name	Type	Required	Description
definitions	Definition[]		Array of app definition objects to be imported in the in-memory store.
mode	"replace" \| "merge"		Mode for importing app definitions. Use `"replace"` (default) to replace all existing in-memory app definitions. Use `"merge"` to update the existing ones and add new ones.

removemethod

Signature

(options: RemoveAppOptions) => Promise<void>

Description

Removes an app definition from the in-memory store.

Parameters

Name	Type	Required	Description
options	RemoveAppOptions		Options for removing an app definition.

Description

Filter for retrieving app instances.

Properties

Property	Type	Description
appNames	string[]	Array of app names as specified in the respective app definitions. Using this as a filter will include in the result all currently available instances of the specified apps.
ids	string[]	Array of app instance IDs.
startedAfter	Date	Only the app instances started after the specified timestamp will be included in the result.
startedBefore	Date	Only the app instances started before the specified timestamp will be included in the result.

Description

Object that can be used for managing running app instances.

Methods

get
getContext
getMany
getState

onStarted
onStateChanged
onStopped
restart

start
stop
waitForReady

getmethod

Signature

(options: InstanceSelect) => Promise<ApplicationInstance>

Description

Retrieves an app instance.

Parameters

Name	Type	Required	Description
options	InstanceSelect		Filter for selecting an app instance.

getContextmethod

Signature

(options: InstanceSelect) => Promise<Record<string, any>>

Description

Retrieves the context of an app instance.

Parameters

Name	Type	Required	Description
options	InstanceSelect		Filter for selecting an app instance.

getManymethod

Signature

(filter?: InstanceFilter) => Promise<ApplicationInstance[]>

Description

Retrieves all running app instances. You can also provide an optional filter to refine the result.

Parameters

Name	Type	Required	Description
filter	InstanceFilter		Filter for retrieving app instances.

getStatemethod

Signature

(options: InstanceSelect) => Promise<InstanceState>

Description

Retrieves the current state of an app instance.

Parameters

Name	Type	Required	Description
options	InstanceSelect		Filter for selecting an app instance.

onStartedmethod

Signature

(handler: InstanceEventHandler<InstanceStartedEvent>) => Promise<UnsubscribeFunction>

Description

Notifies when an app instance has been started. Returns an unsubscribe function.

Parameters

Name	Type	Required	Description
handler	InstanceEventHandler<InstanceStartedEvent>		Callback function for handling the event. Receives as an argument an object describing the started app instance.

onStateChangedmethod

Signature

(handler: InstanceEventHandler<InstanceStateChangedEvent>) => Promise<UnsubscribeFunction>

Description

Notifies when the current state an app instance has been changed. Returns an unsubscribe function.

Parameters

Name	Type	Required	Description
handler	InstanceEventHandler<InstanceStateChangedEvent>		Callback function for handling the event. Receives as an argument an object describing the app instance and its new state.

onStoppedmethod

Signature

(handler: InstanceEventHandler<InstanceStoppedEvent>) => Promise<UnsubscribeFunction>

Description

Notifies when an app instance has been stopped. Returns an unsubscribe function.

Parameters

Name	Type	Required	Description
handler	InstanceEventHandler<InstanceStoppedEvent>		Callback function for handling the event. Receives as an argument an object describing the stopped app instance and a reason (optional) for stopping the instance.

restartmethod

Signature

(options: RestartInstanceOptions) => Promise<ApplicationInstance>

Description

Restarts an app instance.

Parameters

Name	Type	Required	Description
options	RestartInstanceOptions		Options for restarting the instance.

startmethod

Signature

(options: StartAppOptions) => Promise<ApplicationInstance>

Description

Starts a new app instance.

Parameters

Name	Type	Required	Description
options	StartAppOptions		Options for starting the app instance.

stopmethod

Signature

(options: StopInstanceOptions) => Promise<void>

Description

Stops an app instance.

Parameters

Name	Type	Required	Description
options	StopInstanceOptions		Options for stopping the app instance.

waitForReadymethod

Signature

(options: InstanceSelect) => Promise<void>

Description

Waits for an app instance to be fully initialized.

Parameters

Name	Type	Required	Description
options	InstanceSelect		Filter for selecting an app instance.

Description

Options for selecting an app instance.

Properties

Property	Type	Default	Required	Description
id	string			ID of the app instance.

Description

Describes the argument received by the callback function for handling the instance started event.

Properties

Property	Type	Default	Required	Description
instance	ApplicationInstance			Describes the app instance that has been started.

Description

Describes the argument received by the callback function for handling the instance state changed event.

Properties

Property	Type	Default	Required	Description
instance	ApplicationInstance			Describes the app instance whose state has changed.
state	InstanceState			The current state of the app instance.

Description

Describes the argument received by the callback function for handling the instance stopped event.

Properties

Property	Type	Default	Required	Description
instance	ApplicationInstance			Describes the app instance that has been stopped.
reason	string			Reason for stopping the app instance.

Description

Provides access to the current app instance.

Properties

Property	Type	Default	Required	Description
appName	string			The name of the current app.
instance	ApplicationInstance			Describes the current app instance.

Description

Options for removing and app definition from the in-memory store.

Properties

Property	Type	Default	Required	Description
name	string			Name of the app whose definition to remove.
stopInstances	boolean	false		If `true`, all currently running instances of the app will be stopped.

Description

Options for restarting an app instance.

Properties

Property	Type	Default	Description
context	Record<string, any> \| "preserve" \| "clear"	"preserve"	Context to pass to the restarted instance. If you provide `"preserve"` as a value, the context of the original instance will be reused. If you provide `"clear"` as a value, the context of the restarted instance will reset to an empty object.
id	string		The ID of the instance to restart.
timeout	number	120000	Interval in milliseconds to wait for restarting the app instance.
useOriginalDefinition	boolean	false	If `true`, the original app definition will be used for the restarted instance.

Description

Options for starting an app instance.

Properties

Property	Type	Default	Description
context	Record<string, any>		Context to pass to the started app instance. If not provided, the context from the app definition will be used if such exists. Otherwise, this will be set to an empty object.
definitionOverride	Record<string, any>		Key/value pairs of app definition overrides to apply when starting the app instance. The values of the app definition properties specified here will override the values of the respective properties in the already existing app definition.
name	string		Name of the app to start as specified in its app definition.
reuseInstance	boolean	false	If `true`, the platform will attempt to reuse an existing instance of the specified app if such is available.
timeout	number	120000	Interval in milliseconds to wait for starting the app instance.

Description

Describes how the current app instance was started and provides details about the app that started it.

Properties

Property	Type	Description
applicationName	string	Name of the app that started the current app instance.
instanceID	string	ID of the app instance that started the current app instance.
startedBy	"application" \| "intent" \| "autoStart"	Indicates how the current app instance was started. Apps can be started by other apps, by a raised Intent, or can be auto started by the system.

Description

Options for stopping an app instance.

Properties

Property	Type	Default	Description
force	boolean	false	If `true`, the instance will be forcefully stopped without waiting for it to gracefully shut down.
id	string		The ID of the instance to stop.
reason	string		Reason for stopping the app instance.
timeout	number	30000	Interval in milliseconds to wait for stopping the app instance.

AppEventHandlerfunction

Signature

(event: T) => void

Description

Handler for app events.

Parameters

Name	Type	Required	Description
event	T

Description

Type of the app.

"window"
"activity"
"exe"
"node"
"workspaces"
"webGroup"
"clickonce"
"citrix"
"childWindow"

InstanceEventHandlerfunction

Signature

(event: T) => void

Description

Handler for app instance events.

Parameters

Name	Type	Required	Description
event	T

Description

Current state of the app instance.

"started"
"ready"
"stopped"
"failed"

API Reference Documentation

Apps

APIobject

Description

Properties

AppAddedEventobject

Description

Properties

AppChangeSetobject

Description

AppDataOptionsobject

Description

Properties

AppFilterobject

Description

Properties

Applicationobject

Description

Properties

ApplicationCoreobject

Description

Properties

ApplicationInstanceobject

Description

Properties

AppRegistryobject

Description

Properties

Methods

getmethod

Signature

Description

Parameters

getManymethod

Signature

Description

Parameters

hasmethod

Signature

Description

Parameters

onAddedmethod

Signature

Description

Parameters

onRemovedmethod

Signature

Description

Parameters

onUpdatedmethod

Signature

Description

Parameters

AppRemovedEventobject

Description

Properties

AppSelectobject

Description

Properties

AppUpdatedEventobject

Description

Properties

ClearAppsOptionsobject

Description

Properties

Definitionobject

Description

GetAppOptionsobject

Description

Properties

ImportResultobject

Description

Properties

InMemoryStoreobject

Description

Methods

clearmethod

Signature

Description

Parameters