Microsoft Excel

The Microsoft Excel Node creates, parses, updates, and password-protects .xlsx workbooks in a Workflow.

Revision History

0.2.0.8 - Added native password protection for creating, reading, and updating Excel workbooks.
0.1.0.0 - Moved workbook parsing into the awaited Node startup phase.
0.0.0.15 - Standardized the public V2 help article.
0.0.0.11 - Initial release.
0.0.0.12 - Current source exposes Create, Parse, and AddSheet methods with typed column handling, header control, and worksheet append support.
0.0.0.14 - Added automatic default worksheet naming for AddSheet when WorksheetName is left blank, and clarified worksheet option behavior.

Connection

Use the optional Microsoft Excel Connection when a method must create or open a password-protected workbook.

Property	Type	Description
Password	Masked	Case-sensitive password used to open or create encrypted Excel workbooks.

Setup Notes

• Provide workbook content as an .xlsx document stream when using Parse or AddSheet.
• Select a Microsoft Excel Connection when reading encrypted input or when EncryptWorkbook is enabled.
• Create and AddSheet expect every item in Items to be an object where each property represents a worksheet column value.
• When Options.Columns is supplied, column names must be unique and each entry must include Name.
• Supported column type values are Auto, String, Number, Date, DateTime, and Boolean.

Methods

This Node exposes methods to create a workbook, parse one worksheet into objects, and add a worksheet to an existing workbook.

Create

Use this method when you want to generate a new Excel workbook from Workflow rows and optionally force Excel cell types per column.

Parameter	Type	Description
Connection	Connection	Optional Microsoft Excel Connection containing the workbook password. Required when EncryptWorkbook is enabled.
Items	Array	The object rows to write into the worksheet. Each object becomes one worksheet row.
EncryptWorkbook	Boolean	When true, protects the generated workbook with the password from Connection.
Options	Object	Optional settings for workbook creation. Supports WorksheetName, FirstRowContainsColumnHeaders, and Columns. WorksheetName defaults to Sheet1. FirstRowContainsColumnHeaders defaults to true. Columns is an ordered list of column definitions with Name and Type.

Return	Type	Description
Document	Stream	The generated .xlsx workbook stream.

Parse

Use this method when you need to read one worksheet from an Excel workbook back into Workflow-friendly objects.

Parameter	Type	Description
Connection	Connection	Optional Microsoft Excel Connection containing the matching password for encrypted input.
Document	Stream	The Excel workbook to parse.
Options	Object	Optional settings for worksheet selection and header handling. Supports WorksheetName and FirstRowContainsColumnHeaders. When WorksheetName is omitted, the first worksheet is used. FirstRowContainsColumnHeaders defaults to true.

Return	Type	Description
Rows	Array	The parsed row objects from the selected worksheet. Each row is emitted as a business object and no mutation-style default fields are added.

AddSheet

Use this method when you need to append a new worksheet to an existing Excel workbook without replacing the workbook's current sheets.

Parameter	Type	Description
Connection	Connection	Optional Microsoft Excel Connection used to open encrypted input or protect previously unencrypted output.
Document	Stream	The existing Excel workbook to update.
Items	Array	The object rows to write into the new worksheet. Each object becomes one worksheet row.
EncryptWorkbook	Boolean	When true, password-protects previously unencrypted input. Existing encryption is preserved even when this value is false.
Options	Object	Optional settings for the new worksheet. Supports WorksheetName, FirstRowContainsColumnHeaders, and Columns. If WorksheetName is left blank, the Node starts at Sheet1 and automatically increments to the next available default worksheet name when needed. FirstRowContainsColumnHeaders defaults to true. Columns is an ordered list of column definitions with Name and Type.

Return	Type	Description
UpdatedDocument	Stream	The updated .xlsx workbook stream containing the appended worksheet.

Usage Notes

• When Options.Columns is not supplied for Create or AddSheet, column order is taken from the first row in Items.
• When FirstRowContainsColumnHeaders is false and Options.Columns is not supplied, the Node still uses the first row to determine column order, but writes that first row as data instead of using it as worksheet headers.
• Set Options.FirstRowContainsColumnHeaders to false when the worksheet should contain only data rows, or when parsing a worksheet whose first row should be treated as data.
• String column typing preserves text values as strings in the workbook, while Number, Date, DateTime, and Boolean write the corresponding Excel cell types.
• If Parse is used with FirstRowContainsColumnHeaders set to false, returned properties are named Column1, Column2, and so on.
• Parse validates and materializes the selected worksheet while the Node invoke is awaited. Invalid workbook errors surface before downstream row enumeration begins.
• The Node automatically detects encrypted input. Parse and AddSheet require a Connection containing the matching password when the input workbook is encrypted.
• Create and AddSheet use native Agile AES-256 Excel encryption when password protection is requested.
• AddSheet preserves an input workbook's existing encryption and password even when EncryptWorkbook is false.

Known Issues

• Parse reads one worksheet per invocation rather than returning all worksheets from a workbook in one pass.
• Date parsing depends on workbook cell styles being present and recognizable as date-like number formats.