How the program works

What this program is

This is a desktop application that generates documents by following a workflow: an ordered list of instructions that you assemble in a visual editor, without programming. You build the workflow; the program runs it for you, executing the instructions one by one, from top to bottom. Each instruction does one small, well-defined thing (write a paragraph, insert a comment, add a slide, create a chart…), and the combined sequence produces the finished document.

A workflow always follows the same shape: create → modify → save

1. Create (or open) a document. Every workflow begins with an instruction that creates a new document (for example Create text doc, Create spreadsheet, Create presentation, Create PDF…) or opens an existing one. This is where you choose the file name and folder where it will be saved. Both are needed to save it: if either is missing, the workflow stops when it reaches the save and says so, instead of writing a file with no name into whatever folder the program happened to start in. A scratch document you close with Close document never gets written, so it never needs them. Every format except PDF can also be opened from a file you already have: each one has an Opening group (Open text doc, Open spreadsheet, Open presentation, Open txt file, Open Markdown, and for JSON and CSV/TSV the Opening and Reading instructions). A PDF can only be created, because a finished PDF cannot be turned back into an editable document.
2. Modify it. All the other instructions act on that open document: they add, change, or remove content. These instructions do not open or save files on their own; they simply work on the document that is already open.
3. Save it. At the end, a save instruction writes the document to disk. The document stays open in memory during the whole workflow and is written out only once, at the end.

Important: because nothing is written until the save, if the workflow fails partway through, nothing is saved — the document is discarded and you will not end up with a half-finished file. Either the whole workflow succeeds, or the file is not created.

Supported document formats

Each format has its own set of instructions. The instruction names end with the format they belong to so you can tell them apart:

Working with more than one document at once

You are not limited to a single document. Every instruction has a Document field that says which open document it acts on:

• If you leave it empty, the instruction uses the current document (the last one you created, opened, or selected).
• If you fill it in with a name (the same name you gave the document when you created it), the instruction acts on that document specifically.

This lets you, for example, create a spreadsheet and a text document in the same workflow and add content to each one, or copy information from one into another.

Four instructions in the Document menu act on the open documents themselves, and the first three take just a Document name:

• Save document — writes that document to disk and closes it, before the end of the workflow.
• Set current document — makes that document the current one, so the instructions that follow can leave their Document field empty.
• Close document — discards that document without saving it. Use it for a scratch document you only needed along the way; anything it contained is lost.
• Set save encoding — chooses the character set a text document (plain text, Markdown, JSON or CSV/TSV) is written with, for a program at the other end that does not expect UTF-8.

A name can only be in use by one document at a time. If an instruction tries to create or open a document under a name that is already in use, the workflow stops and tells you so, instead of quietly throwing away the first document and everything you had put into it. Save document and Close document both release the name, so reusing one on purpose works: save (or close) the first document, and the name is free again. This matters most inside a repeat: if you create one document per turn, either give each one a different name (using a variable) or save it before the next turn begins.

Passing data between instructions (variables)

Instructions can leave values behind for later instructions to reuse, like a shared notepad. There are three related mechanisms:

• Saving a result: many instructions offer a Save… in field. If you type a name there, the instruction stores its result (a count, an identifier, a piece of text…) under that name. If left empty, nothing is saved.
• Dynamic values (@name): in any text field you can type @ followed by the name of a value saved earlier, and it will be replaced by that value. For example, @customerName in a text field inserts whatever was saved under customerName. To write a text that really starts with an at sign, type it doubled: @@team produces @team. (Only at the beginning of the field: an at sign anywhere else is written as it is.)
• “From variable” fields: the @name trick only works in text fields. So that a numeric field or a yes/no field can also take its value from a saved value, those fields have a companion “from variable” field. Leave it empty to use the value you typed; fill it in with a saved name to use that value instead. This is mainly for chaining instructions (one instruction saves a value, the next one reads it).
• One field of a saved value (@name.field): when what was saved is a whole record — the usual case inside a For each over a list of rows, lines or people — add a dot and the name of the field: @line.price writes the price of that line, not the whole line. It goes as deep as you need (@invoice.lines.1.price), a number is a position counting from 1, and it works the same in a “from variable” field and in a If condition. The name on its own (@line) means the whole record, which in a text field is written out as the data it holds. If the field name is not one the record has, the workflow says so and lists the fields it does have. It does not stop: the value is read as empty and the run carries on, so the report comes out with holes and the message tells you why. This is what catches the usual breakage of a workflow you run every month: the file you export renames a column and everything that read it goes blank. A field the record does have but which comes in empty is a different thing — missing data, not a wrong name — and it is not reported.

