App Management

The App Management API provides a way to manage io.Connect Browser apps. It offers abstractions for:

• Application - a web app as a logical entity, registered in io.Connect Browser with some metadata (name, title, version, 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 has been started;

• Instance - a running copy of an app. The App Management API provides facilities for starting and stopping app instances and tracking app and instance related events;

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

The Live Examples section demonstrates using the App Management API.

To participate in the App Management API, each app in an io.Connect Browser project must have an app definition. App definitions are supplied using the applications property of the configuration object when initializing the @interopio/browser-platform library in the Main app. App definitions can be supplied locally or fetched from a remote source (custom REST service or io.Manager).

⚠️ Note that io.Connect Browser supports both io.Connect and FDC3 app definitions. The only requirement for an FDC3 app definition to be usable in io.Connect Browser is to have a valid URL specified.

For a reference implementation of a remote store supporting the FDC3 App Directory, see the Node.js REST Config Example on GitHub.

Local

To supply local app definitions to the Main app, use the local property of the applications object and provide an array of app Definition objects.

The following example demonstrates defining two apps:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    applications: {
        local: [
            {
                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 { io } = await IOBrowserPlatform(config);

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.

Remote

To supply app definitions from a remote location, use the remote property of the applications object and provide details for the remote app store:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    applications: {
        remote: {
            url: "http://localhost:3001/v2/apps/",
            pollingInterval: 1000,
            requestTimeout: 5000
        }
    }
};

const { io } = await IOBrowserPlatform(config);

The remote object has the following properties:

For details on how to connect to io.Manger to fetch app definitions, see the io.Manager section.

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

⚠️ Note that all app Definition objects provided at runtime are stored in-memory and the methods of the InMemory object operate only on them - i.e., the app definitions provided during the initialization of the @interopio/browser-platform library 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 Definition objects as a first parameter 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 applications = 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 Application object:

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

const appInstance = await app.start();

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

const app = io.appManager.application("ClientList");
const context = { selectedUser: 2 };
const startOptions = { height: 400, width: 500 };

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

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

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

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

await appInstance.stop();

App Events

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 = application => console.log(application.name);

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

App removed event:

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

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

App updated event:

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

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

Instance Events

To monitor instance related events globally (for all instances of all apps running in io.Connect Browser) 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 Browser. 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 a parameter 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);

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 a parameter 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);

Handling Apps, App and Instance Events

App A below demonstrates how to discover the available app definitions using the applications() method of the App Management API. It also allows you to start the apps using the start() method of the app object. Additionally, it lists all instances of running apps and allows you to stop them using the stop() method of the instance object.

App B is subscribed for the onInstanceStarted() and onInstanceStopped() events and logs when an instance has been started or stopped.

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