AdapTable Version:

Framework:

Setting Up Teamsharing

Summary

Team Sharing is configured by developers at Design Time
The UI Entitlements for Team Sharing allow some users only to download (and not upload)

Team Sharing is not available or enabled by default in AdapTable.

Instead, it needs to be explicitly enabled and set up by developers at design time.

Note

Team Sharing uses a very similar loading and persisting pattern as Comments

Developer Guide

Setting up Team Sharing in Team Sharing Options

There are 4 steps you must follow in order for Team Sharing to be available to end users:

const adaptableOptions: AdaptableOptions = {
  entitlementOptions: {
    defaultAccessLevel: 'Hidden',
    moduleEntitlements: [
      {
        adaptableModule: 'TeamSharing',
        accessLevel: 'Full',
      },
    ],
  },
};

Make sure Team Sharing Entitlement is not Hidden

Check the TeamSharing Entitlement is one of these 2 Access Levels:

Full (preferable)
ReadOnly

Alternatively, check the defaultAccessLevel property is set to Full

Caution

Team Sharing will not appear if the defaultAccessLevel property is set to Hidden and the Team Sharing Entitlement is not explicitly overridden

const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    enableTeamSharing: true,
  },
};

Turn on Team Sharing in Team Sharing Options

Set enableTeamSharing to true in Team Sharing Options section of Adaptable Options.

const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    enableTeamSharing: true,
    async loadSharedEntities(adaptableId) {
      return new Promise(resolve => {
        const sharedEntities = JSON.parse(
          localStorage.getItem(`TEAM_SHARING:${adaptableId}`) || '[]'
        );
        resolve(sharedEntities);
      });
    },
  },
};

Provide loadSharedEntities property in Team Sharing Options

The async loadSharedEntities property in Team Sharing Options must be supplied.

This property is used for retrieving any Shared Items from the remote storage location.

const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    enableTeamSharing: true,
    async persistSharedEntities(adaptableId, sharedEntities) {
      return new Promise(resolve => {
        localStorage.setItem(
          `TEAM_SHARING:${adaptableId}`,
          JSON.stringify(sharedEntities)
        );
        resolve();
      });
    },
  },
};

Provide persistSharedEntities property in Team Sharing Options

The async persistSharedEntities property in Team Sharing Options must be supplied.

This property is used for persisting any Shared Items into the remote storage location.

Once Team Sharing is enabled, AdapTable will update the UI in 2 ways:

include the Team Sharing screen in the Settings Panel
add a Share button to every screen in the Settings Panel that displays AdapTable Objects

Hint

The Share button's fore and back colours can be styled using 2 CSS variables:

--ab-color-action-share
--ab-color-text-on-share

Remote State Management

TeamSharing Options provides 4 functions that allow developers to control TeamSharing state management and to provide their own load, persistence, hydration or serialization mechanisms:

loadSharedEntities - (mandatory) Loads Shared Entities from remote storage
applySharedEntities - (mandatory) Retrieves Shared Entities from remote storage
persistSharedEntities - (optional) Hooks into load flow of Shared Entities
saveSharedEntities - (optional) Hooks into persistence flow of Shared Entities

Note

These 4 functions mirror exactly those used to save Adaptable State remotely

loadSharedEntities

Promise<SharedEntity[]>

Loads Shared Entities from remote storage

Promise<SharedEntity[]>

This async function retrieves available Shared Entities that the user can download from the Remote Location.

It then merges them automatically with Adaptable State.

const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    enableTeamSharing: true,
      loadSharedEntities: async (context: SharedEntitiesContext) => {
       return new Promise(resolve => {
         const sharedEntities = JSON.parse(
           localStorage.getItem(`TEAM_SHARING:${context.adaptableId}`) || '[]'
         );
         resolve(sharedEntities);
       });
     },
  },
};

persistSharedEntities

Promise<void>

Retrieves Shared Entities from remote storage

This async function uploads any Shared Entities into remote storage.

This means that they can be downloaded by other members of the team (if entitlements allow)

