APIs

Overview

Available since @interopio/manager-api 4.2.0

The @interopio/manager-api library provides a ManagerLib export that can be included as an additional library when initializing the @interopio/desktop library in io.Connect Desktop projects and the @interopio/browser-platform and @interopio/browser libraries in io.Connect Browser projects.

This enables interacting with io.Manager from interop-enabled apps running in io.Connect Desktop and io.Connect Browser - retrieving the connection state, subscribing for connection state changes, and refreshing platform data such as available apps, Layouts, system configurations, and more.

The following sections describe how to use the ManagerLib export in io.Connect Desktop and io.Connect Browser projects and provide a comprehensive API reference.

ℹ️ For details on configuring your io.Connect Desktop and io.Connect Browser platforms to connect to the io.Manager Server, see the Configuration > Platform section.

io.Connect Desktop

Available since io.Connect Desktop 10.3

To use the functionalities provided by the ManagerLib export in io.Connect Desktop client apps, you must include it in the libraries array of the configuration object for initializing the @interopio/desktop library.

When the io.Connect library has been initialized, a new manager property will be added to the io.Connect API object and the available methods will become accessible via the io.manager object:

import IODesktop from "@interopio/desktop";
import { ManagerLib } from "@interopio/manager-api/desktop";

// Including the `ManagerLib` export as an additional library.
const config = { libraries: [ManagerLib] };

const io = await IODesktop(config);

// Retrieving the state of the connection to io.Manager.
const connectionState = await io.manager.getConnectionState();

// Providing a handler and subscribing for changes in the connection state.
const handler = connectionState => console.log(`Connection state: ${JSON.stringify(connectionState)}`);

const unsubscribe = await io.manager.onConnectionStateChange(handler);

// Refreshing the available apps and Layouts.
const dataToFetch = {
    layouts: true,
    applications: true
};

await io.manager.fetchData(dataToFetch);

ℹ️ For more details on the available methods, see the API Reference section.

io.Connect Browser

Available since io.Connect Browser 4.3

Main App

To use the functionalities provided by the ManagerLib export in the Main app of your io.Connect Browser project, you must include it in the libraries array of the browser object inside the configuration object for initializing the @interopio/browser-platform library.

When the io.Connect library has been initialized, a new manager property will be added to the io.Connect API object and the available methods will become accessible via the io.manager object:

import IOBrowserPlatform from "@interopio/browser-platform";
import { ManagerLib } from "@interopio/manager-api/browser";

const config = {
    licenseKey: "my-license-key",
    browser: {
        // Including the `ManagerLib` export as an additional library.
        libraries: [ManagerLib]
    },
    manager: {
        // Settings for connecting to io.Manager.
    }
};

const { io } = await IOBrowserPlatform(config);

// Retrieving the state of the connection to io.Manager.
const connectionState = await io.manager.getConnectionState();

// Providing a handler and subscribing for changes in the connection state.
const handler = connectionState => console.log(`Connection state: ${JSON.stringify(connectionState)}`);

const unsubscribe = await io.manager.onConnectionStateChange(handler);

// Refreshing the available apps and Layouts.
const dataToFetch = {
    layouts: true,
    applications: true
};

await io.manager.fetchData(dataToFetch);

ℹ️ For more details on the available methods, see the API Reference section.

Browser Clients

To use the functionalities provided by the ManagerLib export in Browser Client apps running in io.Connect Browser, you must include it in the libraries array of the configuration object for initializing the @interopio/browser library.

When the io.Connect library has been initialized, a new manager property will be added to the io.Connect API object and the available methods will become accessible via the io.manager object:

import IOBrowser from "@interopio/browser";
import { ManagerLib } from "@interopio/manager-api/browser";

// Including the `ManagerLib` export as an additional library.
const config = { libraries: [ManagerLib] };

const io = await IOBrowser(config);

// Retrieving the state of the connection to io.Manager.
const connectionState = await io.manager.getConnectionState();

// Providing a handler and subscribing for changes in the connection state.
const handler = connectionState => console.log(`Connection state: ${JSON.stringify(connectionState)}`);

const unsubscribe = await io.manager.onConnectionStateChange(handler);

// Refreshing the available apps and Layouts.
const dataToFetch = {
    layouts: true,
    applications: true
};

await io.manager.fetchData(dataToFetch);

ℹ️ For more details on the available methods, see the API Reference section.

API Reference

