XML Extractor

The XML Extractor plugin processes .xml files uploaded to Flatfile by parsing XML data, flattening its nested structure and attributes, and converting it into a tabular format. The plugin automatically detects the main collection of records within the XML file and transforms each record into a row, making it ideal for importing structured XML data from legacy systems, APIs, or data exports.

​

Installation

Install the XML Extractor plugin using npm:

npm install @flatfile/plugin-xml-extractor

​

Configuration & Parameters

The XML Extractor accepts the following configuration options:

​

Default Behavior

By default, the plugin:

• Flattens nested elements using "/" as a separator (e.g., <country><name>USA</name></country> becomes "country/name")
• Prefixes attributes with "#" (e.g., <country code="US"> becomes "country#code")
• Processes files in chunks of 10,000 records with sequential processing
• Automatically infers headers from all unique keys found across records

​

Usage Examples

​

Basic Usage

import { listener } from '@flatfile/listener';
import { XMLExtractor } from '@flatfile/plugin-xml-extractor';

export default listener.on('file:created', (event) => {
  // Only handle .xml files
  if (event.context.file.ext !== 'xml') {
    return;
  }
  return XMLExtractor()(event);
});

​

Custom Configuration

import { listener } from '@flatfile/listener';
import { XMLExtractor } from '@flatfile/plugin-xml-extractor';

export default listener.on('file:created', (event) => {
  if (event.context.file.ext !== 'xml') {
    return;
  }
  return XMLExtractor({
    separator: '_',
    attributePrefix: '@',
    transform: (row) => {
      if (row.age) {
        row.age = parseInt(row.age, 10);
      }
      return row;
    },
    chunkSize: 5000,
    parallel: 2,
  })(event);
});

​

Using the Standalone Parser

import * as fs from 'fs';
import { xmlParser } from '@flatfile/plugin-xml-extractor';

const xmlBuffer = fs.readFileSync('path/to/your/file.xml');
const workbookData = xmlParser(xmlBuffer, { separator: '.' });

console.log(workbookData.Sheet1.headers);
console.log(workbookData.Sheet1.data[0]);

​

Error Handling

import { xmlParser } from '@flatfile/plugin-xml-extractor';

try {
  const emptyXml = Buffer.from('<?xml version="1.0"?>');
  xmlParser(emptyXml);
} catch (e) {
  console.error(e.message); // "No root xml object found"
}

​

Troubleshooting

​

Fields Not Appearing as Expected

Check the separator and attributePrefix configuration. The default flattening behavior might not match your desired output format.

​

Handling Repeated Tags

If tags within a record are repeated (e.g., multiple <email> tags), the extractor creates indexed headers. The first email tag becomes the email field, the second becomes email/0, the third email/1, and so on.

​

Debugging Row Data

Use the transform function to inspect intermediate parsed output:

XMLExtractor({
  transform: (row) => {
    console.log(row);
    return row;
  }
})

​

Notes

• The plugin is designed for server-side environments and should be used in Flatfile listeners deployed on the Platform
• XML files must have a single root element containing an array of similar child elements (records)
• Not suitable for arbitrary or document-style XML with highly irregular structures
• Headers are automatically inferred from all unique keys found across all records
• The primary error condition is invalid XML structure - if no root element containing records is found, the parser throws “No root xml object found”