const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    enableTeamSharing: true,
    persistSharedEntities: async (
        sharedEntities: SharedEntity[],
        context: SharedEntitiesContext) => {
           return new Promise(resolve => {
             localStorage.setItem(`TEAM_SHARING:${adaptableId}`, JSON.stringify(sharedEntities));
             resolve();
           });
     },
  },
};

applySharedEntities

SharedEntity[]

(Optional) Hooks into load flow of Shared Entities

If defined, it will be invoked with the result of the loadSharedEntities() method invocation, and the result will be passed to Adaptable State.

const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    enableTeamSharing: true,
      applySharedEntities: (sharedEntities: SharedEntity[]) => {
          return sharedEntities.map((sharedEntity) => {
              if (sharedEntity.EntityType === 'adaptableEntity' && sharedEntity.Module === 'Layout') {
                  return { ...sharedEntity, IsReadOnly: true };
              }
              return sharedEntity;
          });
      },
  },
};

saveSharedEntities

SharedEntity[]

(Optional) Hooks into persistence flow of Shared Entities

If defined, it will be invoked before persistSharedEntities(), and persistSharedEntities() will be invoked with the result of this method.

const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    enableTeamSharing: true,
      saveSharedEntities: (sharedEntities: SharedEntity[]) => {
          return sharedEntities.map((sharedEntity) => {
              return { ...sharedEntity, IsReadOnly: false };
          });
      },
  },
};

Configuring and customizing state management

Fork Fork

Users have edit rights only on their own shared entities and read-only rights on other users shared entities. This is done by hooking into the loading/persisting TeamSharing state mechanisms.

Expand to see how the State Management is configured

The loading & persisting mechanisms are configured as usual by providing implementations for loadSharedEntities() and persistSharedEntities() callbacks:

loadSharedEntities: async () => {
    const data = localStorage.getItem(TEAM_SHARING_STATE_KEY);
    if (!data) {
        return [];
    }

    try {
        return JSON.parse(data);
    } catch (e) {
        return [];
    }
}, 
persistSharedEntities: entries => {
    localStorage.setItem(TEAM_SHARING_STATE_KEY, JSON.stringify(entries));
    return Promise.resolve();
},

We hook into the load process and dynamically set the IsReadOnly property comparing the SharedEntity creating user with current user:

applySharedEntities: entities => {
    return entities.map(entity => {
        // shared entity is readonly for anyone except it's creator
        entity.IsReadOnly = userName !== entity.UserName;
        return entity;
    });
}

We hook into the persist process and undo the changes we did to the IsReadOnly property, otherwise we would "pollute" the remote TeamSharing state.

saveSharedEntities: entities => {
    return entities.map(entity => {
        // revert the changes done in `applySharedEntities()`, otherwise we would change the remote state as well
        return {...entity, IsReadOnly: false};
    });
}

Try It Out

Share with each user a FormatColumn
Notice that users can delete only their own shared FormatColumn