The following sections describe the methods and types exposed by the ManagerLibAPI interface. They are accessible via the io.manager object after the ManagerLib export has been included as an additional library when initializing your io.Connect Desktop or io.Connect Browser project.

Failure Modes

When an io.manager.* method is called but isn't usable in the current session, it fails with an Error carrying a code property:

"METHOD_NOT_AVAILABLE" - the host io.Connect platform doesn't provide the method. For a subscription method the error is thrown synchronously; otherwise the returned Promise rejects.
"SERVER_DISABLED" - io.Manager is disabled in the io.Connect platform.
"SERVER_INCOMPATIBLE" - the connected io.Manager Server is too old to support the method.

To avoid these errors, call checkCapability() with the method's API_METHOD_* identifier before calling - its CapabilityStatus reports available, and when it is false, a reason equal to the code above. The getConnectionState(), onConnectionStateChange(), checkCapability(), and checkCapabilities() methods stay usable while io.Manager is disabled.

Methods

The following core methods are available directly on the io.manager object. Domain operations are grouped under the io.manager.layouts, io.manager.users, io.manager.groups, and io.manager.configs namespaces, documented in the sections below.

getConnectionState()

Retrieves information related to the state of the connection to io.Manager.

Signature:

getConnectionState(): Promise<IOManagerConnectionState>;

Returns: Promise that resolves with an IOManagerConnectionState object.

onConnectionStateChange()

Notifies when the state of the connection to io.Manager changes.

Signature:

onConnectionStateChange(
    callback: (connectionState: IOManagerConnectionState) => void
): Promise<UnsubscribeFunction>;

Parameters:

Parameter	Type	Description
`callback`	`function`	Callback function for handling the event. Accepts as an argument an `IOManagerConnectionState` object describing the new connection state.

Returns: Promise that resolves with an UnsubscribeFunction that can be used to stop tracking the event.

fetchData()

Triggers data refresh from io.Manager. You can specify the types of data to be refreshed (e.g. the available apps, Layouts, system configurations).

Signature:

fetchData(args: FetchDataArgs): Promise<void>;

Parameters:

Parameter	Type	Description
`args`	`object`	`FetchDataArgs` object where each key corresponds to a type of data that can be refreshed.

Returns: Promise that resolves with void.

checkCapability()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Checks whether a given client-side capability is usable in the current session and, when it is not, why. Use this method to feature-gate code paths and to render the right message when a feature is unavailable.

The capability argument is drawn from the ClientCapability enumeration. Two kinds of identifier are supported:

Platform-level capabilities (e.g., ADVANCED_LAYOUTS) describe behavioral flags advertised by the io.Connect platform itself.
Method-level capabilities (prefixed with API_METHOD_) provide information whether the specified method can be successfully invoked at the moment - available is true only when the host io.Connect platform provides the method, io.Manager is enabled, and the connected io.Manager Server supports it.

When available is false for a method-level capability, the returned CapabilityStatus carries a reason property of type CapabilityUnavailableReason - the same value the method carries in the code property of its thrown Error, so one mapping handles both this check and a catch block. Unrecognized identifiers resolve with { available: false }.

Signature:

checkCapability(capability: ClientCapability): Promise<CapabilityStatus>;

Parameters:

Parameter	Type	Description
`capability`	`ClientCapability`	The capability to probe. See `ClientCapability` for the supported identifiers.

Returns: Promise that resolves with a CapabilityStatus object.

import { ClientCapability } from "@interopio/manager-api/desktop";

const checkConflictStatus = await io.manager.checkCapability(ClientCapability.API_METHOD_LAYOUTS_CHECK_CONFLICT);

if (checkConflictStatus.available) {
    // Run the pre-save conflict check.
} else {
    // checkConflictStatus.reason: "METHOD_NOT_AVAILABLE" | "SERVER_DISABLED" | "SERVER_INCOMPATIBLE".
    showUnavailableHint(checkConflictStatus.reason);
}

checkCapabilities()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Checks every client-side capability at once, returning a map from each ClientCapability identifier to its CapabilityStatus. Useful for gating a set of features (e.g. a settings panel) in a single call.

Signature:

checkCapabilities(): Promise<Record<ClientCapability, CapabilityStatus>>;

Returns: Promise that resolves with a record from each ClientCapability to its CapabilityStatus.

import { ClientCapability } from "@interopio/manager-api/desktop";