A related convention: instructions that act on a specific element by its identification number accept -1 to mean “all” of them at once.

A reading that finds nothing leaves the saved value as it was. When an instruction that reads (a cell, a field, a piece of text) does not find what it was asked for, it saves nothing — and it does not empty the name either, so whatever was saved under it stays. On its own that is harmless; inside a For Each that reuses the same names on every turn, it is not: the turn that finds nothing keeps the values of the turn before, and the document repeats them instead of leaving a gap. A repeated line reads like good data, which is why it is worth knowing. When a value may be missing, give the name a known value at the start of each turn — Set text variable with an empty text — and read after it.

Filling in colour and file fields

Two kinds of field give you a helper next to the box, so you do not have to type the value by hand. The box itself always stays editable, so everything described above still works in them — including @name and leaving them empty.

• Colour fields take a six-digit hex code without # (for example FF0000 for red). Next to the box there is a colour swatch: click it to pick a colour visually and the code is filled in for you. The swatch is dimmed when the box holds something that is not a plain code — because it is empty, or because it holds an @name. Remember that in some instructions an empty colour field means “no colour” (no fill, no border), which is why the box is never filled in automatically.
• File fields (a source image, a presentation to copy a theme from, a CSV to read…) have a browse button that opens a file chooser filtered to the extensions that instruction accepts. Fields that name a file the instruction is going to write open a save dialog instead, so you can name a file that does not exist yet.

Long texts have room to be written. Every text field has an expand button at its end that opens the field as a large box in the middle of the window, for a paragraph that does not fit comfortably on one line. What you write there is kept when you accept — with the Accept button, with Enter, with Escape, or by clicking outside the box — and only Cancel throws it away. The value stays a single line: the box is for writing comfortably, not for writing several lines, and line breaks pasted into it become spaces.

Writing numbers

A decimal number is written with a dot: 4.5, not 4,5. Number boxes in the program let you type the number directly and take care of this for you, so this only matters where a number arrives as text: a value you stored in a variable and read back with a “from variable” field, or a number that came out of a spreadsheet or a data file.

A number written with a comma is not read as a number at all. The program does not guess whether 4,5 means four and a half or forty-five — it uses the field’s default value instead, and a decision (If) that compares sizes runs neither of its two branches. So if a measurement comes out wrong or a comparison never happens, check whether the value behind it uses a comma. The same applies to grouping: write 1234, not 1,234.

Writing yes/no values

A yes/no value stored in a variable reads back as true or false, in lower case — the same words a data file uses. So a decision (If) that checks one is written @delayed == true. Capitalised True does not match: every comparison in the program tells upper from lower case. The same value put into a text field writes the word true into the document.

Naming a sheet

Almost every spreadsheet instruction asks which sheet to work on, and they all arrive with Sheet1 filled in — the name a spreadsheet app in English gives the first sheet of a new file. A Spanish one calls it Hoja1, and a sheet somebody renamed can be called anything, so the name in the box is often not one the file has. When that happens the instruction does nothing and says so, listing the sheets the file really has; it used to do nothing without a word, and the workflow carried an empty document to the end as if all had gone well. If you do not know the names beforehand, List Sheet Names .xlsx saves them into a variable you can read.

Where a new instruction lands

