@openfin/excel

Microsoft Excel Integration for OpenFin Container

OpenFin’s Microsoft Excel integration enables developers to automate Excel functionality from an application running in OpenFin Container.

Introduction

This 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. The API leverages the native Office primary interop assemblies (PIA), specifically functionality provided by the Microsoft.Office.Interop.Excel namespace. Using the API, developers can:

• Open or create a workbook; control focus; retrieve workbook property values; save and close workbooks.
• Get, add and remove worksheets from open workbooks; retrieve and modify worksheet cell names, values and formatting; create filters; run calculations and protect worksheets.
• Control Excel at the application level; run calculations or quit the application altogether.
• Register event listeners for various events at the application, workbook or worksheet level.

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

Add App Assets to manifest

When initialised, the Excel integration launches a native adapter process in the background that acts as an intermediary between the client-side API and the native Excel PIA. To ensure that the required assets are made available, add the following to your application's manifest:

"appAssets": [{
  "alias": "excel-adapter",
  "src": "https://cdn.openfin.co/release/integrations/excel/1.0.2/OpenFin.Excel.zip",
  "target": "OpenFin.Excel.exe",
  "version": "1.0.2"
}]

Note: The version number referenced in the "src" and "version" properties must match each other as well as the NPM package version being used.

Configure API security

In order to launch the native adapter process, the client-API uses the System.launchExternalProcess OpenFin API function which is a secured API. Therefore you must declare the use of this secured API in your application's manifest:

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

The location of the permissions object will depend on the type of application you are developing and it's use case (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, so as long as your application is running from localhost there is no need to configure desktop owner settings.

Working with the Excel integration API

To begin, call the getExcelApplication function which will launch the native adapter process and return an Excel application instance:

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

const excel = await getExcelApplication();

Using the Excel application instance you can now open or create workbooks, attach to events, and perform other Excel functions:

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 excelApi.quitApplication();

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