Upgrade

Overview

To upgrade io.Manager, you must update the @interopio/manager, @interopio/manager-admin-ui, and @interopio/manager-api packages in your project via npm.

If you aren't using automatic schema migration for PostgreSQL and Microsoft SQL Server databases, you must create the databases manually by using the provided schema creation scripts.

Unless explicitly stated in the changelog or on this page, all io.Manager packages support backward and forward compatibility between each other and with the io.Connect platforms. This means that older versions of io.Connect Desktop and io.Connect Browser will operate properly with newer versions of io.Manager and vice versa.

⚠️ Note that this section focuses only on versions of the io.Manager packages containing breaking changes and any required migration steps other than updating the packages via npm. Before upgrading, it's highly recommended to review the changelog and this section for details about the release to which you want to upgrade and also for all in-between releases. It's important to consider any breaking changes or necessary migration steps related to the packages or to the databases in order to ensure a smoother transition to the targeted version.

@interopio/manager

2.0.0

As of version 2.0.0, the @interopio/manager package will be published in the public NPM registry. Previous versions of the package will still be available in the private JFROG registry.
io.Manager now requires a license key.️ To acquire a license key, contact us at sales@interop.io. Existing customers should contact their Client Success representative to obtain a license key. For more details, see the Requirements > Licensing section.

The license key can be passed to io.Manager via the licenseKey property of the configuration object for initializing io.Manager, or via the API_LICENSE_KEY environment variable, depending on your deployment approach.

The following example demonstrates providing the license key when initializing io.Manager:

import { start } from "@interopio/manager";

const config = {
    // It's now required to provide a valid license key for io.Manager to operate.
    licenseKey: "my-license-key"
};

const server = await start(config);

The following example demonstrates providing the license key by using an environment variable:

API_LICENSE_KEY=my-license-key

Dropped Node.js 18 support. io.Manager now requires Node.js 20 LTS or 22 LTS.
The default value for skipProcessExitOnStop is changed to true. If you want process.exit() to be called when server.stop() is called or when the server fails to start, set skipProcessExitOnStop to false.
TypeScript type changes. The following changes will affect only clients who are using TypeScript instead of pure JavaScript.
- When implementing CustomAuthenticator, you now have to import the following types from @interopio/manager instead of @interopio/manager-api:
  - Token
  - User
- When implementing AuditService, you now have to import the following types from @interopio/manager instead of @interopio/manager-api:
  - AuditLog
  - AuditLogDataResult
  - CleanAuditLogRequest
  - DataRequest
  - User
- When implementing GroupsService, you now have to import the following types from @interopio/manager instead of @interopio/manager-api:
  - DataRequest
  - Group
  - GroupDataResult
  - GroupsFeatures
  - User
- The AuditService.getAll() method now returns AuditLogDataResult instead of DataResult<AuditLog>. The types are structurally equivalent.
- The types AuditLogEntityType and AuditLogOperation have been converted from TypeScript Union types to TypeScript Enums.
- The @interopio/manager-api package is no longer required for io.Manager Server deployments and was subsequently dropped as a dependency.
In CustomAuthenticator implementations, the value of the req.url property will now include the value of the base property provided to io.Manager via configuration. For example, if a request is received for /user and base is set to "api", in version 1.8.0 the value of req.url will be "/user", and in version 2.0.0 the value of req.url will be "/api/user".
Implementations of CustomAuthenticator should always call next even when rejecting requests and should not respond to the request directly. Previously, a common pattern for CustomAuthenticator implementations was rejecting the requests directly:

import type { Request, Response } from "express";
import {
    type CustomAuthenticator,
    type User,
    type Token
} from "@interopio/manager";

export class MyAuthenticator implements CustomAuthenticator {
    initialize(): void {};

    authenticate(
        req: Request,
        res: Response,
        next: (err?: Error, info?: User) = void,
        token?: Token
    ): void {

        const user = this.findUser(req);

        if (user) {
            // Successful authentication request.
            next(undefined, user);
        } else {
            // Failed authentication request.
            res.status(401);
            res.send();
            return;
        };
    };

    private findUser(req: Request): User {
        // Custom authentication logic.
        throw new Error("Not implemented.");
    };
};

Rejecting the requests directly could cause memory leaks and is therefore not recommended. Instead, implementations of CustomAuthenticator should import CustomAuthUnauthorizedError and use it in the following way:

import type { Request, Response } from "express";
import {
    type CustomAuthenticator,
    type User,
    type Token,
    CustomAuthUnauthorizedError
} from "@interopio/manager";

export class MyAuthenticator implements CustomAuthenticator {
    initialize(): void {};

