Escribal
Back to Docs

More

Flow

This group holds the three things a workflow can contain that are not instructions on a document: a block that repeats, a block that runs only when a condition holds, and a note for whoever reads the workflow later. They belong to no format and work the same in all of them. A workflow can do without all three — they are what turns a fixed list of instructions into one that follows the data it is given.

Prerequisite: none of the three needs a document open. A repeat does need a list saved earlier — by a reading instruction, by Group and aggregate, or by any instruction with a Save… in field that holds a list — and a condition usually compares something saved earlier as well.

These concepts are explained here once.

  • Two of them are blocks, not lines. A repeat and a condition contain other instructions, which run as part of them, and either can be nested inside the other as deep as the work needs. A note goes anywhere an instruction goes, inside a block included.
  • Their key fields hold a name, not a value. Array key, Item key, Index key and Save count key name a saved value, the same way a Save… in field does, so they are written without the @. The @ belongs in the instructions inside the block, which read that name in their text fields: a repeat with line in Item key is read as @line by everything inside it.
  • A condition is the other way round. Left and Right are ordinary text fields, so @name in them is replaced by the value before the comparison happens.
  • A name can reach inside what it holds. invoice.lines reaches the list that sits inside the record saved under invoice, and a number in the path is a position counting from 1. It works in Array key and on both sides of a condition.
  • Where the instructions inside a block go: on the canvas, mark a line of the block — one of its instructions, or its start or end line — and what you add next goes in there. Marking the block’s own card adds the next instruction after the whole block, which is how you carry on past it.

For Each

Runs the instructions inside it once for each item of a saved list.

When to use it: whenever a part of the document repeats — a paragraph per customer, a row per order line, a slide per product, a file per department. The list is whatever an earlier instruction saved: the rows of a CSV or of a sheet, the elements of a JSON array, the rows of a database query.

Parameter Meaning Default Required
Array key The name the list was saved under; a path reaches inside a saved record (invoice.lines) (empty) Yes
Item key The name the current item takes inside the block, read there as @ plus this name (empty) Yes
Index key The name the turn number takes inside the block, 1 for the first item (empty) No
Save count key The name the number of turns is saved under once the block ends (empty) No

Important behavior: Item key is what makes the block work — left empty the block does nothing at all, because the current item would have no name to be read by. When Array key names something that is not a list — a single value, or a name nothing saved — no turn runs and the run says so, instead of finishing green with the repeated part missing.

A name that holds a group of lists — what Group Array By Field .json leaves behind — is walked too, one turn per group: @item.name is then the name of the group and item.value its list of records, which a repeat inside this one goes over in its turn.

The item and index names are put back as they were when the block ends, so a repeat inside another one does not disturb the one around it. Save count key is written at the end and counts turns, so an empty list saves 0; a block that ran no turns because the name held no list writes nothing there.

If

Runs the instructions in its first block only when the comparison holds, and those in its otherwise block when it does not.

When to use it: when part of the document depends on the data — a warning paragraph only for overdue invoices, a discount row only above a certain amount, a slide only when there is something to put on it. Inside a repeat it decides turn by turn.

Parameter Meaning Default Required
Left The value on the left of the comparison. Supports @name (empty) Yes
Operator How the two are compared: ==, !=, >, <, >=, <= or contains == Yes
Right The value on the right of the comparison. Supports @name (empty) No

Important behavior: ==, != and contains compare the two sides as text, and every comparison tells upper from lower case: Total and total are different values. contains asks whether Left holds Right somewhere inside it, so an empty Right is inside everything and the condition is always true.

>, <, >= and <= only mean something between numbers: if either side is not one, neither block runs — not the otherwise one either — and the run says so, because guessing which way a comparison of two words should go would be a decision made on your behalf. Write those numbers with a decimal point (0.5), whatever the language of your computer; 0,5 is not a number at all. A yes/no value saved earlier reads back as true or false in lower case, so that is what to compare it with.

The otherwise block is optional: left empty, a condition that does not hold simply adds nothing.

Note

A block of text that does nothing at all, kept in the workflow for whoever opens it later.

When to use it: to say what a stretch of the workflow is for and why it is the way it is — the thing the instruction names alone cannot say. You, in six months, or whoever you send the file to.

Parameter Meaning Default Required
Text The note itself, written on its card in the canvas. It is never read by the run (empty) No

Important behavior: a note is the one thing in the program without a properties panel: you click its card and write in it, right where it is read. It is also the one text written over as many lines as you like, and the one that does not read @ values: @total in a note stays those six characters, because a note is meant for a person and not for the program.

It is not one of the steps: it has no number on the canvas, the progress line does not count it, and it never produces a remark of its own. It travels in the saved file like everything else, and it goes anywhere an instruction goes — inside a repeat, or in either block of a condition.

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