> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optexity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automation Structure

> Understanding the structure of Optexity automations

Optexity uses a declarative model for browser automation. Define **what** actions to perform, and Optexity handles the **how** using AI-assisted element location.

## Overview

```
Automation
├── url                  # Starting point
├── browser_channel      # "chromium" or "chrome"
├── os_emulation         # OS to emulate: "windows", "linux", or null
├── max_retries          # Total run attempts on failure (default: 1)
├── expected_downloads   # Number of files to download
├── parameters           # Input, secure, and generated variables
└── nodes[]              # Sequence of actions
    ├── action_node
    ├── for_loop_node
    └── if_else_node
```

## Complete Example

```json theme={null}
{
  "url": "https://example.com/login",
  "browser_channel": "chromium",
  "os_emulation": null,
  "max_retries": 1,
  "expected_downloads": 0,
  "parameters": {
    "input_parameters": {
      "email": ["user@example.com"]
    },
    "secure_parameters": {},
    "generated_parameters": {}
  },
  "nodes": [
    {
      "type": "action_node",
      "interaction_action": {
        "input_text": {
          "command": "get_by_label(\"Email\")",
          "input_text": "{email[0]}"
        }
      }
    }
  ]
}
```

## Properties

| Property             | Type                                                 | Default      | Description                                                                |
| -------------------- | ---------------------------------------------------- | ------------ | -------------------------------------------------------------------------- |
| `url`                | `str`                                                | —            | Starting URL—use the URL closest to your target to reduce navigation steps |
| `browser_channel`    | `"chromium" \| "chrome"`                             | `"chromium"` | Browser to use                                                             |
| `os_emulation`       | `"windows" \| "linux" \| null`                       | `null`       | OS user-agent to emulate; `null` uses the default system OS                |
| `max_retries`        | `int`                                                | `0`          | Total number of run attempts. `0` = no retry, `1` = one retry, etc.        |
| `expected_downloads` | `int`                                                | `0`          | Number of expected downloads (automation waits for completion)             |
| `parameters`         | `Parameters`                                         | —            | Input, secure, and generated variables                                     |
| `nodes`              | `list[action_node \| for_loop_node \| if_else_node]` | —            | Ordered list of actions                                                    |

## Parameters

Three types of parameters control data flow:

| Type                   | Purpose                            | Example                         |
| ---------------------- | ---------------------------------- | ------------------------------- |
| `input_parameters`     | Values provided before execution   | Username, search queries        |
| `secure_parameters`    | Sensitive data from secure storage | Passwords, API keys             |
| `generated_parameters` | Values extracted during execution  | Order IDs, confirmation numbers |

```json theme={null}
{
  "parameters": {
    "input_parameters": {
      "username": ["admin@example.com"]
    },
    "secure_parameters": {
      "password": [{
        "onepassword": {
          "vault_name": "vault",
          "item_name": "login",
          "field_name": "password"
        }
      }]
    },
    "generated_parameters": {
      "order_ids": []
    }
  }
}
```

<Tip>
  See [Parameters](/docs/building-automations/parameters) for detailed usage.
</Tip>

## Node Types

| Node            | Purpose               | Documentation                                             |
| --------------- | --------------------- | --------------------------------------------------------- |
| `action_node`   | Single atomic action  | [Action Node](/docs/building-automations/action-node)     |
| `for_loop_node` | Iterate over values   | [For Loop Node](/docs/building-automations/for-loop-node) |
| `if_else_node`  | Conditional execution | [If Else Node](/docs/building-automations/if-else-node)   |

## Browser Channel

| Channel      | Use When                                                                     |
| ------------ | ---------------------------------------------------------------------------- |
| `"chromium"` | Default, works for most sites                                                |
| `"chrome"`   | Site requires Chrome specifically, or automation is unreliable with Chromium |

```json theme={null}
{
  "browser_channel": "chrome"
}
```

## Expected Downloads

Set this to wait for file downloads to complete:

```json theme={null}
{
  "expected_downloads": 3
}
```

The automation waits until all expected files are downloaded before completing.

## OS Emulation

Override the OS reported in the browser's user-agent string:

| Value       | Use When                                                         |
| ----------- | ---------------------------------------------------------------- |
| `null`      | Default — uses the host system's OS (recommended for most sites) |
| `"windows"` | Site behaves differently on Windows (e.g. Windows-only portals)  |
| `"linux"`   | Site behaves differently on Linux                                |

```json theme={null}
{
  "os_emulation": "windows"
}
```

<Tip>
  Only set `os_emulation` when a site serves different content or layouts based on the OS. Leave it as `null` otherwise.
</Tip>

## Max Retries

Control how many times the full automation reruns when an unexpected error occurs:

```json theme={null}
{
  "max_retries": 3
}
```

| Value         | Behavior                              |
| ------------- | ------------------------------------- |
| `1` (default) | Runs once; fails immediately on error |
| `2`           | Runs up to twice (1 retry)            |
| `3`           | Runs up to three times (2 retries)    |

<Info>
  `max_retries` is the **total number of attempts**, not the number of extra retries. `AssertionError` failures are never retried regardless of this value.
</Info>

<Tip>
  See [Timing & Retries](/docs/advanced/timing-retries) for controlling per-element retry behavior (`max_tries`) vs. full-automation retries (`max_retries`).
</Tip>