    authenticate(
        req: Request,
        res: Response,
        next: (err?: Error, info?: User) = void,
        token?: Token
    ): void {
        const user = this.findUser(req);

        if (user) {
            // Successful authentication request.
            next(undefined, user);
        } else {
            // Failed authentication request.
            next(new CustomAuthUnauthorizedError());
        };
    };

    private findUser(req: Request): User {
        // Custom authentication logic.
        throw new Error("Not implemented.");
    };
};

If you are using an older versions of io.Manager, you can work around this problem by manually defining an error class and passing an instance of it to the next() function.

ℹ️ For an example of defining an error class and passing it to the next() function, see the Custom Authentication example on GitHub.

As of version 2.0.0, io.Manager will produce warnings when it detects that the authentication pipeline is short-circuited by omitting the call to the next() function.

Added a traceContext database column to the commands table (for PostgreSQL and Microsoft SQL Server only).

⚠️ Note that users who don't use automatic schema migration must create the traceContext column manually by running the following scripts.
For PostgreSQL:
ALTER TABLE commands
    ADD COLUMN IF NOT EXISTS "traceContext" JSON;
For Microsoft SQL Server:
IF NOT EXISTS (
    SELECT *
    FROM   sys.columns
    WHERE  object_id = OBJECT_ID(N'[dbo].[commands]')
    AND name = 'traceContext'
)
ALTER TABLE commands
    ADD traceContext NVARCHAR(MAX);

Changed the type of the commandParams database column of the commands table to JSON (for PostgreSQL only).

⚠️ Note that users who don't use automatic schema migration must change the type of the commandParams column manually by running the following script:
ALTER TABLE commands
    ALTER COLUMN "commandParams" TYPE JSON USING "commandParams"::json;

Changed the precision of the weight database column in the glue42SystemConfig table (for PostgreSQL and Microsoft SQL Server only).

⚠️ Note that users who don't use automatic schema migration must change the precision of the weight column manually by running the following scripts.
For PostgreSQL:
ALTER TABLE "glue42SystemConfig"
   ALTER COLUMN weight TYPE numeric(8, 6) USING weight::numeric(8, 6);
For Microsoft SQL Server:
ALTER TABLE glue42SystemConfig
    ALTER COLUMN weight decimal(8, 6);

Changed the type of the definition database column of the layouts table to JSON (for PostgreSQL and Microsoft SQL Server only).

⚠️ Note that users who don't use automatic schema migration must change the type of the definition column manually by running the following scripts.
For PostgreSQL:
ALTER TABLE layouts
    ALTER COLUMN definition TYPE JSON USING definition::json;
For Microsoft SQL Server:
ALTER TABLE layouts
    ALTER COLUMN definition NVARCHAR(max) NOT NULL;

Changed the type of the comment database column of the crashes table to NVARCHAR(max) (for Microsoft SQL Server only).

⚠️ Note that users who don't use automatic schema migration must change the type of the comment column manually by running the following script:
ALTER TABLE crashes
    ALTER COLUMN comment NVARCHAR(max);

Changed the types of the comment, description and attachment database columns of the feedback table to NVARCHAR(max) (for Microsoft SQL Server only).

⚠️ Note that users who don't use automatic schema migration must change the type of the columns manually by running the following script:
ALTER TABLE feedback
    ALTER COLUMN comment NVARCHAR(max);
ALTER TABLE feedback
    ALTER COLUMN description NVARCHAR(max) NOT NULL;
ALTER TABLE feedback
    ALTER COLUMN attachment NVARCHAR(max) NOT NULL;

Monitoring configuration changes:
- Removed false, "none", and "sentry" as values for the monitoring property. Use { type: "none" } or { type: "sentry" } instead.
Sentry monitoring configuration changes:
- Removed the tracesSampleRate property from the Sentry monitoring configuration. Use sentryOptions.tracesSampleRate instead.
- Removed the dsn property from the Sentry monitoring configuration. Use sentryOptions.dsn instead.
- Tracing via the Sentry SDK is no longer supported. The recommended way to send traces to Sentry is by using OpenTelemetry traces. See also the OpenTelemetry with Sentry example on GitHub.
Removed ["admin"] as a default value for the API_AUTH_EXCLUSIVE_USERS environment variable. This change doesn't affect users who don't use environment variables for configuring io.Manager as the default value was valid only for the API_AUTH_EXCLUSIVE_USERS environment variable.
Due to a change in the FDC3 specification, the name and definition.name app properties won't be checked for consistency for FDC3 app definitions. The name and definition.appId properties will still be checked. For more details, see the FDC3 Standard 2.1.
When using environment variable configuration with .env files, values from the .env files will override the process environment variables. This means that if an environment variable is both defined in the .env file and passed to the process, the value from the .env file will be used.

