Skip to main content

Insert Column

Inserts a new column in a specified location in an Excel sheet.

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 a Catch node is used.

Input​

  • Excel File Descriptor - The unique descriptor identifier for the open Excel file. This ID is generated by the Open Excel or the Create Excel node.
  • Column Name - The name of the new column. This is an optional input property. (e.g. B or F)
  • Column Data - The data for the new column to be inserted. This should be a string array. (e.g. ["Boston","London","Miami"])

Output​

  • Excel File Descriptor - The unique descriptor identifier for the open Excel file.

Options​

  • Target - Select where to insert the column:
    • Active Column - Inserts a new column in the active column.
    • Specific Column - Inserts a new column at a position specified by the column name.

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 Column Input: If specific-column is selected, validates that a column name is provided
  4. Retrieves Handle: Gets the Excel file handle from the descriptor
  5. Parses Column Data: Reads the string array, one entry per row
  6. Determines Column: Based on target option, identifies where the new column goes:
    • Active Column: Uses the column from the active cell
    • Specific Column: Inserts at the named column
  7. Inserts Column: Adds the column and shifts existing columns to the right
  8. Writes Values: Fills the column top to bottom from the array

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-column target, a valid column name must be provided (e.g. B)
  • When using active-column target, an active cell must be set
  • Column Data must be a string array, not an object
  • The file must be saved after insertion to persist changes

Error Handling​

Error CodeDescriptionSolution
Core.Excel.InsertColumn.ErrOnCreateConfiguration parsing failedCheck node configuration is valid
Core.Excel.InsertColumn.OnMessageMessage parsing failedVerify input message format
Core.Excel.InsertColumn.ErrTargetTarget option is empty or invalidSelect a valid target option
Core.Excel.InsertColumn.ErrColumnColumn name is empty for specific-columnProvide a column name such as B
Core.Excel.InsertColumn.ErrFileDescriptorFile descriptor is empty or file not foundEnsure the file is opened/created before inserting a column
Core.Excel.InsertColumn.ErrInputColumn data is not a valid string arrayPass an array such as ["Boston","London"]
Core.Excel.InsertColumn.GetActiveCellActive column cannot be foundSet the active cell before using active-column
Core.Excel.InsertColumn.ErrInsertThe insert operation failedVerify the sheet is not protected and the column is in range

Usage Examples​

Example 1: Insert a Column at a Specific Position​

Add a new column at B, shifting the existing B and beyond to the right:

- Open Excel (data.xlsx) -> fileDesc
- Insert Column:
  - Excel File Descriptor: fileDesc
  - Column Name: B
  - Column Data: ["City","Boston","London","Miami"]
  - Target: specific-column
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Example 2: Insert an Empty Column​

Create the column without filling it, ready to be written later:

- Open Excel (report.xlsx) -> fileDesc
- Insert Column:
  - Excel File Descriptor: fileDesc
  - Column Name: D
  - Target: specific-column
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Example 3: Insert at the Active Column​

Insert where the active cell currently sits:

- Open Excel (inventory.xlsx) -> fileDesc
- Set Active Cell (fileDesc, "C1")
- Insert Column:
  - Excel File Descriptor: fileDesc
  - Column Data: ["Reorder level","10","25","5"]
  - Target: active-column
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Example 4: Add a Computed Column to a Report​

Insert a column built earlier in the flow:

- Open Excel (sales.xlsx) -> fileDesc
- Get Column (fileDesc, "C") -> amounts
- Map (amounts -> withVat)
- Insert Column:
  - Excel File Descriptor: fileDesc
  - Column Name: D
  - Column Data: withVat
  - Target: specific-column
- Save Excel (fileDesc)
- Close Excel (fileDesc)

Usage Notes​

  • Insert Column adds a new column and shifts existing columns to the right
  • Column names are letters (A, B, AA), not numbers
  • The first entry of Column Data lands in row 1, so include the header as the first element when the sheet has one
  • If Column Data is shorter than the sheet, the remaining cells are left empty
  • Column Data must be a string array; a JSON object will raise ErrInput
  • Formulas referencing shifted columns are not automatically updated
  • When inserting several columns, work right to left so earlier positions do not move
  • Remember to save the file to persist the changes

Tips​

  • Insert the column before writing to it rather than overwriting an existing one, so no data is lost
  • Include the header as the first array element - it is easy to forget and shifts every value up by one row
  • Use Get Column to read an existing column before building a derived one
  • Check the sheet is not protected before inserting, or the operation raises ErrInsert
  • Test on a copy of the file when automating inserts into a live workbook