Application Management

Overview

The Application Management API provides a way to manage Glue42 Core applications. It offers abstractions for:

  • Application - a web app as a logical entity, registered in Glue42 Core with some metadata (name, title, version, etc.) and with all the configuration needed to spawn one or more instances of it. The Application Management API provides facilities for retrieving application metadata and for detecting when an application has been started;

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

Application Definitions

To participate in the Application Management API, each application in a Glue42 Core project must have an application definition. Application definitions are supplied using the applications property of the configuration object when initializing the Glue42 Web Platform library in the Main application. Use the local property of the applications object to specify an array of application Definition objects.

The following example demonstrates defining two applications when initializing the Web Platform library:

import GlueWebPlatform from "@glue42/web-platform";

const config = {
    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 { glue } = await GlueWebPlatform(config);

The only required top-level properties are name, details and type. The details object has a required url property that you must use to specify the location of your application.

Application definitions in Glue42 Core are compatible with Glue42 Enterprise.

The Main app is the central hub that provides application information to all Web Client apps. It is responsible for starting, managing, tracking the lifecycle and stopping all application instances, as well as for firing application related events.

The supported application definition formats are Glue42 Core and FDC3. The only requirement for an FDC3 application definition to be usable in Glue42 Core is to have a valid details.url property or a url top-level property in its manifest JSON string property. You can see an example FDC3 application definition in the FDC3 Compliance: App Directory section.

The Live Examples section demonstrates using the Application Management API. To see the code and experiment with it, open the embedded examples directly in CodeSandbox.

Managing Application Definitions at Runtime

The Application Management API is accessible through the glue.appManager object.

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

Note that all application Definition objects provided at runtime are stored in-memory and the methods of the InMemory object operate only on them - i.e., the application definitions provided during the initialization of the Web Platform library aren't affected.

Import

To import a list of application 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 glue.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 application 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 application definitions, use the export() method:

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

Remove

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

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

Clear

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

await glue.appManager.inMemory.clear();

Listing Applications

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

const applications = glue.appManager.applications();

Specific Application

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

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

Current Application Instance

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

const myInstance = glue.appManager.myInstance;

Starting Applications

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

const app = glue.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 = glue.appManager.application("ClientList");
const context = { selectedUser: 2 };
const startOptions = { height: 400, width: 500 };

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

Listing Running Instances

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

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

Stopping Instances

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

await appInstance.stop();

Events

Application Events

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

Application added event:

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

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

Application removed event:

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

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

Application updated event:

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

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

Instance Events

To monitor instance related events globally (for all instances of all applications running in Glue42 Core) or on an application level (only instances of a specific application), use the respective methods exposed by the Application Management API.

Global

The appManager object offers methods which you can use to monitor instance events for all applications running in Glue42 Core. Get notified when an application instance has started, stopped, has been updated or when starting an application instance has failed. The methods for handling instance events receive a callback as a parameter which in turn receives the application 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 = glue.appManager.onInstanceStarted(handler);

Instance stopped event:

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

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

Application Level

To monitor instance events on an application 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 application instance as an argument.

Instance started event:

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

app.onInstanceStarted(handler);

Instance stopped event:

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

app.onInstanceStopped(handler);

Live Examples

Handling Applications, Application and Instance Events

App A below demonstrates how to discover the available application definitions using the applications() method of the Application Management API. It also allows you to start the applications using the start() method of the application object. Additionally, it lists all instances of running applications 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.

Open in CodeSandbox

Reference

Application Management API Reference