Team Sharing

AdapTable Version:

Framework:

Summary

Team Sharing promotes collaboration by allowing colleagues to share Adaptable Objects at run-time
It is designed for use cases where the same grid-related Entity will be required by multiple users
Each object (e.g. a Layout, Format Column, Report etc.) can be shared in one of 2 ways:
- Snapshot - i.e. a one-off operation
- Active - all instances stay linked
It is also possible to share bespoke objects (not necessarily Adaptable specific ones), practically providing a shared mutable state between multiple instances

Team Sharing enables AdapTable users to share Adaptable Objects they have created.

These can be objects created either at run-time or design time.

Once an AdapTable Object is uploaded into Team Share, it is then tagged as a "Shared Entity" and will automatically be available to colleagues to download.

Note

This page explains how to share Adaptable Objects like Layouts, FormatColumns, Alerts, etc.
Advanced users are also able to share Custom Objects if required

The Team Sharing workflow is straightforward but incredibly powerful:

Step 1. AdapTable User uploads an Adaptable Object to the Team Share (for colleagues to download):

UI Step by Step Guide

How to Upload an Adaptable Object To Team Share

Step 2. User's Colleague downloads the Object - known as a Shared Entity:

UI Step by Step Guide

Downloading From Team Share

Step 3. If the Shared Entity is Active Shared, AdapTable will automatically synchronise the team share with local changes, allowing colleagues to update their local copy with the latest version in the team share

Step 4. If the Shared Entity is Snapshot Shared, then it is uploaded to the Team Share and then disconnected from the initial Adaptable Object

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.

Expand to see how Team Sharing is applied

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

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

