Active Team Sharing

AdapTable Version:

Framework:

Team Sharing

Summary

Active Team Sharing ensures that any Shared Entities are 'live'
This means that changes to the object by any sharing user are available to all other sharing users
Sharing users can be notified in a variety of ways about changes to the Shared Entity

By default Team Sharing uses Snapshot Sharing, where each Shared Entity is a separate and unique object.

However AdapTable also allows users to upload a SharedEntity through Active Sharing.

Caution

Active Team Sharing is designed for use cases where items are updated relatively occasionally, so use sensibly
Don't use it in when objects will continually be simultaneously updated by very large numbers of users

In this scenario, the Shared Entity remains linked after it has been uploaded to Team Share by a user (and then subsequently downloaded by her colleagues).

It is then the responsibility of AdapTable to ensure that any local changes to a Shared Entity are automatically synchronised to TeamSharing.

Note

An Adaptable Object can have only 1 Active entity

Deep Dive

How Active Sharing Works

Notifying Active Entity Changes

When a SharedEntity is Active, AdapTable can be configured to watch for all changes and notify any users allowing them to update their local copy.

Update Interval

Team Sharing can be configured so AdapTable regularly checks for a change in an Active Shared Entity.

This is done via the updateInterval property in Team Sharing Options.

updateInterval

Default: 0 (never)

Number

Frequency (in minutes) to check if Active Shared Entities have a newer revision

By default AdapTable will not poll an Active Shared Entity location to see if there are any changes pending.

Set this property (set in minutes) to change this behaviour:

// Poll every 5 minutes to see if an Active Shard Entity has changed
const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    updateInterval: 5,
  },
};

Update Notification

AdapTable always fires the Team Sharing Entity Changed Event whenever an Active Shared Entity is sychronised.

In addition, the updateNotification property in Team Sharing Options can be configured so that each run-time user can be informed of a change to an Active SharedEntity in one of 3 ways:

Alert with Toast Notification - a Toast Notification will appear in the current window and an Alert is fired
Alert without Notification - the Alerts Toolbar and ToolPanel show the Alert but there is no notification
System Status - a System Status message is posted

updateNotification

Default: null

'Alert'|'AlertWithNotification'|'SystemStatus'

How AdapTable informs users when Active Shared Entities have newer revisions

By default AdapTable will not tell a user when an Active Shared Entity has a newer revision.

This property allows you to change that by specifying one of 3 options:

Alert: Fire an Alert
AlertWithNotification: Fire an Alert and show a Toast Notification
SystemStatus: Publish a System Status Message

// Fire an Alert with a Display Notification when there is a newer version of an Active Shared Entity
const adaptableOptions: AdaptableOptions = {
  teamSharingOptions: {
    updateNotification: 'AlertWithNotification',
  },
};

Active Team Sharing

Fork Fork

This demo shows how Team Sharing works in AdapTable
There are 2 users each with their own Initial State:
- Alice - has a Format Column for Name Column
- Bob - has a Format Column for Language Column and uses the Dark Theme
Switching between users - via the custom toolbar - loads a new AdapTable instance with that User's Initial State
Team Sharing is enabled in this demo, allowing Alice and Bob to share entities between them
Note: this demo uses local storage to simulate an api call - but in the real world the shared entity would be stored remotely.
We have set 2 more Team Sharing Options properties for the purposes of this demo:
- suppressOverrideConfigWarning was set to true so that no Override Config warning appears
- updateInterval has been set to a very unrealistic 10 seconds so you can immediately see the Alert appear

Expand to see how Team Sharing is applied

We create 2 Initial Adaptable States - one for each user:

// Alice
{
  FormatColumn: {
    FormatColumns: [
      {
        Name: 'FormatColumn-name-201',
        Scope: {
          ColumnIds: ['name'],
        },
        Style: {
          BackColor: 'lightblue',
          ForeColor: 'brown',
        },
      },
    ],
  },
  Theme: {
    CurrentTheme: 'light',
  },
}

// Bob
{
  FormatColumn: {
    FormatColumns: [
      {
        Name: 'FormatColumn-language-202',
        Scope: {
          ColumnIds: ['language'],
        },
        Style: {
          BackColor: 'yellow',
          ForeColor: 'black',
        },
      },
    ],
  },
  Theme: {
    CurrentTheme: 'dark',
  },
}

In TeamSharingOptions - which is passed into AdaptableOptions - we do 3 things:

set enableTeamSharing to true
provide an implementation for loadSharedEntities
provide an implementation for persistSharedEntities

const teamSharingOptions: TeamSharingOptions = {
  enableTeamSharing: true,
  loadSharedEntities: async adaptableId => {
    const data = localStorage.getItem(TEAM_SHARING_STATE_KEY);
    if (!data) {
      return [];
    }

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

Try It Out

As Alice share the Format Column for the Name Column
As Bob download that Format Column from the Team Share
Note that the new Format Column appears in the Grid for Bob

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 = 'ActiveTeamSharingDemo_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', 'Alert', 'SystemStatus'],
        },
      ],
      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: 'Active Team Sharing Demo' + userName,
    adaptableStateKey: `ActiveTeamSharingDemo_${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();
      },
      updateNotification: 'AlertWithNotification',
      suppressOverrideConfigWarning: true,
      updateInterval: 0.1, // unrealistic in real world
    },
    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(`ActiveTeamSharingDemo_${user}`);
            });
            context.adaptableApi.stateApi.reloadInitialState();
          },
        },
      ],
    },
  };
};

Active Team Sharing

(Recorded with AdapTable v16.0)

FAQ

What happens to my Active Object if a colleague with the same revision number saves his first? The Team Sharing module works on a first come, first served basis. If, for example, you and your colleage both load Revision 3 of a Shared Entity and both make edits but he is quicker to save, then his edit to Revision 4 is persisted, and yours will be rejected. You can still do everything locally but, practically speaking, you are now working on a local fork of the Shared Entity. The only way to synchronise again with your colleagues is to download the latest version of the Shared Entity and repeat your actions (and hope that this time nobody interferes with your update).

PreviousTeam Sharing NextReferenced Team Sharing

Framework: