Capabilities

io.Manager stores the Layouts of the connected io.Connect platforms (Global and Workspace Layouts) and provides them to the users of io.Connect Desktop and io.Connect Browser.

ℹ️ For more details on using Layouts in the io.Connect platforms, see the Capabilities > Windows > Layouts section of the io.Connect Desktop documentation and the Capabilities > Windows > Layouts section of the io.Connect Browser documentation.

The io.Manager Server stores Layouts in one of two models - advanced Layouts or legacy Layouts.

You can configure which model the io.Manager Server provides to the io.Connect platforms, and each connected io.Connect platform must use the same model.

To manage the stored Layouts, use the io.Manager Admin UI or the io.Manager Server REST API.

Available since io.Manager 4.0 & io.Connect Desktop 10.5

Advanced Layouts enable users to share Global and Workspace Layouts directly from io.Connect Desktop. A user can share a Layout they own with specific users and groups, granting each of them view or edit access, or make the Layout public, unlike legacy Layouts, where only an administrator can make a Layout available to other users.

An advanced Layout is identified by its id and carries its own access information, which determines the users that can see and edit the Layout.

The following table describes how advanced Layouts differ from legacy Layouts:

Feature	Advanced Layouts	Legacy Layouts
Identity	The id of the Layout.	The name, type, and owner of the Layout.
Owner	A user.	A user, or * for a common Layout that isn't owned by a specific user.
Visibility	Set by the access level of the Layout - "private", "public", or "shared".	A Layout owned by a user is private. A common Layout is visible to all users, or to specific groups.
Editing	The owner and the users and groups with "edit" access can update, rename, and delete the Layout, and change its access information.	Users can't change a common Layout.
Saving changes without edit access	Rejected with an HTTP 403 status code. No private copy is created.	Saved as a private copy owned by the user. The common Layout stays unchanged.
Name uniqueness	Unique per type and owner while the Layout is private, and unique per type across all owners once the Layout is shared or public.	Unique per type and owner.
Default Global Layout	There is no default Global Layout common to all users. Each user sets their own default Global Layout from the io.Connect platform.	A Layout marked as default is the default Global Layout for every user that can see it, unless the user has a default Global Layout of their own.
Supported platforms	io.Connect Desktop 10.5 or later.	io.Connect Desktop and io.Connect Browser.

Enabling Advanced Layouts

⚠️ Note that the io.Manager Server and all connected io.Connect platforms must use the same Layout model - advanced Layouts must be either enabled in all of them, or disabled in all of them.

⚠️ Note that io.Connect Browser doesn't support advanced Layouts. If any io.Connect Browser clients connect to the io.Manager Server, the server must keep providing legacy Layouts.

To switch from legacy Layouts to advanced Layouts:

1. Set the enabled property of the advancedLayouts top-level key in the configuration object for initializing the io.Manager Server to true, or set the API_ADVANCED_LAYOUTS_ENABLED environment variable to true, depending on your deployment approach.

The following example demonstrates how to enable advanced Layouts when initializing the io.Manager Server:

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

const config = {
    advancedLayouts: {
        // Provide advanced Layouts to the io.Connect platforms.
        enabled: true
    }
};

const server = await start(config);

The following example demonstrates how to enable advanced Layouts via an environment variable:

API_ADVANCED_LAYOUTS_ENABLED=true

2. Enable advanced Layouts in each connected io.Connect Desktop platform instance by setting the "enabled" property of the "advancedLayouts" object under the "server" top-level key in the system.json system configuration file of io.Connect Desktop to true. Using advanced Layouts requires io.Connect Desktop 10.5 or later.

3. If the io.Manager Server already holds legacy Layouts, run the one-time migration of legacy Layouts to advanced Layouts. Until the migration runs, the io.Connect platforms will see only the advanced Layouts created after advanced Layouts were enabled.

4. Optionally, restrict the users that can share Layouts or make them public.

While advanced Layouts are enabled, the REST API endpoints for legacy Layouts reject writes with an HTTP 400 status code. While advanced Layouts are disabled, the endpoints for advanced Layouts reject writes in the same way.

⚠️ Note that you can use the advancedLayoutsEnabled field in the response of the GET /v2/server/info endpoint to determine which Layout model the io.Manager Server uses.

Reverting to Legacy Layouts

To return to legacy Layouts, set to false the settings described in Enabling Advanced Layouts on the io.Manager Server and in each connected io.Connect platform instance.

Changes made to advanced Layouts while they were enabled aren't reflected in the legacy Layouts. Changes made to legacy Layouts after they were migrated aren't carried over by a later migration run, and once the migration has completed without failures, it can't be run again.

