Skip to content

Excel

Excel actions exposed to the robot allow opening, reading, editing and saving Excel files.

Important note: only methods decorated with @decorators.robotaction are user actions and documented here. Action returns are mapped to robot state variables — e.g. if an action returns {'workbook': workbook} you access it in the flow with $workbook.

Actions

Each section describes the action, parameters, return keys (which become state variables) and notes.

excel.append

Append a single row or multiple rows to the worksheet.

Parameters:
  • worksheet — Worksheet.
  • line_values (optional) — list representing a row.
  • grid_values (optional) — list of lists to append multiple rows.
Return:

none.

excel.convert_to_xlsx

Convert a file (e.g. .xls) to .xlsx. Requires Excel installed on the robot host.

Important: To use this action, the Excel software must be installed on the machine and all Excel windows should be closed.

Parameters:
  • filepath — path in assets.
  • excel_visible (optional) — shows Excel during conversion.
Return:

none. The converted file is created next to the original with .xlsx extension.

excel.create_new

Create a new blank workbook.

Parameters:

none.

Return:
  • workbook — new Workbook.
  • worksheet — active Worksheet created.

Note: use excel.save to persist to disk.

excel.create_sheet

Create a new sheet in the workbook.

Parameters:
  • workbook — Workbook.
  • sheet_name — new sheet name.
Return:
  • workbook — updated Workbook.
  • worksheet — the created Worksheet.

excel.create_style_template

Create a reusable style template.

Parameters:
  • font_name, font_size, bold, italic, underline, font_color, background_color, border_style, border_color.
Return:
  • template — object usable by excel.set_template.

excel.delete_rows

Remove rows from start to end inclusive. If end is omitted only start is removed.

Parameters:
  • worksheet, start, end (optional).
Return:

none.

excel.execute_macro

Execute a macro via COM (requires Excel installed).

Parameters:
  • file_path — file containing the macro.
  • macro — macro identifier/name.
  • save_after_execution (optional, default True) — save after execution.
Return:

none. Macro errors may be raised.

excel.get_cell

Return a cell or range content.

Parameters:
  • worksheet — Worksheet.
  • range — Excel range string (e.g. A1 or A1:C3).
Return:
  • first_col, first_row, last_col, last_row, values — values is a matrix with rows and columns (e.g. values[0][1]).
Exceptions:
  • InvalidRange if the range is invalid (implementation detail).

excel.get_dimensions

Return the used range of the sheet.

Parameters:
  • worksheet — Worksheet.
Return:
  • range — Excel range string (e.g. A1:F150).
  • first_cell — first cell reference.
  • last_cell — last cell reference.

excel.last_line

Return the last used row number.

Parameters:
  • worksheet — Worksheet.
Return:
  • last_line — integer with last row number.

excel.list_sheets

Return sheet names and active sheet.

Parameters:
  • workbook — Workbook object.
Return:
  • sheets — list of sheet names.
  • active_sheet — name of active sheet.

excel.open

Open an Excel file and (optionally) try to update calculated values by opening Excel locally before loading.

Parameters:
  • filepath — path to the file in assets.
  • use_formula (optional, default False) — when True returns formulas instead of evaluated values.
  • auto_update (optional, default True) — when True attempts to open Excel to refresh formulas before loading.
  • excel_visible (optional, default False) — when True shows the Excel application during update.
Return:
  • workbook — openpyxl Workbook object.
  • worksheet — active Worksheet.
Exceptions:
  • FileNotFoundException if the file does not exist in assets.
  • InvalidExcelFile when the file is in an incompatible or corrupted format (e.g. .xls). Use excel.convert_to_xlsx when applicable.

excel.rename_sheet

Rename given worksheet.

Parameters:
  • worksheet — Worksheet to rename.
  • new_name — new name.
Return:
  • worksheet — updated Worksheet.

excel.save

Save workbook to disk.

Parameters:
  • workbook — Workbook.
  • filepath — destination path (including filename).
Return:

none.

excel.select_sheet

Select a sheet from the workbook.

Parameters:
  • workbook — Workbook.
  • sheet_name (optional) — sheet name; if omitted returns the active sheet.
Return:
  • workbook — Workbook (same object provided).
  • worksheet — selected Worksheet.

excel.set_style

Apply style properties to a cell or range.

Parameters:
  • worksheet, range and style properties (font_name, font_size, bold, italic, underline, font_color, background_color, border_style, border_color).
Return:

none.

excel.set_table_format

Apply header/odd/even line styles to a range.

Parameters:
  • worksheet, range, header_style, odd_line_style, even_line_style (optional).
Return:

none.

Exceptions:

WrongVarType if range is not a valid range.

excel.set_template

Apply a template (from excel.create_style_template) to a range.

Parameters:
  • worksheet, range, template.
Return:

none.

excel.update_cell

Update a cell value.

Parameters:
  • worksheet — Worksheet.
  • value — value to insert.
  • cell — cell reference (e.g. A1).
Return:
  • same format as excel.get_cell (first_col, first_row, last_col, last_row, values).