AdapTable Version:

Framework:

Module Entitlements

Summary

Every Module in AdapTable can be given one of 3 Access Levels:
- ReadOnly
- Hidden
- Full
Module Entitlements can be provided in 2 ways:
- as a 'hard-coded list'
- via a function
Additionally a different DefaultAccessLevel can be specified in preference to the default value of Full

Every Module in AdapTable has an Entitlement AccessLevel.

Note

Any Module not given an explicit Entitlement will use that provided by the defaultAccessLevel property

Caution

In addition any Object-level Entitlements will take priority over the Module Entitlement

This is set by the moduleEntitlements property of Entitlement Options and can provided in 2 ways:

with a 'hard-coded' list
via a function invoked by AdapTable as required

moduleEntitlements

Entitlement[]

Provide Entitlements for each Module

Entitlement[]

This property is used to set the Entitlement for any Module in AdapTable.

Note

This will override the default Entitlement provided by defaultAccessLevel

It is defined as follows:

moduleEntitlements?:
    | Entitlement[]
    | ((entitlementContext: EntitlementContext) => AccessLevel | undefined);

As can be seen it offers 2 ways to provide Entitlements:

Hard Coded Value that is set once for all use cases
Function invoked by AdapTable each time an Entitlement is required; it receives context and returns an AccessLevel

List-based Module Entitlements

The most straightforward way of providing Module Entitlements is via a list.

The list includes every Entitlement for which the defaultAccessLevel is not suitable.

Entitlements: By List

Fork Fork

In this example we have provided Entitlements using a List (see below) as follows:
- The Alerts Module has a Readonly Entitlement - Alerts can be triggered (change GitHub Stars to under 500) but not edited, deleted or created
- The Format Column Module has a Readonly Entitlement - 3 Format Columns are rendered but cannot be edited, deleted or created
- The Custom Sort Module has a Hidden Entitlement - it is invisible in all UI elements

See how the Permissions are set as a List

entitlementOptions: {
  moduleEntitlements: [
    {
      adaptableModule: 'FormatColumn',
      accessLevel: 'ReadOnly',
    },
    {
      adaptableModule: 'Alert',
      accessLevel: 'ReadOnly',
    },
    {
      adaptableModule: 'CustomSort',
      accessLevel: 'Hidden',
    },
  ],
},

Try It Out

Open the Settings Panel and note that Format Columns and Alert objects are disabled and Custom Sort is missing
Fork the example and change the Entitlement of Alert to Hidden

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

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'List-Based Entitlements',

  entitlementOptions: {
    moduleEntitlements: [
      {
        adaptableModule: 'FormatColumn',
        accessLevel: 'ReadOnly',
      },
      {
        adaptableModule: 'Alert',
        accessLevel: 'ReadOnly',
      },
      {
        adaptableModule: 'CustomSort',
        accessLevel: 'Hidden',
      },
    ],
  },

  initialState: {
    Dashboard: {
      ModuleButtons: ['Alert', 'FormatColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    Alert: {
      AlertDefinitions: [
        {
          Name: 'alert-github-stars',
          MessageType: 'Warning',
          Scope: {
            ColumnIds: ['github_stars'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'LessThan',
                Inputs: [1000],
              },
            ],
          },
          AlertProperties: {
            HighlightCell: true,
            DisplayNotification: true,
          },
        },
      ],
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-week_issue_change',
          Style: {
            ForeColor: 'Green',
          },
          Scope: {
            ColumnIds: ['week_issue_change'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'Positive',
              },
            ],
          },
        },
        {
          Name: 'formatColumn-week_issue_change',
          Style: {
            ForeColor: 'Red',
          },
          Scope: {
            ColumnIds: ['week_issue_change'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'Negative',
              },
            ],
          },
        },
        {
          Name: 'style-all',
          Style: {
            BackColor: '#00ffff',
            ForeColor: 'Brown',
          },
          Scope: {
            All: true,
          },
          Rule: {
            BooleanExpression: '[language] = "HTML"',
          },
        },
      ],
    },
    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,
        },
      ],
    },
  },
};

Function-based Module Entitlements

An alternative way of providing Module Entitlements is via a JavaScript function.

