Flows and automation

A flow is a directed graph: nodes with wires between them, walked from one starting point. It is deliberately not a script that loops. Four rules fix the shape, and the editor refuses to deploy a drawing that breaks one of them, naming the node that is wrong.

• Exactly one trigger. The trigger node is the only way in, and it decides which variables exist in the rest of the drawing.
• No cycles. A wire that leads back to a node it came from is refused, because a flow has no way to wait: a loop would simply never end.
• Every node has to be reachable from the trigger. A node hanging loose is a mistake you cannot see on a screenshot, so it is a mistake at deploy time.
• Branches are walked one after another, never side by side. Two branches at the same time would write into state at the same time, and the outcome would depend on timing.

The editor is a canvas and there is no second one. A new flow opens on it straight away, and a flow that was a straight list of steps opens as a straight chain of nodes.

• The palette holds the twelve node types. Click one to drop it on the canvas, or drag it to the spot you want.
• Drag a node by its header to move it. Everything else on the node is a control, so it does not start a drag.
• A wire runs from an output dot to an input dot. Drag from the one to the other, or click the output and then the input. Both do the same thing, and the second one is the keyboard path.
• Let a wire go in empty space and nothing happens. To remove one, select it and press Delete, or use the cross that sits on it.
• Zoom between 50 and 200 percent, use Fit to see the whole drawing, and drag the background to pan. There is no minimap.

Twelve types, and the list is short on purpose. Every type is a panel, nine translations, a branch in the runner and a row in the truth table, so a type that carries its weight is worth more than a type that almost does.

Five moments, and the one you choose is not only when the flow runs. It is also which variables exist, which the picker offers you, and which the platform refuses to save. A path that cannot exist at that moment is an error while you save it, not an empty string in the middle of a run.

Every value a flow can read comes from one of these groups. The picker in the editor shows the ones that exist at your trigger and nothing else. Reading an unknown path is an error and never a blank: a wrong assumption should be loud.

A set node writes into state. Its value is literal text, unless you tick the expression box; then it is read as a template with the variables of this run filled in.

• The tick is deliberate. A value that happens to hold two braces, a piece of Ansible or a Helm fragment, keeps meaning what it said. Nothing changes meaning because of a change nobody asked for.
• The language is output only. Two braces and a path, and nothing else: no assign, no capture, no loop, no include. What stands on the canvas is what comes out, with the values filled in.
• There are 46 filters: text, numbers, dates, the few list filters that produce text, and the platform's own quote, ini and ipoctet. The picker in the editor lists them. Two families are missing on purpose, the ones that roll dice and the ones that hand back an object where you wanted a word.
• Secrets are not available here, and neither are snippets. What a set node writes ends up in the record of the run, and a secret has no business being there.

A flow can stop and wait for a person, and it can walk the same nodes more than once. Both were impossible until a run could be parked and woken up again; that queue exists now.

• An approval node stops the run, writes a request and notifies the account. Answering it needs a separate right, so the person who wrote the flow is not automatically the person who signs it off.
• Every request carries a deadline and what happens without an answer: continue as approved, continue as rejected, or end the run as not applicable. There is no fourth choice, because a run that waits forever is a run nobody hears about again.
• For each walks its loop output once per item of a list. Inside the loop, state.loop holds the current item, its position and the total.
• Nothing from outside a loop may hang on the nodes inside it. Those nodes run again on every round, and a notification wired to both would write one message per round.
• An approval step can send email as well. That mail goes only to the members who may decide on approvals, not to everyone who can see flows, and the panel notification is written either way.

A run that stands still is not a run that failed. Three things can park one, and all three use the same queue: an approval, a long pause, and a subflow whose child is itself waiting.

• A delay of half a minute or less simply waits inside the request that started it, which is what you want when you are giving an agent a moment. Anything longer parks the run, so the order that started it finishes right away and the rest of the flow follows later.
• A subflow runs another flow of this account as one step. Its outcome decides the output: a child that succeeded or found nothing to do continues over OK, a child that failed over Error. The status, the run and the flow name stand in state.subflow.
• A flow may never reach itself, directly or through another flow. That is checked when you deploy, and the message names the chain it found.
• Flows may call each other at most three levels deep. Because flows are edited on their own, that limit is checked twice: once when you deploy, and once while the run is actually walking.

A webhook endpoint gives an outside system a URL of its own. It posts JSON, the flow behind the URL runs, and the answer is a bare status code. Endpoints live under Scripts, on the Webhooks tab, and are separate objects: the same endpoint can be pointed at another flow without the sender noticing.

1. 01Create the endpoint and give it a name you will recognise later. The URL is generated for you and cannot be chosen: 32 random characters, which is 160 bits, so guessing one is not a strategy.
2. 02Pick how the sender proves who it is, and copy the secret. It is shown once and never again; lose it and you regenerate, which also gives you a new URL.
3. 03Point the endpoint at a flow whose trigger is a webhook. The endpoint may exist before the flow does, and until then a request is accepted and answered with a 202 that starts nothing. That is the order in which people actually build this, so it is not treated as a mistake.

The signature is the word sha256, an equals sign, and the HMAC-SHA256 of the exact bytes of the timestamp, a dot, and the body, in lower case hexadecimal. It goes in X-Provibr-Signature, and the timestamp itself goes in X-Provibr-Timestamp as whole seconds since the epoch.

A request whose timestamp is more than 300 seconds old, or in the future, is refused with a 401. The window is a real rule and not decoration, because the timestamp is inside the material that was signed: a captured request cannot be replayed tomorrow with a fresh timestamp pasted over it.

Signing a request is one line of openssl. This example posts a small object; the shell text stays English on purpose, so it matches what your terminal shows you.

# Sign the raw body together with the timestamp, then post it.
SECRET="$PROVIBR_WEBHOOK_SECRET"
BODY='{"reason":"maintenance","attempt":1}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -sS -X POST 'https://app.provibr.com/api/hooks/flows/<your-slug>' \
  -H 'Content-Type: application/json' \
  -H "X-Provibr-Timestamp: $TS" \
  -H "X-Provibr-Signature: sha256=$SIG" \
  --data "$BODY"

Every request leaves a receipt, accepted or not: the outcome, the status that went back, the source address in full, and how many bytes were really read. The body is never kept. Receipts are removed after 90 days, sooner than the runs themselves, because a source address is personal data belonging to somebody who is not our customer.

Two questions that look alike have two different answers here. Who changed what, and when, is a revision. What did this particular run actually walk, is a copy kept on the run itself. A snapshot cannot answer the first question and a revision cannot answer the second, so both exist.

• Every deploy writes a revision, including a deploy that changed nothing. The number counts up per flow and is never reused.
• The difference between two revisions is a readable list and not raw JSON: a node added, removed or changed with the fields named, a wire added or removed. Where a node sits on the canvas is not a change.
• Restore does not rewind. It writes the old drawing back as a new revision on top of the history, with a note saying which one it came from.
• Every run keeps the drawing it walked. Editing a flow afterwards never rewrites what an older run did.
• A run holds a row per node it visited, with the outcome and the output it left through, and a row per node it did not visit with the reason. Not visited is a fact worth writing down, not an absence.
• The run list filters on trigger, status and revision, and exports to CSV. The export stops at 5000 rows and says so inside the file rather than quietly ending.

Script templates keep a history of their own, next to this one: every saved version of the body, and a line by line difference between any two of them.