n8n-nodes-sharepointexcel 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# N8N SharePoint Excel Node
+
+An N8N community node that allows you to read Excel tables from SharePoint and perform table lookups.
+
+## Features
+
+- **Get Table**: Retrieve all data from a named Excel table in SharePoint
+- **Lookup**: Search for values in a table column and return matching rows
+- **Get Table Names**: List all table names in an Excel file
+- **Multiple Match Types**: Exact match, contains, starts with, ends with
+- **Flexible Output**: Return all matches or just the first one
+
+## Installation
+
+### Via NPM (Recommended)
+
+N8N will automatically detect and install this node when you use it in a workflow, or you can install it manually:
+
+```bash
+npm install n8n-nodes-sharepointexcel
+```
+
+### Manual Installation
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Build the node:
+```bash
+npm run build
+```
+
+3. Copy the `dist` folder to your N8N custom nodes directory:
+   - For Docker: `/home/node/.n8n/custom/`
+   - For npm: `~/.n8n/custom/`
+
+## Setup
+
+### Azure AD App Registration
+
+1. Go to [Azure Portal](https://portal.azure.com) → Azure Active Directory → App registrations
+2. Create a new registration
+3. Note your **Application (client) ID** and **Directory (tenant) ID**
+4. Go to "Certificates & secrets" → Create a new client secret
+5. Go to "API permissions" → Add permissions:
+   - Microsoft Graph → Delegated permissions:
+     - `Files.Read.All`
+     - `Sites.Read.All`
+   - Click "Grant admin consent"
+
+### N8N Credentials Setup
+
+1. In N8N, go to Credentials → Add Credential
+2. Select "SharePoint OAuth2 API"
+3. Enter your:
+   - **Client ID**: Your Azure AD Application ID
+   - **Client Secret**: Your Azure AD Client Secret
+   - **Tenant ID**: Your Azure AD Tenant ID
+4. Complete the OAuth2 flow to authorize access
+
+## Usage
+
+### Get Table Names
+
+1. Add the "SharePoint Excel" node to your workflow
+2. Select operation: "Get Table Names"
+3. Enter:
+   - **SharePoint Site URL**: `https://yourtenant.sharepoint.com/sites/yoursite`
+   - **File Path**: `/Shared Documents/MyFile.xlsx`
+4. Execute to get a list of all table names
+
+### Get Table Data
+
+1. Select operation: "Get Table"
+2. Enter:
+   - **SharePoint Site URL**: Your SharePoint site URL
+   - **File Path**: Path to your Excel file
+   - **Table Name**: Name of the Excel table (e.g., "Table1")
+3. Execute to get all rows from the table
+
+### Table Lookup
+
+1. Select operation: "Lookup"
+2. Enter:
+   - **SharePoint Site URL**: Your SharePoint site URL
+   - **File Path**: Path to your Excel file
+   - **Table Name**: Name of the Excel table
+   - **Lookup Column**: Column name to search in
+   - **Lookup Value**: Value to search for
+   - **Match Type**: How to match (exact, contains, startsWith, endsWith)
+   - **Return All Matches**: Whether to return all matches or just the first
+3. Execute to get matching rows
+
+## Example Workflow
+
+```
+Trigger → SharePoint Excel (Get Table Names) → 
+SharePoint Excel (Lookup) → Process Results
+```
+
+## File Path Format
+
+The file path should be relative to the SharePoint site root:
+- `/Shared Documents/MyFile.xlsx`
+- `/Documents/Reports/Data.xlsx`
+- `/SiteAssets/Data/Table.xlsx`
+
+## Excel Table Requirements
+
+- The Excel file must contain named tables (created via Insert → Table in Excel)
+- Table names are case-sensitive
+- Column names are taken from the table header row
+
+## Troubleshooting
+
+### "Table not found" error
+- Ensure the table name matches exactly (case-sensitive)
+- Verify the table exists in the Excel file
+- Use "Get Table Names" operation to list available tables
+
+### Authentication errors
+- Verify your Azure AD app has the correct permissions
+- Ensure admin consent has been granted
+- Check that the OAuth2 flow completed successfully
+
+### File not found
+- Verify the file path is correct
+- Ensure the path starts with `/`
+- Check that the file exists in SharePoint
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT

package/dist/credentials/SharePointOAuth2Api.credentials.d.ts

@@ -0,0 +1,8 @@
+import { ICredentialType, INodeProperties } from "n8n-workflow";
+export declare class SharePointOAuth2Api implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    extends: string[];
+    properties: INodeProperties[];
+}