This function will be invoked by AdapTable each time an Entitlement needs to be evaluated.

This is a more powerful and flexible approach than a hard coded value as it can return different AccessLevel values depending on the User, or other information.

Hint

You can use this option to connect to an external permisssioning or entitlement service if required

Deep Dive

Providing Module Entitlements by Function

The relevant definition of the moduleEntitlements property is:

((entitlementContext: EntitlementContext) => AccessLevel | undefined);

As can be seen, the function receives an object of type EntitlementContext which contains information about what is being permissioned, and returns an AccessLevel.

The EntitlementContext property is defined as follows:

Property	Description
adaptableModule	Module being entitled
defaultAccessLevel	The default Access Level for the current instance
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

// Call a permission service on External Server to get Entitlements
const adaptableOptions: AdaptableOptions = {
  entitlementOptions: {
    moduleEntitlements: (entitlementContext: EntitlementContext) => {
      return getPermission(
        entitlementContext.adaptableModule,
        entitlementContext.userName
      );
    },
  },
};

Caution

The function must return an AccessLevel in all circumstances.
AdapTable will not revert to the Default Access Level if no Access Level is returned from the function

Entitlements: By Function

Fork Fork

This example uses a function to define permissions for Modules
Based on the user-access-level, they can have Full, ReadOnly or Hidden access

Expand to see the moduleEntitlements function

entitlementOptions: {
  defaultAccessLevel: 'Hidden',
  moduleEntitlements: (entitlementContext: EntitlementContext) => {
    // check if the user has admin access
    if (isUserAdmin(user)) {
      return 'Full';
    }

    const fullModules: AdaptableModule[] = ['FormatColumn', 'CustomSort'];
    if (fullModules.includes(entitlementContext.adaptableModule)) {
      return 'Full';
    }

    const readOnlyModules: AdaptableModule[] = [
      'CellSummary',
      'Alert',
      'Dashboard',
      'ToolPanel',
      'SettingsPanel',
    ];

    if (readOnlyModules.includes(entitlementContext.adaptableModule)) {
      return 'ReadOnly';
    }

    // the rest are hidden for normal users
    return 'Hidden';
  },
},

Try It Out

Fork the example and change the entitlement function to make Alert module visible.

import {
  AdaptableModule,
  AdaptableOptions,
  EntitlementContext,
} from '@adaptabletools/adaptable';

const user = {
  id: '1',
  accessLevel: 'normal-user',
};

const isUserAdmin = (user: {id: string; accessLevel: string}) =>
  user.accessLevel === 'admin';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Function-provided Entitlements',

  entitlementOptions: {
    defaultAccessLevel: 'Hidden',
    moduleEntitlements: (entitlementContext: EntitlementContext) => {
      // check if the user has admin access
      if (isUserAdmin(user)) {
        return 'Full';
      }

      const fullModules: AdaptableModule[] = ['FormatColumn', 'CustomSort'];
      if (fullModules.includes(entitlementContext.adaptableModule)) {
        return 'Full';
      }

      const readOnlyModules: AdaptableModule[] = [
        'CellSummary',
        'Alert',
        'Dashboard',
        'ToolPanel',
        'SettingsPanel',
      ];

      if (readOnlyModules.includes(entitlementContext.adaptableModule)) {
        return 'ReadOnly';
      }

      // the rest are hidden for normal users
      return 'Hidden';
    },
  },

  initialState: {
    Dashboard: {
      ModuleButtons: ['FormatColumn', 'SettingsPanel'],
    },
    Theme: {CurrentTheme: 'dark'},
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'formatColumn-all',
          Scope: {
            All: true,
          },
          Rule: {
            BooleanExpression: '[language] = "TypeScript"',
          },
          Style: {
            BackColor: '#f2f2f2',
            ForeColor: 'Brown',
          },
        },
        {
          Name: 'formatColumn-week_issue_change',
          Style: {
            ForeColor: 'Green',
          },
          Scope: {
            ColumnIds: ['week_issue_change'],
          },
          Rule: {
            Predicates: [
              {
                PredicateId: 'Positive',
              },
            ],
          },
        },
      ],
    },
    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,
        },
      ],
    },
  },
};

