XLSX to JSON Converter icon

XLSX to JSON Converter

Convert Excel spreadsheets to JSON via REST service
Join our community

Overview

This node converts Excel (XLSX) spreadsheets into JSON format by leveraging an external REST API conversion service. It downloads an XLSX file from a specified URL, uploads it to the conversion service, configures parameters such as which sheet and columns to export, and retrieves the converted JSON data.

Common scenarios:

  • Automating data extraction from Excel reports or exports hosted online.
  • Integrating Excel-based data sources into workflows that require JSON input.
  • Transforming specific sheets or columns of large spreadsheets into structured JSON for further processing.

Practical example:
You have a publicly accessible Excel file with sales data. You want to extract only certain columns (e.g., product name, price, quantity) from the second sheet and convert them into JSON objects for use in downstream automation tasks like database updates or analytics.

Properties

Name Meaning
XLS Service URL URL of the XLS to JSON conversion service API endpoint. Example: http://localhost:3000/api.
File URL URL of the XLSX file to download and convert. Must be a valid HTTP/HTTPS URL.
Sheet Index Zero-based index of the sheet within the Excel file to convert. For example, 0 means the first sheet.
Headers Row Index Zero-based index of the row containing column headers. For example, 0 means the first row is headers.
Export Fields Comma-separated list of zero-based column indices to export. Example: "0,3,5" exports the 1st, 4th, and 6th columns. Leave empty to export all columns.
Field Mapping JSON array defining custom field names mapped to column indices. Format example: [{"index": 0, "name": "model"}, {"index": 3, "name": "price"}]. Leave empty to keep original column names.
Authentication Boolean flag indicating if the conversion API requires authentication.
API Key API key string used for authenticating requests to the conversion service. Only shown if Authentication is enabled.
API Key Header Name HTTP header name to send the API key under (e.g., X-API-KEY, Authorization). Only shown if Authentication is enabled.
Advanced Options Boolean flag to show advanced configuration options.
Timeout (seconds) Maximum time in seconds to wait for responses from the conversion service. Only shown if Advanced Options is enabled.
Retry Attempts Number of retry attempts for failed API requests. Only shown if Advanced Options is enabled.
Debug Mode Enables additional debug logging output. Only shown if Advanced Options is enabled.

Output

The node outputs an array of items where each item's json property contains one record from the converted Excel sheet as a JSON object.

  • Each JSON object represents a row from the selected sheet.
  • The keys correspond to either the original column headers or the custom field names defined via Field Mapping.
  • Only the columns specified in Export Fields are included; if Export Fields is empty, all columns are included.
  • Binary data output is not produced by this node.

Dependencies

  • Requires access to an external XLSX to JSON conversion REST API service reachable at the configured XLS Service URL.
  • If authentication is enabled, an API key credential must be provided and sent in the specified header.
  • The node uses HTTP(S) to download the XLSX file from the given File URL.
  • Network connectivity and proper CORS or firewall settings must allow these HTTP requests.
  • Environment variable XLS_SERVICE_URL can provide a default API endpoint if not set explicitly.

Troubleshooting

Common issues:

  • Invalid URLs: The node validates both the XLS service URL and the file URL. Errors occur if these are malformed or unreachable.
  • File size limit: Files larger than 50 MB are rejected to prevent overload.
  • Sheet index out of range: Specifying a sheet index outside the available sheets causes an error.
  • No fields found: If the specified header row does not contain any fields, the node throws an error.
  • API connection errors: Connection refused, timeout, or DNS resolution failures when contacting the conversion service or downloading the file.
  • Authentication errors: Missing or incorrect API key or header name leads to authorization failures.

Error messages and resolutions:

  • "Invalid XLS Service URL" or "Invalid File URL": Check and correct the URLs.
  • "File size exceeds 50 MB limit": Use a smaller file or split the spreadsheet.
  • "No sheets found in the Excel file": Verify the file content and sheet presence.
  • "Invalid sheet index": Adjust the sheet index parameter to a valid value.
  • "Failed to get exported data: HTTP ...": Inspect network connectivity and API availability.
  • "Connection timed out": Increase the timeout setting or check server responsiveness.
  • "Cannot connect to conversion service": Ensure the service is running and accessible at the specified URL.
  • Parsing errors in Field Mapping: Provide valid JSON array with correct structure.

Enabling Debug Mode provides detailed logs to help diagnose issues.

Links and References

  • Axios HTTP client - Used internally for HTTP requests.
  • FormData API - Used for file upload.
  • URL validation - Node validates URLs before use.
  • General guidance on Excel to JSON conversion services depends on the specific external API used.

Discussion