Flow Markdown Specification (flow.md Rulebook)
This document establishes the official syntax rules and structural guidelines for flow.md, the file format of every Kinenix flow.
1. Vision & Core Principles
A Kinenix flow is one file, flow.md: the file people read, the file an AI assistant writes, and the file Kinenix runs.
- Readable: Markdown with headings and bullet points, readable on GitHub, in an editor, or in a pull request diff.
- Written well by AI: the step headings and
- **parameter:** valuebullets are easy for language models to produce. In a comparison on thebot_fx_raterequirement, a local 7B model wrote validflow.mdmore reliably than the same flow in YAML, whose quoting rules clash with${...}expressions (benchmark). - Checked before it runs:
kinenix validate,kinenix run, and the worker parse the file, then report unknown actions and parameters, lines the parser ignores, and step headings without an action, with line numbers and suggestions.
There is no separate JSON file to keep in sync. kinenix run and kinenix-worker run read flow.md directly and compile it in memory on every run; subflows (flow.call) work the same way. To inspect the compiled form, run kinenix compile <bundle>, which prints it as JSON (validated against flow.schema.json) without writing any file next to flow.md.
Flows written as flow.json by Kinenix 0.2.0b3 or older are not run; kinenix export-md <bundle> converts one into flow.md once. Files with a UTF-8 BOM (written by Windows PowerShell 5 and some editors) are read correctly.
2. The 5 Golden Rules of flow.md
To ensure 100% deterministic compilation without requiring massive cloud LLMs, every flow.md must strictly adhere to the following 5 rules:
Rule 1: Document Header & Metadata (Title, Description, Variables)
Rule 2: Step Declarations with Mandatory Action Anchors in Parentheses
Rule 3: Key-Value Action Parameters as Bullet Points
Rule 4: Standard Indentation for Nested Sub-steps (Loops & Conditions)
Rule 5: Variable Interpolation Syntax (${config.*}, ${var.*})
Rule 1: Document Header & Metadata
Every flow.md must start with a Level 1 Heading (#) denoting the Flow Name, followed by optional blockquotes for description and version, and an optional ## Variables section.
Syntax
# [Flow Name]
> Description: [Brief summary of business intent]
> Version: [Semantic version, e.g. 1.0.0]
> Requires: [Kinenix version needed, e.g. kinenix>=0.2.0b4]
## Variables
- `variable_name`: [initial_value]
> Requires: is optional. A Kinenix older than the version named refuses to run the flow with a message to upgrade. Flows that use ## On Error or ## Finally need > Requires: kinenix>=0.2.0b4 (section 3.2).
kinenix validate reports a missing or too low > Requires: when the flow uses something an older Kinenix would run wrongly instead of refusing, and names the version to require:
| Version | Features |
|---|---|
| 0.2.0b4 | ## On Error, ## Finally, inherit_config on flow.call |
| 0.3.0b1 | Expressions in ${...}, and / or / not in conditions |
| 0.4.0b1 | on_error: next_item |
| 0.5.0b1 | match or search_text on web.choose |
| 1.0.0 | fail_on_error: true on http.request, round() (halves round away from zero) |
| 1.1.0 | List functions and comparisons in ${...}, logic.break, logic.next, times on logic.loop, on_error: ignore, error_message, on_item_error and rule_error on web.get_list and web.get_table, category: system on flow.fail |
Example
# RPA Challenge Solver
> Description: Automatically complete 10 rounds of RPA Challenge form submission using Excel data.
> Version: 1.0.0
## Variables
- `non_programmers`: []
- `processed_count`: 0
Rule 2: Step Declarations & Mandatory Action Anchors
Each step must be declared as a Level 3 Heading (###) and MUST include the exact registered action name in parentheses ([action_name]).
Syntax
- Step Number / ID: Can be a number (
1.) or explicit ID (step_1.). If a number is given, the compiler automatically assignsstep_1,step_2, etc. - Action Anchor: The action name enclosed in parentheses (e.g.
(web.open),(excel.read),(logic.loop)). This anchor prevents AI models from inventing unregistered action names.
Example
### 1. Open Challenge Webpage (`web.open`)
### 2. Read Candidate Spreadsheet (`excel.read`)
### 3. Click Start Timer Button (`web.click`)
Rule 3: Key-Value Action Parameters as Bullet Points
All parameters passed to the action must be written as Markdown bullet items directly under the step header, using the format - **parameter_name:** value.
Syntax
### [Step Name] (`[action.name]`)
- **[parameter_1]:** [value]
- **[parameter_2]:** [value]
- **output_var:** [variable_name]
Supported Value Types:
- String:
- **url:** https://example.com - Boolean:
- **headless:** falseor- **clean_headers:** true - Number:
- **timeout:** 5000or- **delay:** 1.5. A value with a leading zero, such as- **branch:** 0012, stays text, so codes keep their zeros. To make any value text, quote it:"120" - List or object (JSON):
- **columns:** ["Date", "Rate"]or- **item:** {"net": "${number(inv.amount)}"}. Put quotes around${...}inside JSON; a value written as{...}or[...]that is not valid JSON is read as text, andkinenix validatereports it - Dynamic Variable Expression:
- **url:** ${config.website} - Output Variable:
- **output_var:** my_result(stores action result in context). An action that returns nothing and a step that fails leave it empty, so a loop never reuses the previous item's value; a step skipped by itsconditionleaves it as it was - Error Handling:
- **on_error:** continue,- **max_retries:** 2,- **retry_interval:** 3.0,- **fallback_step_id:** step_9(deprecated). These four keys are compiled into the step'serror_handler, not into the action parameters (see Step Resilience & Error Handling).
Example
### 1. Open Challenge Webpage (`web.open`)
- **url:** `${config.website}`
- **headless:** false
- **timeout:** 10000
### 2. Read Candidate Spreadsheet (`excel.read`)
- **file_path:** `${config.excel_path}`
- **clean_headers:** true
- **output_var:** `challenge_data`
Multi-line Values
A value with several lines, such as an email body, starts with | after the parameter name. The lines below it that are indented further than the parameter line are its value; their common indentation is removed, and blank lines inside are kept. The value ends at the first line that is not indented further, such as the next parameter.
### 5. Email Report (`email.send`)
- **to:** `${config.email.to}`
- **subject:** Insurance packages
- **body:** |
Hello,
The packages for ${request_count} requests are attached.
- Source: tipinsure.com
- **attachments:** ["${packed.zip_path}"]
The body above is "Hello,\n\nThe packages for ${request_count} requests are attached.\n- Source: tipinsure.com". A | with no indented lines after it is the plain value | (for example - **delimiter:** |). Text lines under a step that are neither a parameter nor part of a | value are ignored, and kinenix validate reports each one with its line number.
Rule 4: Standard Indentation for Control Flow (logic.loop & logic.if)
For actions that contain nested steps, use standard Markdown 2-space or 4-space indentation under - **Sub-steps:** (and optionally - **Else-steps:** for logic.if).
A. Loop Syntax (logic.loop)
### [Step Name] (`logic.loop`)
- **items:** `${collection_variable}`
- **item_var:** `item_name`
- **Sub-steps:**
- [Child Step Name] (`[action.name]`):
- **param1:** value
- **param2:** value
From Kinenix 1.1.0, - **times:** 10 (a number or ${...}) repeats the sub-steps that many times instead of going through items; item_var then holds 1, 2, 3, ... A logic.next step skips the rest of the current item and goes on with the next one (the item counts as done), and a logic.break step leaves the innermost loop of its flow; both usually stand behind a condition, so "read page after page until there is no next page" is a times loop as a limit and a logic.break where it should end (actions_reference.md). Running out of times is not an error, and items not reached because of a break are not counted.
B. Condition Syntax (logic.if)
### [Step Name] (`logic.if`)
- **condition:** `${row.Status} == 'Active'`
- **Sub-steps:**
- [Then Step Name] (`[action.name]`):
- **param1:** value
- **Else-steps:**
- [Else Step Name] (`[action.name]`):
- **param1:** value
C. Conditions
condition on any step runs the step only when the condition is true; on logic.if it chooses between Sub-steps and Else-steps. A condition is left operator right, or left is empty / left is not empty:
| Operator | True when |
|---|---|
==, != | the two sides are equal / differ. Two numbers compare as numbers, so 100.0, 100, and 100.00 are equal; anything else compares as text and ignores case. A side in quotes always compares as text |
>, >=, <, <= | both sides are numbers and compare so. 1,200 and ฿1200 are numbers; a side that is empty or is other text, such as N/A or 12 items, stops the run with exit code 4 and says why |
contains, not contains | right is / is not part of left; with a list on the left, an item equals right |
in, not in | left is / is not part of right; with a list on the right, an item equals left |
starts with, ends with | left starts / ends with right |
is empty, is not empty | left is / is not missing or blank (no right side) |
The condition is split into its sides before variables are replaced, so values containing <, >, or the word in (for example < 5,000 km) never split it, and neither does text inside ${...} or quotes. Quote a literal that contains an operator: ${label} == 'x > y'.
Join comparisons with and and or, and put not before one comparison (Kinenix 0.3.0b1 and newer). and binds tighter than or. Parentheses cannot group a condition: kinenix validate and the run report it. Write out each case instead, or use logic.if steps:
Numbers and text: values from CSV files and web pages are text, so a code such as 0012 looks like a number. When a value is a code, compare it as text with quotes: ${branch} == '0012' is false for 12, while ${branch} == 0012 is true. To compare a value that may be empty, check it first: ${amount} is not empty and ${amount} > 0. To take a number out of longer text, use number: ${number(price)} > 500.
Examples:
- **condition:** `${row.status} == Active and ${row.amount} > 0`
- **condition:** `${brand} is empty or ${model} is empty`
- **condition:** `not ${row.note} contains skip`
A condition is split at and / or only when every part is a comparison by itself, so ${company} == Johnson and Johnson still compares with the text Johnson and Johnson. Quoting is the safe form: ${company} == 'Johnson and Johnson'.
### 6. Skip Requests Without A Model (`flow.fail`)
- **condition:** `${req.model} is empty`
- **message:** Request ${req.request_id} has no car model
- **category:** business
Example
### 4. Loop Applicants and Submit Form (`logic.loop`)
- **items:** `${challenge_data}`
- **item_var:** `row`
- **Sub-steps:**
- Fill First Name (`web.type`):
- **selector:** `//input[@ng-reflect-name="labelFirstName"]`
- **text:** `${row.First Name}`
- Fill Last Name (`web.type`):
- **selector:** `//input[@ng-reflect-name="labelLastName"]`
- **text:** `${row.Last Name}`
- Click Round Submit Button (`web.click`):
- **selector:** `input[value="Submit"]`
Rule 5: Variable Interpolation Syntax
Dynamic variables must use the standard expression format:
${config.property}: Accesses configuration values loaded fromconfig/config.json.${variable_name}: Accesses runtime variables initialized in flow or stored byoutput_var.${item.property}: Accesses fields of the current iteration object inlogic.loop.${env.VAR_NAME}: Accesses operating system environment variables.${error.*}and${run.*}: The last failure and the current run (section 3.3).${__flow_dir__}: The absolute path of the flow's bundle folder. Relative paths in file actions already resolve against it; use it to build an absolute path, for example to pass a file location to a subflow:"${__flow_dir__}/output/report.csv".
A variable that nothing sets is empty, so a misspelled name does not stop the run. kinenix validate checks every ${name} against what can set it: ## Variables, the keys of the config files in config/ (each is also a variable of its own), output_var, logic.set_variable, logic.append, the outputs of flow.call, a loop's item_var and <item_var>_index, and run, error, config, env, and the trigger_* variables of the worker. A name close to one of those is a problem (Did you mean 'customer_email'?); any other is a hint, because it may come from --vars. Declare the variables a flow takes from --vars under ## Variables, empty if they have no default, and the hint goes away.
Expressions (Kinenix 0.3.0b1 and newer)
Inside ${...}, a value can also be calculated: counted, joined, cleaned, picked from a list, or computed. Nothing written in a flow can run code; only the functions and operators below exist. Design: design/expressions.md.
- **subject:** ${len(packages)} packages for ${join(ok_ids, ', ')}
- **value:** ${number(row.premium) * 12}
- **name:** ${trim(upper(row.brand))}
- **first:** ${rows[0].request_id}
- **month:** ${part(row.due_date, '-', 1)}
| Function | Result | Example |
|---|---|---|
len(x) | Number of items, keys, or characters; 0 when empty | ${len(rows)} |
join(list, sep) | The items as text, joined by sep (default ", ") | ${join(ids, ', ')} gives R001, R002 |
number(x) | The first number in the text, without thousands separators and units; (1,200) is -1200, .5 is 0.5; empty when empty. It stops at the first space or letter, so 12 345 is 12 and 1e5 is 1 | ${number('15,434.75 บาท/ปี')} gives 15434.75 |
trim(x), lower(x), upper(x) | Without surrounding spaces, lower case, upper case | ${trim(row.name)} |
replace(x, old, new) | Every old replaced by new | ${replace(row.price, ' บาท', '')} |
default(x, fallback) | x, or fallback when x is empty | ${default(row.note, '-')} |
round(x, digits) | Rounded number (digits defaults to 0). Halves go away from zero, as in Excel: 2.5 gives 3, -2.5 gives -3, and round(2.675, 2) gives 2.68 | ${round(total / count, 2)} |
part(x, sep, n) | Piece n (from 0; negative counts from the end) of the text split at sep | ${part('25-10-2019', '-', 1)} gives 10 |
substring(x, start, length) | length characters from position start (from 0), or to the end | ${substring('TH2026ABC', 2, 4)} gives 2026 |
| Form | Example |
|---|---|
Arithmetic on numbers: + - * / % and parentheses | ${(count + 1) * 2}, ${number(row.price) * 1.07} |
Index into a list (from 0; -1 is the last) | ${rows[0]}, ${rows[-1].id} |
| Key with spaces or symbols | ${row['Unit Price (THB)']} (or ${row.Unit Price (THB)}, as before) |
| Text and numbers as values | 'abc', "abc", 12, 3.5 |
- Values inside text read as written in a flow. In
Total: ${x},1200.0gives1200, true givestrue, and a list or object gives JSON, such as[{"a": 1}]. A value alone, such as${x}, keeps its type, soexcel.writestill gets a number. To control decimals, useround. - Arithmetic needs numbers. Text that is a plain number (
"12","3.5", as read from CSV) counts as a number; other text is an error that suggestsnumber(...). A whole result is written without.0. - Missing values are empty, as for variables: a missing key or an index past the end gives empty, and the functions treat empty as listed above.
- A variable that exists is always read as before.
${row.First Name}and${row.Role in Company}are keys ofrow, not expressions. Text is evaluated as an expression only when it names no existing variable. - Comparisons and
and/or/notwork inside${...}from Kinenix 1.1.0, with the rules of conditions; see Lists, comparisons, and true/false values. On older versions write them in a condition:${count} > 3. - Not allowed: method calls (
x.upper(); useupper(x)), names starting with_,**, slices ([1:3]; usesubstring), lambdas, comprehensions, and any function not in the table. Expressions are limited to 500 characters. - Errors stop the step with the expression and the reason, for example
${lenn(rows)}: unknown function 'lenn'.kinenix validatereports them before a run, with the line.
Turning labels into values with a table in config.json. An index can be any expression, so a mapping in the config converts text to a value without a special function. On books.toscrape.com a rating is a CSS class such as star-rating Three:
Changing the threshold is then one number. A label that is not in the table gives empty, and the comparison stops the step and says so.
Lists, comparisons, and true/false values (Kinenix 1.1.0 and newer)
After web.get_list, web.get_table, excel.read, or csv.read, sort, filter, count, and add up rows in one value instead of a loop, and set true/false or either-or values without logic.if. Add > Requires: kinenix>=1.1.0 to a flow that uses them; kinenix validate says when. Design: design/list-functions.md.
- **value:** ${sort_by(books, 'category', '-price')}
- **value:** ${len(where(books, 'price', '<', config.cheap_limit))} cheap books, ${sum(books, 'price')} THB in total
- **value:** {"title": "${book.title}", "cheap": "${price < config.cheap_limit}", "in_stock": "${contains(book.availability, 'In stock')}"}
| Function | Result | Example |
|---|---|---|
sort_by(list, key, ...) | A new list sorted by one or more keys, low to high; -key sorts that key high to low. Numbers (also text such as "1,200" or "£12.00") sort as numbers, text without case; empty values always come last; equal rows keep their order | ${sort_by(rows, 'category', '-price')} |
where(list, key, operator, value) | A new list of the rows whose key compares to value. Operators: == != < <= > >= contains not contains in not in starts with ends with is empty is not empty (the last two take no value). With < <= > >=, a row whose value is empty is left out. For two conditions that must both hold, put one where inside another | ${where(rows, 'status', '==', 'Paid')} |
column(list, key) | The values of one key, in order | ${join(column(rows, 'id'), ', ')} |
sum(list), sum(list, key) | The total; empty values do not count, other text that is not a number stops the step | ${sum(rows, 'amount')} |
min, max, average | Smallest, largest, mean; same arguments as sum; empty for an empty list | ${max(rows, 'price')} |
unique(list), unique(list, key) | Each value once, in the order first seen; with a key, the first row for each value | ${column(unique(rows, 'category'), 'category')} |
first(list), last(list) | The first or last item; empty for an empty list | ${first(rows).id} |
contains(x, part) | true when the text holds part (without case) or the list holds the value | ${contains(row.note, 'urgent')} |
text(x) | The value as text, so == and != compare it as text: text(a.code) == text(b.code) keeps 0012 apart from 12 | ${text(row.branch) == text(other.branch)} |
ifelse(test, a, b) | a when test is true, else b; only the chosen one is evaluated | ${ifelse(row.qty > 0, 'In stock', 'Sold out')} |
| Form | Example | Result |
|---|---|---|
Comparison: == != < <= > >= | ${price < config.cheap_limit}, ${1 < x <= 10} | true or false |
and, or, not, with parentheses | ${(in_stock or preorder) and price < 20} | true or false |
- The rules of conditions. Two values that look like numbers compare as numbers (
100 == 100.00,"1,200" == 1200); anything else compares as text, without case. Text in quotes, or passed throughtext(...), compares as text:${branch == '0012'}does not match12.<<=>>=need numbers on both sides; an empty or non-number side stops the step (exit code 4) and says which value. - A misspelled key is an error, not an empty list:
where: no row has the key 'prcie'; keys: category, price, title. - Functions never change the list they get; they return a new one. Lists of up to 100,000 items.
inis not a comparison inside${...}, so${row.Role in Company}stays a key as before; usecontains(list, value)orwhere(..., 'in', list).- A missing key with
and,or, ornotin its name, such as${row.Terms and Conditions}, is still empty, as before.
3. Failures: Retries, On Error, and Finally
3.1 Retries and on_error on a step
Any step can retry and then decide what happens:
### 2. Open Portal (`web.open`)
- **url:** ${config.portal_url}
- **max_retries:** 2
- **retry_interval:** 5
- **on_error:** continue
max_retries always retries first (2 more attempts above). Only the last attempt counts in the run's record, also for a flow.call: a step that succeeds on a retry is not a failure, and the step's retries says how many it took. After the last attempt, on_error decides:
on_error | After the last attempt |
|---|---|
not set, fail, or stop | The flow fails: the remaining steps are skipped and ## On Error runs |
retry | Same as fail. Deprecated: removed in Kinenix 2.0; kinenix validate and every run warn. Delete the line, max_retries does the retrying |
continue | The failure is recorded and the flow goes on with the next step. It counts as a failure: in a loop with item_label the item counts as failed, and the run ends as partial (exit code 8) |
ignore | For a step whose failure does not matter (Kinenix 1.1.0), such as closing a popup that is not always shown: the failure is kept in the log and the run record (handled: ignored), and the flow goes on with the next step, but it is not counted. The item counts as done, and the run can end with exit code 0 |
next_item | For a step inside a logic.loop (Kinenix 0.4.0b1): the failure is recorded, the rest of this item's sub-steps are skipped, and the loop goes on with its next item. The item counts as failed. Outside a loop it stops the flow like fail, and kinenix validate reports it |
continue inside a loop goes on with the next sub-step of the same item, which suits an optional step such as a screenshot. To give up on an item, for example when flow.fail finds bad data, use next_item:
> Requires: kinenix>=0.4.0b1
### 1. Each Invoice (`logic.loop`)
- **items:** ${invoices}
- **item_var:** inv
- **item_label:** ${inv.no}
- **Sub-steps:**
- No Amount (`flow.fail`):
- **condition:** `${inv.amount} is empty`
- **message:** Invoice ${inv.no} has no amount
- **on_error:** next_item
- Add To Summary (`logic.append`):
- **target:** summary
- **item:** {"no": "${inv.no}", "amount": "${number(inv.amount)}"}
With nested loops, next_item ends the item of the innermost loop. In a subflow called for each item, set next_item on the flow.call step in the loop; the subflow's own steps are not inside that loop.
A sub-step without on_error still stops the whole loop and the flow when it fails. When some sub-steps of a loop use next_item, kinenix validate prints a hint for the other sub-steps that may fail and have no on_error, optional: true, or fallback_step_id: one bad item would then end the batch, usually by mistake. Steps that do not fail because of one item's data are left out: the logic.* actions, flow.return, flow.fail, web.close, file.exists, and web.is_visible. Add on_error: next_item to the steps that may fail for one item. Where one failure should stop the run (a login that fails, for example), write on_error: fail: it behaves like the default, but says it is meant, and the hint goes away. The hint does not change the exit code (cli_guide.md, section 2.9).
For a step that may fail without it mattering, ignore keeps the run clean:
> Requires: kinenix>=1.1.0
- Close Popup If Shown (`web.click`):
- **selector:** `.popup-close`
- **timeout:** 2000
- **on_error:** ignore
Your own message for a failure (Kinenix 1.1.0)
error_message on any step replaces the action's message when the step fails, in the log, in ${error.message}, in the run's failure, and on the Hub. ${error.message} inside it is the action's own message, so it can be kept:
> Requires: kinenix>=1.1.0
### 1. Open The Shop (`web.open`)
- **url:** ${config.shop_url}
- **max_retries:** 2
- **error_message:** เปิดเว็บไม่ได้: ${error.message}
It works with every on_error value; without on_error the flow stops with this message. It replaces the follow-up flow.fail step that a custom message needed before. If error_message itself cannot be evaluated, the action's message is kept and the log says why.
Where these keys go: on the step that may fail. They have no effect on logic.if, logic.loop, or flow.return, and kinenix validate reports them there. Put them on the steps inside the block:
### 3. Each Invoice (`logic.loop`)
- **items:** ${invoices}
- **item_var:** `inv`
- **Sub-steps:**
- Upload (`http.request`):
- **url:** ${config.api_url}
- **max_retries:** 2
- **on_error:** continue
For a failure anywhere in the flow, use ## On Error (section 3.2). To go on after a whole block fails, put on_error: continue on each step inside it, or move the block to a subflow and set on_error on the flow.call, which does retry and continue.
fallback_step_id still runs a recovery step instead, but it is deprecated and removed in Kinenix 2.0: use on_error: continue and a next step with a condition, or ## On Error. max_retries and retry_interval accept ${...}, for example ${config.retries}. Business errors (flow.fail) are not retried.
3.2 ## On Error and ## Finally
Steps that handle a failure for the whole flow go into two optional sections after ## Steps:
# TIPH Quotes
> Requires: kinenix>=0.2.0b4
## Steps
### 1. Open Portal (`web.open`)
- **url:** ${config.portal_url}
## On Error
### 1. Capture Screen (`web.screenshot`)
- **path:** ./output/error.png
### 2. Email Error (`email.send`)
- **to:** ${config.email.to}
- **subject:** TIPH failed at ${error.step_name}
- **body:** |
${error.message}
Where: ${error.path} (line ${error.line})
Item: ${error.loop.item}
- **attachments:** ["./output/error.png"]
## Finally
### 1. Close Browser (`web.close`)
Run order:
## Stepsrun in order.- When a step fails (after its retries, and its
on_erroris notcontinue), the remaining steps are skipped,${error}is set, and## On Errorruns. Aflow.failruns it too. ## Finallyruns every time: after success, after a failure, and afterflow.return.- The run is failed when Steps failed; On Error does not turn a failure into a success. A step that fails in Finally also makes the run fail, and the log says
in Finally; On Error does not run for it.
A failing step inside On Error or Finally is recorded and the rest of that section still runs. Steps in these sections are ordinary steps: parameters, condition, loops, and flow.call work the same. Their ids are on_error_N and finally_N. A subflow can have its own On Error and Finally; they run inside the subflow, then the failure continues to the caller.
> Requires: kinenix>=0.2.0b4 under the title is needed for flows with On Error or Finally: Kinenix 0.2.0b3 and older would run their steps as ordinary steps on every run, while newer versions refuse a flow that needs a version they are not. kinenix validate reports a missing line.
When a run is stopped: Ctrl+C, systemctl stop, and systemctl restart ask the run to stop. The current step ends, the remaining steps are skipped, ## Finally runs, the log is written, and the run reaches the Hub as interrupted, with exit code 130. ## On Error does not run, because nothing failed. In a subflow, its own Finally runs first.
- A step that waits, such as a page that loads, ends at its timeout.
logic.delayends at once. - A second Ctrl+C or SIGTERM stops the process at once: Finally is cut short and no final log is written.
kinenix-worker daemonstarts no new run and waits up to 60 seconds for the running flows.systemctl stopalso ends the browser, so web steps in Finally may fail. Keep Finally to files, emails, and other work that needs no open page.- SIGKILL, a power cut, and
taskkill /Fon Windows cannot be handled: only the live.jsonllog remains.
3.3 ${error} and ${run}
${error} describes the step that failed in ## Steps, including one handled by on_error: continue. Failures inside On Error and Finally do not replace it. Values are redacted like logs (logging.md).
| Field | Example |
|---|---|
${error.message} | Timeout 30000ms exceeded waiting for role=option[name='HONDA'] |
${error.type} | Technical or Business; what other RPA tools call a System or Application Exception is Technical (logging.md, section 3) |
${error.step_id}, ${error.step_name}, ${error.action} | sub_step_3_1, Choose Brand, web.click |
${error.path} | TIPH Quotes > Each Request > process_one > Choose Brand (loops, conditions, and subflows on the way) |
${error.subflow} | process_one, or empty |
${error.line} | Line of the step heading in its flow.md |
${error.loop.item}, ${error.loop.index}, ${error.loop.of} | R007 HONDA HR-V, 7, 12 (innermost loop; index starts at 1) |
${error.retries} | 2 |
${error.root_cause}, ${error.suggested_fix} | Kinenix's diagnosis of the failure |
${error.screenshot} | Path of the automatic failure screenshot, or empty |
${error.exception}, ${error.section} | TimeoutError; steps |
When a step inside a subflow fails, the caller's ${error} describes that inner step.
${run} describes the run; subflows share it:
| Field | Meaning |
|---|---|
${run.id} | Unique id of the run, such as 20261013T221502-qhzk; use it in paths: ./output/${run.id}/, or "error_dir": "./output/errors/${run.id}" in config |
${run.flow}, ${run.started} | Flow name, start time |
${run.status} | running in Steps and On Error; success, failed, or interrupted in Finally |
${run.log_path} | The run's live log (one JSON line per finished step), for attaching to an error e-mail (logging.md) |
error and run are reserved variable names.
3.4 item_label on logic.loop
item_label names the item a loop is working on, so ${error.loop.item} (and later the Hub's run records) say which one failed:
### 2. Each Request (`logic.loop`)
- **items:** ${requests}
- **item_var:** req
- **item_label:** ${req.request_id} ${req.brand} ${req.model}
- **Sub-steps:**
- Choose Brand (`web.click`):
- **selector:** text=${req.brand}
Without item_label, the first three fields of the item are used. The label is built from a redacted copy of the item.
Loops with item_label are the flow's work items: the run log counts them as done or failed (items in logging.md), so give it to the loop over the things the flow processes (requests, invoices, rows), not to loops that only pick options.
4. Complete Reference Example
Below is a complete flow.md: an earlier version of the RPA Challenge Solver, whose current version is in kinenix/examples:
# RPA Challenge Solver
> Description: Self-Contained Project Bundle: Automate filling RPA Challenge form (10 rounds, 70 fields) from local bundle assets.
> Version: 1.0.0
## Variables
- `non_programmers`: []
## Steps
### 1. Open RPA Challenge Webpage (`web.open`)
- **url:** `${config.website}`
- **headless:** false
### 2. Read Challenge Excel File (`excel.read`)
- **file_path:** `${config.excel_path}`
- **clean_headers:** true
- **output_var:** `challenge_data`
### 3. Click START Button to Begin Timer (`web.click`)
- **selector:** `button:has-text('Start')`
### 4. Loop Through 10 Rows and Process Roles (`logic.loop`)
- **items:** `${challenge_data}`
- **item_var:** `row`
- **Sub-steps:**
- Check If Role in Company is Programmer (`logic.if`):
- **condition:** `${row.Role in Company} == 'Programmer'`
- **Sub-steps:**
- Fill First Name (`web.type`):
- **selector:** `//input[@ng-reflect-name="labelFirstName"]`
- **text:** `${row.First Name}`
- Fill Last Name (`web.type`):
- **selector:** `//input[@ng-reflect-name="labelLastName"]`
- **text:** `${row.Last Name}`
- **Else-steps:**
- Record Non-Programmer Person (`logic.append`):
- **target:** non_programmers
- **item:** `{"First Name": "${row.First Name}", "Role in Company": "${row.Role in Company}"}`
- Click Round Submit Button (`web.click`):
- **selector:** `input[value="Submit"]`
### 5. Take Screenshot of Result (`web.screenshot`)
- **path:** `${config.screenshot_path}`
### 6. Close Browser (`web.close`)
5. Checking and Inspecting a Flow
- Validation of actions and parameters: Each action declares the parameters it reads.
kinenix validate,kinenix run, andkinenix-worker runreport unknown actions, parameters that no action reads (which would otherwise be ignored silently), lines the parser ignores, step headings without an action, and a flow without steps, and suggest the closest name (for exampletimout->timeout). They also report${names}that nothing sets (Rule 5), and followflow.calltargets into subflows.runonly warns, except that a flow without steps does not run. Lines starting withHint:are not problems and do not change the exit code (cli_guide.md, section 2.9). Thekinenix-coretest suite validates every flow underflows/and every example indocs/. - Compiled form (for inspection): The result is validated against
kinenix compile flows/examples/quote_requests # print the compiled flow as JSON kinenix compile flows/examples/quote_requests -o /tmp/flow.json # or write it to a file kinenix compile flows/examples/quote_requests --strict # also exit 1 when validation finds problemskinenix.models.flow.FlowDefinition; parsing errors name the line. - Converting an old JSON flow (once):
6. AI Prompting Template for Generating flow.md
When prompting an LLM or Small Language Model (SLM) to generate a new workflow, provide this system prompt:
You are an expert RPA workflow architect for kinenix.
Generate a valid flow specification adhering strictly to the Flow Markdown Specification rules:
1. Title with Level 1 Heading (# Flow Name).
2. Level 3 Heading for each step with explicit action anchor: ### Step Name (`action.name`).
3. Parameters formatted as bullet points: - **param_name:** value.
4. Output variable formatted as: - **output_var:** var_name.
5. Indented sub-steps under - **Sub-steps:** for loops and conditions.
Only output the raw Markdown content.