pfx-excel Component

Since: IM 1.1.18 (March 2020, PFIMCORE-280)

This component is used for easy Excel file manipulation. It supports reading (unmarshalling) and writing (marshalling) of both XLS and XLSX formats.

URI format	`pfx-excel:<method>`

When to Use

Scenario	Method	Example
Export Pricefx data to Excel for customer reporting	`marshal`	Fetch products, marshal, send via SFTP
Import product catalog from Excel file	`unmarshal`	Read Excel from inbox, unmarshal, loaddata
Process large Excel file (10k+ rows) without OOM	`streamingUnmarshal`	Stream rows, split, process in batches
Append data to existing Excel template	`marshal` with `fileToAppend`	Split batches, append to template.xlsx
Preserve formatting (leading zeros in SKUs)	`marshal` with `dataConversionMode=NONE`	Export SKU codes without numeric conversion

Quick Start: Import Excel to Pricefx

XML

<route id="excelImport">
    <from uri="file:{{inbox}}?include=.*\.xlsx"/>
    <to uri="pfx-excel:unmarshal"/>
    <to uri="pfx-api:loaddata?objectType=P&amp;mapper=productMapper"/>
</route>

Available Methods

Method	Since	Description	Details
marshal	IM 1.1.18	Converts internal representation (List of Maps) into an Excel file	Properties: `hasHeaderRecord`, `skipHeaderRecord`, `header`, `format`, `sheetIndex`, `sheetName`, `fileToAppend`, `dataConversionMode`
unmarshal	IM 1.1.18	Converts an Excel file (XLS/XLSX) into internal representation (List of Maps)	Properties: `hasHeaderRecord`, `skipHeaderRecord`, `header`, `sheetIndex`, `sheetName`
streamingUnmarshal	PFIMCORE-463 (Oct 2022)	Streaming variant of unmarshal for large XLSX files with lower memory footprint	Properties: `hasHeaderRecord`, `skipHeaderRecord`, `header`, `sheetIndex`, `sheetName`

Shared Properties

These properties are available across all methods:

Option	Type	Default	Since	Description
`hasHeaderRecord`	Boolean	`true`	IM 1.1.18	Indicates whether the input contains a header record (must be on the first row).
`skipHeaderRecord`	Boolean	`false`	IM 1.1.18	Determines whether to skip the header record in the output.
`header`	String		IM 1.1.18	Comma-separated list of headers. For unmarshal with `hasHeaderRecord=false`, defines column names. For marshal, filters which columns appear in output.
`sheetIndex`	Integer	`0`	IM 1.1.18	Index of the sheet (0-based).
`sheetName`	String		IM 1.1.18	Name of the sheet. If set, takes precedence over `sheetIndex`.

Marshal-only Properties

Option	Type	Default	Since	Description
`format`	String	`xlsx`	IM 1.1.18	Output format: `xlsx` or `xls`.
`fileToAppend`	String		PFIMCORE-1876 (Feb 2024)	Full path to an existing Excel file to append data to. Uses `SXSSFWorkbook` for streaming writes. Supports split operations.
`dataConversionMode`	Enum	`AUTO`	IM 6.0.13 (PFIMCORE-2687, Oct 2025)	Controls data type conversion: `AUTO` (parse integers as numeric cells) or `NONE` (all values as strings). Marshal only -- does not apply to unmarshal or streamingUnmarshal.

Supported Formats

Format	Extension	unmarshal	streamingUnmarshal	marshal
OOXML (Office Open XML)	`.xlsx`	Yes	Yes	Yes (default)
OLE2 (Binary Excel)	`.xls`	Yes	No	Yes (`format=xls`)

Format auto-detection for unmarshal uses Apache POI's FileMagic -- it peeks at the stream's first bytes via mark/reset without buffering the entire file (since PFIMCORE-2862, March 2026).

Version History

Version / Ticket	Date	Change
IM 1.1.18 (PFIMCORE-280)	March 2020	Initial component with `marshal` and `unmarshal` methods
PFIMCORE-463	October 2022	Added `streamingUnmarshal` method for large XLSX files
PFIMCORE-1876	February 2024	Added `fileToAppend` property for append-to-file support in marshal
IM 6.0.13 (PFIMCORE-2687)	October 2025	Added `dataConversionMode` property (AUTO/NONE) for marshal
PFIMCORE-2862	March 2026	Migrated to POI 5.x, replaced streaming library, improved format auto-detection
PFIMCORE-2881	March 2026	Fixed scientific notation and numeric edge cases in cell value extraction

See Also

pfx-excel:marshal -- full marshal reference with examples
pfx-excel:unmarshal -- full unmarshal reference with numeric handling rules
pfx-excel:streamingUnmarshal -- streaming unmarshal for large files
pfx-csv Component -- for CSV file handling (lighter weight alternative)
pfx-api:loaddataFile -- for direct file upload to Pricefx without unmarshal step