Escribal
Back to Docs

Spreadsheet

Sheets

This group works with the sheets (tabs) of a spreadsheet as objects: adding a new one, renaming it, deleting it, duplicating it, changing its order, hiding it, colouring its tab, and reading the list of sheet names. Every other spreadsheet instruction works inside a sheet chosen by name; this group is the one that creates and organises those sheets.

Prerequisite: before using any of these instructions, the workflow must already have an XLSX spreadsheet created or opened (with Create spreadsheet or Open spreadsheet). A newly created spreadsheet starts with a single sheet named Sheet1.

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. If the document doesn’t exist, the instruction simply does nothing.

  • Sheet names are matched ignoring capitals: sales, Sales and SALES all find the same sheet. For the same reason, two sheets cannot have names that differ only in capitals.

  • Position: where the sheet sits among the tabs, counting from 1 for the leftmost one. -1 (or any number past the last tab) means last.

  • Dynamic values (@name): in a text field (sheet name, new name, tab colour) you can type @ followed by the name of a value saved earlier in the workflow, and it will be replaced by that value.

  • Saving a result: List Sheet Names has Save list key and Save count key fields. If you leave them empty nothing is saved; if you fill them in, the result is stored under that name for later instructions to use.

  • “From variable” fields: the @name trick only works in text fields. The numeric field (Position) and the yes/no field (Visible) each have a companion “from variable” field:

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

    This is mainly for chaining instructions. If you only work with fixed values, you can ignore these fields.

Add Sheet .xlsx

Adds a new, empty sheet to the spreadsheet.

When to use it: to build a workbook with more than one tab — one sheet per month, per region, or per report section.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Name of the new tab. Supports @name Sheet2 Yes
Position Where to place it, counting from 1. -1 = last -1 No
Position (from variable) Reads the position from a saved value (empty) No

Important behavior: if Sheet name is empty, nothing happens. If a sheet with that name already exists (ignoring capitals), nothing happens — the existing sheet is left untouched rather than duplicated. The new sheet is empty and can be written to immediately by any other spreadsheet instruction using its name.

Copy Sheet .xlsx

Duplicates a sheet, with all of its content, under a new name.

When to use it: to reuse a prepared layout — copy a template tab once per client and then fill each copy in.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to copy. Supports @name Sheet1 No
New name Name of the copy. Supports @name (empty) Yes
Position Where to place the copy, counting from 1. -1 = last -1 No
Position (from variable) Reads the position from a saved value (empty) No

Important behavior: if New name is empty, if no sheet has the source name, or if the new name is already in use, nothing happens. The copy includes the content written so far in the workflow, not the state the file had on disk.

Delete Sheet .xlsx

Removes a sheet and everything in it.

When to use it: to drop a working tab before saving the final workbook.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to delete. Supports @name (empty) Yes

Important behavior: if Sheet name is empty or no sheet has that name, nothing happens. The last remaining sheet is never deleted: a spreadsheet with no sheets cannot be opened, so in that case the instruction does nothing.

List Sheet Names .xlsx

Reads the names of every sheet, in tab order, and saves them for later instructions.

When to use it: to loop over the sheets of a spreadsheet that was opened from disk, or to check how many there are before deciding what to do.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Save list key Name to save the list of names under (empty) No
Save count key Name to save how many sheets there are under (empty) No

Important behavior: this instruction reads only — it changes nothing in the document. If both save fields are empty, nothing is saved and the instruction has no effect. Hidden sheets are included in the list.

Move Sheet .xlsx

Changes the order of the tabs by moving one sheet to another position.

When to use it: to put a summary tab first, or send a working tab to the end.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to move. Supports @name Sheet1 No
Position New position, counting from 1. -1 = last 1 No
Position (from variable) Reads the position from a saved value (empty) No

Important behavior: if no sheet has that name, nothing happens. A position past the last tab is treated as last, so it is never an error.

Rename Sheet .xlsx

Changes the name of an existing sheet.

When to use it: to give the default Sheet1 a meaningful name, or to name a tab after a value computed earlier in the workflow.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to rename. Supports @name Sheet1 No
New name The new name for the tab. Supports @name (empty) Yes

Important behavior: if New name is empty, or no sheet has that name, nothing happens. If another sheet already uses the new name, nothing happens — a spreadsheet cannot hold two sheets with the same name. Formulas written earlier that mention the old sheet name are not rewritten, so rename before writing cross-sheet formulas.

Set Sheet Tab Color .xlsx

Colours the tab of a sheet.

When to use it: to mark tabs by status or by section, so the workbook can be read at a glance.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to colour. Supports @name Sheet1 No
Tab color Colour in 6-digit hex, no # (e.g. FF0000). Supports @name (empty) Yes

Important behavior: if Tab color is empty, nothing happens — the tab keeps whatever colour it had. If no sheet has that name, nothing happens.

Set Sheet Visibility .xlsx

Shows or hides a sheet without deleting it.

When to use it: to keep intermediate calculation tabs out of the reader’s way while the formulas that use them keep working.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Sheet name Tab to show or hide. Supports @name Sheet1 No
Visible Yes = visible, No = hidden Yes No
Visible (from variable) Reads yes/no from a saved value (empty) No

Important behavior: if no sheet has that name, nothing happens. The last visible sheet is never hidden, because a spreadsheet whose sheets are all hidden cannot be opened. A hidden sheet keeps its content, and the formulas that read it keep working.

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