package/dist/credentials/SharePointOAuth2Api.credentials.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharePointOAuth2Api = void 0;
+class SharePointOAuth2Api {
+    constructor() {
+        this.name = "sharePointOAuth2Api";
+        this.displayName = "SharePoint OAuth2 API";
+        this.documentationUrl = "https://docs.microsoft.com/en-us/graph/auth/";
+        this.extends = ["oAuth2Api"];
+        this.properties = [
+            {
+                displayName: "Grant Type",
+                name: "grantType",
+                type: "hidden",
+                default: "authorizationCode",
+            },
+            {
+                displayName: "Authorization URL",
+                name: "authUrl",
+                type: "hidden",
+                default: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+            },
+            {
+                displayName: "Access Token URL",
+                name: "accessTokenUrl",
+                type: "hidden",
+                default: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+            },
+            {
+                displayName: "Scope",
+                name: "scope",
+                type: "hidden",
+                default: "https://graph.microsoft.com/.default",
+            },
+            {
+                displayName: "Auth URI Query Parameters",
+                name: "authQueryParameters",
+                type: "hidden",
+                default: "",
+            },
+            {
+                displayName: "Authentication",
+                name: "authentication",
+                type: "hidden",
+                default: "body",
+            },
+        ];
+    }
+}
+exports.SharePointOAuth2Api = SharePointOAuth2Api;

package/dist/nodes/SharePointExcel/SharePointExcel.node.d.ts

@@ -0,0 +1,5 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from "n8n-workflow";
+export declare class SharePointExcel implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/SharePointExcel/SharePointExcel.node.js

