Find Excel Cell

Find Excel Cell

Type: excel-find-cell  ·  Package: Excel Activities v1.0.6  ·  Output: Dictionary

Searches the sheet for a value and returns the location of the first matching cell (address, row and column). It is the equivalent of Excel’s “Find”. Useful to locate a header, find where a specific piece of data is, or locate a row by its identifier before reading or writing around it.

How it works

It scans the sheet’s used range (or the given searchRange) row by row, left to right, and returns the first cell that matches value according to matchType. If nothing matches, it returns null.

• The comparison is text-based and case-insensitive: value converted to text is compared with each cell’s content as text.
• Numbers and dates in cells are compared in the robot’s regional format (1500,5 on a Spanish machine). Whole numbers and text behave the same on any machine.
• Formulas are compared by their result.

Accepts session or path — see the two modes. Read-only: in fast mode it does not modify the file.

Required parameters

Parameter	Type	Default	Description
value	object	—	The value to look for. Compared as text.

Optional parameters

Parameter	Type	Default	Description
session	ZoanExcelSession	—	Excel Open session (instead of path).
path	string	—	Path to the .xlsx (required if there is no session). The file must exist.
sheet	string | int	—	Sheet name or 1-based index. If omitted, the first sheet.
matchType	string	"exact"	How to compare: exact (the cell equals the value) · contains (the cell contains the value) · starts-with (the cell starts with the value).
searchRange	string	—	Limit the search to a range, e.g. "A1:Z100". If omitted, the sheet’s whole used range. Avoid whole columns ("A:A"): over a million rows are scanned when the value is not there.

Output

Returns a Dictionary with these exact keys, or null when there is no match (or the sheet is empty):

Key	Type	Description
address	string	Cell address, e.g. "B7" (no $ or sheet name).
row	int	Row number in the sheet (1-based), even if you limited the search with searchRange.
column	int	Column number in the sheet (1-based: A = 1).
value	object	The cell’s value with its type, as in Read Excel Cell (double number, DateTime date, boolean or text).

Common errors

Message	Cause and fix
'value' is required.	value is empty or the expression returned null.
'session' or 'path' is required.	Neither session nor path is set.
File not found.	path does not exist.
'…' is not A1 address or named range.	searchRange is not a valid address.
There isn't a worksheet named '…'.	No sheet has that name.
There isn't a worksheet associated with that position.	The sheet index does not exist (or the name is just a number and was taken as an index).

Not finding the value is not an error: the activity returns null.

Example

Find Excel Cell   path = asset("data.xlsx")   value = "Total"   → output: cell
If   condition = isNull(cell)
 ├─ then:
 │    Log   level = warning   message = "Cell 'Total' not found"
 └─ else:
      Log   message = "Found at " + cell["address"] + " (row " + cell["row"] + ")"

Locate an invoice by its number and update its status in column E of the same row:

Excel Open   path = "C:/invoices/control.xlsx"   → output: workbook
Find Excel Cell    session = workbook   value = invoiceNumber   → output: cell
If   condition = !isNull(cell)
 └─ then:
      Write Excel Cell   session = workbook   cell = "E" + cell["row"]   value = "Paid"
Excel Close   session = workbook

Check whether something was found

When the value may not exist, check the result with isNull(cell) before reading its keys, so that accessing cell["address"] doesn’t fail.

Related activities

• Read Excel Cell — read a cell at a known position.
• Read Excel Sheet — read the whole sheet and filter it with Filter DataTable.