const caps = await io.manager.checkCapabilities();

if (caps[ClientCapability.API_METHOD_LAYOUTS_CHECK_CONFLICT].available) {
    // Run the pre-save conflict check.
}

Layouts

Layout operations, available under io.manager.layouts.

checkConflict()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Checks whether saving a Layout with the given identity would conflict with an existing Layout. Use this method before submitting a save (e.g., from a Save or Share Workspace flow) to prompt the user when the chosen name is already taken, instead of catching a failure from the server after the fact. Requires io.Manager 4.0 or later.

Signature:

checkConflict(
    request: CheckLayoutConflictRequest
): Promise<CheckLayoutConflictResult>;

Parameters:

Parameter	Type	Description
`request`	`object`	`CheckLayoutConflictRequest` object describing the Layout identity to check.

Returns: Promise that resolves with a CheckLayoutConflictResult object. The result is a discriminated union - narrow on its kind field to read the matching conflict:

const result = await io.manager.layouts.checkConflict({
    type: "Workspace",
    name: "my-workspace",
    accessLevel: "private"
});

if (result.kind === "advanced" && result.conflict) {
    // Prompt the user before overwriting `result.conflict`.
} else if (result.kind === "legacy" && result.conflict) {
    // Prompt the user before overwriting `result.conflict`.
} else {
    // No conflict - the Layout can be saved cleanly.
}

Users

User queries, available under io.manager.users.

query()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Looks up users known to io.Manager by name. Results are de-duplicated and sorted alphabetically. Requires io.Manager 4.0 or later.

Signature:

query(args: QueryByNameRequest): Promise<QueryUsersResponse>;

Parameters:

Parameter	Type	Description
`args`	`object`	`QueryByNameRequest` object describing the search term and an optional result cap.

Returns: Promise that resolves with a QueryUsersResponse object.

Groups

Group queries, available under io.manager.groups.

query()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Looks up groups known to io.Manager by name. Both the groups io.Manager has on record and the groups declared in the auth_extra_groups server configuration property are matched; the built-in permission groups are never returned. Results are de-duplicated and sorted alphabetically. Requires io.Manager 4.0 or later.

Signature:

query(args: QueryByNameRequest): Promise<QueryGroupsResponse>;

Parameters:

Parameter	Type	Description
`args`	`object`	`QueryByNameRequest` object describing the search term and an optional result cap.

Returns: Promise that resolves with a QueryGroupsResponse object.

Configs

Config-file access, available under io.manager.configs.

Only the custom config files an administrator has added in io.Manager are available here. The config files the io.Connect platform itself consumes - system.json, themes.json, stickywindows.json, channels.json, logger.json and browser-platform.json - are not exposed to apps: naming one of them produces the same result as naming a config file that has never been set. The comparison is case-insensitive and covers the whole name, so SYSTEM.JSON is treated as a platform config file, while a custom config file named system (without the extension) is not.

list()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Returns the names of the custom config files set in io.Manager.

Signature:

list(): Promise<string[]>;

Returns: Promise that resolves with an array of the custom config file names set in io.Manager.

get()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Returns the raw string contents of the named custom config file, or undefined if it isn't set.

Signature:

get(name: string): Promise<string | undefined>;

Parameters:

Parameter	Type	Description
`name`	`string`	The name of the custom config file to read.

Returns: Promise that resolves with the raw string contents of the named custom config file, or undefined if it isn't set. A platform config file name always resolves with undefined.

onChange()

Available since @interopio/manager-api 5.0.0 & io.Connect Desktop 10.5 (unreleased)

Subscribes to changes in the custom config files set in io.Manager. On subscribe, the callback fires once per currently-set file (filtered by options.name when set); thereafter it fires on every add, modify, or remove. A removal is signaled by value: undefined. A platform config file never raises an event, so naming one in options.name produces a subscription that never fires.

Signature:

onChange(
    callback: (event: ConfigChangeEvent) => void,
    options?: OnConfigChangeOptions
): Promise<UnsubscribeFunction>;

Parameters:

Parameter	Type	Description
`callback`	`function`	Callback function for handling the event. Accepts as an argument a `ConfigChangeEvent` object describing the change.
`options`	`object`	Optional `OnConfigChangeOptions` object. When omitted, the callback receives events for every custom config file.

Returns: Promise that resolves with an UnsubscribeFunction that can be used to stop tracking the event.

