Control Flow

Figranium provides robust control flow mechanisms to handle dynamic web pages, conditional logic, pagination, and multi-step processes.

Conditional Execution (If / Else / End)

The If block executes a sequence of actions only when a condition is met.

Structure

Every if block must be closed with an end block. An optional else block can be placed between them.

{ "type": "if",   "value": "<condition>" },
  // actions if condition is true
{ "type": "else" },
  // actions if condition is false (optional)
{ "type": "end" }

Condition Types

1. JavaScript Expression A JS expression evaluated in the browser page context. Must return a truthy/falsy value.

exists('.error-message')           // checks if element exists
text('.status') === 'Success'      // checks element text
url().includes('/dashboard')       // checks current URL
{$count} > 5                       // compares a variable
block.output !== ''                // checks previous block result

Available helpers in expressions:

Helper	Description
`exists(selector)`	Returns `true` if the element is found in the DOM
`text(selector)`	Returns the text content of the first matching element
`url()`	Returns the current page URL
`vars.name`	Access a runtime variable by name
`block.output`	The result of the previous action block
`html`	The full page HTML as a string

2. Structured Condition A form-based alternative to JS expressions. Define a variable or selector, an operator, and a comparison value.

Field	Description
`conditionVarType`	`string`, `number`, or `boolean`
`conditionVar`	Variable name or `{$varName}` reference
`conditionOp`	Comparison operator (see table below)
`conditionValue`	The value to compare against

Operators by type:

Type	Operators
String	`equals`, `not_equals`, `contains`, `starts_with`, `ends_with`, `matches` (regex)
Number	`equals`, `not_equals`, `gt`, `gte`, `lt`, `lte`
Boolean	`is_true`, `is_false`

Check whether the user is already logged in, and skip the login form if so:

{ "type": "navigate", "value": "https://app.example.com" },
{ "type": "if", "value": "exists('.user-avatar')" },
  { "type": "stop", "value": "success" },
{ "type": "else" },
  { "type": "click", "selector": "#login-button" },
  { "type": "type", "selector": "#email", "value": "{$email}" },
  { "type": "type", "selector": "#password", "value": "{$password}" },
  { "type": "click", "selector": "[type='submit']" },
{ "type": "end" }

Nested Conditions

You can nest if blocks inside each other. Each nested block requires its own end:

{ "type": "if", "value": "exists('.product')" },
  { "type": "if", "value": "text('.stock-status') === 'In Stock'" },
    { "type": "click", "selector": ".add-to-cart" },
  { "type": "else" },
    { "type": "set", "varName": "outOfStock", "value": "true" },
  { "type": "end" },
{ "type": "end" }

While Loop

Executes a block of actions repeatedly as long as the condition remains true.

{ "type": "while", "value": "exists('.next-page')" },
  // actions to repeat
{ "type": "end" }

Common use cases:

Pagination: Click “next page” until there are no more pages.
Polling: Wait for a specific element or state to appear.
Retry logic: Re-attempt an action until it succeeds.

Example: Scraping paginated results

{ "type": "navigate", "value": "https://example.com/listings" },
{ "type": "while", "value": "exists('.pagination .next:not(.disabled)')" },
  { "type": "javascript", "value": "/* collect items on this page */" },
  { "type": "click", "selector": ".pagination .next" },
  { "type": "wait", "value": "1500" },
{ "type": "end" }

Prevent infinite loops by tracking a counter variable:

{ "type": "set", "varName": "pageNum", "value": "1" },
{ "type": "while", "value": "exists('.next') && {$pageNum} <= 10" },
  { "type": "start", "value": "scrape-page-task-id" },
  { "type": "click", "selector": ".next" },
  { "type": "set", "varName": "pageNum", "value": "{$pageNum} + 1" },
{ "type": "end" }

Foreach Loop

Iterates over all elements matching a CSS selector, executing the block once per element.

{ "type": "foreach", "selector": ".product-card" },
  // actions scoped to each element
{ "type": "end" }

Loop variables available inside the block:

Variable	Description
`loop.index`	Zero-based index of the current iteration
`loop.text`	The full text content of the current element
`loop.html`	The full HTML of the current element
`loop.item`	Reference to the current element (for click/interact without a selector)

Example: Clicking each item in a list

{ "type": "foreach", "selector": ".todo-item input[type='checkbox']:not(:checked)" },
  { "type": "click" },
{ "type": "end" }

Example: Extracting data from a table

{ "type": "foreach", "selector": "table tbody tr" },
  { "type": "javascript", "value": "return { row: loop.index, text: loop.text }" },
{ "type": "end" }

Repeat N Times

Executes a block a fixed number of times regardless of any condition.

{ "type": "repeat", "value": "5" },
  // actions to repeat
{ "type": "end" }

The loop.index variable is available inside repeat blocks (zero-based). Example: Submit a form 3 times

{ "type": "repeat", "value": "3" },
  { "type": "click", "selector": "#submit-btn" },
  { "type": "wait", "value": "2000" },
{ "type": "end" }

Error Handling (On Error)

The On Error block acts like a try/catch. If any action in the main flow throws an error (timeout, element not found, network failure), execution jumps to the error handler block.

{ "type": "on_error" },
  // recovery actions
{ "type": "end" }

Example: Handle a CAPTCHA popup

{ "type": "navigate", "value": "https://example.com" },
{ "type": "click", "selector": ".login-button" },
{ "type": "on_error" },
  { "type": "if", "value": "exists('.captcha-frame')" },
    { "type": "stop", "value": "error" },
  { "type": "end" },
{ "type": "end" }

Example: Dismiss a cookie banner that may or may not appear

{ "type": "on_error" },
{ "type": "end" },
{ "type": "click", "selector": "#cookie-accept", "timeout": 3000 },

Placing an empty on_error/end block before an optional action effectively makes that action non-fatal. See Error Handling for a deeper guide on retry patterns and resilient task design.

Stop Task

Immediately terminates the current task execution with a given status.

{ "type": "stop", "value": "success" }
{ "type": "stop", "value": "error" }

Use stop inside conditionals to short-circuit execution when a goal is already met or when an unrecoverable state is detected.

Intro

Installation

Basics

Features

Agent Logic

Integrations

API

Ops

Changelog

Conditional Execution (If / Else / End)

Structure

Condition Types

Nested Conditions

While Loop

Foreach Loop

Repeat N Times

Error Handling (On Error)

Stop Task

​Conditional Execution (If / Else / End)

​Structure

​Condition Types

​Example: Login Check

​Nested Conditions

​While Loop

​Foreach Loop

​Repeat N Times

​Error Handling (On Error)

​Stop Task

Conditional Execution (If / Else / End)

Structure

Condition Types

Example: Login Check

Nested Conditions

While Loop

Foreach Loop

Repeat N Times

Error Handling (On Error)

Stop Task