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

# Web Automation

> Run a browser workflow on an external portal and pause the task until it finishes.

Use `await_web_automation_workflow` when an agent needs to operate a web portal outside Nanonets — eligibility checks, EHR workflows, payer portals, or other browser-based work that takes longer than one step.

The flow is asynchronous:

1. The agent submits a workflow and receives a remote task id.
2. The task pauses while the browser workflow runs. A live browser preview can appear in the task feed.
3. When the workflow finishes (success, failure, or cancel), the agent resumes with the result and an optional screenshot.

## Inputs

Required:

* `endpoint_name`: Workflow endpoint name in the browser automation service, for example `verify_patient_eligibility`.
* `input_parameters`: Key/value parameters for the workflow. An empty list is rejected because the remote workflow usually needs portal details, patient fields, or other workflow-specific inputs.

Optional:

* `web_ui_integration_id`: Binding for a connected Web UI connector. The agent does not fill this directly — select a Web UI connection in **Customer Portal Connection** on the configured tool.
* `secure_parameters`: TOTP / authenticator material when the workflow requires MFA.
* `use_proxy`: Routes the workflow through a proxy when the remote service supports it.
* `timeout_minutes`: Maximum minutes the workflow may run. Defaults to the workspace web-automation timeout when omitted. This is also the ceiling the remote service enforces, so it must exceed the workflow's total wall-clock time including any sleep or poll steps — a workflow that waits 20 minutes for a report needs more than 20 here. Set too low, the run is killed without reporting back and a later step fails on missing output rather than on a timeout.

Saved connector credentials are resolved server-side. If a per-run argument supplies the same key as the connector, the connector value wins. This keeps placeholders such as `practice_user` from overriding the selected connection.

## Live browser preview

While the workflow runs, the task feed can show a live browser session. The preview URL is short-lived and fetched through the platform — the browser automation API key never reaches the user's browser.

If the completion webhook is missed, opening the task page can recover the result from the remote service's status and output APIs.

## Web UI connector credentials

Web UI connectors are admin-managed credential connectors for browser portals. They are separate from API and MCP connectors and are used by this tool through the **Customer Portal Connection** binding.

Use this when a workflow needs reusable portal login credentials, such as payer portals, EHR web UIs, or customer-specific browser workflows.

### Admin setup

Open **Web UI Connectors** and create a definition with:

1. **Basics** — a stable service key (for example `bswhealthplan_ui`), a display name, optional icon, and enabled flag. Disabled definitions do not appear on the connectors page.
2. **Validation workflow** — optional workflow endpoint used to test credentials. If blank, new connections become active immediately. If set, new connections start as `pending_validation` until a successful callback or refresh marks them `active`.
3. **Credential fields** — the form users fill when creating a connection. Typical fields are `username`, `password`, and optionally a TOTP secret. Mark password/TOTP fields as sensitive.
4. **Workflow mapping** — maps saved credential fields to workflow parameters as either an **input parameter** or **Secure TOTP**.
5. **Validation static params** — optional non-secret constants such as `portal_url`, `tenant`, or `practice_id` sent only during validation.

### TOTP mapping

Store the TOTP secret as a sensitive credential field, then map it as **Secure TOTP** in the workflow mapping editor.

Example credential field:

```json theme={null}
{
  "name": "totp_secret",
  "label": "TOTP Secret",
  "type": "password",
  "required": false,
  "sensitive": true,
  "order": 3
}
```

Example mapping:

```json theme={null}
{
  "username": "username",
  "password": "password",
  "totp_secret": {
    "parameter": "auth_code",
    "type": "totp",
    "digits": 6
  }
}
```

The remote workflow must declare and use the same secure parameter name, for example `auth_code`.

### Configuring an agent tool

After an admin creates the definition and a user creates an active connection:

1. Open the agent's tool configuration.
2. Add or edit a configured tool using `await_web_automation_workflow`.
3. Set `endpoint_name` to the workflow endpoint, for example `practice_test_login`.
4. Select the active Web UI connection in **Customer Portal Connection**.
5. Add `input_parameters` only for workflow inputs that are not credentials, such as `patient_id`, `member_id`, or `date_of_service`.

The connection picker only shows active Web UI connections. `pending_validation` and `validation_failed` connections are hidden because they are not usable by tools.

### Input parameters vs connector credentials

Use Web UI connector credentials for portal login fields, and `input_parameters` for the rest of the workflow:

```json theme={null}
[
  { "key": "member_id", "value": "M12345" },
  { "key": "date_of_service", "value": "2026-05-27" }
]
```

If both the connector and a per-run argument provide the same key, the connector value wins.

### Validation status

| Status               | Meaning                                                                   |
| -------------------- | ------------------------------------------------------------------------- |
| `active`             | Usable by configured tools.                                               |
| `pending_validation` | Validation workflow was submitted and is waiting for callback or refresh. |
| `validation_failed`  | Validation workflow failed or could not be submitted.                     |

Failed connections can be retried from the connector details page.

## When authoring agent instructions

* Name the exact `endpoint_name` the browser service exposes.
* List the parameters the agent must collect before calling the tool.
* Tell the agent to use `ask_user` when required portal credentials, patient identifiers, or MFA material are missing.
* Set `timeout_minutes` high enough for the portal workflow, especially when human MFA, slow payer portals, or sleep/poll steps are involved. It bounds the remote run as well as the wait, so a value below the workflow's real runtime kills it.