import {InitialState, AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

// use a common Team Sharing state key for both users
const TEAM_SHARING_STATE_KEY = 'ConfigStateTeamSharingDemo_TeamSharingState';
export const getAdaptableOptionsForUser = (
  userName: 'Alice' | 'Bob',
  updateCurrentUser: (userName: 'Alice' | 'Bob') => void
): AdaptableOptions<WebFramework> => {
  const commonInitialState: InitialState = {
    Dashboard: {
      Revision: Date.now(),
      Tabs: [
        {
          Name: 'Select Current User',
          Toolbars: ['CurrentUser'],
        },
      ],
      ModuleButtons: ['FormatColumn', 'TeamSharing', 'SettingsPanel'],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  };
  const userSpecificInitialState =
    userName === 'Alice'
      ? {
          FormatColumn: {
            FormatColumns: [
              {
                Name: 'formatColumn-name',
                Scope: {
                  ColumnIds: ['name'],
                },
                Style: {
                  BackColor: 'lightblue',
                  ForeColor: 'brown',
                },
              },
            ],
          },
          Theme: {
            CurrentTheme: 'light',
          },
        }
      : // Bob
        {
          FormatColumn: {
            FormatColumns: [
              {
                Name: 'formatColumn-language',
                Scope: {
                  ColumnIds: ['language'],
                },
                Style: {
                  BackColor: 'yellow',
                  ForeColor: 'black',
                },
              },
            ],
          },
          Theme: {
            CurrentTheme: 'dark',
          },
        };

  return {
    primaryKey: 'id',
    adaptableId: 'State Configuration Team Sharing Demo',
    adaptableStateKey: `StateConfigTeamSharingDemo_${userName}`,
    userName,
    initialState: {
      ...commonInitialState,
      ...userSpecificInitialState,
    },
    teamSharingOptions: {
      enableTeamSharing: true,
      loadSharedEntities: async () => {
        const data = localStorage.getItem(TEAM_SHARING_STATE_KEY);
        if (!data) {
          return [];
        }

        try {
          return JSON.parse(data);
        } catch (e) {
          return [];
        }
      },
      persistSharedEntities: entries => {
        localStorage.setItem(TEAM_SHARING_STATE_KEY, JSON.stringify(entries));
        return Promise.resolve();
      },
      applySharedEntities: entities => {
        return entities.map(entity => {
          // shared entity is readonly for anyone except it's creator
          entity.IsReadOnly = userName !== entity.UserName;
          return entity;
        });
      },
      saveSharedEntities: entities => {
        return entities.map(entity => {
          // revert the changes done in `applySharedEntities()`, otherwise we would change the remote state as well
          return {...entity, IsReadOnly: false};
        });
      },
    },
    dashboardOptions: {
      customToolbars: [
        {
          name: 'CurrentUser',
          title: 'Current User',
          toolbarButtons: [
            {
              label: 'Alice',
              buttonStyle: () => {
                return {
                  tone: userName === 'Alice' ? 'success' : 'neutral',
                  variant: userName === 'Alice' ? 'raised' : 'outlined',
                };
              },
              onClick: () => {
                updateCurrentUser('Alice');
              },
            },
            {
              label: 'Bob',
              buttonStyle: () => {
                return {
                  tone: userName === 'Bob' ? 'success' : 'neutral',
                  variant: userName === 'Bob' ? 'raised' : 'outlined',
                };
              },
              onClick: () => {
                updateCurrentUser('Bob');
              },
            },
          ],
        },
      ],
      customDashboardButtons: [
        {
          tooltip: 'Reset state',
          icon: {
            name: 'refresh',
          },
          buttonStyle: {
            tone: 'error',
          },
          onClick: (button, context) => {
            localStorage.removeItem(TEAM_SHARING_STATE_KEY);
            ['Alice', 'Bob'].forEach(user => {
              localStorage.removeItem(`StateConfigTeamSharingDemo_${user}`);
            });
            context.adaptableApi.stateApi.reloadInitialState();
          },
        },
      ],
    },
  };
};

UI Entitlements

The UI Entitlements for Team Sharing are as follows:

Hidden the Team Sharing UI is completely unavailable
ReadOnly - users can import existing Shared items, but are not allowed to create or delete them;

Note

Changes to Active entities are still pushed if the Entitlement is ReadOnly

Full - everything is available in the UI, and users have full Read, Write and Download access

Team Sharing Admin and User

Fork Fork

User Alice has entitlements set to Full and Bob has entitlements set to ReadOnly.

import {AdaptableOptions, InitialState} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

// use a common Team Sharing state key for both users
const TEAM_SHARING_STATE_KEY = 'EntitlementsTeamSharingDemo_TeamSharingState';
export const getAdaptableOptionsForUser = (
  userName: 'Alice' | 'Bob',
  updateCurrentUser: (userName: 'Alice' | 'Bob') => void
): AdaptableOptions<WebFramework> => {
  const commonInitialState: InitialState = {
    Dashboard: {
      Revision: Date.now(),
      Tabs: [
        {
          Name: 'Select Current User',
          Toolbars: ['CurrentUser'],
        },
      ],
      ModuleButtons: ['FormatColumn', 'TeamSharing', 'SettingsPanel'],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  };
  const userSpecificInitialState =
    userName === 'Alice'
      ? {
          FormatColumn: {
            FormatColumns: [
              {
                Name: 'formatColumn-name',
                Scope: {
                  ColumnIds: ['name'],
                },
                Style: {
                  BackColor: 'lightblue',
                  ForeColor: 'brown',
                },
              },
            ],
          },
          Theme: {
            CurrentTheme: 'light',
          },
        }
      : // Bob
        {
          FormatColumn: {
            FormatColumns: [
              {
                Name: 'formatColumn-language',
                Scope: {
                  ColumnIds: ['language'],
                },
                Style: {
                  BackColor: 'yellow',
                  ForeColor: 'black',
                },
              },
            ],
          },
          Theme: {
            CurrentTheme: 'dark',
          },
        };

  const isAlice = userName === 'Alice';

  return {
    primaryKey: 'id',
    adaptableId: 'Entitlements Team Sharing Demo',
    adaptableStateKey: `EntitlementsTeamSharingDemo_${userName}`,
    userName,
    initialState: {
      ...commonInitialState,
      ...userSpecificInitialState,
    },
    entitlementOptions: {
      moduleEntitlements: [
        {
          adaptableModule: 'TeamSharing',
          accessLevel: isAlice ? 'Full' : 'ReadOnly',
        },
      ],
    },
    teamSharingOptions: {
      enableTeamSharing: true,
      loadSharedEntities: async () => {
        const data = localStorage.getItem(TEAM_SHARING_STATE_KEY);
        if (!data) {
          return [];
        }

        try {
          return JSON.parse(data);
        } catch (e) {
          return [];
        }
      },
      persistSharedEntities: entries => {
        localStorage.setItem(TEAM_SHARING_STATE_KEY, JSON.stringify(entries));
        return Promise.resolve();
      },
    },
    dashboardOptions: {
      customToolbars: [
        {
          name: 'CurrentUser',
          title: 'Current User',
          toolbarButtons: [
            {
              label: 'Alice',
              buttonStyle: () => {
                return {
                  tone: userName === 'Alice' ? 'success' : 'neutral',
                  variant: userName === 'Alice' ? 'raised' : 'outlined',
                };
              },
              onClick: () => {
                updateCurrentUser('Alice');
              },
            },
            {
              label: 'Bob',
              buttonStyle: () => {
                return {
                  tone: userName === 'Bob' ? 'success' : 'neutral',
                  variant: userName === 'Bob' ? 'raised' : 'outlined',
                };
              },
              onClick: () => {
                updateCurrentUser('Bob');
              },
            },
          ],
        },
      ],
      customDashboardButtons: [
        {
          tooltip: 'Reset state',
          icon: {
            name: 'refresh',
          },
          buttonStyle: {
            tone: 'error',
          },
          onClick: (button, context) => {
            localStorage.removeItem(TEAM_SHARING_STATE_KEY);
            ['Alice', 'Bob'].forEach(user => {
              localStorage.removeItem(`EntitlementsTeamSharingDemo_${user}`);
            });
            context.adaptableApi.stateApi.reloadInitialState();
          },
        },
      ],
    },
  };
};

Entity Entitlements

ReadOnly rights at entity level can be specified by setting IsReadOnly to true for the SharedEntity

Caution

This can only be done programmatically - there is no option to set this in the UI

Override Warning

AdapTable warns users if they try to import an object in Team Sharing that already exists in Adaptable State.

Note

It does this by checking the Uuid (not the Name) of the imported Adaptable Object

If the user proceeds with the import after seeing the warning, the new object will overwrite the exsisting one.

This behaviour can be changed using the suppressOverrideConfigWarning property in Team Sharing Options.

suppressOverrideConfigWarning

Default: false

Boolean

Suppress messages warning that imported Object already exists

Set this property to true to suppress the warning when an Imported Object already exists.

This will have the effect of ensuring that the overwrite will happen automatically.

// Suppress warnings from AdapTable when importing an existing object
const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    suppressOverrideConfigWarning: true
  },
}

PreviousReferenced Team Sharing NextCustom Team Sharing

Framework: