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:

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

  2. Import the plugin:

    import openfin from '@adaptabletools/adaptable-plugin-openfin';
  3. Import the OpenFin Api:

    import { OpenFinApi } from '@adaptabletools/adaptable/types';
  1. Create the OpenFinPluginOptions as appropriate:

    const openfinPluginOptions: OpenFinPluginOptions = {
    notificationTimeout: false,
    showApplicationIconInNotifications: true,
    }
  2. 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
    }
  3. 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:

const demoConfig: PredefinedConfig = {
Dashboard: {
Tabs: [
{
Name: 'Dashboard Toolbars',
Toolbars: ['Layout', 'OpenFin', 'Export'],
},
],
},
};

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:

"services": [
{ "name": "excel",
"manifestUrl": "http://openfin.github.io/excel-api-example/provider/app.json"
}
]

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:

PropertyDescriptionDefault
broadcastFDC3InstrumentUseful 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
notificationTimeoutTimeout (in ms) for OpenFin Notifications to expire; set false for notifications not to auto-dismiss5000
onNotificationActionFunction which is invoked when a button in OpenFin notification is clicked
onShowNotificationUpdates OpenFin Notification object before it's displayed (just add/remove properties); return false to stop Notification showing
onValidationFailureInExcelAction to perform when a data change in Live Excel report triggers Prevent Edit Alert failure
showAdaptableAlertsAsNotificationsConverts AdapTable Alerts configured to display in popup as OpenFin Notificationstrue
showAppIconInNotificationsIcon to show in Notification - uses the value supplied in UserInterfaceOptionstrue
throttleTimeHow long (in ms) AdapTable throttles when sending data update to OpenFin2000

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:

const openFinApi = adaptableApi.pluginsApi.getPluginApi('openfin');

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.

MethodDescription
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

More Information