Migrate from the Excel service

The @openfin/excel NPM package supersedes the previous Excel service which is now deprecated.

The NPM package has a number of advantages over the service:

Lighter footprintThere is no "Add-in" component that requires installation in Excel.
Runtime version consistencyThe adapter process uses the same runtime version that the parent app uses.
Improved isolationMultiple apps that use different versions of the Excel Integration can be run at once.
Simple configurationBy default no additional configuration is required unless you choose to self-host the adapter package.
Standard upgrade pathUpgrading to newer versions is the same process as per any NPM dependency.
Typescript supportThe new client-side API is provided as an ES module including type definitions.

The new client-side API is not a one-to-one match with the API provided by the service.
There are implementation as well as functional differences, some of which will be addressed in future releases.

Migration steps

If you are using the Excel service and wish to migrate your app to use the NPM package, follow these steps:

  1. Review the API documentation and ensure that it meets the functional requirements of your app.

  2. Make the required changes to your app:

    1. Add the @openfin/excel NPM package as a dependency.

    2. Remove any script tags referencing the Excel service API JavaScript file, fin.desktop.Excel.js or ExcelAPI.js.

    3. Update your app's source code where it calls deprecated API statements and replace them as per the API documentation.



      The Excel RTD functionality has been replaced by data streams in the new Excel integration. Remember to factor in removing references to the OpenFinRTD function in all affected Excel workbooks, and replacing with the named cell ranges used by the data streams implemented in your app.

    4. If using a bundler (such as webpack), update your app’s bundling process to remove the Excel service API JavaScript file (if being included in the bundle) and ensure required files from the NPM package are included.

    5. Update your app’s manifest to remove references to the "excel" service:

          {"name": "excel"}
    6. If required, update your app’s manifest to include the necessary API permissions (see Configure API security above).

    7. If planning on self-hosting the adapter, update your app’s manifest to include the required appAssets entry (see Self-hosting the adapter above).

  3. Optional: Remove the deprecated Excel service add-in from any desktop that ran the Excel service.

    We recommend this step only if you know that no applications are targeting version of the OpenFinRuntime. If you’re confident that is the case, please proceed with the following optional steps:

    1. Locate where the add-in file resides and delete it. If you do not know its location, in Excel, click File > Options > Add-ins and find "OpenFin Excel API Add-In". Typically the location is %LocalAppData%\OpenFin\shared\assets\excel-api-addin.

    2. Close down Excel and then delete the entire `excel-api-addin`` folder.

    3. Start Excel. If the preceding steps were done correctly, an alert appears stating that the OpenFin.ExcelApi-AddIn.xll add-in could not be found; click on OK to continue.

    4. In Excel, click File > Options > Add-ins, and then select "Excel Add-ins" next to "Manage" and click Go.

    5. Uncheck the "Openfin.Excelapi-Addin" option, and when yoare prompted to delete it from the list, click Yes.

    6. Click OK to close the Add-ins window.

    7. Delete this folder: %LocalAppData%\OpenFin\cache\ (Substitute your OpenFin installation folder path if different than this one.)

    8. Delete all folders that start with Excel-Service-Manager in the following folder %LocalAppData%\OpenFin\apps\.