io.Manager Documentation

Changelog

5.0

5.0.0

Release date: 28.08.2026

Breaking Changes

For more details, see the Upgrade section.

  • The type of the attachment field of the AddFeedbackRequest DTO has been changed from string to File | NodeJSReadStream.

  • The type of the upload_file_minidump field of the CreateCrashRequest DTO has been changed from string to File | NodeJSReadStream.

  • The declared return type of the whoAmI() method has been changed from Promise<User> to Promise<WhoAmIResponse>. The method has always returned only the id, email, apps, and groups fields at runtime; the type now reflects that.

  • The following exports have been removed from the @interopio/manager-api package:

    • BaseAPI
    • AuthOptions
    • CustomRequest
    • CustomRequestResponse
    • ClientOptions
    • IOManagerCache
    • IOManagerCacheItem
    • IOManagerLogger
    • IOManagerAsyncSequelizer
    • SanitizedIOManagerApiError
    • IOManagerRequestValidationError
    • CachedClientAPI
    • CachedClientOptions
    • IOManagerConnectionState
    • isIOManagerTimeoutError

New Features

  • Added a ClientAPIV2 class - a client for the io.Manager Server V2 user-facing REST API.

  • Added a getFileResultBytes(commandId: string): Promise<Blob> method to the Commands class. It returns the command result file as its own bytes. Note that using this method requires io.Manager 4.0 or later.

  • Added a groupsV2 client - a GroupsV2 class for the io.Manager Server /v2/groups REST API. It reads, creates, updates, and deletes stored groups, and expands a set of group names into the full set of groups and granular permission groups they map to.

  • Added an advancedLayouts client - an AdvancedLayouts class for working with advanced Layouts through the io.Manager Server admin REST API. Using this client requires io.Manager 4.0 or later.

  • Added getMigration(), getMigrationLayouts(), and runMigration() methods to the AdvancedLayouts class for reviewing and running the one-time migration of legacy Layouts to advanced Layouts. All three methods require the IO_MANAGER:LAYOUTS:WRITE permission group and are available only when advanced Layouts are enabled on the server. Using these methods requires io.Manager 4.0 or later.

  • Added a getDump(id: string): Promise<Blob> method to the Crashes class. Use this method to download the binary crash dump file for a given crash ID. The call reuses the client's existing authentication, so no additional credentials need to be supplied.

  • Added a getLogsArchive(options?: GetLogsArchiveOptions): Promise<Blob> method to the ServerAPI class. It returns a zip archive of the log files the io.Manager Server writes, including rotated backups. Use the includeBackups and fileNames options to narrow what the archive contains. Note that using this method requires io.Manager 4.0 or later.

  • Added an optional configKeys parameter to the systemConfig.getAll() method. Use this parameter to narrow which config-file names appear in each entry's configs map.

  • Added an isSystemConfigFile(name: string): boolean method to the systemConfig client. It reports whether a config-file name is one of the config files the io.Connect platform consumes itself, as opposed to a custom config file added for apps to read. Only custom config files are readable by apps through the io.Manager client API.

  • Added a browser-platform.json member to the ConnectConfigKey enumeration, so that it names every config file the io.Connect platform consumes itself: system.json, themes.json, stickywindows.json, channels.json, logger.json, and browser-platform.json.

  • The following methods have been added to the ManagerLibAPI interface exposed by the ManagerLib export, accessible via the io.manager object after the library has been included as an additional library when initializing io.Connect Desktop or io.Connect Browser. Domain operations are grouped under the layouts, users, groups, and configs namespaces:

New Method Description
users.query(args: QueryByNameRequest): Promise<QueryUsersResponse> Looks up users known to io.Manager by name. Matching is case-insensitive and partial; results are de-duplicated and sorted alphabetically.
groups.query(args: QueryByNameRequest): Promise<QueryGroupsResponse> Looks up groups known to io.Manager by name. Matching is case-insensitive and partial; results are de-duplicated and sorted alphabetically.
layouts.checkConflict(request: CheckLayoutConflictRequest): Promise<CheckLayoutConflictResult> Checks whether saving a Layout with the given identity would conflict with an existing Layout, before the save is submitted. Returns a discriminated union narrowed by the kind field - "advanced" or "legacy" - that exposes the conflicting Layout when one is found, or no conflict when the Layout can be saved cleanly.
checkCapability(capability: ClientCapability): Promise<CapabilityStatus> Checks whether a given client-side capability is usable in the current session and, when it isn't, why. Supports both platform-level capabilities (e.g. ADVANCED_LAYOUTS) and method-level capabilities prefixed with API_METHOD_.
checkCapabilities(): Promise<Record<ClientCapability, CapabilityStatus>> Checks every client-side capability at once, returning a map from each ClientCapability identifier to its CapabilityStatus.
configs.list(): Promise<string[]> Returns the names of the custom config files set in io.Manager.
configs.get(name: string): Promise<string | undefined> Returns the raw string contents of the named custom config file, or undefined if it isn't set.
configs.onChange(callback, options?: { name?: string }): Promise<UnsubscribeFunction> 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.

