OpenFin Plugin
note
Watch our webinar to see OpenFin and AdapTable integration in action
The OpenFin Plugin provides extra functionality for users when AdapTable is running in the OpenFin container.
Setup
To set up the plugin and access the OpenFin Api object, follow these steps:
Reference these 3 Services in your OpenFin json file:
"services": [{"name": "excel","manifestUrl": "https://cdn.openfin.co/release/exceljs/4.0.1/provider/app.json"},{"name": "notifications"},{"name": "fdc3"}],note
These are the 3 OpenFin Services that AdapTable leverages to provide additional functionality
Import the plugin:
import openfin from '@adaptabletools/adaptable-plugin-openfin';Import the OpenFin Api:
import { OpenFinApi } from '@adaptabletools/adaptable/types';
Create the OpenFinPluginOptions as appropriate:
const openfinPluginOptions: OpenFinPluginOptions = {notificationTimeout: false,showApplicationIconInNotifications: true,}Specify the Plugin in Adaptable Options passing in the Options set up in previous step:
const adaptableOptions: AdaptableOptions = {adaptableId: 'openfindemo',plugins: [openfin(openfinPluginOptions),]// ... other options}Access the Open Fin Api via the main Adaptable Api object and use as needed:
const openfinApi: OpenFinApi = adaptableApi.pluginsApi.getPluginApi('openfin');
OpenFin Toolbar
The OpenFin Plugin makes a dedicated Dashboard Toolbar called 'OpenFin' available.
important
This makes it possible to run Live Reports in Excel
The Toolbar can be referenced in Dashboard Predefined Config as follows:
Live Reports
One feature available when AdapTable is running in the OpenFin Plugin is Live Export via Excel.
This enables grid data to be sent from AdapTable to Excel with 2 way updates:
note
Any Reports created in the Export Module will appear in the Toolbar
- Excel will automatically update in line with cell edits and ticking data changes in AdapTable
- Any date edits made directly in Excel will be automatically reflected in AdapTable
tip
Live Reports can, like all Reports, be set to run on a Schedule.
To make this functionality available, specify the following in the app.json file:
Validating Excel Changes
The Alert Module in AdapTable enables custom Rules to be provided to perform validation after each Data Change in the Grid.
When running Live Reports these validation rules can be extended to edits made in Excel, by setting the onValidationFailureInExcel property in OpenFinPluginOptions.
This property can take one of 3 values:
override: automatically updates Excel with the previous value (i.e. before the edit was made)
show-notification: displays an OpenFin Notification explaining that the edit in Excel broke validation
show-undo-notification: displays an OpenFin Notification containing a button; when clicked AdapTable will override the edit in Excel with the previous cell value
OpenFin Notifications
AdapTable will automatically convert Alerts (set to show as Popup) into OpenFin Notifications.
note
When this happens all Alert Buttons become OpenFin Notification Action Buttons.
AdapTable will display the Alert as an OpenFin Notification (using the same message type).
tip
Turn this off by setting showAdaptableAlertsAsNotifications to false in OpenFin PluginOptions
Managing Notifications
Two properties in OpenFinPluginOptions help to manage how OpenFin notifications will look and work:
notificationTimeout - when OpenFin notifications will expire after being displayed
showAppIconInNotifications - displays App Icon (supplied in User Interface Options) in the Notification
Most of the time AdapTable Alerts will appear seamlessly as OpenFin Notifications with no extra work required.
However 2 properties (both JavaScript functions) are available for when greater control over the look and feel or functionality of a Notification is required:
onNotificationAction - function invoked when a button in an OpenFin notification is clicked
onShowNotification - function which custom updates an OpenFin notification before it is displayed
UI Entitlements
OpenFin only works if it's Entitlement is set to Full and the plugin was injected into Adaptable Options.
note
The ReadOnly Entitlement behaviour is the same as if the Access Level was Hidden.
OpenFin Plugin Options
OpenFin PluginOptions are optional configuration settings used when running the OpenFin Plugin.
It contains these properties:
| Property | Description | Default |
|---|---|---|
| broadcastFDC3Instrument | Useful when you also use the finance plugin configured with instrumentColumns - values in cells in an instrument column can be broadcasted to fdc3, and this function will be called for broadcasting. It's your job to broadcast to the desired fdc3 channel | |
| notificationTimeout | Timeout (in ms) for OpenFin Notifications to expire; set false for notifications not to auto-dismiss | 5000 |
| onNotificationAction | Function which is invoked when a button in OpenFin notification is clicked | |
| onShowNotification | Updates OpenFin Notification object before it's displayed (just add/remove properties); return false to stop Notification showing | |
| onValidationFailureInExcel | Action to perform when a data change in Live Excel report triggers Prevent Edit Alert failure | |
| showAdaptableAlertsAsNotifications | Converts AdapTable Alerts configured to display in popup as OpenFin Notifications | true |
| showAppIconInNotifications | Icon to show in Notification - uses the value supplied in UserInterfaceOptions | true |
| throttleTime | How long (in ms) AdapTable throttles when sending data update to OpenFin | 2000 |
OpenFin API
Provides run-time access to the OpenFin Plugin.
Because OpenFin is available via a Plugin, the way to access the Api is as follows:
The available methods in the OpenFin Api are as follows:
caution
Some of these methods are intended for internal use only - and have been marked as such.
| Method | Description |
|---|---|
| clearOpenFinInternalState() | Clears any objects in internal OpenFin state created by AdapTable |
| getCurrentLiveOpenFinReport() | Retrieves the OpenFin currently sending live data to Excel |
| getNotificationsOptions() | Gets the Notification section from Adaptable Options |
| getOpenFinSchedules() | Retrieves all Schedules that send data to Excel via OpenFin |
| getOpenFinState() | Retrieves the OpenFin section of System State |
| getOpenFinThrottleTime() | Retrieves the Throttle time for live updates |
| getPluginOptions() | Retrieves the OpenFinPlugOptions provided in OpenFin Plugin |
| isOpenFinAvailable() | Whether OpenFin is available |
| isOpenFinRunning() | Whether OpenFin is currently running |
| showNotification(notification) | Shows a notification in OpenFin |
| showNotificationForAlert(alert) | Displays Alert as an OpenFin Notification |
| startLiveData(OpenFinReport) | Runs Report in Excel as Live Report (so updates as AdapTable ticks) |
| stopLiveData() | Stops live data; data will no longer be sent from AdapTable to Excel |