Team Sharing allows users to share - at run-time - Adaptable Objects between colleagues.
It is designed for use cases where the same, newly-created Adaptable Object (e.g. a Layout, Conditional Style, Report etc.) will be required by multiple users.
Each shared object can be either a Snapshot (i.e. a one-off operation) or Active (all instances stay linked).
Enabling Team Sharing
Team Sharing is only available if the
enableTeamSharing property is true in Team Sharing Options.
How It Works
The sharing workflow is straightforward: an AdapTable user will upload an object to the Team Share, which colleagues can subsequently choose to download.
If the object is Active Shared, AdapTable will automatically synchronise the team share with local changes; this then allows colleagues to update their local copy with the latest version in the team share.
Uploading To Team Share
The steps to upload an AdapTable Object to Team Share are as follows:
If Team Sharing is enabled, every Adaptable Object will display a 'Share' button in each Module's popup
The 'Share' button's fore and back colours can be styled using CSS variables
Clicking that button will display a popup where a name for the Shared Object must be provided
Click 'OK' and the object will be uploaded into Team Share, ready to be downloaded by colleagues (as a Shared Entity)
Downloading from Team Share
Once the Shared Entity is uploaded into Team Share, it will be available to colleagues to download.
Any user (with Team Sharing entitlemens) can access the Team Share by opening the Team Sharing popup.
This screen displays details of all Adaptable Objects which have been shared, together with a button to download each Shared Entity.
AdapTable will perform referenced sharing automatically.
This is when a Shared Entity contains references to other objects.
Adaptable will find all these dependencies, and they will be uploaded with the main Shared Entity.
These transitive dependencies can be multiple levels. For example, if a shared Layout included a Calculated Column with a BooleanExpression which referenced a Named Query which itself referenced another Named Query, then all 4 objects would be uploaded to Team Share.
If the Sharing is Active and the uploaded Shared Entity has dependencies, these will all be Active as well
The most straightforwad way in which a SharedEntity can be uploaded is by 'Snapshot Sharing'.
In versions prior to AdapTable 9 this was the only way Team Sharing worked
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.
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 the SharedEntity is through 'Active Sharing'.
In this scenario, the Shared Enitty remains linked after it has been uploaded to Team Share by a user (and then subsequently downloaded by her colleagues).
AdapTable will ensure that any local changes to a Shared Entity are automatically synchronised to TeamSharing.
An Adaptable Object can have only 1 Active entity
When a SharedEntity is Active, AdapTable will watch for all changes and notify any users allowing them to update their local copy.
The Team Share is polled at an interval set by the
updateInterval property of Team Sharing Options
Each user can be informed of a synchronisation change to an Active SharedEntity in one of 3 ways:
This option can be configured in the
updateNotification property of Team Sharing Options
- Alert with Notification - a Notification will appear in the current window
- Alert without Notification - the Alert Toolbar and ToolPanel show the Alert but there is no notification
- System Status - a System Status message is posted
In addition, AdapTable fires the TeamSharingEntityChanged Event each time an Active Shared Entity is sychronised
How Active Sharing Works
Active Sharing works by using the
Revision property of the Shared Entity.
AdapTable uses a concurrency model which allows Objects to be shared and updated by multiple users.
But Team Sharing is not designed for extreme use cases where objects will be continually be simultaneously updated by large numbers of users, so use sensibly.
As soon as any user uploads a new Shared Entity as Active, it will be implicitly marked with Revision 1.
Any subsequent changes to this object (either by the creator or by any other user which downloaded it) will be automatically synchronised with the Team Share, and the Revision of the Shared Entity will be incremented
The concurrency model is optimistic: any local change is possible and the remote state update is triggered
If Team Share contains a higher Revision for a Shared Enitty than that which has been triggered, the update is rejected.
Team Sharing Entitlements
UI Entitlements in Team Sharing are finer grained than those provided in other Modules:
The Module-Level Entitlements in Team Sharing work as follows:
Hidden (the default): Team Sharing UI is hidden
ReadOnly: users can import existing Shared items, but are not allowed to create or delete them;
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
ReadOnly rights at entitty level can be specified by setting
IsReadOnly to true for the SharedEntity
This can only be done programmatically. There is currently no option to set this in the UI
Team Sharing Options
Team Sharing Options is used to set up Team Sharing:
|enableTeamSharing||Whether Team Sharing is enabled||false|
|getSharedEntities||Function which retrieves available Shared Entities that user can download and merge automatically with Adaptable State||null|
|setSharedEntities||Function which uploads Shared Entities so they can be downloaded by other members of the team||null|
|updateInterval||Frequency (in minutes) to check if Active Shared Entities have a newer revision||0 (never)|
|updateNotification||How user is informed when Active Shared Entities have newer revisions: can be 'Alert', 'AlertWithNotification' or 'SystemStatus'||null (none)|
Setting up Team Sharing requires the provision - at design-time - of 2 functions.
Each returns a Promise and each is supplied through Team Sharing Options:
This functions retrieves any available SharedEntities that the user is able to download (and which AdapTable will then merge automatically into Adaptable State)
This function is used to save (essentially upload) SharedEntities so they can be downloaded (and re-used) by other members of the team
Team Sharing Entity Changed Event
The Event Info contains a TeamSharingEntityChangedInfo object:
|sharedEntity||Object containing the Shared Entity that has changed|
This wraps a SharedEntity object that is defined as follows:
|ChangedAt||Last time when the object was changed|
|ChangedBy||Last User who changed the object|
|Description||Description of object being shared|
|Entity||Actual Adaptable Object being shared|
|EntityDependencyIds||Ids of direct entity dependencies|
|Module||Adaptable Module to which object belongs|
|Revision||Revision - incremental for 'Active', always 1 for 'Snapshot'|
|Timestamp||When the object was shared|
|Type||'Snapshot' (for 1-time sharing) or 'Active' (for continuous sharing between local state & Team Share)|
|UserName||User who shared the object|
Subscribing to the Event is done the same as with all Adaptable Events:
Team Sharing API
|checkForUpdates()||Checks if active Shared Entities have updates (higher revisions than the local counterpart objects)|
|fireTeamSharingEntityChangedEvent(sharedEntity)||Fires the Team S|
|getSharedEntities()||Retrieves all Shared Entities in Team Sharing State|
|getTeamSharingState()||Retrieves Team Sharing section of State|
|hasTeamSharingFullRights()||Whether current user has full Team Sharing rights (for creating & updating shared items)|
|isTeamSharingActivated()||Whether Team Sharing is Activated|
|showTeamSharingPopup()||Opens Team Sharing popup screen|
Can we turn off Team Sharing if we don't want to use it?
You don't need to turn off Team Sharing as its 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.
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).