Additional Module Entitlement Rules

For some AdapTable Modules providing an Entitlement of Full or ReadOnly is insufficient to ensure availability.

Additional conditions are required - supplied typically in Adaptable Options:

for Team Sharing set enableTeamSharing property in Team Sharing Options to true
in ipushpull the ippConfig property must be provided in ipushpull Plugin Options
in OpenFin the OpenFin configuration needs to be supplied

Default Module ReadOnly Behaviour

The ReadOnly behaviour for an Entitlement differs by Module and use case.

As a general rule, if the Module performs an action but does not contain an object (e.g. Smart Edit, Bulk Update or Cell Summary) the behaviour is the same as for Hidden.

If the Module contains a collection of objects (e.g. Format Columns, Shortcuts, Custom Sort), these objects are actionable as needed (and fully viewable by the user) but cannot be edited, deleted or suspended; nor can new ones be added.

However items can be selected in Modules where Users are able to make a selection (e.g. Layout or Export).

Caution

Objects provided in Initial Adaptable State are fully available in ReadOnly mode, as is the Adaptable API

There are some special cases to be aware of, here is full ReadOnly Entitlement behaviour for each Module:

Module	Read Only Behaviour
Alerts	Alerts trigger as normal but users cannot manage or suspend Alert Definitions; Alerts may be still cleared however.
Bulk Update	Same as `Hidden` Access Level
Calculated Column	Calculated Columns can be added / removed from Layouts and will be applied but Users cannot manage or suspend them
Cell Summary	Same as `Hidden` Access Level
Charts	Same as `Full` Access Level (charts are managed by AG Grid)
Column Filters	The Filter Bar cannot be made hidden / visible but Column Filters can still be created
Comments	Existing Comments - either previously created or provided by other users are visible - but new Comments cannot be added
Custom Sort	Custom Sorts will be applied but Users cannot manage or suspend them
Dashboard	The Dashboard cannot be configured (but can be expanded / hidden / floated etc.). Individual Toolbars cannot be closed or re-ordered.
Data Change History	Data Change History will display and work (if active) but it cannot be activated, inactivated or suspended
Data Sets	Predefined Data Sets can be selected - and the DataSetSelected Event will fire - but Users cannot manage or suspend them
Export	Reports can be run but Users cannot manage or suspend them
FDC3	Same as `Hidden` Access Level
Format Column	Format Columns will be applied but Users cannot manage or suspend them
FreeText Column	FreeText Columns can be added / removed from Layouts and visible in the Grid (with cells fully editable) but Users cannot manage or suspend them
Grid Filter	Existing Named Queries can be run in the Grid Filter but new Named Queries cannot be saved
Grid Info	Same as `Hidden` Access Level
Layout	Predefined Layouts can be selected but Users cannot actively manage or suspend them; Column changes can be made at runtime but they are not persisted
Notes	Notes in Initial State are visible, but Notes cannot be added, edited or deleted
Plus Minus	Plus Minus Nudges will be applied but Users cannot manage or suspend them
Quick Search	Same as `Hidden` Access Level
Schedule	Schedules will be run as specified, but Users cannot manage or suspend them
Settings Panel	Same as `Full` Access Level
Shortcuts	Shortcuts will be applied but Users cannot manage or suspend them
Smart Edit	Same as `Hidden` Access Level
State Management	The 'Retrieve State' dropdowns operate but the 'Delete State' button is disabled
Status Bar	Status Bar Panels can be used but the Status Bar cannot be configured
Styled Column	Styled Columns will be rendered but Users cannot manage or suspend them
System Status	System Status Messages can be viewed, but the 'Delete' buttons are disabled
Team Sharing	Users may import existing Shared items, but are not able to create or delete them
Theme	The Theme cannot be changed
Tool Panel	The Adaptable Tool Panel cannot be configured. Individual ToolPanels can be opened and closed but not hidden or re-ordered.

Plugin-based Modules

Plugin	Read Only Behaviour
ipushpull	Same as `Hidden` Access Level
OpenFin	Same as `Hidden` Access Level
interop.io	There are no Entitlements

PreviousPermissions NextPermissioning Objects

Framework: