Escribal
Back to Docs

Spreadsheet

Cells & content

This group of instructions fills, reads, clears, copies, and annotates the cells of a spreadsheet: writing single values or whole blocks, reading a cell back into a saved value, clearing content or formatting, merging cells, naming ranges, adding hyperlinks and comments, and finding or replacing text across a sheet.

Prerequisite: before using any of these instructions, the workflow must already have an XLSX spreadsheet created or opened (with Create spreadsheet). Every instruction works on a sheet (tab) inside that spreadsheet, identified by name (Sheet1 by default), which must already exist.

These concepts recur across several instructions in this group; they are explained here once.

  • Document: indicates which document in the workflow the instruction applies to. If left empty, the current document is used.

  • Cell addresses use the A1 style: a cell is named by its column letter followed by its row number — for example B3 is column B, row 3. A range is given as two opposite corners, a start cell and an end cell (for example start A1, end C3 covers a 3×3 block).

  • The sheet must already exist: the Sheet name field chooses which tab the instruction works on, and defaults to Sheet1. If no sheet with that name is found, the instruction does nothing and the workflow continues with the next instruction.

  • Values are typed automatically: when you write a value, the program decides its type on its own — text that looks like a number is stored as a number, everything else as text. Turn on Treat value as a date to store it as a date instead (when the text can be read as one).

  • An invalid cell address does nothing: instructions that write to a single cell (such as Write cell value or Insert hyperlink) quietly do nothing if the cell address is not a valid A1 reference.

  • Dynamic values (@name): in any text field (cell address, value, sheet name, search text, and so on) you can type @ followed by the name of a value saved earlier in the workflow, and it will be replaced by that value. For example, if you saved a cell reference in target, you can type @target in the Cell address field.

  • Saving a result: some instructions can store their result in a named value so a later instruction can use it — the “Save … to” fields. Leave the field empty to not save anything.

  • “From variable” fields: the @name trick only works in text fields. The yes/no options in this group (like Treat value as a date or Case-sensitive) each have a companion “from variable” field:

    • If you leave it empty, the value chosen in the normal yes/no field is used.
    • If you fill it in with the name of a saved value, the engine ignores the normal field and reads the yes/no from that variable.

    This is mainly for chaining instructions (one instruction saves a value, the next one reads it). If you only work with fixed values, you can ignore these fields.

Clear Cell All .xlsx

Removes a cell entirely — both its content and its formatting.

When to use it: to wipe a cell completely, leaving it as if it had never been touched.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cell is on. Supports @name Sheet1 No
Cell address The cell to clear (A1 style). Supports @name A1 No

Important behavior: deletes the whole cell. If the cell does not exist there is nothing to remove, so the instruction does nothing.


Clear Cell Content .xlsx

Removes a cell’s value (and any formula) but keeps its formatting.

When to use it: to empty a cell while preserving its colors, borders, and number format.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cell is on. Supports @name Sheet1 No
Cell address The cell to empty (A1 style). Supports @name A1 No

Important behavior: clears the value and formula; the cell’s style is left untouched. Does nothing if the cell does not exist.


Clear Cell Format .xlsx

Removes a cell’s formatting but keeps its value.

When to use it: to strip styling from a cell while keeping what it says.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cell is on. Supports @name Sheet1 No
Cell address The cell to reset (A1 style). Supports @name A1 No

Important behavior: removes the cell’s style, keeping its content. Does nothing if the cell does not exist.


Copy Cell .xlsx

Copies one cell’s value and formatting to another cell.

When to use it: to duplicate a cell elsewhere without retyping it.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab both cells are on. Supports @name Sheet1 No
Source cell address The cell to copy from (A1 style). Supports @name A1 No
Target cell address The cell to copy into (A1 style). Supports @name B1 No

Important behavior: copies the value, type, and style from source to target, creating the target cell if needed. Does nothing if the source cell does not exist or the target address is invalid.


Copy Range .xlsx

Copies a rectangular block of cells to a new location.

When to use it: to duplicate a table or block of cells elsewhere on the sheet.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cells are on. Supports @name Sheet1 No
Source start address Top-left corner of the block to copy. Supports @name A1 No
Source end address Bottom-right corner of the block to copy. Supports @name C3 No
Target start address Where to place the top-left of the copy. Supports @name E1 No

