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

JavaScript Expression
Structured Condition
Selector Condition

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

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`
Selector	`exists`, `not_exists`

Set conditionVarType to selector to branch on whether an element is currently present in the DOM. Figranium runs document.querySelector(selector) against the live page each time the condition is evaluated.

Field	Description
`conditionVarType`	`selector`
`selector`	CSS selector to check against the current page. Supports template variables like `{$productId}`.
`conditionOp`	`exists` (element is present) or `not_exists` (element is absent).

Use the target icon next to the selector input to pick the element with the Highlight Tool instead of typing the selector by hand.Example: Skip a modal only when it’s showing

{ "type": "navigate", "value": "https://example.com" },
{ "type": "if",
  "conditionVarType": "selector",
  "selector": ".cookie-banner",
  "conditionOp": "exists"
},
  { "type": "click", "selector": ".cookie-banner .accept" },
{ "type": "end" }

Example: Paginate while a “next” button remains

{ "type": "while",
  "conditionVarType": "selector",
  "selector": ".pagination .next:not(.disabled)",
  "conditionOp": "exists"
},
  { "type": "click", "selector": ".pagination .next" },
  { "type": "wait", "value": "1500" },
{ "type": "end" }

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" }

Loop Types

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.

Error Handling

Learn retry patterns and resilient task design.

Variables

Use variables to build dynamic conditions and counters.

JavaScript Execution

Write custom logic for complex conditions.

Modular Workflows

Break complex flows into reusable sub-tasks.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

Conditional Execution (If / Else / End)

Structure

Condition Types

Nested Conditions

Loop Types

Error Handling (On Error)

Stop Task

Error Handling

Variables

JavaScript Execution

Modular Workflows

​Conditional Execution (If / Else / End)

​Structure

​Condition Types

​Example: Login Check

​Nested Conditions

​Loop Types

​Error Handling (On Error)

​Stop Task

Error Handling

Variables

JavaScript Execution

Modular Workflows

Conditional Execution (If / Else / End)

Structure

Condition Types

Example: Login Check

Nested Conditions

Loop Types

Error Handling (On Error)

Stop Task