Entitlements

Options for managing UI Entitlements in AdapTable.

important

Entitlements work at the UI Level only so that users only see Modules and edit objects which are relevant

Entitlements Options contains just 2 properties:

PropertyDescriptionDefault
defaultAccessLevelAccessLevel to use when an Entitlement is not explicitly set; may be provided as a hardcoded value or as a function to invoke'Full'
moduleEntitlementsReturns either collection of Entitlements, or a function to invoke when an Entitlement is required

Access Levels

Each Module has an AccessLevel which can be one of 3 potential values:

Hidden Access Level

All UI elements connected to the Module are hidden from the user.

The Module does not appear in any UI elements exposed by AdaptTable - Popup, Dashboard, Tool Panel, Column Menu, Context Menu etc.

caution

Any objects provided in Predefined Config will still be available and will be applied as needed.

Likewise, the Adaptable Api will continue to operate normally

Full Access Level

The Module is fully visible and editable and everything can be done by the user - creating, editing, suspending and deleting objects as required.

The Module can be accessed in all UI elements exposed by AdaptTable - Popup, Dashboard, Tool Panel, Column Menu, Context Menu etc.

note

Object-level Entitlements (see below) still take precedence - so an object which is 'ReadOnly' cannot be edited in a Module with a 'Full' Access Level

ReadOnly Access Level

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. Conditional Style, Shortcut, 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 Predefined Config are fully available in ReadOnly mode, as is the Adaptable Api

There are some special use cases to be aware of, so we thought it best to provide the full ReadOnly behaviour per Module as follows:

ModuleRead Only Behaviour
DashboardThe Dashboard cannot be configured (but can be expanded / hidden / floated etc.). Individual Toolbars cannot be closed or re-ordered.
ToolPanelThe Adaptable ToolPanel cannot be configured. Individual ToolPanels can be opened and closed but not hidden or re-ordered.
AlertAlerts trigger as normal but users cannot manage or suspend Alert Definitions; Alerts may be still cleared however.
Bulk UpdateSame as Hidden Access Level
Calculated ColumnCalculated Columns can be added / removed from Layouts and will be applied but Users cannot manage or suspend them
Cell SummarySame as Hidden Access Level
Change HistoryThe Table is displayed but the Edit button in each row is disabled
Conditional StyleConditional Styles will be applied but Users cannot manage or suspend them
Custom SortCustom Sorts will be applied but Users cannot manage or suspend them
Data SourcePredefined Data Sources can be selected - and the SearchChanged Event will fire, but Users cannot manage or suspend them
ExportReports can be run but Users cannot manage or suspend them
FilterThe Quick Filter Bar cannot be made hidden / visible
Format ColumnFormat Columns will be applied but Users cannot manage or suspend them
FreeText ColumnFreeText Columns can be added / removed from Layouts and visible in the Grid (with cells fully editable) but Users cannot manage or suspend them
Grid InfoSame as Hidden Access Level
LayoutPredefined Layouts can be selected but Users cannot actively manage or suspend them (though column changes made at runtime are persisted)
Plus MinusPlus Minus Nudges will be applied but Users cannot manage or suspend them
QueryExisting Queries can be run, and new Queries can be created (but they cannot be saved as Named Queries)
Quick SearchSame as Hidden Access Level
ScheduleSchedules will be run as specified, but Users cannot manage or suspend them
ShortcutShortcuts will be applied but Users cannot manage or suspend them
Smart EditSame as Hidden Access Level
State ManagementThe 'Retrieve State' dropdowns operate but the 'Delete State' button is disabled
System StatusSystem Status Messages can be viewed, but the 'Delete' buttons are disabled
ThemeThe Theme cannot be changed

Other ReadOnly Rules are:

AreaRead Only Behaviour
Team SharingUsers may import existing Shared items, but are not able to create or delete them
ipushpullSame as Hidden Access Level
OpenFinSame as Hidden Access Level
Glue42Same as Hidden Access Level

Default Access Level

By default every Module has the Entitlement of Full.