Important behavior: copies each cell’s value, type, and style, keeping the block’s shape, and places its top-left at the target start. Empty cells in the source are skipped. Does nothing if any of the addresses is invalid.


Define Named Range .xlsx

Gives a friendly name to a cell or range so formulas can refer to it by name.

When to use it: to make formulas readable — for example =SUM(Sales) instead of =SUM(B2:B10).

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Range name The name to assign. Supports @name MyRange Yes
Sheet name Tab the range is on. Supports @name Sheet1 No
Start cell address Top-left corner of the range. Supports @name A1 No
End cell address Bottom-right corner of the range. Supports @name A1 No

Important behavior: creates the named range; if a range with that name already exists, it is replaced. If the start and end cells are the same, the name points to a single cell. Does nothing if Range name is empty, or if Sheet name does not match an existing tab (which would otherwise create a broken name).


Delete Cell Comment .xlsx

Removes the note attached to a cell.

When to use it: to clear a comment you no longer need.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cell is on. Supports @name Sheet1 No
Cell address The cell whose comment to remove (A1 style). Supports @name A1 No

Important behavior: removes the comment and its on-sheet marker. Does nothing if the cell has no comment.


Delete Named Range .xlsx

Removes a previously defined named range.

When to use it: to clean up a name you no longer use.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Range name The named range to remove. Supports @name MyRange Yes

Important behavior: removes the named range. Does nothing if Range name is empty or no range has that name.


Find Text In Sheet .xlsx

Lists every cell in a sheet whose content contains a piece of text.

When to use it: to locate where a word or value appears, or to count how many cells contain it, and feed that into later instructions.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to search. Supports @name Sheet1 No
Search text The text to look for. Supports @name (empty) Yes
Case-sensitive Whether upper/lowercase must match exactly No No
Case-sensitive (from variable) Reads the case-sensitive yes/no from a saved value (empty) No
Save matching cells to Name under which to save the list of cell addresses found (empty) No
Save count to Name under which to save how many cells matched (empty) No

Important behavior: scans the sheet and collects the addresses (like B4) of cells that contain the search text, then optionally saves the list of addresses and the count. Does nothing if Search text is empty. With Case-sensitive off, upper- and lowercase are treated as the same.


Iterate Rows .xlsx

Publishes the rows of a sheet into a variable, so a For Each can walk them one by one.

When to use it: to go through a sheet row by row — totalling, checking, or copying each row somewhere else.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Sheet the rows are read from. Supports @name Sheet1 No
Use first row as header Yes: the first row names the fields and is not a turn. No: the fields are column1, column2… and every row is a turn true No
Use first row as header (from variable) Reads that yes/no from a saved value (empty) No
Save key Name of the variable that receives the rows. Empty = the instruction does nothing useful (empty) No
Save count key Name of the variable that receives how many rows there are (empty) No

Only the rows the file has: a gap between row 3 and row 7 is not four empty turns. A row that skips a column does not shift the ones after it, because every cell carries its own address.

Important behavior: the turns are a copy taken when the instruction runs: what the loop walks does not change if the body edits the document. To leave a result back in the row, write it by position — but this format is the one exception: Write Cell Value takes a cell address, not a row number, so there is no “(from variable)” field for the Index to feed. Build the address first with Set Text Variable — text D{row} with the Index of the For Each saved as row — and pass the saved variable to Cell address as @cellAddress.

The turn is not the row of the sheet. The Index counts turns: 1 for the first row walked. With a header row and no gaps that means the sheet row is Index + 1, which is what the address above assumes. If the sheet has empty rows in between, that sum is wrong — and nothing reports it, the value simply lands on the wrong row.


Merge Cells .xlsx

Joins a rectangular range of cells into a single larger cell.

When to use it: to make a heading span several columns, for example.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cells are on. Supports @name Sheet1 No
Start cell address Top-left corner of the range to merge. Supports @name A1 No
End cell address Bottom-right corner of the range to merge. Supports @name C1 No

Important behavior: merges the range into one cell. If that exact range is already merged, nothing changes (no duplicate merge is created).


Move Cell .xlsx

Moves a cell’s value and formatting to another cell, emptying the original.

When to use it: to relocate a cell’s content in a single step.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab both cells are on. Supports @name Sheet1 No
Source cell address The cell to move from (A1 style). Supports @name A1 No
Target cell address The cell to move into (A1 style). Supports @name B1 No

Important behavior: copies the value, type, and style to the target, then removes the source cell. Does nothing if the source cell does not exist or the target address is invalid.