The configs namespace exposes only the custom config files an administrator has added in io.Manager. The config files the io.Connect platform itself consumes aren't available to apps: naming one of them produces the same result as naming a config file that has never been set.

The existing fetchData() method now also accepts a preferences opt-in toggle on its FetchDataArgs parameter - set it to true to refresh the set of app preferences available to the user, alongside apps, Layouts, commands, and configs.

A new ClientCapability enumeration has been added alongside the checkCapability() method, exported from the @interopio/manager-api/desktop and @interopio/manager-api/browser sub-path entry points. It provides constants for two flavors of capability identifier - platform-level (e.g. ADVANCED_LAYOUTS) and method-level (API_METHOD_* constants identifying individual io.manager.* methods). For the full list of members, see the ClientCapability reference.

The CapabilityStatus interface returned by checkCapability() and the CapabilityUnavailableReason enumeration it reports (METHOD_NOT_AVAILABLE, SERVER_DISABLED, SERVER_INCOMPATIBLE) are exported from the same sub-path entry points. CapabilityUnavailableReason is also the code carried by the Error a member throws when called while unavailable, so a single mapping handles both the up-front check and a catch block.

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

// Refreshing the available apps, Layouts, and preferences.
await io.manager.fetchData({
    layouts: true,
    applications: true,
    preferences: true
});

// Looking up users and groups by name.
const users = await io.manager.users.query({ name: "alice" });
const groups = await io.manager.groups.query({ name: "traders" });

// Checking whether the chosen identity would conflict with an existing
// Layout before submitting the save.
const conflict = await io.manager.layouts.checkConflict({
    type: "Workspace",
    name: "my-workspace",
    accessLevel: "private"
});

if (conflict.kind === "advanced" && conflict.conflict) {
    // Prompt the user before overwriting `conflict.conflict`.
} else if (conflict.kind === "legacy" && conflict.conflict) {
    // Prompt the user before overwriting `conflict.conflict`.
}

// Checking client-side capabilities - and learning why one is unavailable.
const checkConflictStatus = await io.manager.checkCapability(ClientCapability.API_METHOD_LAYOUTS_CHECK_CONFLICT);
if (!checkConflictStatus.available) {
    // checkConflictStatus.reason is "METHOD_NOT_AVAILABLE", "SERVER_DISABLED", or "SERVER_INCOMPATIBLE".
}

// Listing and reading the config files set in io.Manager.
const names = await io.manager.configs.list();
const contents = await io.manager.configs.get("my-config.json");

// 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" });

⚠️ Note that using these methods requires io.Manager 4.0 or later and io.Connect Desktop 10.5 (unreleased). For more details, see the APIs > Initiating Interactions from io.Connect section.

Deprecated Methods

The following methods have been deprecated:

Deprecated Method New Method
Commands.getFileResult() Use Commands.getFileResultBytes() instead.
ServerAPI.getLog() Use ServerAPI.getLogsArchive() instead.

Improvements & Bug Fixes

  • Corrected the declared return type of the io.manager.onConnectionStateChange() method to Promise<UnsubscribeFunction>. The method has always returned a Promise at runtime; the type now reflects that, so await the call to obtain the unsubscribe function.

Dependency Changes

The following dependencies have been updated:

  • @interopio/schemas from version ^9.7.0 to ^10.0.0

4.0

4.2.0

Release date: 10.03.2026

New Features

  • Added a new ManagerLib export that integrates the @interopio/manager-api library with the @interopio/desktop library in io.Connect Desktop projects and the @interopio/browser-platform and @interopio/browser libraries in io.Connect Browser projects. This export provides methods for 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 configuration, and more.

⚠️ Note that using this feature requires io.Connect Desktop 10.3 or later and io.Connect Browser 4.3 or later.

New sub-path exports have been added to the library, which expose the ManagerLib export for usage in io.Connect Desktop and io.Connect Browser projects:

