@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

The Excel integration can be used with version 9.61.35.22 or later of the OpenFin runtime.

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

Add this NPM package as a dependency for your app using the relevant package manager, e.g.:

npm install @openfin/excel

Configuration

On initialization, the client-side API downloads and launches a .Net adapter process in the background that functions as an intermediary between the client-side API and Microsoft’s Excel Interop API.

Some app configuration is required in order to facilitate this process.

Configure API security

When running on v12 or later of the OpenFin runtime, your app will require permission to use the System.downloadAsset and System.launchExternalProcess secured APIs. Be sure to declare the following permissions 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, when running on v20 or later of the OpenFin runtime, 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 behavior 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.2.0"
}]

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 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.2.0:

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

Working with the Excel integration

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 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}`);

// Get the worksheet named Sheet1
const sheet1 = (await workbook.getWorksheets()).find(async (worksheet) => (await worksheet.getName()) === 'Sheet1');

// Update the value of cell A1 and format as a number
const cellRange = 'A1';
sheet1!.setCellValues(cellRange, [[1000000]]);
const formatting: CellFormatting = { numberFormat: '#,##0' };
await sheet1!.setCellFormatting(cellRange, formatting);

// Retrieve the value of cell A1 and output to console
const cell_a1 = (await sheet1!.getCells(cellRange))[0];
console.log(`A1: ${cell_a1.value}`);

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