Read Cell Value .xlsx

Reads what is in a cell and saves it into a named value for later instructions.

When to use it: to pick up a value from the sheet and reuse it elsewhere in the workflow.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cell is on. Supports @name Sheet1 No
Cell address The cell to read (A1 style). Supports @name A1 No
Save value to Name under which to save the cell’s value (empty) No

Important behavior: reads the cell’s displayed value (resolving shared text automatically) and stores it under the Save value to name. If the cell is empty or does not exist, an empty value is saved. If Save value to is empty, nothing is saved.

A cell holding a formula reads as empty, and the run says so. A formula written by the workflow —=SUM(D2:D11)— is not worked out by the engine but by the spreadsheet program when someone opens the file, so there is no value to read yet. To have that number in the workflow, walk the rows with Iterate rows and add them up with Aggregate list.


Replace Text In Sheet .xlsx

Finds and replaces text across all cells of a sheet.

When to use it: to fix a recurring word or value everywhere it appears in a sheet.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to work on. Supports @name Sheet1 No
Search text The text to look for. Supports @name (empty) Yes
Replacement text The text to put in its place. Supports @name (empty) No
Case-sensitive Whether upper/lowercase must match exactly No No
Match whole cell only Replace only cells whose entire content equals the search text No No
Case-sensitive (from variable) Reads the case-sensitive yes/no from a saved value (empty) No
Match whole cell only (from variable) Reads the whole-cell yes/no from a saved value (empty) No
Save count to Name under which to save how many cells were changed (empty) No

Important behavior: replaces occurrences of the search text with the replacement in every cell, and optionally saves how many cells were changed. With Match whole cell only on, only cells whose entire content equals the search text are replaced (and the whole cell is replaced); with it off, the text is replaced wherever it appears inside a cell. Does nothing if Search text is empty.


Set Cell Comment .xlsx

Attaches a note (comment) to a cell, with an author name.

When to use it: to leave an explanation or reminder on a cell.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cell is on. Supports @name Sheet1 No
Cell address The cell to annotate (A1 style). Supports @name A1 No
Comment text The note’s text. Supports @name (empty) No
Author name The name shown as the note’s author. Supports @name Author No

Important behavior: adds the note to the cell and shows the usual comment marker. If the cell already has a comment, it is replaced.


Unmerge Cells .xlsx

Splits a previously merged range back into individual cells.

When to use it: to undo a merge.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cells are on. Supports @name Sheet1 No
Start cell address Top-left corner of the merged range. Supports @name A1 No
End cell address Bottom-right corner of the merged range. Supports @name C1 No

Important behavior: removes the merge for that exact range. Does nothing if that range is not currently merged.


Write Cell Value .xlsx

Writes a value into a single cell.

When to use it: to fill in a cell with text, a number, or a date.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab the cell is on. Supports @name Sheet1 No
Cell address The cell to write to (A1 style). Supports @name A1 No
Value The value to write. Supports @name (empty) No
Treat value as a date Store the value as a date instead of text/number No No
Treat as date (from variable) Reads the “treat as date” yes/no from a saved value (empty) No

Important behavior: writes the value into the cell, creating the cell if needed. The value is stored as a number if it looks like one, otherwise as text; turn on Treat value as a date to store it as a date when the text can be read as one. Does nothing if the cell address is invalid.


Write Range Values .xlsx

Fills a block of cells from a single delimited list of values.

When to use it: to load a small table into the sheet in one instruction.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to write to. Supports @name Sheet1 No
Start cell address Where the block begins (its top-left cell). Supports @name A1 No
Values The values, separated by the column and row separators. Supports @name (empty) Yes
Column separator Character(s) that separate cells within a row. Supports @name , No
Row separator Character(s) that separate rows. Supports @name ; No
Fill by row Whether values fill left-to-right then down (on) or top-to-bottom then across (off) Yes No
Fill by row (from variable) Reads the fill-by-row yes/no from a saved value (empty) No

Important behavior: splits Values into rows (by the row separator) and cells (by the column separator) and writes them starting at the start cell. With Fill by row on, values fill left-to-right then down; with it off, they fill top-to-bottom then across (the block is transposed). Each value is typed automatically (number or text). Does nothing if Values is empty or either separator is empty.


This documentation is the help of the application, and it comes underCreative Commons Attribution 4.0.