Export Description
@interopio/manager-api/browser Exposes the ManagerLib export for usage with the @interopio/browser-platform and @interopio/browser libraries.
@interopio/manager-api/desktop Exposes the ManagerLib export for usage with the @interopio/desktop library.

To use the functionalities provided by the ManagerLib export, you must include it in the libraries array of the configuration object for initializing the respective io.Connect library.

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

New Method Description
getConnectionState(): Promise<IOManagerConnectionState> Retrieves information related to the state of the connection to io.Manager.
fetchData(args: FetchDataArgs): Promise<void> Triggers data refresh from io.Manager. You can specify the types of data to be refreshed (e.g. data related to apps, Layouts, system configurations).
onConnectionStateChange(callback): UnsubscribeFunction Notifies when the state of the connection to io.Manager changes. Returns an unsubscribe function.

The following example demonstrates using the ManagerLib export in an io.Connect Desktop client app:

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 = 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 using the methods in io.Connect Desktop and io.Connect Browser projects and for a complete API reference, see the APIs > Initiating Interactions from io.Connect section.

4.1.1

Release date: 24.02.2026

Improvements & Bug Fixes

  • Migrated from zod to zod/mini for a smaller bundle footprint.

  • Improved integration between io.Connect and io.Manager.

4.1.0

Release date: 30.01.2026

New Features

  • New API methods have been added:
New Method Description
api.getAllCommandDescriptions(): Promise<AggregatedCommandDescription[]> Retrieves all supported commands across all io.Connect platform versions. Each AggregatedCommandDescription object of the resulting array describes a unique supported command and contains information about the command type, the command description, version-specific command parameter examples, and a list of the io.Connect platform versions which support the command.

4.0.7

Release date: 15.08.2025

Improvements & Bug Fixes

  • Improved integration between io.Connect and io.Manager.

4.0.6

Release date: 15.08.2025

Improvements & Bug Fixes

  • Improved integration between io.Connect and io.Manager.

4.0.5

Release date: 15.08.2025

Improvements & Bug Fixes

  • Improved integration between io.Connect and io.Manager.

4.0.4

Release date: 15.08.2025

Improvements & Bug Fixes

  • Improved integration between io.Connect and io.Manager.

4.0.3

Release date: 12.08.2025

Improvements & Bug Fixes

  • Improved integration between io.Connect and io.Manager.

4.0.2

Release date: 08.08.2025

Improvements & Bug Fixes

  • Improved integration between io.Connect and io.Manager.

4.0.1

Release date: 07.08.2025

Improvements & Bug Fixes

  • Improved integration between io.Connect and io.Manager.

Dependency Changes

The following dependencies have been added to the package:

  • zod version ^4.0.10

4.0.0

Release date: 11.07.2025

Breaking Changes

  • TypeScript types. For more details, see the Upgrade section.
  • The MatchAll export has been renamed to ConfigMatchAll.

Improvements & Bug Fixes

  • Added URL encoding to all path and query parameters.
  • Added JSDoc comments to all API methods.

Dependency Changes

The following dependencies have been removed from the package:

  • @types/request

The following dependencies have been updated:

  • @interopio/schemas from version ^9.2.0 to ^9.7.0
  • axios from version ^1.7.4 to ^1.9.0
  • form-data from version ^4.0.0 to ^4.0.2
  • jwt-decode from version ^3.1.2 to ^4.0.0

3.0

3.1.0

Release date: 16.08.2024

New Methods

New API methods have been added:

