App Management

The App Management API is accessible via the io.appManager object.

See the JavaScript App Management example on GitHub.

The App Management API is enabled by default. However, there are several initialization options for it depending on what set of features you want to use.

To specify the desired mode for the App Management API, use the optional Config object when initializing the io.Connect library:

// Enabling all features of the App Management API.
const config = { appManager: "full" };

const io = await IODesktop(config);

The appManager property of the Config object accepts the following values:

To restart io.Connect Desktop, use the restart() method. This will close all running apps and their instances and then restart io.Connect Desktop:

await io.appManager.restart();

To shut down io.Connect Desktop, use the exit() method. This will close all running apps and their instances:

await io.appManager.exit();

For details on how to execute custom code before restart or shutdown and also how to prevent restart or shutdown, see the Events > Shutdown section.

To retrieve all available app definitions, use the getConfigurations() method:

const allAppDefinitions = await io.appManager.getConfigurations();

To retrieve the definitions of specific apps, pass an array with app names as an argument:

const appNames = ["my-app", "my-other-app"];

const myAppDefinitions = await io.appManager.getConfigurations(appNames);

App definitions can be imported, exported and removed at runtime using the InMemoryStore object of the App Management API.

⚠️ Note that all app definition objects provided at runtime are stored in-memory and the methods of the InMemoryStore object operate only on them - i.e., the app definitions provided to io.Connect Desktop through local or remote configuration files aren't affected.

Import

To import a list of app definitions at runtime, use the import() method:

const definitions = [
    {
        name: "my-app",
        type: "window",
        title: "My App",
        details: {
            url: "https://my-domain.com/my-app"
        }
    },
    {
        name: "my-other-app",
        type: "window",
        title: "My Other App",
        details: {
            url: "https://my-domain.com/my-other-app"
        }
    }
];
const mode = "merge";

const importResult = await io.appManager.inMemory.import(definitions, mode);

The import() method accepts a list of app definition objects as a first argument and an import mode as a second. There are two import modes - "replace" (default) and "merge". Using "replace" will replace all existing in-memory definitions with the provided ones, while using "merge" will merge the existing ones with the provided ones, replacing the app definitions with the same name. Use the imported property of the returned ImportResult object to see a list of the successfully imported definitions and its errors property to see a list of the errors:

const importedApps = importResult.imported;
const errors = importResult.errors;

importedApps.forEach(console.log);
errors.forEach(e => console.log(`App: ${e.app}, Error: ${e.error}`));

Export

To export a list of already imported in-memory app definitions, use the export() method:

const definitions = await io.appManager.inMemory.export();

Remove

To remove a specific in-memory app definition, use the remove() method and provide the app name:

await io.appManager.inMemory.remove("my-app");

Clear

To clear all imported in-memory definitions, use the clear() method:

await io.appManager.inMemory.clear();

To see a list of all apps available to the current user, use the applications() method:

const apps = io.appManager.applications();

Specific App

To get a reference to a specific app, use the application() method and pass the name of the app as an argument:

const app = io.appManager.application("ClientList");

Current App Instance

To get a reference to the instance of the current app, use the myInstance property:

const myInstance = io.appManager.myInstance;

To start an app, use the start() method of the app object:

const app = io.appManager.application("ClientList");

const appInstance = await app.start();

The start() method accepts two optional arguments - a context object (object in which you can pass custom data to your app) and an ApplicationStartOptions object.

The following example demonstrates how to start an app with context, enable the io.Connect Channels for it and join it to a specific Channel:

const app = io.appManager.application("ClientList");
const context = { selectedUser: 2 };
const startOptions = { channelSelector: { enabled: true, channelId: "Red" } };

const appInstance = await app.start(context, startOptions);

⚠️ Note that all app options available under the "details" top-level key in the app definition can be passed as properties of the ApplicationStartOptions object. For more details on the available app definition options, see the definition for the "window" app type under the "details" top-level of the app definition schema.