@@ -0,0 +1,426 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SharePointExcel = void 0;
+const microsoft_graph_client_1 = require("@microsoft/microsoft-graph-client");
+const ExcelJS = __importStar(require("exceljs"));
+class SharePointExcel {
+    constructor() {
+        this.description = {
+            displayName: "SharePoint Excel",
+            name: "sharePointExcel",
+            icon: "file:sharepoint.svg",
+            group: ["transform"],
+            version: 1,
+            subtitle: '={{$parameter["operation"]}}',
+            description: "Read Excel tables from SharePoint and perform table lookups",
+            defaults: {
+                name: "SharePoint Excel",
+            },
+            inputs: ["main"],
+            outputs: ["main"],
+            credentials: [
+                {
+                    name: "sharePointOAuth2Api",
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: "Operation",
+                    name: "operation",
+                    type: "options",
+                    noDataExpression: true,
+                    options: [
+                        {
+                            name: "Get Table",
+                            value: "getTable",
+                            description: "Get all data from an Excel table",
+                            action: "Get all data from a table",
+                        },
+                        {
+                            name: "Lookup",
+                            value: "lookup",
+                            description: "Lookup a value in a table and return matching row(s)",
+                            action: "Lookup a value in a table",
+                        },
+                        {
+                            name: "Get Table Names",
+                            value: "getTableNames",
+                            description: "Get list of table names in the Excel file",
+                            action: "Get list of table names",
+                        },
+                    ],
+                    default: "getTable",
+                },
+                {
+                    displayName: "SharePoint Site URL",
+                    name: "siteUrl",
+                    type: "string",
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ["getTable", "lookup", "getTableNames"],
+                        },
+                    },
+                    default: "",
+                    placeholder: "https://yourtenant.sharepoint.com/sites/yoursite",
+                    description: "The SharePoint site URL where the Excel file is located",
+                },
+                {
+                    displayName: "File Path",
+                    name: "filePath",
+                    type: "string",
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ["getTable", "lookup", "getTableNames"],
+                        },
+                    },
+                    default: "",
+                    placeholder: "/Shared Documents/MyFile.xlsx",
+                    description: "The path to the Excel file in SharePoint",
+                },
+                {
+                    displayName: "Table Name",
+                    name: "tableName",
+                    type: "string",
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ["getTable", "lookup"],
+                        },
+                    },
+                    default: "",
+                    description: "The name of the Excel table to work with",
+                },
+                {
+                    displayName: "Lookup Column",
+                    name: "lookupColumn",
+                    type: "string",
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ["lookup"],
+                        },
+                    },
+                    default: "",
+                    description: "The column name to search in",
+                },
+                {
+                    displayName: "Lookup Value",
+                    name: "lookupValue",
+                    type: "string",
+                    required: true,
+                    displayOptions: {
+                        show: {
+                            operation: ["lookup"],
+                        },
+                    },
+                    default: "",
+                    description: "The value to search for",
+                },
+                {
+                    displayName: "Match Type",
+                    name: "matchType",
+                    type: "options",
+                    displayOptions: {
+                        show: {
+                            operation: ["lookup"],
+                        },
+                    },
+                    options: [
+                        {
+                            name: "Exact Match",
+                            value: "exact",
+                        },
+                        {
+                            name: "Contains",
+                            value: "contains",
+                        },
+                        {
+                            name: "Starts With",
+                            value: "startsWith",
+                        },
+                        {
+                            name: "Ends With",
+                            value: "endsWith",
+                        },
+                    ],
+                    default: "exact",
+                    description: "How to match the lookup value",
+                },
+                {
+                    displayName: "Return All Matches",
+                    name: "returnAll",
+                    type: "boolean",
+                    displayOptions: {
+                        show: {
+                            operation: ["lookup"],
+                        },
+                    },
+                    default: false,
+                    description: "Whether to return all matching rows or just the first one",
+                },
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const returnData = [];
+        const nodeInstance = this;
+        const operation = this.getNodeParameter("operation", 0);
+        // Get credentials
+        const credentials = await this.getCredentials("sharePointOAuth2Api");
+        // Initialize Microsoft Graph client with access token
+        const accessToken = credentials.accessToken;
+        const client = microsoft_graph_client_1.Client.init({
+            authProvider: (done) => {
+                done(null, accessToken);
+            },
+        });
+        // Create helper instance to access private methods
+        const helper = new SharePointExcelHelper();
+        for (let i = 0; i < items.length; i++) {
+            try {
+                const siteUrl = this.getNodeParameter("siteUrl", i);
+                const filePath = this.getNodeParameter("filePath", i);
+                // Get the Excel file from SharePoint
+                const fileContent = await helper.downloadExcelFile(client, siteUrl, filePath);
+                // Load the workbook
+                const workbook = new ExcelJS.Workbook();
+                // ExcelJS.load accepts Buffer, ArrayBuffer, or Uint8Array
+                // TypeScript 5.9 has strict Buffer types - ExcelJS accepts Buffer at runtime
+                // @ts-expect-error - TypeScript 5.9 strict Buffer type checking, but ExcelJS accepts Buffer
+                await workbook.xlsx.load(fileContent);
+                if (operation === "getTableNames") {
+                    // Get all table names from all worksheets
+                    const tableNames = [];
+                    workbook.eachSheet((worksheet) => {
+                        const tables = worksheet.tables || [];
+                        tables.forEach((table) => {
+                            tableNames.push(table.name);
+                        });
+                    });
+                    returnData.push({
+                        json: {
+                            tableNames,
+                        },
+                        pairedItem: { item: i },
+                    });
+                }
+                else {
+                    const tableName = this.getNodeParameter("tableName", i);
+                    // Find the table in the workbook
+                    let targetTable = null;
+                    let targetWorksheet = null;
+                    workbook.eachSheet((worksheet) => {
+                        const tables = worksheet.tables || [];
+                        tables.forEach((table) => {
+                            if (table.name === tableName) {
+                                targetTable = table;
+                                targetWorksheet = worksheet;
+                            }
+                        });
+                    });
+                    if (!targetTable || !targetWorksheet) {
+                        throw new Error(`Table "${tableName}" not found in the Excel file`);
+                    }
+                    if (operation === "getTable") {
+                        // Get all data from the table
+                        const tableData = helper.getTableData(targetWorksheet, targetTable);
+                        returnData.push({
+                            json: {
+                                tableName,
+                                data: tableData,
+                            },
+                            pairedItem: { item: i },
+                        });
+                    }
+                    else if (operation === "lookup") {
+                        // Perform lookup
+                        const lookupColumn = this.getNodeParameter("lookupColumn", i);
+                        const lookupValue = this.getNodeParameter("lookupValue", i);
+                        const matchType = this.getNodeParameter("matchType", i);
+                        const returnAll = this.getNodeParameter("returnAll", i);
+                        const tableData = helper.getTableData(targetWorksheet, targetTable);
+                        const matches = helper.performLookup(tableData, lookupColumn, lookupValue, matchType, returnAll);
+                        if (returnAll) {
+                            returnData.push({
+                                json: {
+                                    tableName,
+                                    lookupColumn,
+                                    lookupValue,
+                                    matches,
+                                    matchCount: matches.length,
+                                },
+                                pairedItem: { item: i },
+                            });
+                        }
+                        else {
+                            // Return each match as a separate item
+                            matches.forEach((match) => {
+                                returnData.push({
+                                    json: {
+                                        tableName,
+                                        lookupColumn,
+                                        lookupValue,
+                                        ...match,
+                                    },
+                                    pairedItem: { item: i },
+                                });
+                            });
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({
+                        json: {
+                            error: error instanceof Error ? error.message : String(error),
+                        },
+                        pairedItem: { item: i },
+                    });
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return [returnData];
+    }
+}
+exports.SharePointExcel = SharePointExcel;
+// Helper class to access private methods
+class SharePointExcelHelper {
+    async downloadExcelFile(client, siteUrl, filePath) {
+        // Extract site ID from URL
+        const siteId = await this.getSiteId(client, siteUrl);
+        // Get drive ID
+        const drive = await client.api(`/sites/${siteId}/drive`).get();
+        const driveId = drive.id;
+        // Download the file
+        const response = await client
+            .api(`/sites/${siteId}/drives/${driveId}/root:${filePath}:/content`)
+            .getStream();
+        // Convert stream to buffer (Node.js environment)
+        const chunks = [];
+        for await (const chunk of response) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        }
+        return Buffer.concat(chunks);
+    }
+    async getSiteId(client, siteUrl) {
+        // Extract hostname and path from URL
+        const url = new URL(siteUrl);
+        const hostname = url.hostname;
+        const path = url.pathname;
+        // Get site by hostname and path
+        const site = await client.api(`/sites/${hostname}:${path}`).get();
+        return site.id;
+    }
+    getTableData(worksheet, table) {
+        const data = [];
+        // ExcelJS Table range structure
+        const range = table.range || {};
+        const headerRow = range.top || 1;
+        const startRow = (range.top || 1) + 1; // Skip header
+        const endRow = range.bottom || worksheet.rowCount;
+        const startCol = range.left || 1;
+        const endCol = range.right || worksheet.columnCount;
+        // Get column names from header row
+        const columnNames = [];
+        for (let col = startCol; col <= endCol; col++) {
+            const cell = worksheet.getCell(headerRow, col);
+            columnNames.push(cell.value?.toString() || `Column${col}`);
+        }
+        // Get data rows
+        for (let row = startRow; row <= endRow; row++) {
+            const rowData = {};
+            for (let col = startCol; col <= endCol; col++) {
+                const cell = worksheet.getCell(row, col);
+                const columnName = columnNames[col - startCol];
+                rowData[columnName] = this.getCellValue(cell);
+            }
+            data.push(rowData);
+        }
+        return data;
+    }
+    getCellValue(cell) {
+        if (cell.value === null || cell.value === undefined) {
+            return null;
+        }
+        if (typeof cell.value === "object" && "text" in cell.value) {
+            return cell.value.text;
+        }
+        if (cell.value instanceof Date) {
+            return cell.value.toISOString();
+        }
+        return cell.value;
+    }
+    performLookup(tableData, lookupColumn, lookupValue, matchType, returnAll) {
+        const matches = [];
+        for (const row of tableData) {
+            const cellValue = row[lookupColumn];
+            if (cellValue === null || cellValue === undefined) {
+                continue;
+            }
+            const cellValueStr = String(cellValue).toLowerCase();
+            const lookupValueStr = String(lookupValue).toLowerCase();
+            let isMatch = false;
+            switch (matchType) {
+                case "exact":
+                    isMatch = cellValueStr === lookupValueStr;
+                    break;
+                case "contains":
+                    isMatch = cellValueStr.includes(lookupValueStr);
+                    break;
+                case "startsWith":
+                    isMatch = cellValueStr.startsWith(lookupValueStr);
+                    break;
+                case "endsWith":
+                    isMatch = cellValueStr.endsWith(lookupValueStr);
+                    break;
+            }
+            if (isMatch) {
+                matches.push(row);
+                if (!returnAll && matches.length === 1) {
+                    break;
+                }
+            }
+        }
+        return matches;
+    }
+}

package/dist/nodes/SharePointExcel/sharepoint.svg

@@ -0,0 +1,34 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <!-- Excel logo inspired design in blue -->
+  <defs>
+    <linearGradient id="blueGradient" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#2171B5;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#185A9D;stop-opacity:1" />
+    </linearGradient>
+  </defs>
+  
+  <!-- Main rectangle with folded corner -->
+  <path d="M 10 10 L 90 10 L 90 90 L 10 90 Z M 10 10 L 25 10 L 10 25 Z" 
+        fill="url(#blueGradient)" stroke="#0F4C75" stroke-width="1"/>
+  
+  <!-- Folded corner highlight -->
+  <path d="M 10 10 L 25 10 L 10 25 Z" fill="#2E86AB" opacity="0.6"/>
+  
+  <!-- White X on the left side -->
+  <text x="20" y="60" font-family="Arial, sans-serif" font-size="45" font-weight="bold" fill="white">X</text>
+  
+  <!-- Grid pattern on the right side -->
+  <g fill="none" stroke="white" stroke-width="2.5" stroke-linecap="square">
+    <!-- Vertical lines -->
+    <line x1="50" y1="20" x2="50" y2="80"/>
+    <line x1="65" y1="20" x2="65" y2="80"/>
+    <line x1="80" y1="20" x2="80" y2="80"/>
+    
+    <!-- Horizontal lines -->
+    <line x1="50" y1="20" x2="80" y2="20"/>
+    <line x1="50" y1="35" x2="80" y2="35"/>
+    <line x1="50" y1="50" x2="80" y2="50"/>
+    <line x1="50" y1="65" x2="80" y2="65"/>
+    <line x1="50" y1="80" x2="80" y2="80"/>
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "n8n-nodes-sharepointexcel",
+  "version": "1.0.0",
+  "description": "N8N node for reading Excel tables from SharePoint and performing table lookups",
+  "keywords": [
+    "n8n-community-node-package",
+    "n8n",
+    "n8n-nodes",
+    "sharepoint",
+    "excel",
+    "table",
+    "lookup",
+    "microsoft-graph"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "postinstall": "chmod +x node_modules/.bin/* 2>/dev/null || true",
+    "build": "node build.js",
+    "build:ts": "node -r typescript/bin/tsc",
+    "build:icons": "node -r gulp/bin/gulp.js build:icons",
+    "dev": "node -r typescript/bin/tsc --watch",
+    "format": "prettier nodes credentials --write",
+    "lint": "eslint nodes credentials package.json",
+    "lintfix": "eslint nodes credentials package.json --fix",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "n8n": {
+    "n8nNodesApiVersion": 1,
+    "nodes": [
+      "dist/nodes/SharePointExcel/SharePointExcel.node.js"
+    ],
+    "credentials": [
+      "dist/credentials/SharePointOAuth2Api.credentials.js"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^18.15.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "eslint": "^10.0.1",
+    "eslint-plugin-n8n-nodes-base": "~1.16.6",
+    "gulp": "^5.0.1",
+    "n8n-workflow": "*",
+    "prettier": "^3.8.1",
+    "typescript": "~5.9.3"
+  },
+  "dependencies": {
+    "@microsoft/microsoft-graph-client": "^3.0.7",
+    "exceljs": "^4.4.0",
+    "n8n-workflow": "*"
+  }
+}