// Subscribing for changes to a specific config file.
const unsubscribe = await io.manager.configs.onChange(event => {
    if (event.value === undefined) {
        // The config file was removed.
    } else {
        // The config file was added or modified.
    }
}, { name: "my-config.json" });

Types

CapabilityStatus

Available since @interopio/manager-api 5.0.0

The usability of an io.manager member in the current session, returned by checkCapability().

Property	Type	Description
`available`	`boolean`	Whether the member is usable right now.
`reason`	`CapabilityUnavailableReason`	When `available` is `false`, why the member is unavailable. Populated only for method-level (`API_METHOD_*`) capabilities; platform-level capabilities report availability without a reason.

CapabilityUnavailableReason

Available since @interopio/manager-api 5.0.0

The reason an io.manager member is not usable. The same value the member carries on its thrown Error's code, so a single mapping serves both checkCapability() and a catch block.

Member	Value	Description
`METHOD_NOT_AVAILABLE`	`"METHOD_NOT_AVAILABLE"`	The hosting io.Connect platform does not provide the member. Permanent for that platform.
`SERVER_DISABLED`	`"SERVER_DISABLED"`	The member is provided, but io.Manager is disabled. Recoverable by enabling io.Manager.
`SERVER_INCOMPATIBLE`	`"SERVER_INCOMPATIBLE"`	The member is provided and io.Manager is enabled, but the connected io.Manager Server is too old to support it. Resolved by upgrading the server.

CheckLayoutConflictRequest

Available since @interopio/manager-api 5.0.0

Describes the Layout identity to check. Passed as an argument to the layouts.checkConflict() method.

Property	Type	Description
`id`	`string`	Optional ID of an existing Layout being updated. When provided, that Layout is excluded from the conflict check, so renaming a Layout to its own current name does not count as a conflict.
`type`	`string`	The Layout type.
`name`	`string`	The Layout name.
`accessLevel`	`"private" \| "shared" \| "public"`	Optional access level. Defaults to `"private"` when omitted. Always treated as `"private"` when using legacy Layouts.

CheckLayoutConflictResult

Available since @interopio/manager-api 5.0.0

Describes the result returned by layouts.checkConflict(). The result is a discriminated union - the kind field selects the Layout flavor the check was resolved against and the shape of the matching conflict. Narrow on kind to read the conflicting Layout safely.

Property	Type	Description
`kind`	`"advanced" \| "legacy"`	Selects the Layout flavor the check was resolved against.
`conflict`	`UserAdvancedLayoutDefinition \| UserLayoutDefinitionV2`	The existing conflicting Layout when a collision was detected, or absent when the Layout can be saved cleanly. The shape is `UserAdvancedLayoutDefinition` when `kind` is `"advanced"` and `UserLayoutDefinitionV2` when `kind` is `"legacy"`.

ClientCapability

Available since @interopio/manager-api 5.0.0

Enumerates the client-side capabilities recognized by checkCapability(). Exported from the @interopio/manager-api/desktop and @interopio/manager-api/browser subpath entry points. Unrecognized identifiers passed at runtime resolve with { available: false }.

Each API_METHOD_* member corresponds to a method on the io.manager object. An available: true status from checkCapability() for one of these members means the corresponding io.manager.* method is usable in the current session - the host io.Connect platform provides it, io.Manager is enabled, and the connected io.Manager Server supports it.

Member	Value	Description
`ADVANCED_LAYOUTS`	`"ADVANCED_LAYOUTS"`	Advertised when the io.Connect platform supports advanced Layouts. Requires io.Connect Desktop* 10.5 (unreleased).*
`API_METHOD_GET_CONNECTION_STATE`	`"API_METHOD_GET_CONNECTION_STATE"`	Advertised when `io.manager.getConnectionState()` is usable in the current session.
`API_METHOD_FETCH_DATA`	`"API_METHOD_FETCH_DATA"`	Advertised when `io.manager.fetchData()` is usable in the current session.
`API_METHOD_ON_CONNECTION_STATE_CHANGE`	`"API_METHOD_ON_CONNECTION_STATE_CHANGE"`	Advertised when `io.manager.onConnectionStateChange()` is usable in the current session.
`API_METHOD_LAYOUTS_CHECK_CONFLICT`	`"API_METHOD_LAYOUTS_CHECK_CONFLICT"`	Advertised when `io.manager.layouts.checkConflict()` is usable in the current session.
`API_METHOD_USERS_QUERY`	`"API_METHOD_USERS_QUERY"`	Advertised when `io.manager.users.query()` is usable in the current session.
`API_METHOD_GROUPS_QUERY`	`"API_METHOD_GROUPS_QUERY"`	Advertised when `io.manager.groups.query()` is usable in the current session.
`API_METHOD_CONFIGS_LIST`	`"API_METHOD_CONFIGS_LIST"`	Advertised when `io.manager.configs.list()` is usable in the current session.
`API_METHOD_CONFIGS_GET`	`"API_METHOD_CONFIGS_GET"`	Advertised when `io.manager.configs.get()` is usable in the current session.
`API_METHOD_CONFIGS_ON_CHANGE`	`"API_METHOD_CONFIGS_ON_CHANGE"`	Advertised when `io.manager.configs.onChange()` is usable in the current session.

