# Workflow, variables and structure nodes

This page describes how workflows are structured, as a reference for developers and AI agents who write workflows. Use the [structure schema](/browser-rpa/local-api#local-machine-readable-contract) together with this page; the [validation endpoint](/browser-rpa/api/validate-workflow) is responsible for semantics. To get started, see the [Local API reference](/browser-rpa/local-api) and the [Quickstart](/browser-rpa/quickstart).

## 1. Document and order

```json
{
  "editorVersion": 2,
  "editorParametersVersion": 1,
  "variables": {
    "type": "object",
    "properties": {}
  },
  "nodes": [
    {
      "id": "start",
      "type": "start"
    },
    {
      "id": "end",
      "type": "end",
      "data": {
        "inputsValues": {
          "status": {
            "type": "constant",
            "content": "success"
          },
          "message": {
            "type": "constant",
            "content": "Done"
          }
        }
      }
    }
  ]
}
```

Writes accept only editorVersion=2 and editorParametersVersion=1. Data with parameter version 2 can still be read in its original form, but external callers do not silently rewrite it. Edit such data only after it has been explicitly migrated in the desktop client. Array order is execution order, and blocks express nesting. There are no edges, connections, or activation states.

The root array has start first and end last, with exactly one of each. Every node has a unique id. We recommend that an ID start with an ASCII letter, continue with letters, digits, or underscores, and be at most 64 characters long. IDs cannot use the editor's reserved names `system`, `initVars`, or `custom`. Group and branch IDs also count toward uniqueness. A regular action uses type=`browser_<action>`, data.browserAction must match it, and its inputs go in data.browserUi.inputs.

The shared data area contains title/description, meta (JSON display data), and data.inputs/outputs (editor descriptions; the outputs of action nodes are generated by the server, see [Fields the server fills in](#fields-the-server-fills-in)). The values in browserUi.test and simulated initialization results are not actual results, so do not use them to make decisions about a run. For the consolidated contract of each node type, see [static node contracts](/browser-rpa/nodes). It covers the input structure, defaults, conditions, output variants, and field policies.

## 2. Initial variables: six field types

variables=`{type:'object',properties:{fieldName:Variable},required?:string[]}`. Parameter names can contain Chinese characters. A name cannot be empty after trimming, cannot contain `.`, `[`, `]`, `${`, or `}`, and cannot equal custom/system/parameters or any node ID in this workflow. The names `__proto__`, `constructor`, and `prototype` are forbidden. Every entry in required must exist in properties, and duplicate entries are rejected.

A public Variable can use these properties: type, description, default, and extra. The extra property holds the editor configuration declared below. A public write rejects unknown fields that affect execution, and display configuration allows only published fields. A field is required when `extra.required=true` or when the top-level required list contains it. We recommend using only the top-level required. If the two conflict, the write returns 422 rather than letting AI agents rely on an implicit precedence.

| Business type | Declaration | Extra configuration and defaults | Regular run value |
|  --- | --- | --- | --- |
| String | type=string | extra.private=false, localPath=false; charValid={enabled:false,value:…}; multiline={value:1,autoHeight:true} | kind=json, value is a string |
| Number | type=number; integers can also use type=integer | decimalPlaces: defaults to 2 for number and is fixed at 0 for integer (same as the editor); numberRange={enabled:false,min:null,max:null}; numberSuffix={enabled:false,value:''} | kind=json, value is a finite number; range and precision must match the declaration |
| Boolean | type=boolean | No business extra | kind=json, value is a boolean |
| Array | type=array | multiline={value:1,autoHeight:true} | kind=json, value is a JSON array; do not pass a JSON string in its place |
| Object | type=object | multiline={value:1,autoHeight:true} | kind=json, value is a JSON object |
| File | type=object for a single file, type=array for multiple files; extra.type=file | multipleFiles={enabled:false,unlimited:false,maxCount:9} (for multiple files, omitting maxCount allows up to 9 files, and only unlimited=true removes the count limit); formatType is an array of file extensions; sizeLimit={unit:'KB' or 'MB',value:positive number}, and when it is omitted, each file can be at most 10MB (same as the editor) | kind=json, value is an absolute local path string (single file) or an array of strings (multiple files). The server references the file at that path directly, the same way a client run does, without copying it. The path must exist and meet the extension, count, and size limits. The url that the node receives is this path. File parameters cannot declare a default value |


The multiline.value setting is an integer from 1 to 200. For character counts, precision, and file limits, the live contract is authoritative; do not use mock data from the UI. The extra.name/index/placeholder fields are display fields and do not change the name used to reference the parameter. The fieldId is the key in properties.

A regular default value has two existing editor representations. Variable.default is recommended, and extra.defaultValue={enabled:true,value:…} is supported for compatibility. Setting extra.defaultValue.enabled=false explicitly means no default. When enabled=true, its value applies. If default is also given and the two differ, a public write returns RPA_DEFAULT_CONFLICT instead of silently choosing one. An array or object default is a JSON value. A run cannot start when a required value is missing and there is no default. Omitting an optional value is different from passing an explicit null or an empty array, and null must pass validation for the target field.

```json
{
  "type": "object",
  "properties": {
    "targetUrl": {
      "type": "string",
      "description": "Target URL",
      "default": "https://example.com"
    },
    "count": {
      "type": "integer",
      "default": 2,
      "extra": {
        "decimalPlaces": 0,
        "numberRange": {
          "enabled": true,
          "min": 1,
          "max": 10
        }
      }
    },
    "enabled": {
      "type": "boolean",
      "default": true
    },
    "items": {
      "type": "array",
      "default": []
    },
    "settings": {
      "type": "object",
      "default": {}
    },
    "attachment": {
      "type": "object",
      "extra": {
        "type": "file",
        "multipleFiles": {
          "enabled": false
        },
        "formatType": [
          "txt"
        ],
        "sizeLimit": {
          "unit": "KB",
          "value": 100
        }
      }
    }
  },
  "required": [
    "targetUrl"
  ]
}
```

Workflows with file parameters, or with string parameters that have localPath=true, can run externally, the same as in a client run. Pass a local path at run time.

## 3. Private default values

A private variable must have type=string and extra.private=true. The Local API does not redact private values. You can submit a plaintext default value, GET returns the plaintext default value, and a workflow with private parameters can run externally (at run time you can pass plaintext directly; see [ParameterValues](/browser-rpa/api/data-types#parametervalues)).

Write a plaintext default value:

```json
{
  "type": "string",
  "default": "p@ssw0rd",
  "extra": {
    "private": true,
    "defaultValue": {
      "enabled": true,
      "value": "p@ssw0rd"
    }
  }
}
```

This matches how the client's Custom Templates editor saves: the plaintext is written as is into the cloud template content, and GET returns it in the plaintext form shown above. When the client editor saves a default value as a reference to local secure storage, reading it on this machine decrypts the value and returns it.

| Write or read case | Rule |
|  --- | --- |
| POST/PUT/node-edits submits a plaintext default or defaultValue.value | Written to the cloud template as is; the save succeeds |
| GET template details | Private default values are returned in plaintext as `default` and `defaultValue:{enabled:true,value}`; `redactedPaths` is always `[]` |
| Responses of write endpoints (create, update, copy, node edits) | Same as GET; private default values are returned in plaintext |
| Idempotency receipts (same-key replay, the result of `GET /requests/{key}`) | Receipts do not store template content. On replay, the server reads the cloud template again and returns its current content, the same as GET |
| PUT/inline validation that carries the original template as base, the original field name, string, and private=true, and sends back `publicState:"retained"` | Keeps the existing default of this field in this template (for compatibility with older callers); if there is no matching default, returns 422 RPA_PRIVATE_DEFAULT_INVALID |
| retained submitted for a new template, or for another template or field | 422 RPA_PRIVATE_DEFAULT_INVALID; the value is not taken from another template. For a new template, submit plaintext |
| defaultValue omitted, or enabled=false | Clears the existing default; the field can still be private; returns warning RPA_PRIVATE_DEFAULT_CLEARED |
| node-edits without variables | Keeps the server's existing variables and private defaults |
| node-edits with complete variables | Handled the same way as PUT |
| copy | The copy keeps the private default values of the source template, with no warning |
| The private default value is a reference to local secure storage that can no longer be read (for example, it was saved on another device, or local secure storage was reset) | GET returns `{enabled:false}` with warning RPA_PRIVATE_DEFAULT_UNAVAILABLE; submit the plaintext again to restore it |


A validation-only call is read-only. It does not write the cloud template, and it does not create or change values in secure storage. Private parameters must be strings, and `publicState` can be used only on private string fields.

NodeContract gives each field sensitivity=public|secret|credential|localPath|inlineFile|sourceCode, which only describes the nature of the field. `authoringPolicy` is always `allowed`. Fields such as script source code (javaScript/injectJavaScript.content), local paths (the path of each file action, the screenshot folder), inline files, Cookie/LocalStorage, and 2FA keys can all take a literal or a reference directly. GET returns them as is, and runs are not restricted. Callers must store and redact this content themselves; see [Data and execution boundaries](/browser-rpa/api/common#data-and-execution-boundaries).

## 4. The six structure nodes

| type | data | blocks | Execution semantics |
|  --- | --- | --- | --- |
| start | title/description; customVariables; taskSettings (template task settings, see below); the descriptive inputsValues for initialization can be kept but do not supply real run parameters | Omitted or [] | First in the root; declares the custom variables of this workflow |
| end | inputsValues.status/message; a fixed success or failed is recommended for status; message can be a WorkflowValue; null becomes an empty string, objects go through JSON.stringify, and other values go through String, so the final value is a string | Omitted or [] | Ends the current workflow; status=failed makes it fail, otherwise it succeeds; public writes reject other deterministic literals; the public raw result is the message string |
| group | title/name/description/collapsed | Required node array, can be empty; **cannot contain another group** (groups cannot be nested, same as the editor; otherwise RPA_INVALID_NODE is returned) | Organizes order and does not produce an execution result that can be referenced on its own; it is flattened at run time, but the saved workflow keeps the group |
| case | title/description optional (we recommend describing what the branch means; if omitted, the default title `分支` is filled in); conditionGroups:[{content:Condition[]}], **only one group allowed** | Required node array | Only directly under ifElse; conditions within the group are combined with AND; to express "or", add more branches; the first case that matches, in case order, is taken |
| caseDefault | title/description optional (we recommend describing what the branch means; if omitted, the default title `默认分支` is filled in) | Required node array | Runs only when ifElse matches no case; at most one, and it must be last |
| exceptionBlock | title/description optional | Required node array, can be empty | Used only as the direct blocks of a node set to "Run exception handling branch"; exactly two, the success branch first and the failure branch second; see [Exception handling branches](#exception-handling-branches) |


The start.data.taskSettings object holds the template-level settings that the editor saves from "Task settings". GET returns them as is, and you can write them back unchanged or modify them. For the fields and values, see `$defs.start` in workflow.schema.json. The settings take effect only in actual runs (a full-workflow run in the editor, a run started through the Local API, or a scheduled task). They have no effect in single-step or group debugging, and taskSettings in a called child template have no effect either. Key points:

- delayMinutes: The run first stays queued without occupying the environment, and it starts the browser only at `startAfter` (a run summary field; for scheduled tasks, the scheduled time is the baseline). The run can be canceled while it is queued.
- timeoutSeconds: Timing starts when the delay ends and the browser starts. On timeout, the browser of the main environment is closed and the run fails with error code RPA_TASK_TIMEOUT. Nodes that are running at the time of the timeout (including enclosing loop, condition, and child workflow nodes) are also recorded as failed with RPA_TASK_TIMEOUT. They are not retried and do not go through exception handling. The task timeout and node timeouts apply independently.
- completionTabs / completionBrowser: After success or failure, these settings act on the main environment (the environment used when the run started). Nothing is done when the user stops the run. Environments opened by the "Start browser" node are not affected.
- headless, launchArguments, disableAutofill, allowSavePasswords, and clearCacheOnClose apply only to browsers that this run starts (including those started by the "Start browser" node). They have no effect on environments that were already open before the run. A headless browser requires browser kernel version 130 or later (otherwise RPA_HEADLESS_CORE_UNSUPPORTED), and it is always closed when the task ends, including when the user stops it.


Public writes of case accept only conditionGroups, with exactly one condition group (same as the editor; more than one group returns RPA_WORKFLOW_SCHEMA_INVALID with reason=limit). When the legacy inputsValues.condition is read, the API boundary projects it into a single-element conditionGroups. If both are present, it is a structural error inside the workflow: save or update returns 422, and a validation-only call returns 200 with valid=false and an issue. Neither form can be silently ignored. Each group must be non-empty, and every condition requires a left operand. The operators are eq/ne/gt/lt/gte/lte/contains/notContains/exists/notExists, and only exists/notExists can omit right. The gt/gte/lt/lte operators compare numbers or numeric strings. When either side is null (for example, a reference to a node that was skipped after it failed), the condition is not met. Other values that cannot be converted to numbers return VALUE_CONVERSION_FAILED. Write an operand as a constant `{"type":"constant","content":…}` or as a reference `{"type":"ref","content":["nodeId","data","field"]}`. The content of a reference **must be an array of path segments** (same as the editor). If you write it as the string `"nodeId.data.field"`, the editor treats it as not filled in, and the write returns RPA_NODE_INPUT_INVALID (reason=required). You cannot turn an entire condition group into a ref.

The root workflow.outputs is the actual workflow output mapping, as opposed to the editor descriptions in a node's data.outputs. When it is not declared explicitly, the runtime derives `{result:"${<endId>.data.result}"}` from the end node at the end of the root. An explicit workflow.outputs overrides this default, which is why call_child.data.outputs.result in the child workflow example comes from this mapping. Every reference in the declaration also goes through scope, type, and run policy checks.

Structure nodes do not count as executable actions, so do not treat start or group as missing at run time when you read capabilities. The breakLoop node is a control action. It can only be placed in a loop body of the current workflow, and its blocks must be omitted or empty. A break in a child workflow cannot exit the caller's loop.

When you create a loop, always write `"accumulatorMode": "none"` (write another value when you need to accumulate results), which matches loops created in the client editor. When omitted, it is treated as `none`, which matches what the editor shows. The loop output `index` is the current iteration and **starts at 1** (the first iteration is 1). In times mode, `item` is the same as `index`. In list/elements mode, `item` is the current element or value, and for an object list, `item` is `{key,value}`. For fields that pick the Nth element by position (such as getElement's serial, which also starts at 1), reference `${loopId.data.index}` directly and do not add 1. After the loop ends, `index` is the number of the last iteration, or 0 if the loop ran zero times. In while mode, write loopConditions only as a rule array, `[{"field":"index","operator":"lt","value":3}]` (same as the editor; a condition group `{content:[…]}` is not accepted). When maxIterations is reached, the loop ends normally and exitReason is max_iterations.

## 5. Custom variables and references

Each item in start.data.customVariables is `{id,name,type,initialValue}`. Its type is string/number/boolean/array/object, and initialValue must match the type. The id must be unique and expressible in path syntax. Reference the variable with `${custom.<id>}`, not by name. Custom variables are initialized independently for each full run and for each child workflow call. The public API does not expose debugging, so values are not inherited across runs.

There is only one way to write custom variables (same as the editor): declare them in start.data.customVariables and change them with `browser_updateCustomVariable`. The variableId must be static and already declared, and the operation must apply to the variable's type. You cannot dynamically write arbitrary parameters or system variables. The editor has no setCustomVariable node, so writing one returns RPA_WORKFLOW_SCHEMA_INVALID. A setCustomVariable node left over in an existing template fails before the run (RPA_ACTION_UNSUPPORTED, with the node ID and path).

```json
[
  {"id": "start", "type": "start", "data": {"customVariables": [{"id": "demoCounter", "name": "Counter", "type": "number", "initialValue": 0}]}},
  {"id": "set_counter", "type": "browser_updateCustomVariable", "data": {"browserAction": "updateCustomVariable",
    "browserUi": {"inputs": {"variableId": "demoCounter", "operation": "assign", "value": "2"}}}},
  {"id": "end", "type": "end", "data": {"inputsValues": {"status": {"type": "constant", "content": "success"},
    "message": {"type": "ref", "content": ["custom", "demoCounter"]}}}}
]
```

`${parameterName}` reads an initial parameter, `${nodeId.data.field}` reads the execution data of a node, `${custom.id}` reads a custom variable, and `${system.browser.id}` and similar paths read the system context. A whole-value reference keeps the original type, and a reference inside a concatenated string is converted to text. WorkflowNumber takes a number or a restricted arithmetic expression, not a ref object. `${…}` can contain only a reference path, not arithmetic: `${loop.data.index + 1}` returns RPA_REFERENCE_EXPRESSION_UNSUPPORTED. In a number field, write `"${loop.data.index}+1"` (the reference is written on its own, and the arithmetic goes outside `${}`). Regular text fields do not evaluate arithmetic. References in the browserUi.inputs/bindings of an action node are written **only as `${path}` text** (same as the editor), not as wrapper objects such as `{type:'ref'}`. Element and frame fields also take only reference text such as `${previousNode.data.element}`; do not write ElementRef/FrameRef objects by hand. Writing a wrapper object returns RPA_WORKFLOW_SCHEMA_INVALID or RPA_NODE_INPUT_INVALID (reason=format). The ref object `{type:'ref',content:[pathSegments]}` is used only in the inputsValues of the end node and in condition branch operands.

A WorkflowValue (the inputsValues of the end node, condition operands, and the key/value of script parameters) is a plain JSON value or a constant/ref/expression wrapper. When public semantic validation sees the reserved key type=ref/constant/expression, it must validate the value as a wrapper. It cannot let the broad JsonValue union absorb a malformed wrapper. If an object with these reserved keys really needs to be plain business data, wrap it in constant and handle it according to the rules of the target field.

**No general escape rule for `${…}` is guaranteed in literal strings.** To output such text, use the constant wrapper that the contract of the field allows, and check it with validate. If the current parser still interpolates the text, the result is reported as unsupported. Do not try to work around this by guessing backslash escapes.

Whether a mode field (such as selectorType/loopMode/outputRange) allows dynamic references is defined by the NodeContract. When it does, validation returns runtimeChecks, and the actual value is checked again at run time. Choose the output type according to the mode, and do not assume that every node has a result.

## 6. Display data and normalization

`node.meta` is an optional, opaque JSON object that holds only display information. It allows any JSON subfields (for example position, collapsed, or a caller-defined layout), and the object as a whole is subject to the byte-size and nesting limits of the workflow. Do not put tokens, secrets, or local connection details in it. Neither meta nor node.data.title/description/inputs/outputs changes run semantics, and they are not parameters or actual outputs. The server must not execute meta content, and callers must not treat its text as instructions.

New nodes do not need generated coordinates or meta. Both replace and PUT keep any valid meta that is provided exactly as is, including unknown display keys, null, and arrays. Omitting the meta of a node removes its display data. In node-edits, nodes that are not touched keep their meta, and for replace, the caller is responsible for sending back the entire node. To change only one display field, deep-merge the change into the GET result; do not overwrite other keys. Key order inside meta is not guaranteed, and values must not be silently truncated.

The only allowed template normalizations are trimming title, the declared conversion when the legacy case form is read, the stored and returned form of private default values (see section 3) with explicit warnings, and the "Fields the server fills in" described below. The server does not rename node IDs, change description or meta, drop unknown meta fields, or change node order or references. The saved source is kept separate from the execution plan. NodeContract.defaults only fills in omitted inputs for the compiled or validated plan and is not written into browserUi.inputs, and the save response keeps the inputs that were originally omitted. An explicit 0, false, empty string, or null does not trigger a default. The complete returned result is still what the caller should base further edits on.

### Fields the server fills in

A saved workflow must be able to open in the Browser RPA editor of the desktop client (on the template edit page, and as the workflow snapshot in execution records and schedules). Therefore, every write (create, replace, copy, node edits, validation with purpose=save/run, and client saves and draft runs) fills in the fields missing from each action node (`browser_<action>`) with what the editor writes when it creates the same node. The result is then checked with the loading rules of the editor:

| Field | Fill rule |
|  --- | --- |
| `data.browserUi.inputs` / `bindings` | `{}` when omitted; the default values of node inputs are not written into inputs |
| `data.browserUi.exception` | When omitted, or when some fields are missing, each missing field gets the editor default (see [Node exception policy](#node-exception-policy-workflowexception)); explicitly written fields are kept as is |
| `data.title` | When omitted, the node's name from the editor is filled in, in its original Chinese wording. This is only a fallback. Write a name that describes the purpose of the node. When the name is omitted, empty, or equal to the default name, the server returns warning `RPA_NODE_TITLE_GENERIC` (see below) |
| `data.inputs` / `data.inputsValues` | When omitted, `{"type":"object","properties":{}}` and `{}` respectively; the inputsValues of an action node must be an empty object |
| `data.outputs` | Always generated by the server from the node type and browserUi.inputs. It describes the variables that later nodes can reference. Callers do not need to fill it in; if they do, the generated result takes precedence |
| `data` of the start / end nodes | Missing keys are filled in from the start and end nodes that the editor creates for a new template: start gets `title` `初始化`; end gets `title` `结束`, `inputs`/`inputsValues` (status=success and an empty message, which gives the same execution result as omitting them), and `outputs`. Explicitly written keys (including a custom title and status=failed) are kept as is |
| `data.title` of case / caseDefault | When omitted, the default branch names from the editor are filled in: `分支` for case and `默认分支` for caseDefault. An explicitly written name (including an empty string) is kept as is |


As a result, action nodes and start/end nodes read back with GET always contain the complete structure above, and the compact form on submission (only browserAction and browserUi.inputs) is still valid. A workflow that the editor still cannot open after the fields are filled in (for example, the node type does not match browserAction, or a condition branch is not under a condition node) returns 422, and issues.path points to the affected node. Complete content that the client editor saves itself is never rewritten.

**Name reminder**: The client editor shows only the names of nodes and branches in a template. So create, replace, node edits, and `POST /validations` return one warning `RPA_NODE_TITLE_GENERIC` for each action node and each case/caseDefault whose name is omitted, empty, or equal to the default name in the editor. Each warning has a path that points to the `data/title` of the node, and it includes `nodeId`. The warning does not block saving or running. The start/end, group, and exceptionBlock nodes are not checked, and copying a template does not return this warning. Rename such nodes to describe their purpose (for example, "Wait for search results to appear" or "Find the target video").

## 7. Exact mapping of the final result

On the success path, `end.data.inputsValues.message` is evaluated → null becomes `""`, objects and arrays go through JSON.stringify, and other values go through String → the execution data of the end node, `end.data.result` (string). When workflow.outputs is not provided explicitly, the compiler derives `{ "result": "${<endId>.data.result}" }`, so `data.result.outputs.result` in the GET run response is exactly this string. If workflow.outputs is set explicitly, the result follows that mapping, and there is no implicit result field. With status=failed, the workflow ends as a failure and does not claim to produce a successful result.

For example, if the value of getUrl(type=search,key=item) is `"42"` and end.message references that value, the final outputs.result is `"42"`. When the key does not exist, getUrl.value="" and the final outputs.result is `""`. This does not mean that the node failed. If end.message references the entire data object of getUrl, the result is the JSON string of that object. Do not mix up the node-level result and the run-level result.

## 8. URLs and the limits of validation evidence

A URL initial parameter only needs to be declared as string; URL is not a separate variable type. In save validation, a fixed literal in gotoUrl.url must be an absolute HTTP(S) URL. For a reference that has no run value yet, validation checks its declaration and scope and lists it in runtimeChecks. Validation cannot assert that the URL is valid or reachable. The run preflight checks the URL format again with the actual parameters. Website connectivity, redirects, and page changes can still be confirmed only during execution. An empty runtimeChecks array is not proof that a run will succeed. When valid=false, fix the problems and then validate again.

## 9. Reference forms, base, and display changes

The literal form is a plain JSON value for the target field. The template form is a string that contains `${…}` (a whole-value reference keeps its type, and concatenation converts to text). The numericExpression form is a bounded arithmetic expression with the four basic operations and numeric references, as supported by WorkflowNumber; it is not JavaScript. The reference form is `{type:"ref",content:[pathSegments]}` and appears only in the inputsValues of the end node and in condition operands (it is not used in the browserUi of an action node). The schema describes what is structurally possible, and referenceRules restrict the forms that the field publicly allows. Both must be satisfied. The gotoUrl.url field supports literal/template.

With getUrl.type=href, value and url are both the complete current address at the moment of reading, including query/hash. If an earlier navigation was redirected, this is the address of the current page after the redirect. With origin, value is the scheme, host, and port. With search, value is the first value of the given query key, or an empty string when the key does not exist, and url is still the complete address.

An inline source without base is an independent candidate for a new template. The server cannot infer which existing template it came from, so it does not check any saved version and does not allow retained. When you modify a template, you must send base so that the version check can protect this preflight. Saving still requires If-Match. If the caller cannot access the base or template, the server returns 403/404 first, not RPA_TEMPLATE_VERSION_CONFLICT, and it does not reveal the version.

When a client user saves a display layout or edits a form, that user also counts as another writer. This should increase the template version and invalidate old ETags. Merely opening a template is not a write operation that the API guarantees, so do not conclude from it that the version has not changed. Always read the current template again before you continue editing.

## 10. Choosing wait nodes

"Wait after visiting" can use gotoUrl.postWaitMs or a separate waitTime, and both waits add up. If the user also wants to edit the wait node separately, we recommend an explicit postWaitMs=0 plus a separate waitTime, which avoids counting the wait twice. This is the default composition choice, not a protocol restriction. For waitTime, fixed.timeout allows finite fractional milliseconds, but the scheduling precision of the run is not guaranteed. Both ends of randomInterval also allow fractions (for the value rules, see the browser_waitTime contract). The response meta (Metadata) is HTTP tracing information, while node.meta is canvas display information. Neither can be used to fill in the other.

When you change a node ID, you must fix all references at the same time. Either replace the whole template with PUT, or, in one node-edits batch, remove the old node, insert the new node, and replace every node that references it. The replace operation itself cannot change node.id. With either approach, validate the complete candidate first, keep the user's data, and use the current If-Match and a new write intent key.

## Node exception policy (WorkflowException)

The configuration goes in `node.data.browserUi.exception`, at the same level as inputs and bindings. It is not written inside inputs. For the field structure, value ranges, and defaults, see the [WorkflowException schema](/browser-rpa/local-api#local-machine-readable-contract).

When the whole exception object or any of its fields is omitted, the server fills in each missing field before saving, using the default that the client editor sets for a new node (see [Fields the server fills in](#fields-the-server-fills-in)). You can see the complete values when you read the template back. Explicitly written fields are kept as is. The filled values are the same as the values of the same node created in the editor and the values shown in the exception settings panel of the editor. Execution uses the filled values.

| Field | Filled in when omitted | Values and semantics |
|  --- | --- | --- |
| policy | `"interrupt"` | interrupt: the run stops after the node fails. skip: keep the failed node record and continue. handle: process the failure with handler, then continue or stop. A node timeout is handled by policy like any other failure. If the original operation still has not finished within one more timeout period after the timeout, the executor first disconnects and takes over the same environment again (keeping the original current tab), then applies policy. If the takeover fails (the execution context has been isolated) or the run is canceled, skip/handle cannot force the run to continue. |
| handler | Not filled in; the executor treats it as `"screenshot"` | Takes effect only when policy=handle and [exception handling branches](#exception-handling-branches) are not used. screenshot: continue after a successful screenshot, or stop if the screenshot fails. stop: stop the rest of the workflow. remark: record an environment remark. |
| screenshot | `true` | Tries to take a screenshot when the node finally fails. Setting false turns off regular failure screenshots, but policy=handle with handler=screenshot still requires a screenshot. A screenshot may not be possible when the page is closed, the run is canceled, or the execution context has been isolated. A failed screenshot does not replace the original node error. The local file nodes useExcel (Read Excel), exportExcel (Write Excel), importText (Import text), and saveData (Save text) never take screenshots, because their failures are not related to a browser page. For these nodes, handler=screenshot only records the error and continues. |
| timeout | `30000` for action nodes; `0` (no limit) for control nodes | Milliseconds, an **integer** in the range 0–2147483647 (same as the editor; a fractional value returns RPA_WORKFLOW_SCHEMA_INVALID). `0` means no time limit. This is the timeout of a single execution, and it is also bounded by the remaining time of the whole run. It is not the Local API HTTP wait timeout. The injectJavaScript node is also bounded by its executionTimeoutMs input. |
| retry | `false` | Enables retries when an atomic action fails. |
| retryTimes | `1` | Takes effect when retry=true. An integer in the range 1–10 that sets the number of additional attempts; the action runs at most 1+retryTimes times. |
| retryInterval | `2` | Interval between retries, in seconds, in the range 0–2147483. This unit differs from timeout, which uses milliseconds. |


**When timeout is omitted, action nodes (including navigation nodes such as gotoUrl) get 30 seconds, and control nodes (loop, ifElse, breakLoop, applySubProcess, updateCustomVariable) get `0`, which means no time limit.** A control node without a time limit is bounded only by the remaining time of the whole run, the maxIterations of the loop, and cancellation. Each child action inside it still runs with its own timeout (30 seconds by default), so a single action on a slow page needs an explicitly larger timeout. A timeout set explicitly on a control node covers the entire call and all of its child nodes, and the node fails with TIMEOUT when that time runs out.

The client editor also writes 0 (no limit) for new control nodes and 30000 for new action nodes. Any node that needs no time limit can set 0 explicitly. A value of 2147483647 saved by earlier versions is still valid and also means no time limit; it is not rewritten when read. When AI agents compose workflows, they should set exception explicitly based on the business need instead of relying on defaults.

Retries apply to atomic actions. Control nodes do not use these settings to retry the entire subgraph. A node timeout is also retried according to the configuration (this may repeat an action that already took effect). If the original operation still has not finished within one more timeout period after the timeout, the retry happens only after the environment has been taken over again. There is no automatic retry after cancellation or a failed takeover. Neither skip nor a successful handle changes a failed node to success, so you still need to check hasNodeErrors.

For example, the following shows a loop that runs for at most 10 minutes and skips a failing element and continues, and a node on a slow page that reads a value and retries twice when it fails:

```json
[
  {
    "id": "each_item",
    "type": "browser_loop",
    "data": {
      "browserAction": "loop",
      "browserUi": {
        "inputs": {
          "loopMode": "times",
          "times": 20,
          "accumulatorMode": "none"
        },
        "exception": {
          "policy": "interrupt",
          "timeout": 600000,
          "screenshot": true
        }
      }
    },
    "blocks": [
      {
        "id": "read_title",
        "type": "browser_getElement",
        "data": {
          "browserAction": "getElement",
          "browserUi": {
            "inputs": {
              "selectorType": "selector",
              "selectorRadio": "CSS",
              "selector": "h1",
              "type": "innerText"
            },
            "exception": {
              "policy": "skip",
              "timeout": 15000,
              "retry": true,
              "retryTimes": 2,
              "retryInterval": 1,
              "screenshot": true
            }
          }
        }
      }
    ]
  }
]
```

After a screenshot is published successfully, `data.items` of `GET /runs/{id}/artifacts` contains the metadata of that artifact, and the `artifacts` of the node execution record that produced the screenshot reference the same id. The API does not provide a download URL or the file content. `path` is the path of the screenshot on the local machine.

### Exception handling branches

An action node (including control actions such as applySubProcess, updateCustomVariable, and breakLoop, but not ifElse or loop, which have their own blocks) can hand its failure to the two branches on the canvas, success and failure. This works the same as "Run exception handling branch" in the client editor. To set it up:

- Set `data.exception` to `{"mode":"branchHandle"}` (at the same level as `data.browserUi`, not inside browserUi.exception).
- Set `data.browserUi.exception.policy` to `"handle"`.
- Make `blocks` exactly two `exceptionBlock` nodes: the first is the success branch, and the second is the failure branch. Only the array order determines the role. Titles and IDs can be anything, and a branch can contain no nodes.


Execution semantics:

| Final result of the parent node | Behavior |
|  --- | --- |
| Success (including success after retries) | Runs only the success branch, then continues with the nodes after the parent |
| Failure (retries exhausted) | Runs only the failure branch, then continues. The node record of the parent stays failed and keeps the original error and the failure screenshot, with `nextAction=continue`; the run has hasNodeErrors=true |
| Canceled, or the original operation still had not finished after the timeout and taking over the environment again failed (the execution context has been isolated) | Does not enter the failure branch; the run ends, the same as with other policies |


- In branch mode, `handler` has no effect (no substitute screenshot, no remark, no stop). Whether a failure screenshot is taken depends only on `screenshot`.
- The `data` of the parent node resolves to null under the rule for "nodes that continue after failure". Inside the failure branch, you can reference `${parentId.error.code}` and `${parentId.status}`.
- The two branches are alternatives to each other. A node in one branch cannot reference a node in the other branch (RPA_REFERENCE_NOT_VISIBLE), and an `exceptionBlock` itself cannot be referenced. When a node after the branches references a node inside a branch, the reference needs a runtime check.
- When a node inside a branch fails, it is handled by its own exception and does not enter the failure branch of the parent again. A retry of the parent node does not replay the branches.
- A structure mismatch returns RPA_STRUCTURE_INVALID: mode=branchHandle but blocks are not exactly two exceptionBlock nodes, policy is not handle, the setting is placed on ifElse/loop, or an exceptionBlock is not under such a node.
- `data.exception.mode` set to `skipStep` / `stopTask` is only an editor marker. Execution follows policy, and the node cannot have exceptionBlock children.


```json
{
  "id": "open_shop",
  "type": "browser_newPage",
  "data": {
    "browserAction": "newPage",
    "browserUi": {
      "inputs": {"openMode": "url", "url": "https://example.com"},
      "exception": {"policy": "handle", "retry": true, "retryTimes": 2, "retryInterval": 2, "screenshot": true}
    },
    "exception": {"mode": "branchHandle"}
  },
  "blocks": [
    {"id": "open_ok", "type": "exceptionBlock", "data": {"title": "Success"}, "blocks": []},
    {"id": "open_failed", "type": "exceptionBlock", "data": {"title": "Failure"}, "blocks": [
      {"id": "wait_retry", "type": "browser_waitTime", "data": {"browserAction": "waitTime", "browserUi": {"inputs": {"timeoutType": "fixed", "timeout": 1000}}}}
    ]}
  ]
}
```

### Control nodes, terminal states, and validation stages

The control nodes in the public catalog are browser_ifElse, browser_loop, browser_breakLoop, browser_applySubProcess, and browser_updateCustomVariable (whether a node is offered still depends on the catalog of the instance). These nodes accept an exception object. The timeout field bounds the entire control call and its child calls, and it is 0 (no limit) when omitted. The policy/handler/screenshot fields handle failures of the control call, including errors that bubble up to the call. Normal break, end, and stop control signals are not treated as retryable failures. The retry/retryTimes/retryInterval fields must still pass field validation, but control nodes ignore retries at run time and do not rerun the entire subgraph. Atomic actions in child nodes run according to their own exception.

A node with handler=remark can be saved, and it can also run externally through the Local API, the same as in a client run.

Nodes that continue after failure: when a node has run, finally failed, and continued according to its exception (policy=skip, or continuing after handle), later references to fields under its `data` resolve to `null`. A whole-value reference (such as `{type:'ref',content:['read','data','value']}` or the whole string `"${read.data.value}"`) gets `null`, and a reference concatenated in a template string (such as `"Title: ${read.data.value}"`) gets an empty string. References to non-data paths, such as `${id.status}` and `${id.error}`, are unchanged. A reference to a node that does not exist, a node that has not run yet, or a field that does not exist on a successful node still fails at run time with MISSING_VARIABLE. The rules for static reference checks before save and run are unchanged. Therefore, downstream nodes can directly reference a data-collection node that might be skipped, without an extra "clear/record" variable node. In a condition, a gt/gte/lt/lte comparison with null is not met. To tell "nothing was read" apart from "0 was read", check exists first.

The table below describes only the default outcome after a single executed node fails. It assumes that the outcome is not overridden by cancellation, execution context isolation, a later failure, a failed output evaluation, or an explicit end instruction:

| Policy | Next action | run.status | hasNodeErrors |
|  --- | --- | --- | --- |
| interrupt | Interrupt the run | failed | true |
| skip | Continue with the next nodes | success (when all later nodes run normally) | true |
| handle + screenshot, screenshot succeeds | Continue with the next nodes | success (when all later nodes run normally) | true |
| handle + screenshot, screenshot fails | Interrupt the run | failed | true |
| handle + stop | Run no further nodes | stopped | true |


These are execution semantics, not rules for inferring results instead of querying them. Cancellation can result in cancelled. A node timeout results in failed (TIMEOUT) and is handled by retry/screenshot/policy. When the task times out, or the browser of the main environment is closed during the run, the running node ends as failed, like the run (RPA_TASK_TIMEOUT / ENVIRONMENT_CLOSED), and retry/policy do not apply. When a stop cannot be confirmed, the run ends as failed with error.code OUTCOME_UNKNOWN. In the end, always read the actual run.status, hasNodeErrors, and isolation.

The JSON Schema of WorkflowException constrains only the shape of the fields; integer and range rules are enforced by semantic validation. Even after the local schema check passes, you must still call validations. A single call of an atomic action attempts at most one failure screenshot after its retries are exhausted. Multiple calls in a loop, or separate failures of parent and child nodes, can produce multiple screenshots.

Complete example of attaching an exception policy to a node (the selector `[` deliberately triggers a run-time failure so that you can observe the failure handling):

```json
{
  "id": "capture_failure",
  "type": "browser_getElement",
  "data": {
    "browserAction": "getElement",
    "browserUi": {
      "inputs": {
        "selector": "[",
        "selectorType": "selector",
        "outputRange": "single",
        "type": "innerText"
      },
      "exception": {
        "policy": "interrupt",
        "screenshot": true,
        "retry": false
      }
    }
  }
}
```

For where artifact fields appear on node records and how to query them page by page, see [List node executions](/browser-rpa/api/list-run-nodes). For the shape of the artifact collection, see [List run artifacts](/browser-rpa/api/list-run-artifacts).