The canvas is a list of lines. Most of them are instructions; each list also has a line for its start and one for its end, and those two only show themselves when the pointer is on them or when they are the marked one.

Click a line to mark it. Marking does two things at once: the panel on the right shows that instruction’s fields, and the next instruction you add goes in right below it and becomes the marked line in its turn. So instructions keep cascading downwards from wherever you are pointing — and to add one at the top of a workflow of three hundred, you mark the line at the start and add it there.

With nothing marked, an instruction goes at the end of the workflow, which is what happens on an empty canvas.

Two things follow from the rule, and they are worth knowing:

• A loop or a condition is one line like any other. Marking its card adds the next instruction after the whole block, not inside it. To put something inside, mark a line of the branch you want — one of its instructions, or the start or end line the branch has of its own. An empty branch has a single line, and that is the one to mark.
• Deleting the marked line moves the mark up, to the line above it. So the place you just emptied is the place the next instruction goes into: deleting an instruction and adding the right one is two steps and no reordering.

Paste follows the same rule as adding. Duplicate is the exception, and on purpose: a copy appears immediately below its original, wherever that is.

Changing what is already on the canvas

Instructions can be undone, moved, copied and deleted, from two places.

The Edit menu, on the marked line, with a shortcut for each entry: Undo (Ctrl+Z) and Redo (Ctrl+Y) go back and forth through everything you have done to the workflow — adding, deleting, moving, and the values typed into the panel; Copy (Ctrl+C) takes the marked instruction, and a whole block with everything inside it; Paste (Ctrl+V) puts it back in; Duplicate (Ctrl+D) copies it in place.

The buttons on the instruction itself, which appear when the pointer is over its line, and stay in view on the marked one and on the three that contain other instructions: move up, move down, duplicate, copy and delete. They are the same operations, on the line you are pointing at rather than the marked one.

Deleting an instruction leaves the mark on the line above, so what you add next takes the place of what you just removed — replacing one instruction with another is two steps and no reordering. An undo puts the deleted instruction back with everything it contained.

Repeating instructions, making decisions and leaving notes

Beyond plain sequences, a workflow can repeat blocks of instructions, make choices, and carry notes for whoever opens it:

• Repeat for each item (loop): you can run a block of instructions once for each item in a saved list. For example, for each name in a list of customers, insert a paragraph with that name. Inside the block, the current item is available as a value you can reference with @. The loop has four fields: Array key (the saved list to go through), Item key (the name the current item takes inside the block — required; left empty the loop does nothing), Index key (optional: the name under which the turn number is available, 1 for the first item, so you can number rows or name files sheet-@i) and Save count key (optional: the name under which the total number of turns is saved when the loop ends). Item and index names go back to what they were when the block finishes.

  A loop can also go over a group of named lists — what Group Array By Field .json leaves in Save group key, one entry per group. Each turn is then one group: @item.name is the group’s name and item.value is its list of records, which an inner loop can go over in its turn. And when the name you give it holds neither a list nor a group of them — a single value, or a name nobody saved — the loop says so instead of quietly running its block zero times.

• Conditions (if / otherwise): you can run a block of instructions only when a condition is met — comparing two values as equal, different, greater than, less than, or checking whether one contains the other. You can also provide an “otherwise” block that runs when the condition is not met. When the comparison is numeric, write the numbers with a decimal point (0.5), whatever the language of your computer. All the comparisons tell upper from lower case: Total and total are different values. Greater than and less than only make sense between numbers: if either side is not one, neither block runs — not the “otherwise” one either.

• Note: a block of text that does nothing at all. It is there so that whoever opens the workflow later — you, in six months, or the person you sent it to — understands what a stretch of it is for. It is saved in the file along with everything else and it is the one text in the program that is written over as many lines as you like: a note is read, not put into a document.

  A note is not one of the steps: it has no number on the canvas, the progress bar does not count it, and it produces no warnings. And it is the one text field that does not read @ values: @total written in a note stays the six characters @total, because a note is meant for a person, not for the program. Put one wherever an instruction goes — inside a loop, or in either block of a condition.

  It is also the one thing on the canvas with no properties panel: click the note and write in it, right where it is read. Its text is all there is to it.