If you want to start an app that has an app definition, but that's not interop-enabled (doesn't initialize the io.Connect library), set the awaitInterop property in the ApplicationStartOptions object to false. Otherwise, the io.Connect library will assume that you are trying to start an interop-enabled app and will wait for it to initialize its io.Connect API instance and connect properly to the io.Connect framework. This will lead to a timeout and your app won't be started.

The following example demonstrates how to start an app that's not interop-enabled:

const app = io.appManager.application("MyNonInteropEnabledApp");
const startOptions = { awaitInterop: false };

const appInstance = await app.start(null, startOptions);

To list all running instances of all apps, use the instances() method:

// Returns a collection of the running instances of all apps.
const allInstances = io.appManager.instances();

The instances() method returns a list of Instance objects describing the currently running instances of all apps.

Available since io.Connect Desktop 9.3

To retrieve information about how the app instance was started, use the startedBy() method of an Instance object:

const startDetails = await io.appManager.myInstance.startedBy();

console.log(startDetails);

The startedBy() method resolves with a StartedByInfo object with the following properties:

To stop a running instance, use the stop() method of an instance object:

await appInstance.stop();

Shutdown

The shutdown event provided by the App Management API allows you to execute custom code before io.Connect Desktop shuts down. The available time for the execution of your code is 60 seconds. The callback you provide for handling the event will receive a ShuttingDownEventArgs object as an argument. Use its restarting property to determine whether io.Connect Desktop is restarting or is shutting down:

// The async code in the handler will be awaited up to 60 seconds
// before the platform shuts down.
const handler = async (args) => {
    const isRestarting = args.restarting;

    if (isRestarting) {
        console.log("Restarting...");
    } else {
        await handleShutdown();
    };
};

io.appManager.onShuttingDown(handler);

To prevent shutdown or restart of io.Connect Desktop, the async handler must resolve with an object with a prevent property set to true:

const handler = async () => { return { prevent: true } };

io.appManager.onShuttingDown(handler);

App

The set of apps defined for the current user can be changed at runtime. To track the events which fire when an app has been added, removed or updated, use the respective methods exposed by the App Management API.

App added event:

const handler = app => console.log(app.name);

// Notifies you when an app has been added.
const unsubscribe = io.appManager.onAppAdded(handler);

App removed event:

const handler = app => console.log(app.name);

// Notifies you when an app has been removed.
const unsubscribe = io.appManager.onAppRemoved(handler);

App updated event:

const handler = app => console.log(app.name);

// Notifies you when an app definition has been updated.
const unsubscribe = io.appManager.onAppChanged(handler);

Instance

To monitor instance related events globally (for all instances of all apps running in io.Connect Desktop) or on an app level (only instances of a specific app), use the respective methods exposed by the App Management API.

Global

The appManager object offers methods which you can use to monitor instance events for all apps running in io.Connect Desktop. Get notified when an app instance has started, stopped, has been updated or when starting an app instance has failed. The methods for handling instance events receive a callback as an argument which in turn receives the app instance as an argument. All methods return an unsubscribe function - use it to stop receiving notifications about instance events.

Instance started event:

const handler = instance => console.log(instance.id);

const unsubscribe = io.appManager.onInstanceStarted(handler);

Instance stopped event:

const handler = instance => console.log(instance.id);

const unsubscribe = io.appManager.onInstanceStopped(handler);

Instance updated event:

const handler = instance => console.log(instance.id);

const unsubscribe = io.appManager.onInstanceUpdated(handler);

App Level

To monitor instance events on an app level, use the methods offered by the Application object. The methods for handling instance events receive a callback as an argument which in turn receives the app instance as an argument.

Instance started event:

const app = io.appManager.application("ClientList");
const handler = instance => console.log(instance.id);

app.onInstanceStarted(handler);

Instance stopped event:

const app = io.appManager.application("ClientList");
const handler = instance => console.log(instance.id);

app.onInstanceStopped(handler);

For a complete list of the available App Management API methods and properties, see the App Management API Reference Documentation.