@openfin/excel

Microsoft Excel Integration for OpenFin Container

OpenFin’s Microsoft Excel integration enables application providers to integrate their applications with Microsoft Excel running on the same machine, providing two-way communication between Excel and your OpenFin applications.

Use this API to do the following:

• Create, open and save workbooks and worksheets from your OpenFin app.
• Push and receive data between your OpenFin app and a worksheet.
• Select items in either your OpenFin app or a worksheet, based on events in the other.
• Programmatically format cells in worksheets.

Prerequisites

OpenFin

If you are not already familiar with building apps for OpenFin Container, follow this guide to help you get started.

Microsoft Excel 2013

Any machine where the integration will be used must have Microsoft Excel 2013 or later installed.

.NET Framework 4.7.2

Any machine where the integration will be used must have the .NET Framework 4.7.2 runtime installed.

Getting started

Installation

First, add the package as a dependency for your app.

npm install @openfin/excel

or

yarn add @openfin/excel

Configure your app to run the native adapter process

On initialization, the client-side API downloads and launches a native adapter process in the background that acts as an intermediary between the API and the native Excel PIA.

The adapter process exists for as long as your application is running and connected, after which the adapter process terminates automatically.

The adapter process is for the sole use of the app that launched it, so if multiple apps are running that use the Excel integration they will each run their own separate adapter process.

Configure API security

To enable the client-side API to download and run an external process, your app will require permission to use both the System.downloadAsset and System.launchExternalProcess OpenFin API functions. Since these are both secured APIs, the following permissions must be declared in your app’s manifest:

"permissions": {
  "System": {
    "downloadAsset": true,
    "launchExternalProcess": true
  }
},

(The location of the permissions object will depend on whether or not your app uses Platform API, see here for more information).

In addition, the desktop owner must also allow your application to use this secured API in desktop owner settings. However, this is not required during development if your application is running from localhost, in which case there is no need to configure desktop owner settings.

Self-hosting the adapter

If you do not want the client-side API to automatically download the adapter from OpenFin’s CDN, you can override the default behaviour by declaring the adapter as an appAsset in your app’s manifest:

"appAssets": [{
  "alias": "excel-adapter",
  "src": "https://yourdomain.com/OpenFin.Excel.zip",
  "target": "OpenFin.Excel.exe",
  "version": "1.0.3"
}]

The alias and target values must match those in the example above. The version value should correspond to the NPM package version being used by your app. The src value should be the URL where your app can download the adapter package from.

The adapter package for any given version can be downloaded from OpenFin’s CDN at the following location:

https://cdn.openfin.co/release/integrations/excel/{API_VERSION}/OpenFin.Excel.zip

where {API_VERSION} is the version to download. For example, to download version 1.0.3:

https://cdn.openfin.co/release/integrations/excel/1.0.3/OpenFin.Excel.zip

Working with the Excel integration API

The @openfin/excel NPM package contains an ES module that exports a client-side API, enabling developers to automate various functions of Microsoft Excel via their OpenFin apps.

To begin, call the getExcelApplication function which will launch the native adapter process and return an Excel application instance, you can then do things like open or create workbooks, attach to events, and perform other functions in Excel:

import { getExcelApplication } from '@openfin/excel';

// Get Excel application instance
const excel = await getExcelApplication();

// Create a new workbook and log the name to console
const workbook = await excel.createWorkbook();
const workbookName = await workbook.getName();
console.log(`Created workbook ${workbookName}`);

// Save and close the workbook
const savePath = 'C:\\temp\\MyWorkbook.xlsx';
await workbook.saveAs(savePath);
await workbook.close();

// Quit Excel
await excel.quit();

For more code examples and full API reference, please refer to the documentation which can be found here.