Loops and conditions can be nested inside one another to build more elaborate workflows, and a note goes anywhere inside them.

Saving a workflow, and opening it again

A workflow is a file of its own, ending in .scriba, and the File menu is where it is kept: New file starts an empty one, Save writes it back where it already lives, Save as asks for a name and a folder, and Open brings one back. Saving the workflow is not the same as producing the documents: the .scriba holds the list of instructions, and the .docx, .xlsx or .pdf it describes appear when you run it.

It is meant to be passed around. A .scriba carries the whole workflow — every instruction, every field, the notes — in one file you can send to somebody else, who opens it here and runs it.

Your workflows work on other computers. When a workflow is saved, every folder and file path stored in it has your user name replaced by a marker, and the marker is turned back into the right user name when the file is opened. So a workflow saved by one person that reads images from their Documents folder keeps working for a colleague whose user folder has a different name, as long as the file is in the same place relative to their user folder.

What it never carries is a password. If the workflow reads from a database, the file holds only the Connection key — a name — and the server, the database and the password are asked for on the machine that runs it, every time it runs.

Running a workflow, and what it says back

Run is in the top bar, and it always runs the workflow from the file: if there is work that is not on disk it is saved first, and a workflow that has never been saved runs from a temporary copy, so trying one out does not force you to pick a name and a folder first.

While it runs, the bar reads Running… 7/23 · Insert Text .docx, so you can see which step it is on; a second run cannot start on top of it, and Stop ends the one that is going. Pulling the plug is not a failure and is not reported as one: nothing is written until the end, so nothing is left half done. If any instruction of the workflow reads from a database, this is the moment the connection details are asked for.

When it ends, the status box at the bottom of the right-hand panel says what happened. It is a headline and a list: the headline is the outcome — the files that were written, or the error that stopped everything — and under it goes one line for each thing the run remarked on the way. Click the box to open it; the number in its header counts what is waiting inside, so you can tell a clean run from one with ten remarks without opening it.

Two colours, and they mean the same thing in the box and on the canvas:

• Amber — something was skipped. The run carried on, but one instruction could not do what it was asked: a sheet name the file does not have, a style the document never defines, an average over values that were not numbers. This is the one worth reading, because the workflow still ends in green and the document still gets written — with a piece of it missing.
• Red — the step that stopped the run. There is at most one, and it is also the headline. When a run stops this way no file is written at all, not even the part that had already been built.

Those same two colours land on the canvas, on the dot and the number of the step they belong to, so you can go from a message to the line it is talking about. A repeat or a condition gets a dot in its corner when what the run said happened inside it, because a long block can hide the step that earned it off the bottom of the screen. A step the run had no comment on is painted as it always is, so a workflow that has never run and one that ran cleanly look the same.

The marks stay while you fix things. They are what that run said, so editing a step does not wipe them; they go when the next run starts, or when another file is opened.

Letting an assistant use the program

The engine that does the work in this program can also answer an AI assistant — the one you already use, in its own window — so that you can ask for a document in your own words instead of assembling the workflow yourself. Assistant, in the top bar, shows what to paste into your assistant’s configuration, with the path already filled in.

Connected, an assistant can read every instruction this program has, write a workflow and check it, save it as a .scriba you can open here, and run it to produce the documents. Two things stay with you: a workflow that reads from a database it will not run, because the connection is asked for in this window; and nothing is written into your assistant’s configuration by this program — it shows you the lines and the pasting is yours.

The assistant only knows what the workflow tells it, so names that are already inside a file — the name of a sheet, of a column, of a style, a path — are yours to give it: it cannot open your files to look, and a guessed name does not fail, it quietly does nothing.