1.7.0

Added database column others to the last_updated table (for PostgreSQL and Microsoft SQL Server only).

⚠️ Note that users who don't use automatic schema migration must create the others column manually by running the following scripts.
For PostgreSQL:
ALTER TABLE last_updated
    ADD COLUMN IF NOT EXISTS others JSON NULL;
For Microsoft SQL Server:
IF NOT EXISTS (
    SELECT *
    FROM   sys.columns
    WHERE  object_id = OBJECT_ID(N'[dbo].[last_updated]')
      AND name = 'others'
)
ALTER TABLE last_updated
    ADD others NVARCHAR(MAX);

1.6.0

Added database column browser to the machines table (for PostgreSQL and Microsoft SQL Server only).

⚠️ Note that users who don't use automatic schema migration must create the browser column manually by running the following scripts.
For PostgreSQL:
ALTER TABLE machines
    ADD COLUMN IF NOT EXISTS browser JSON NULL;
For Microsoft SQL Server:
IF NOT EXISTS (
    SELECT *
    FROM   sys.columns
    WHERE  object_id = OBJECT_ID(N'[dbo].[machines]')
    AND name = 'browser'
)
ALTER TABLE machines
    ADD browser NVARCHAR(MAX);

1.0.0

Users can now be compared in a case-insensitive way. You can use the username_case_sensitive property in the configuration object for initializing the io.Manager Server or the API_USERNAME_CASE_SENSITIVE environment variable to switch between the two modes. The new default is case-insensitive. To switch back to case sensitive mode, set the username_case_sensitive property or the API_USERNAME_CASE_SENSITIVE environment variable to true.
Removed status endpoint. Use GET / instead.

@interopio/manager-admin-ui

3.0.0

As of version 3.0.0, the @interopio/manager-admin-ui package will be published in the public NPM registry. Previous versions of the package will still be available in the private JFROG registry.
Dropped React 17 support. The io.Manager Admin UI now requires React 18. See the React 18 Upgrade Guide and the Admin UI example on GitHub.
Removed the users top-level configuration property. Its options will now be implied from the auth top-level configuration property.
If using TypeScript, the "jsx" property of the "compilerOptions" object in the tsconfig.json file must be set to "react-jsx".
All io.Manager Admin UI style imports have been combined in one:

// This is the only required style import.
import "@interopio/manager-admin-ui/styles.css";

The @interopio/theme-demo-apps dependency can be safely removed from your package.json file. For a complete example, see the Admin UI example on GitHub.

For clients using Auth0 authentication: The @auth0/auth0-react package has been updated from v1 to v2. The @auth0/auth0-react v2 package introduces breaking changes to the auth_auth0 property which accepts a value of type Auth0ProviderOptions imported from @auth0/auth0-react. For more details, see the Auth0-React v2 Migration Guide.
For clients using the manager-admin-ui docker image: The PUBLIC_URL environment variable has been deprecated and won't have any effect. Setting the REACT_APP_BASE environment variable will be enough for the routing to work correctly.

@interopio/manager-api

4.0.0

TypeScript type changes. The following changes will affect only clients who are using TypeScript instead of pure JavaScript.
- The usage of type DataResult<T> has been replaced with several concrete types:
  - AppPreferenceDataResult
  - AuditLogDataResult
  - CommandDataResult
  - ClientCrashDataResult
  - FeedbackDataResult
  - GroupDataResult
  - LayoutDataResult
  - MachineDataResult
  - UserSessionDataResult
  - SystemConfigEntryDataResult
- Removed type alias GetAppsRequest - use DataRequest instead.
- Removed type alias GetCommandsResponse - use CommandDataResult instead.
- Removed type alias GetUsersResponse - use UserDataResult instead.
- The types of the following interface properties have been converted from inline TypeScript Union types to TypeScript Enums:
  - CleanSessionsAction.action is now of type CleanSessionsAction.
  - UserAppStatus.explain is now of type UserAppStatusExplain.
  - AuditLog.entityType is now of type AuditLogEntityType.
  - AuditLog.operation is now of type AuditLogOperation.
  - Command.status is now of type CommandStatus.
  - Command.resultType is now of type ResultType.
  - TextFilterCondition.type is now of type TextFilterType.
  - BooleanFilterCondition.type is now of type BooleanFilterType.
  - NumberFilterCondition.type is now of type NumberFilterType.
  - DateFilterCondition.type is now of type DateFilterType.
  - SortOrder.sort is now of type SortOrderEnum.
  - LogicalCondition.operator is now of type LogicalConditionOperator.
- Removed types SimpleCondition and Filter.
The MatchAll export has been renamed to ConfigMatchAll.

io.Manager Documentation

Upgrade