// Bob
{
  FormatColumn: {
    FormatColumns: [
      {
        Name: 'FormatColumn-language-267',
        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 shares 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 {InitialState, AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

// use a common Team Sharing state key for both users
const TEAM_SHARING_STATE_KEY = 'BasicTeamSharingDemo_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',
            'github_stars',
            'license',
            'github_watchers',
            'language',
            'open_issues_count',
            'closed_issues_count',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'description',
            'open_pr_count',
            'closed_pr_count',
            'has_projects',
            'has_pages',
            '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: 'Basic Team Sharing Demo',
    adaptableStateKey: `BasicTeamSharingDemo_${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();
      },
    },
    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(`BasicTeamSharingDemo_${user}`);
            });
            context.adaptableApi.stateApi.reloadInitialState();
          },
        },
      ],
    },
  };
};

There are a few important concepts to know.

The most straightforwad way in which a SharedEntity can be uploaded is by Snapshot Sharing.

This is a one off operation in which the SharedEntity is uploaded to the Team Share and then disconnected from the initial Adaptable Object.

This means that any changes made by the original sharer - or any colleagues who download the Shared Entity - will not be fed back to the other.

Hint

However, the object will remain in the team share, meaning that any user who has locally amended the initial shared object can revert to the shared version at any time by downloading it again

The other way to upload a SharedEntity is through Active Sharing.

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).

AdapTable ensures that any local changes to a Shared Entity are automatically synchronised to TeamSharing.

Find Out More

See Active Team Sharing for full details on how Live sharing works in AdapTable

Sometimes a Shared Entity contains references to other objects.

Most commonly a Layout will reference Special Columns (ie. Calculated, FreeText or ActionColumn).

When this happens, AdapTable will find all the associated dependencies, and they will be uploaded into Team Share together with the main Shared Entity.

Find Out More

See Referenced Team Sharing for further information

Multiple Teams

Team Sharing with Multiple Teams

Fork Fork

This example illustrates how Team Sharing can be used with multiple teams
It is identical to the demo above (with 2 users) but in addition each user can share to 2 teams

Try It Out

Share Adaptable Objects between users and distribute them between the teams
Note that only those Shared Entities which are located to the current Team are displayed

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

// use a common Team Sharing state key for both users
export const getAdaptableOptionsForUserAndTeam = (
  userName: 'Alice' | 'Bob',
  updateCurrentUser: (userName: 'Alice' | 'Bob') => void,
  team: 'Red' | 'Blue',
  updateCurrentTeam: (userName: 'Red' | 'Blue') => void
): AdaptableOptions<WebFramework> => {
  const commonInitialState: InitialState = {
    Dashboard: {
      Revision: Date.now(),
      Tabs: [
        {
          Name: 'Select User & Team',
          Toolbars: ['CurrentUser', 'CurrentTeam'],
        },
      ],
      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: '#00008b',
                },
              },
            ],
          },
          Theme: {
            CurrentTheme: 'dark',
          },
        };

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

        try {
          return JSON.parse(data);
        } catch (e) {
          return [];
        }
      },
      persistSharedEntities: entries => {
        localStorage.setItem(
          `MultiTeamSharingDemo_TeamSharingState_${team}`,
          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');
              },
            },
          ],
        },
        {
          name: 'CurrentTeam',
          title: 'Current Team',
          toolbarButtons: [
            {
              label: 'Red',
              buttonStyle: () => {
                return {
                  tone: team === 'Red' ? 'error' : 'neutral',
                  variant: team === 'Red' ? 'raised' : 'outlined',
                };
              },
              onClick: () => {
                updateCurrentTeam('Red');
              },
            },
            {
              label: 'Blue',
              buttonStyle: () => {
                return {
                  tone: team === 'Blue' ? 'accent' : 'neutral',
                  variant: team === 'Blue' ? 'raised' : 'outlined',
                };
              },
              onClick: () => {
                updateCurrentTeam('Blue');
              },
            },
          ],
        },
      ],
      customDashboardButtons: [
        {
          tooltip: 'Reset state',
          icon: {
            name: 'refresh',
          },
          buttonStyle: {
            tone: 'error',
          },
          onClick: (button, context) => {
            ['Red', 'Blue'].forEach(teamName => {
              localStorage.removeItem(
                `MultiTeamSharingDemo_TeamSharingState_${teamName}`
              );
            });
            ['Alice', 'Bob'].forEach(user => {
              localStorage.removeItem(`MultiTeamSharingDemo_${user}`);
            });
            context.adaptableApi.stateApi.reloadInitialState();
          },
        },
      ],
    },
  };
};

While the primary use case for TeamSharing is to allow different AdapTable instances to share AdapTable Objects (Layouts, Format Columns, etc.), it is also possible to share bespoke object structures and values.

Find Out More

See Custom Team Sharing for more information

Downloading Existing Objects

AdapTable will warn users if they are trying to import an Object which already exists.

It does this by checking whether Uuid of the Adaptable Object is unique.

Hint

Set suppressOverrideConfigWarning to true in Team Sharing Options to avoid seeing this warning

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.

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

Find Out More

See Configuring Team Sharing for step by step instructions on setting up Team Sharing

FAQ

Can we turn off Team Sharing if we don't want to use it? You don't need to turn off Team Sharing as it's not available by default. Team Sharing is only available if the enableTeamSharing property is set to true in Team Sharing Options and the Entitlement for the Team Sharing Module is 'Full'.

Can we share Adaptable Objects between differently identified Adaptable instances? Strictly speaking no (but in practice it is possible).

Team Sharing is intended to be used only for instances that share the same adaptableId; e.g. all users of a CDS Pricer can share the same Report but it cannot also be used in a Bond Matrix Pricer.

However while we use adaptableId as the identifier we don't enforce this so you can - at your discretion - share objects between AdapTable instances with different Ids.

Can we use Team Sharing to share bespoke data (i.e. not AdapTable objects)? Yes, Custom Objects Sharing was introduced in AdapTable Version 15

NextActive Team Sharing

Framework:

Team Sharing

Summary

Note

Team Sharing Workflow

UI Step by Step Guide

How to Upload an Adaptable Object To Team Share

UI Step by Step Guide

Downloading From Team Share

Expand to see how Team Sharing is applied

Snapshot Sharing

Hint

Active Sharing

Find Out More

Referenced Sharing

Find Out More

Multiple Teams

Custom Objects Sharing

Find Out More

Downloading Existing Objects

Hint

Configuring Team Sharing

Find Out More

FAQ