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

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# On dashboard run

> Let organization members run an automation on demand.

`onDashboardRun` lets an organization member start an automation on demand from the Automations page, with optional form fields for run inputs. Use it for approvals, internal requests, maintenance tasks, and other workflows that need a human starting point.

## Example

```ts automations/approval-request.automation.ts theme={null}
import { automation, onDashboardRun, sendEmail, t } from "automate.ax"

export default automation("Request approval", () => {
  const dashboardRun = onDashboardRun({
    title: "Request approval",
    description: "Describe the purchase you want approved.",
    submitLabel: "Run approval request",
    fields: {
      email: {
        type: "email",
        label: "Contact email",
        placeholder: "you@example.com",
      },
      amount: {
        type: "number",
        label: "Amount",
        min: 0,
        step: 0.01,
      },
      priority: {
        type: "select",
        label: "Priority",
        options: [
          { label: "Normal", value: "normal" },
          { label: "Urgent", value: "urgent" },
        ],
      },
      reason: {
        type: "textarea",
        label: "Reason",
        minLength: 10,
      },
      confirmed: {
        type: "checkbox",
        label: "I confirmed these details are correct",
      },
    },
  })

  sendEmail({
    to: "*",
    subject: t`${dashboardRun.data.priority} approval request`,
    text: t`${dashboardRun.triggeredBy.name} requested approval for $${dashboardRun.data.amount}: ${dashboardRun.data.reason}`,
  })
})
```

The Automations page shows a button named with the configured `title` for every deployed dashboard run. Selecting it opens the configured fields in a dialog. Only members of the project's organization can submit the form.

## Form options

| Property      | Type                                | Required | Default | Description                                                                                      |
| ------------- | ----------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
| `title`       | `string`                            | Yes      | —       | Form heading.                                                                                    |
| `description` | `string`                            | No       | —       | Supporting text below the heading.                                                               |
| `fields`      | `Record<string, DashboardRunField>` | Yes      | —       | Named fields, shown in declaration order. Each key becomes a property under `dashboardRun.data`. |
| `submitLabel` | `string`                            | No       | `"Run"` | Run button text.                                                                                 |

Trigger configuration is static and cannot use signals.

## Field types

Every field accepts `label`, optional `description`, and optional `required`. Fields are required by default.

| `type`     | Submitted value             | Options                                               |
| ---------- | --------------------------- | ----------------------------------------------------- |
| `text`     | `string`                    | `placeholder`, `minLength`, `maxLength`               |
| `email`    | `string`                    | `placeholder`, `minLength`, `maxLength`               |
| `url`      | `string`                    | `placeholder`, `minLength`, `maxLength`               |
| `textarea` | `string`                    | `placeholder`, `minLength`, `maxLength`               |
| `number`   | `number`                    | `placeholder`, `min`, `max`, `step` (defaults to `1`) |
| `select`   | The configured option value | `placeholder`, `options: { label, value }[]`          |
| `checkbox` | `boolean`                   | —                                                     |

An optional empty number is `null`; other optional empty text and select fields are `""`. Select values are inferred as a string-literal union from the configured options.

## Trigger data

The trigger emits:

```ts theme={null}
interface DashboardRunEvent<TFields> {
  data: DashboardRunValues<TFields>
  triggeredAt: Date
  triggeredBy: {
    id: string
    email: string
    name: string
  }
}
```

Automate.ax validates required values, email and URL formats, number bounds, string lengths, and select options before starting the automation.