New Method Description
api.initialize(): Promise<void> Initializes the API client. Calling it is required before using any of the new methods described here.
api.hasCapability(capability: ServerCapability): boolean Checks whether the specified capability is supported by the io.Manager Server. Returns true if the capability is supported and false otherwise. Use the ServerCapability enumeration to specify the desired capability - e.g., api.hasCapability(ServerCapability.ADMIN_API_V2_APP_ADD).
api.appsV2.addApp(app: AddAppRequest): Promise<App> Creates a new app definition or throws an error if an app definition with the same name property already exists. Returns the created app definition.
api.appsV2.addOrUpdateApp(app: AddOrUpdateAppRequest): Promise<App> Creates a new app definition or updates an existing one if an app definition with the same name property already exists. Returns the created or updated app definition.
api.appsV2.updateApp(app: UpdateAppRequest): Promise<App> Updates an app definition or throws an error if an app definition with the specified name property isn't found. Returns the updated app definition.
api.layoutsV2.addLayout(layout: AddLayoutRequest): Promise<Layout> Creates a new Layout definition or throws an error if a Layout definition with the same combination of name, type and owner properties already exists. Returns the created Layout definition.
api.layoutsV2.addOrUpdateLayout(layout: AddOrUpdateLayoutRequest): Promise<Layout> Creates a new Layout definition or updates an existing one if a Layout definition with the same id property (or the same combination of name, type and owner properties if id isn't provided) already exists. Returns the created or updated Layout definition.
api.layoutsV2.updateLayout(layout: UpdateLayoutRequest): Promise<Layout> Updates a Layout definition or throws an error if a Layout definition with the specified id property (or the specified combination of name, type and owner properties if id isn't provided) isn't found. Returns the updated Layout definition.

Deprecated Methods

The following API methods have been deprecated:

Deprecated Method New Method
api.apps.addOrUpdate() Use api.appsV2.addOrUpdateApp() instead.
api.layouts.addCommonLayout() Use api.layoutsV2.addLayout() instead.
api.layouts.addLayout() Use api.layoutsV2.addLayout() instead.
api.layouts.addUserLayout() Use api.layoutsV2.addLayout() instead.

Improvements & Bug Fixes

  • Audit fix for NPM packages.

2.0

2.0.2

Release date: 15.05.2024

Improvements & Bug Fixes

  • Extended typings for NumberFilterCondition and DateFilterCondition with notExists option.
  • Updated dependencies.

2.0.1

Release date: 27.03.2024

Improvements & Bug Fixes

2.0.0

Release date: 22.03.2024

Breaking Changes

  • Remove the dataRequest parameter from systemConfig.getAll().

1.0

1.6.3

Release date: 10.02.2024

Improvements & Bug Fixes

  • Fixed Axios error interceptor.

1.6.2

Release date: 12.01.2024

Improvements & Bug Fixes

  • Audit fix for NPM packages.

1.6.0

Release date: 29.11.2023

New Features

  • Added a response interceptor.

Improvements & Bug Fixes

  • Updated Axios to from 0.28.0 to 1.6.2.

1.5.0

Release date: 15.06.2023

New Features

  • Added a core option in GlueInfo.

1.4.0

Release date: 19.05.2023

New Features

  • Added a assignLayoutToUser() API method.
  • Added a setExplicitUserItems() API method.

1.3.2

Release date: 16.05.2023

Improvements & Bug Fixes

  • Relaxed hello request.

1.3.1

Release date: 16.05.2023

Improvements & Bug Fixes

  • Relaxed machine configuration.

1.3.0

Release date: 27.04.2023

New Features

  • Exposed transformResponse options.

1.2.0

Release date: 31.03.2023

Improvements & Bug Fixes

  • Updated to latest @interopio/schemas.

1.1.2

Release date: 01.11.2022

Improvements & Bug Fixes

  • Fixed System Configuration API bug.

1.1.1

Release date: 01.11.2022

Improvements & Bug Fixes

  • Fixed System Configuration API bug.

1.1.0

Release date: 31.10.2022

New Features

  • Added a removeConfigForIdentifier() method in the System Configuration API.

1.0.2

Release date: 23.10.2022

Improvements & Bug Fixes

  • Added a weight property to Glue42SystemConfigIdentifier.

1.0.1

Release date: 23.10.2022

Improvements & Bug Fixes

  • Made some of the properties of AuditLog optional.

1.0.0

Release date: 15.10.2022

Breaking Changes

  • Removed Node.js core dependencies fs and path which causes breaking changes in the Client API.

0.1

0.8.0

Release date: 27.09.2022

New Features

  • Added an unload() method to the Client API.

0.7.6

Release date: 19.09.2022

Improvements & Bug Fixes

  • Fixed typings.

0.7.5

Release date: 07.06.2022

Improvements & Bug Fixes

  • Fixed the addFeedback() method.

0.7.3

Release date: 07.06.2022

Improvements & Bug Fixes

  • Fixed URL joining when using a custom request module.

0.7.2

Release date: 07.06.2022

Improvements & Bug Fixes

  • Removed urlJoin() and fixed URL joining when using a custom request module.

0.7.0

Release date: 22.05.2022

New Features

  • Added support for passing a custom request library.

0.6.0

Release date: 22.03.2022

New Features

  • Added a Schema API.

0.5.0

Release date: 21.03.2022

New Features

  • Added support for Basic authentication in Options.
  • Added a password property in User.

0.4.5

Release date: 13.03.2022

New Features

  • Added a getGroupsFeatures() method in the Groups API.