Capabilities

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

ℹ️ For more details on sharing Layouts in io.Connect Desktop via the Launchpad and Workspaces App, see the Capabilities > Windows > Layouts > Overview > Layout Sharing section of the io.Connect Desktop documentation.

Each advanced Layout (Global or Workspace Layout) carries its access information in its accessInfo property: the owner of the Layout, its access level, and the users and groups granted access to it. The io.Manager Server uses this information to decide which users can see the Layout and which users can change it.

The accessInfo object has the following properties:

The access level of an advanced Layout determines which users can see the Layout and which users can edit it:

Editing a Layout covers updating its definition, renaming it, deleting it, and changing its access information. A user with "edit" access can change the access level of the Layout and the users and groups granted access to it, subject to the sharing restriction, but can't change the owner of the Layout from an io.Connect platform. The owner can be changed only from the io.Manager Admin UI or via the REST API.

A user who can see a Layout but can't edit it can't save changes to it. The io.Manager Server rejects the save, rename, or delete with an HTTP 403 status code and sets the reason field of the error response to LAYOUT_EDIT_NOT_PERMITTED.

A Layout that is disabled in io.Manager isn't visible to any user, including its owner, regardless of its access level. You can disable and enable Layouts only from the io.Manager Admin UI or via the REST API - the io.Connect platforms can't change the disabled flag of a Layout.

Each object in the accessEntities array describes the access granted to one user or one group and has the following properties:

A group entry grants access to each member of the group.

A "shared" Layout must have at least one access entity. A "public" Layout is visible to all users, so its access entities are used only to grant "edit" access to specific users and groups - entries with "view" access are discarded when the Layout is saved.

By default, any authenticated user can save advanced Layouts with the "shared" or "public" access level.

To allow only the members of specific groups to share Layouts or make them public, use the sharingRequiredGroup property of the advancedLayouts top-level key in the configuration object for initializing the io.Manager Server, or the API_ADVANCED_LAYOUTS_SHARING_REQUIRED_GROUP environment variable, depending on your deployment approach.

The sharingRequiredGroup property accepts a group name or a list of group names, and the environment variable accepts a comma-delimited list of group names. A member of any listed group can share Layouts and make them public.

The following example demonstrates how to restrict Layout sharing to the members of the "layout-sharers" and "team-leads" groups when initializing the io.Manager Server:

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

const config = {
    advancedLayouts: {
        enabled: true,
        // Only members of the `layout-sharers` or the `team-leads` group will be allowed
        // to save advanced Layouts with `accessLevel` set to `"shared"` or `"public"`.
        sharingRequiredGroup: ["layout-sharers", "team-leads"]
    }
};

const server = await start(config);

The following example demonstrates how to restrict Layout sharing to the members of the "layout-sharers" and "team-leads" groups via environment variables:

API_ADVANCED_LAYOUTS_ENABLED=true
API_ADVANCED_LAYOUTS_SHARING_REQUIRED_GROUP=layout-sharers,team-leads

The restriction applies when a Layout is saved from an io.Connect platform with its access level set to "shared" or "public". When the user isn't a member of any of the listed groups, the io.Manager Server rejects the save with an HTTP 403 status code and sets the reason field of the error response to LAYOUT_SHARING_NOT_PERMITTED. Saving "private" Layouts is never restricted. Renaming a Layout the user can edit, or updating its definition without sending its access information, requires only "edit" access.

When an io.Connect platform saves several Layouts at once and the server refuses some of them because of missing "edit" access or the sharing restriction, the response reports the same reason on each failed entry.

The restriction doesn't apply to the io.Manager Admin UI or to the /advancedLayouts endpoints of the io.Manager Server REST API.

The io.Manager Server reports to each connected io.Connect platform whether the current user can share Layouts and make them public, so that the platform can hide or disable its sharing options. The reported value follows the changes in the group membership of the user.

The name of an advanced Layout is unique per type and owner while the Layout is "private", and unique per type across all owners once the Layout is "shared" or "public". This means that two users can each own a private Workspace Layout named "Trading Desk", but only one shared or public Workspace Layout can have that name. Sharing a private Layout or making it public is rejected with an HTTP 400 status code when a shared or public Layout of the same type already has the same name.

To check whether a Layout name is available before saving, use the checkConflict() method of the io.Manager API from an io.Connect platform, or the POST /advancedLayouts/check-conflict endpoint of the io.Manager Server REST API.