AI Automation Excel Plugin

Excel task pane add-in that uploads a W-2 (PDF or image), sends it to Azure AI Document Intelligence using the prebuilt model prebuilt-tax.us.w2, and writes extracted fields as one header row and one value row on the active worksheet (each new import is placed below existing content with a blank row in between).

Prerequisites

• Node.js (v18+; v20+ recommended for some transitive tooling)
• Microsoft Excel — desktop (Windows or Mac) and/or Excel on the web (browser; Microsoft 365)
• An Azure AI Document Intelligence (or compatible Azure AI services) resource with endpoint and key

Azure setup

1. In the Azure Portal, create a Document Intelligence / Azure AI services resource.
2. Open Keys and Endpoint and copy Endpoint and Key 1.
3. Paste them into .env (see below). The service must support API version 2024-11-30 (Document Intelligence v4).

Local configuration

cp .env
# Edit .env: set AZURE_DI_ENDPOINT and AZURE_DI_KEY

Never commit .env. Keys stay on the local HTTPS dev server only; the add-in bundle does not embed them.

Install and run

npm install
npm start

This builds the task pane (dist/) and starts https://localhost:3000 with:

• Static files for the add-in (taskpane.html, taskpane.js)
• POST /api/analyze — forwards base64Source to Azure, polls until analysis completes, returns analyzeResult JSON

Leave this process running while you use Excel.

Sideload the add-in in Excel

With the server running:

npm run sideload

Or manually: Insert → Add-ins → Upload My Add-in (wording varies by platform) and choose manifest.xml.

Excel on the web: Open Excel online, create or open a workbook, then Insert → Add-ins → Upload my Add-in and select manifest.xml. Keep npm start running on the same machine; the browser loads the task pane from https://localhost:3000. After sideloading, use the Home tab → Tax import → W-2 import (same as desktop).

The manifest points the task pane to https://localhost:3000/taskpane.html. Trust the localhost certificate when the browser or Office prompts you.

Chrome: NET::ERR_CERT_AUTHORITY_INVALID

The dev server uses HTTPS with a certificate signed by a local developer CA (office-addin-dev-certs). Chrome shows ERR_CERT_AUTHORITY_INVALID until that CA is trusted on your system (or imported into Chrome). This is expected for local development; it is not a bug in the app.

Fix (try in order):

1. Install the developer CA (recommended)
   From the project root:

   npm run certs

   On Linux, this usually needs elevated rights so the CA is installed system-wide. If it fails, run the same command with sudo, or install manually (step 2).

2. Trust the CA in Chrome (Linux manual example)
   The CA file is:

   ~/.office-addin-dev-certs/ca.crt

   In Chrome: Settings → Privacy and security → Security → Manage certificates → Authorities → Import → select ca.crt → enable Trust this certificate for identifying websites → restart Chrome.
   Then reload https://localhost:3000/taskpane.html.

3. Windows / macOS
   Run npm run certs from an elevated / admin terminal if prompted so the CA is added to the OS trust store; restart Chrome afterward.

4. If the CA file does not exist yet
   Start the server once (npm start); cert generation runs when certs are missing. Then run npm run certs again.

After the CA is trusted, the error should disappear for https://localhost:3000 and for the add-in task pane in Excel.

Development workflow

For faster iteration, run the dev server and rebuild the bundle on file changes:

npm run dev

In another terminal, keep using npm run sideload once per Excel session, or reload the add-in from My Add-ins.

How it works

1. You pick a file in the task pane; it is sent as base64 to /api/analyze.
2. The server calls Azure Document Intelligence prebuilt-tax.us.w2 (tax model docs).
3. The client flattens analyzeResult.documents[0].fields into label/value pairs and writes them with the Excel JavaScript API.

Production

Host the built dist/ assets and a secure backend that holds Azure credentials (for example Azure Functions + Key Vault) at stable HTTPS URLs, then update SourceLocation and icon URLs in manifest.xml accordingly.

References

• Analyze Document REST API (v4.0)
• US tax schema samples (GitHub)