If this is not the required behaviour then it can be changed through the defaultAccessLevel property.

For instance setting this to 'Hidden' will automatically remove all Modules, and then only those explicity permissioned (in moduleEntitlements) will be available.

tip

If defaultAccessLevel is set to 'Hidden', make sure to enable the Dashboard for access to Toolbars

The property can either directly return an AccessLevel, or a function which returns an Access Level:

defaultAccessLevel?: AccessLevel |
((userName: string, adaptableId: string) => AccessLevel);

Module Entitlements

The moduleEntitlements property offers 2 ways to provide Entitlements:

moduleEntitlements?:
| Entitlement[]
| ((module: AdaptableModule, userName: string,
adaptableId: string, defaultAccessLevel: AccessLevel)
=> AccessLevel | undefined);

Entitlements List

This provides a collection of Entitlement objects, each of which is defined as follows:

PropertyDescription
accessLevelAccess Level for an Entitlement; options are: 'Full', ''ReadOnly', 'Hidden'
adaptableModuleName of Adaptable Module that has the Entitlement applied
export default {
// Set 2 ReadOnly Entitlements: Export and Layout.
// Users can access existing layouts & reports but not add / edit / delete their own
// Set 2 Hidden Entitlements: Percent Bar and Query.
// These Module wont be available in menus, Toolbars or Tool Panels
const adaptableOptions: AdaptableOptions = {
entitlementOptions: {
moduleEntitlements: [
{
adaptableModule: 'Export',
accessLevel: 'ReadOnly',
},
{
adaptableModule: 'Layout',
accessLevel: 'ReadOnly',
},
{
adaptableModule: 'PercentBar',
accessLevel: 'Hidden',
},
{
adaptableModule: 'Query',
accessLevel: 'Hidden',
},
]
},
};

Using Custom Function

An alternative to a list of Entitlements is to provide a custom function implementation.

note

This function will be invoked each time an Entitlement is checked returing the apppropriate Access Level

tip

You can use this function to query permissions stored remotely and which might update in real time

The function must return an AccessLevel in all circumstances.

caution

AdapTable will not revert to the Default Access Level if no Access Level is returned from the function

// Call a permission service on External Server to get Entitlements
const adaptableOptions: AdaptableOptions = {
entitlementOptions: {
moduleEntitlements: (adaptableModule: Module, userName: string,
adaptableId: string, defaultAccessLevel: AccessLevel) => {
return callPermissionService(adaptableModule, userName, adaptableId);
},
};

Additional Rules

Some AdapTable Modules require additional conditions for it to be available in addition to setting the Entitlement.

These are usually supplied in Predefined Config or Adaptable Options. These include:

  • Team Sharing: the enableTeamSharing property must be set to true in TeamSharingOptions

  • glue42: the glue42 Predefined Config must contain the glue42 object

  • ipushpull: the ipushpull Predefined Config must contain the ipushpull object

Entitlements Scope

As stated above, Entitlements work at the UI Level only.

This means that AdapTable will ensure that end users cannot see or access - throughout the AdapTable UI - elements like menus, toolbars, popups etc. in Modules to which they are not entitled.

However the Adaptable Api does not take notice of Entitlements, so anything that is managed programatically through code will ignore the User's entitlements.

tip

To ensure that the Adaptable Api is not called for functions to which the user has no access, use the getEntitlementAccessLevelForModule in Grid Api

if (gridApi.getEntitlementAccessLevelForModule('Layout')=='Full'){
layoutApi.doSomething....
}

Overriding Entitlements

Sometimes the Module level restriction of Entitlements is insufficient; e.g. a use case requires a Module to have a 'Full' entitlement (i.e. it's editable) but one particular object must be ReadOnly (i.e. cannot be deleted).

The IsReadOnly property of AdaptableObject is designed for precisely this reason, and it will overrride the 'Full' Entitlement in the Adaptable Module.

warning

There is no property for the opposite use case - where the Module's Entitlement is 'ReadOnly' but one AdaptTable object should be 'Full'

See Adaptable Objects for more.

More Information