App Management
6.9.0The App Management API provides a way to manage io.Connect Desktop apps. It offers abstractions for:
Application - 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.
Instance - a running copy of an app. The App Management API provides facilities for starting/stopping app instances and tracking app-related events.
The App Management API is accessible through the io.appManager object.
APIobject
Description
App Management API.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| inMemory | InMemoryStore | API for handling app definitions at runtime. |
||
| myApplication | Application | Returns the current app. |
||
| myInstance | Instance | Returns the current app instance. |
Methods
applicationmethod
Signature
(name: string) => Application
Description
Retrieves an app by name.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the desired app. |
applicationsmethod
exitmethod
getConfigurationsmethod
Signature
(apps?: string[]) => Promise<ApplicationConfig[]>
Description
Retrieves the configurations of the specified apps.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| apps | string[] | List of names of the apps for which to retrieve configurations. |
instancesmethod
onAppAddedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is registered in the environment.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppAvailablemethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is available and can be started.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppChangedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when the configuration for an app has changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppRemovedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is removed from the environment.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppUnavailablemethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is no longer available and can't be started.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onInstanceStartedmethod
onInstanceStartFailedmethod
onInstanceStoppedmethod
onInstanceUpdatedmethod
onShuttingDownmethod
Signature
(callback: (args: ShuttingDownEventArgs) => Promise<{ prevent: boolean; }>) => void
Description
Notifies when io.Connect will shut down or restart. If the callback is asynchronous, it will be awaited up to 60 seconds before shutdown continues.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (args: ShuttingDownEventArgs) => Promise<{ prevent: boolean; }> | Callback function for handling the event. |
readymethod
Signature
() => Promise<void>
Description
Notifies when the App Management API is ready to be used.
Applicationobject
Description
Describes an app.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| allowMultiple | boolean | true | If |
|
| autoStart | boolean | If |
||
| available | boolean | If |
||
| caption | string | Caption of the app. |
||
| container | string | Container identifier. |
||
| hidden | boolean | false | If |
|
| icon | string | App icon. |
||
| iconURL | string | URL of the app icon. |
||
| instances | Instance[] | Array of objects describing the running app instances. |
||
| isShell | boolean | false | If |
|
| keywords | string[] | An array of keywords for discovering the app more easily. |
||
| mode | "html" | "flat" | "tab" | "frameless" | "unknown" | Mode of the app window.
Possible values are |
||
| name | string | App name. |
||
| sortOrder | number | Sort indicator used when ordering apps in a list. |
||
| title | string | App title. |
||
| type | string | Type of the app. |
||
| userProperties | PropertiesObject | Custom configuration object attached to the app. |
||
| version | string | App version. |
||
| windowSettings | WindowSettings | Describes the settings for the app window. |
Methods
getConfigurationmethod
Signature
() => Promise<ApplicationConfig>
Description
Retrieves the app configuration.
onAvailablemethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when the app becomes available.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onChangedmethod
Signature
(callback: (app: Application) => any) => void
Description
Notifies when the app configuration is changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onInstanceStartedmethod
onInstanceStoppedmethod
onRemovedmethod
Signature
(callback: (app: Application) => any) => void
Description
Notifies when the app is removed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onUnavailablemethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when the app becomes unavailable.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
startmethod
Signature
(context?: object, options?: ApplicationStartOptions) => Promise<Instance>
Description
Starts an instance of the app.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| context | object | Context to be passed to the started app instance. |
|
| options | ApplicationStartOptions | Options for the started app instance that will override the default app configuration. |
ApplicationStartOptionsobject
Description
Options for starting an app.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| allowClose | boolean | true | If |
|
| allowCollapse | boolean | false | If |
|
| allowExtract | boolean | false | If |
|
| allowLockUnlock | boolean | false | If |
|
| allowMaximize | boolean | true | If |
|
| allowMinimize | boolean | true | If |
|
| allowTabClose | boolean | true | If |
|
| allowUnstick | boolean | true | If |
|
| autoAlign | boolean | true | If |
|
| autoSnap | boolean | true | If |
|
| awaitInterop | boolean | true | If |
|
| base64ImageSource | string | Base64 image that will be used as a taskbar icon for the window. The supported formats are PNG, ICO, JPG and APNG. |
||
| borderColor | string | Color for the window border. Can be a color name such as |
||
| buttonsVisibility | "off" | "onDemand" | "always" | "onFocus" | "onDemand" | Determines the conditions under which the window buttons will be visible.
Valid only for io.Connect Windows with |
|
| cascade | CascadeSettings | Settings for opening new window instances of the same app in a cascade. |
||
| channelSelector | ChannelSelector | Settings for the Channel Selector UI. |
||
| collapseHeight | number | -1 | Defines the height of the window when collapsed. |
|
| devToolsEnable | boolean | true | If |
|
| downloadSettings | DownloadSettings | Defines the file download behavior of the window. |
||
| env | Record<string, string> | Key/value pairs that will be merged with the |
||
| focus | boolean | true | If |
|
| hasMoveAreas | boolean | true | If |
|
| hasSizeAreas | boolean | true | If |
|
| height | number | 400 | Window height in pixels. |
|
| hidden | boolean | false | If |
|
| historyNavigationEnabled | boolean | true | If |
|
| ignoreFromLayouts | boolean | If |
||
| ignoreSavedLayout | boolean | false | If |
|
| isChild | boolean | false | If |
|
| isCollapsed | boolean | false | If |
|
| isSticky | boolean | true | If |
|
| left | number | 0 | Distance of the top left window corner from the left edge of the screen in pixels. |
|
| loader | Loader | Defines loader behavior. |
||
| maxHeight | number | Specifies the maximum window height in pixels. |
||
| maxWidth | number | Specifies the maximum window width in pixels. |
||
| minHeight | number | 30 | Specifies the minimum window height in pixels. |
|
| minWidth | number | 50 | Specifies the minimum window width in pixels. |
|
| mode | WindowMode | "flat" | io.Connect Window mode. Possible values are |
|
| moveAreaBottomMargin | string | "0, 0, 0, 0" | Margin for the move area located at the bottom border of the window. The string value corresponds to the left, top, right and bottom borders of the move area.
Setting this to "10, 0, 10, 0" will take away 10 pixels from the left and the right sides of the move area.
Valid only for io.Connect Windows with |
|
| moveAreaLeftMargin | string | "0, 0, 0, 0" | Margin for the move area located at the left border of the window. The string value corresponds to the left, top, right and bottom borders of the move area.
Setting this to "0, 10, 0, 10" will take away 10 pixels from the top and the bottom of the move area.
Valid only for io.Connect Windows with |
|
| moveAreaRightMargin | string | "0, 0, 0, 0" | Margin for the move area located at the right border of the window. The string value corresponds to the left, top, right and bottom borders of the move area.
Setting this to "0, 10, 0, 10" will take away 10 pixels from the top and the bottom of the move area.
Valid only for io.Connect Windows with |
|
| moveAreaThickness | string | "0, 12, 0, 0" | How much of the window area is to be considered as a moving area.
The string value corresponds to the left, top, right and bottom borders of the window.
Setting this to "0, 20, 0, 0" will set a 20 pixel thick move area at the top of the window.
Valid only for io.Connect Windows with |
|
| moveAreaTopMargin | string | "0, 0, 0, 0" | Margin for the move area located at the top border of the window. The string value corresponds to the left, top, right and bottom borders of the move area.
Setting this to "10, 0, 10, 0" will take away 10 pixels from the left and the right sides of the move area.
Valid only for io.Connect Windows with |
|
| onTop | boolean | false | If |
|
| parameters | string | Optional parameters that will be passed to the executable app that is to be started. The value will be used as is and no validation will be performed on it. |
||
| placement | PlacementSettings | Specifies the window position relative to the screen. |
||
| preloadScripts | string[] | A list of preload scripts (URLs) that will be loaded and executed before the actual page is executed. |
||
| relativeDirection | RelativeDirection | "right" | Direction for positioning the window relatively to the window specified in the |
|
| relativeTo | string | ID of the window that will be used to relatively position the new window. Can be combined with |
||
| showInTaskbar | boolean | true | If |
|
| showTitleBar | boolean | true | If |
|
| sizeAreaThickness | string | "5, 5, 5, 5" | How much of the window area in pixels is to be considered as a sizing area.
The string value corresponds to the left, top, right and bottom borders of the window.
Valid only for io.Connect Windows with |
|
| snappingEdges | string | "all" | Specifies the active io.Connect Window snapping edges.
Possible values are |
|
| startLocation | string | Specifies the window start location.
Possible options are |
||
| stickyFrameColor | string | "#5b8dc9" | Specifies the io.Connect Window frame color. Accepts a hexadecimal color as string (e.g., |
|
| stickyGroup | string | "Any" | If set, the io.Connect Window can only stick to windows that have the same group. |
|
| tabGroupId | string | Specifies the tab group ID. If two or more tab windows are defined with the same ID, they will be hosted in the same container as tabs. |
||
| tabIndex | number | The tab index of the current window. All tabs in a common tab container have different indices. |
||
| tabSelected | boolean | true | If |
|
| tabTitle | string | "" | Sets the tab title. |
|
| tabTooltip | string | "" | Sets the tab tooltip. |
|
| timeout | number | Interval in seconds to wait for the app to initialize. |
||
| title | string | Sets the window title. To work properly, there should be a |
||
| top | number | 0 | Distance of the top left window corner from the top edge of the screen in pixels. |
|
| urlLoadOptions | LoadURLOptions | Options for loading the window URL. Can be used for POST requests, like uploading a file or specifying additional headers. |
||
| useRandomFrameColor | boolean | false | If |
|
| width | number | 400 | Window width in pixels. |
|
| windowState | FrameState | "normal" | If set, the window will start in the specified state ( |
AppManagerobject
Description
App Management API that allows you to handle your interop-enabled apps.
Methods
applicationmethod
Signature
(name: string) => Application
Description
Retrieves an app by name.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the desired app. |
applicationsmethod
getConfigurationsmethod
Signature
(apps?: string[]) => Promise<ApplicationConfig[]>
Description
Retrieves the configurations of the specified apps.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| apps | string[] | List of names of the apps for which to retrieve configurations. |
getConfigurationsmethod
Signature
(apps: string[]) => Promise<Record<string, any>>
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| apps | string[] |
instancesmethod
onAppAddedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is registered in the environment.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppAvailablemethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is available and can be started.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppChangedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when the configuration for an app has changed.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppRemovedmethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is removed from the environment.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onAppUnavailablemethod
Signature
(callback: (app: Application) => any) => UnsubscribeFunction
Description
Notifies when an app is no longer available and can't be started.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| callback | (app: Application) => any | Callback function for handling the event. |
onInstanceStartedmethod
onInstanceStartFailedmethod
onInstanceStoppedmethod
ExitOptsobject
Description
Options for shutdown or restart of io.Connect.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| autoSave | boolean | If |
||
| showDialog | boolean | If |
ImportResultobject
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 errors from importing app definitions. |
||
| imported | string[] | Array of names of the successfully imported apps as specified in their definitions. |
InMemoryStoreobject
Description
API for handling app definitions at runtime. The API methods operate only on in-memory app definitions.
Methods
clearmethod
Signature
() => Promise<void>
Description
Removes all app definitions from the in-memory store.
exportmethod
Signature
() => Promise<ApplicationConfig[]>
Description
Exports all available app definitions from the in-memory store.
importmethod
Signature
(definitions: ApplicationConfig[], mode?: "replace" | "merge") => Promise<ImportResult>
Description
Imports the provided collection of app definitions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| definitions | ApplicationConfig[] | A collection of app definition objects to be imported. |
|
| mode | "replace" | "merge" | Mode for importing app definitions. Use |
removemethod
Signature
(name: string) => Promise<void>
Description
Removes an app definition from the in-memory store.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Name of the app to be removed. |
Instanceobject
Description
Describes an app instance.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| application | Application | The app object of the instance. |
||
| id | string | App instance ID. |
||
| interopInstance | Instance | Access to the Interop instance. Use this to invoke Interop methods for the app instance. |
||
| title | string | Title of the app instance. |
Methods
activatemethod
getContextmethod
Signature
() => Promise<object>
Description
Retrieves the starting context of the instance.
getWindowmethod
Signature
() => Promise<IOConnectWindow>
Description
Retrieves the window object corresponding to the app instance.
onInteropReadymethod
onStoppedmethod
startedBymethod
Signature
() => Promise<StartedByInfo>
Description
Retrieves information about how the current app instance was started, and about the identity of the initiator.
Available since version io.Connect Desktop 9.3
stopmethod
Signature
() => Promise<void>
Description
Stops the app instance.
Intentobject
Description
Describes an Intent.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| contexts | string[] | The type of predefined data structures with which the Intent handler app works. |
||
| customConfig | object | Custom configuration for the Intent. |
||
| displayName | string | Display name of the Intent. Can be used in context menus or other UI elements to visualize the Intent. |
||
| name | string | Name of the Intent. |
||
| resultType | string | The type of predefined data structure which the Intent handler app returns. |
PropertiesObjectobject
Description
Generic object for passing properties or settings in the form of key/value pairs.
ShuttingDownEventArgsobject
Description
Describes the event for shutting down io.Connect.
Properties
| Property | Type | Default | Required | Description |
|---|---|---|---|---|
| initiator | Instance | Describes the Interop instance that has initiated the shutdown. |
||
| reason | string | Reason for the shutdown. |
||
| restarting | boolean | If |
StartedByInfoobject
Description
Describes how the current app instance was started and provides details about the app that started it.
Properties
| Property | Type | Default | Required | 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. |
Modeenumeration
Description
Mode for initializing the App Management API.
Use "full" to enable all features of the API.
Use "skipIcons" to enable all features of the API, omitting the information about the app icons.
Use "startOnly" to start the API in a restricted mode. You will be able to start apps,
but the App Management API events and the information about the apps and their instances won't be available.
- "startOnly"
- "skipIcons"
- "full"