ConfigChangeEvent

Available since @interopio/manager-api 5.0.0

Describes a per-entry change notification emitted by configs.onChange().

Property	Type	Description
`name`	`string`	The name of the config file.
`value`	`string \| undefined`	The raw string contents of the config file after the change, or `undefined` if it was removed.

FetchDataArgs

Arguments accepted by fetchData(). Each property is an opt-in toggle for refreshing the corresponding category of io.Manager data.

Property	Type	Description
`applications`	`boolean`	When `true`, refreshes the set of apps available to this user.
`layouts`	`boolean`	When `true`, refreshes the set of Layouts available to this user.
`commands`	`boolean`	When `true`, refreshes the set of commands available to this user.
`configs`	`boolean`	When `true`, refreshes the set of config entries available to this user.
`preferences`	`boolean`	When `true`, refreshes the set of preferences available to this user.

IOManagerConnectionState

Describes the current connection state of the io.Manager client.

Property	Type	Description
`baseUrl`	`string`	The base URL of the io.Manager Server.
`cacheEnabled`	`boolean`	If `true`, client-side caching is enabled.
`disconnectionError`	`Error`	The error that caused the disconnection. Present only when the client was disconnected by one.
`isConnected`	`boolean`	If `true`, the client is currently connected to the io.Manager Server.
`serverEnabled`	`boolean`	If `true`, the io.Manager Server is enabled in the io.Connect platform.

OnConfigChangeOptions

Available since @interopio/manager-api 5.0.0

Options object accepted by configs.onChange().

Property	Type	Description
`name`	`string`	Optional. When set, the subscription only fires for changes to the named custom config file (and the initial subscribe event is filtered to that file). When omitted, the callback receives events for every custom config file.

QueriedGroup

Available since @interopio/manager-api 5.0.0

Describes a group entry returned by groups.query().

Property	Type	Description
`name`	`string`	The group name.

QueriedUser

Available since @interopio/manager-api 5.0.0

Describes a user entry returned by users.query().

Property	Type	Description
`id`	`string`	The user ID.

QueryByNameRequest

Available since @interopio/manager-api 5.0.0

Describes the arguments passed to users.query() and groups.query().

Property	Type	Description
`name`	`string`	The name to look up. Matching is case-insensitive and partial. A name shorter than three characters returns no results.
`limit`	`number`	Optional maximum number of items to return. When omitted, all matches are returned.

QueryGroupsResponse

Available since @interopio/manager-api 5.0.0

Describes the result returned by groups.query().

Property	Type	Description
`groups`	`QueriedGroup[]`	The matching groups, de-duplicated and sorted alphabetically by name. See `QueriedGroup`.

QueryUsersResponse

Available since @interopio/manager-api 5.0.0

Describes the result returned by users.query().

Property	Type	Description
`users`	`QueriedUser[]`	The matching users, de-duplicated and sorted alphabetically by ID. See `QueriedUser`.

UserAdvancedLayoutDefinition

Available since @interopio/manager-api 5.0.0

Describes an advanced Layout owned by or accessible to the calling user. Returned as the conflict value of a CheckLayoutConflictResult when kind is "advanced". The full type definition is exported from the @interopio/manager-api library.

UserLayoutDefinitionV2

Available since @interopio/manager-api 5.0.0

Describes a legacy Layout owned by or accessible to the calling user. Returned as the conflict value of a CheckLayoutConflictResult when kind is "legacy". The full type definition is exported from the @interopio/manager-api library.

io.Manager Documentation

APIs