Skip to main content

Insert Row

Inserts a row into an excel file.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If ContinueOnError property is true, no error is caught when the project is executed even if Catch node is used.

Input​

  • Excel File Descriptor - The opened excel file descriptor id obtained from Open Excel Node. This ID is generated by the Open Excel or the Create Excel node.
  • Row Number - The row number after which data has to be inserted.
  • Row Data - The data to be inserted in json format. E.g. {"A": "value1", "B": "value2", "C": "value3"}

Options​

  • Target - Select where to insert the row:
    • Active Row - Inserts the row into the current active row.
    • Specific Row - Inserts the row at a position specified by the row number.
  • Header - If true, the row data json keys will be acted as header names

Output​

  • Excel File Descriptor - The unique descriptor identifier for the open Excel file, so the node can be chained directly into the next Excel node.

How It Works​

  1. Validates Input: Checks that the file descriptor and target option are provided
  2. Verifies Target: Ensures a valid target option is selected
  3. Checks Row Input: If specific-row is selected, validates that a row number is provided
  4. Retrieves Handle: Gets the Excel file handle from the descriptor
  5. Parses Row Data: Reads the JSON object and maps each key to a column
  6. Determines Row: Based on target option, identifies where the new row goes:
    • Active Row: Uses the row number from the active cell
    • Specific Row: Inserts after the provided row number
  7. Inserts Row: Adds the row and shifts existing rows downward
  8. Writes Values: Fills each column from the Row Data keys

Requirements​

  • The Excel file must be opened with Open Excel or created with Create Excel
  • A valid file descriptor must be provided
  • When using specific-row target, a valid row number must be provided (must be greater than 0)
  • When using active-row target, an active cell must be set
  • Row Data must be a valid JSON object, not an array
  • The file must be saved after insertion to persist changes

Error Handling​

Error CodeDescriptionSolution
Core.Excel.InsertRow.ErrOnCreateConfiguration parsing failedCheck node configuration is valid
Core.Excel.InsertRow.OnMessageMessage parsing failedVerify input message format
Core.Excel.InsertRow.ErrTargetTarget option is empty or invalidSelect a valid target option
Core.Excel.InsertRow.ErrRowRow number is empty for specific-rowProvide a valid row number when using specific-row
Core.Excel.InsertRow.ErrFileDescriptorFile descriptor is empty or file not foundEnsure the file is opened/created before inserting a row
Core.Excel.InsertRow.ErrInputRow data is not valid JSONPass an object such as {"A": "value1", "B": "value2"}
Core.Excel.InsertRow.GetActiveCellNo active rowSet the active cell before using active-row
Core.Excel.InsertRow.ErrSetActiveCellCould not move the active cell after insertionVerify the sheet is not protected

Usage Examples​

Example 1: Insert a Row at a Specific Position​

Add a row after row 5:

- Open Excel (data.xlsx) -> fileDesc
- Insert Row:
  - Excel File Descriptor: fileDesc
  - Row Number: 5
  - Row Data: {"A": "2026-08-08", "B": "Acme Ltd", "C": "1450.00"}
  - Target: specific-row
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Example 2: Insert Below the Header​

Add a new record directly under the header row:

- Open Excel (customers.xlsx) -> fileDesc
- Insert Row:
  - Excel File Descriptor: fileDesc
  - Row Number: 1
  - Row Data: {"A": "Hiroshi Tanaka", "B": "hiroshi@example.com"}
  - Target: specific-row
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Example 3: Insert at the Active Row​

Insert where the active cell currently sits:

- Open Excel (inventory.xlsx) -> fileDesc
- Set Active Cell (fileDesc, "A10")
- Insert Row:
  - Excel File Descriptor: fileDesc
  - Row Data: {"A": "SKU-9931", "B": "In stock"}
  - Target: active-row
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Example 4: Insert Rows by Header Name​

With Header enabled, the JSON keys match column headers instead of letters:

- Open Excel (orders.xlsx) -> fileDesc
- Insert Row:
  - Excel File Descriptor: fileDesc
  - Row Number: 1
  - Row Data: {"Order ID": "A-1042", "Customer": "Globex", "Total": "980.00"}
  - Header: true
  - Target: specific-row
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Example 5: Insert Many Rows from a Data Table​

Insert each record from a loop (insert from bottom to top to keep positions stable):

- Open Excel (report.xlsx) -> fileDesc
- For Each (record in records)
  - Insert Row:
    - Excel File Descriptor: fileDesc
    - Row Number: 1
    - Row Data: record
    - Header: true
    - Target: specific-row
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Usage Notes​

  • Insert Row adds a new row and shifts existing rows downward
  • The row is inserted after the row number you specify, so Row Number 5 creates a new row 6
  • Row numbers start from 1 (not 0)
  • Row Data must be a JSON object; a JSON array will raise ErrInput
  • With Header set to false, keys are column letters ("A", "B"); with Header set to true, keys are header names
  • Keys that do not match any column are ignored rather than raising an error
  • Formulas referencing shifted rows are not automatically updated
  • When inserting several rows in a loop, insert from bottom to top so earlier positions do not move
  • Remember to save the file to persist the changes

Tips​

  • Use Header mode when the source data already has named fields - it survives column reordering, which letter keys do not
  • Insert at Row Number 1 to prepend a record directly under the header
  • Use Get Row first if you need to read the row you are about to displace
  • Check the sheet is not protected before inserting, or the active-cell move will fail
  • For appending to the end of a sheet, Append Excel is simpler than counting rows
  • Test on a copy of the file when automating inserts into a live workbook