Legacy Layouts are the default Layout model of the io.Manager Server. A legacy Layout is identified by its name, type, and owner. The following fields describe the visibility of a legacy Layout and whether it is a default Global Layout:

Field	Description
accessList	Groups that can see a common Layout.
default	If true, the Layout is the default Global Layout for every user that can see it, unless the user has a default Global Layout of their own.
owner	The user that owns the Layout, or * for a common Layout that isn't owned by a specific user - e.g., a public Layout or a Layout shared with groups via accessList.
public	If true, a common Layout is visible to all users.

Users can't change a common Layout. When a user saves a public or shared Layout, io.Manager creates a private copy of it for that user, and the common Layout stays unchanged.

The io.Manager Server REST API manages Layouts via the following endpoints. Each endpoint requires the listed permission group.

ℹ️ For more details on the request and response shapes of the endpoints, see the Swagger UI provided by the io.Manager Server.

The @interopio/manager-api library exposes the operations for advanced Layouts and Layout migration via the advancedLayouts property of an AdminAPI instance.

Advanced Layouts

Available since io.Manager 4.0

Use the following endpoints to manage advanced Layouts:

Endpoint	Permission	Description
DELETE /advancedLayouts	IO_MANAGER:LAYOUTS:WRITE	Deletes all advanced Layouts.
DELETE /advancedLayouts/{id}	IO_MANAGER:LAYOUTS:WRITE	Deletes the advanced Layout with the given id.
GET /advancedLayouts	IO_MANAGER:LAYOUTS:READ	Lists advanced Layouts. Use the optional params query parameter to filter, group, sort, and page the results.
GET /advancedLayouts/{id}	IO_MANAGER:LAYOUTS:READ	Returns the advanced Layout with the given id.
POST /advancedLayouts	IO_MANAGER:LAYOUTS:WRITE	Creates an advanced Layout, or updates it if one with the same id already exists.
POST /advancedLayouts/add	IO_MANAGER:LAYOUTS:WRITE	Creates an advanced Layout. Returns 400 when the Layout would break the name uniqueness rule, so an existing Layout is never overwritten.
POST /advancedLayouts/check-conflict	IO_MANAGER:LAYOUTS:READ	Checks whether saving a Layout with the given name, type, owner, and access level would conflict with an existing advanced Layout.
POST /advancedLayouts/update	IO_MANAGER:LAYOUTS:WRITE	Updates the advanced Layout with the given id. Returns 404 when no Layout with that id exists.

Layout Migration

Available since io.Manager 4.0

Use the following endpoints to review and run the migration of legacy Layouts to advanced Layouts:

Endpoint	Permission	Description
GET /advancedLayouts/migration/layouts	IO_MANAGER:LAYOUTS:WRITE	Lists the legacy Layouts a migration run would migrate, each with the access information it will receive. Use the optional params query parameter to filter, sort, and page the results.
GET /advancedLayouts/migration/status	IO_MANAGER:LAYOUTS:WRITE	Returns the migration status, the number of legacy Layouts a run would migrate, and the outcome of the last run.
POST /advancedLayouts/migration/run	IO_MANAGER:LAYOUTS:WRITE	Runs the migration and returns its outcome.

Legacy Layouts

Use the following endpoints to manage legacy Layouts:

Endpoint	Permission	Description
DELETE /layouts	IO_MANAGER:LAYOUTS:WRITE	Deletes all legacy Layouts.
DELETE /layouts/{id}	IO_MANAGER:LAYOUTS:WRITE	Deletes the legacy Layout with the given id.
DELETE /layouts/{type}/{name}	IO_MANAGER:LAYOUTS:WRITE	Deletes the public or shared legacy Layout with the given type and name.
GET /layouts	IO_MANAGER:LAYOUTS:READ	Lists legacy Layouts. Use the optional params query parameter to filter, group, sort, and page the results.
GET /layouts/{id}	IO_MANAGER:LAYOUTS:READ	Returns the legacy Layout with the given id.
GET /layouts/{type}/{name}	IO_MANAGER:LAYOUTS:READ	Returns the public or shared legacy Layout with the given type and name.
POST /v2/layouts/add	IO_MANAGER:LAYOUTS:WRITE	Creates a legacy Layout. Returns 400 when a Layout with the same name, type, and owner already exists.
POST /v2/layouts/add-or-update	IO_MANAGER:LAYOUTS:WRITE	Creates a legacy Layout, or updates it if it already exists.
POST /v2/layouts/update	IO_MANAGER:LAYOUTS:WRITE	Updates an existing legacy Layout. Returns 404 when no Layout with the given id, or with the given name, type, and owner, exists.