On dashboard run

onDashboardRun lets organization members start an automation from the dashboard, either immediately or with configured form inputs.

Example

automations/approval-request.automation.ts

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: [
      {
        name: "amount",
        type: "number",
        defaultValue: 100,
        min: 0,
        step: 0.01,
      },
      {
        name: "priority",
        type: "select",
        defaultValue: "normal",
        options: [
          { label: "Normal", value: "normal" },
          { label: "Urgent", value: "urgent" },
        ],
      },
      {
        name: "reason",
        type: "textarea",
        minLength: 10,
      },
      {
        name: "confirmed",
        type: "checkbox",
        label: "I confirmed these details are correct",
        required: true,
      },
    ],
  })

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

Each active onDashboardRun trigger appears on the Automations page and the automation’s detail page as a button named with its title. Selecting it opens configured fields in a dialog. description appears below the title when configured. If you omit fields or pass an empty array, selecting the button starts the automation immediately. Only members of the project’s organization can start the run.

Run without fields

automations/record-dashboard-run.automation.ts

import { automation, markSignificant, onDashboardRun } from "automate.ax"

export default automation("Record dashboard run", () => {
  const run = onDashboardRun({ title: "Record test run" })

  markSignificant(run)
})

markSignificant keeps each dashboard test in the default Recent runs view without sending email or changing another service.

Form options

Property	Type	Required	Default	Description
`title`	`string`	Yes	—	Form heading.
`description`	`string`	No	—	Supporting text below the heading.
`fields`	`FormField[]`	No	`[]`	Ordered fields. Each field’s `name` becomes a property under `dashboardRun.data`. Omit fields to run immediately without a dialog.
`submitLabel`	`string`	No	`"Run"`	Run button text.

onDashboardRun configuration is static and can’t use signals.

Field types

Each field requires name and accepts optional label, description, and required. When you omit label, onDashboardRun sentence-cases name: contactEmail becomes Contact email. Inferred checkbox labels also end in a question mark. Array order controls form order. Fields are required by default except checkboxes, which are optional unless you set required: true.

`type`	Submitted value	Options
`text`	`string`	`defaultValue`, `placeholder`, `minLength`, `maxLength`
`textarea`	`string`	`defaultValue`, `placeholder`, `minLength`, `maxLength`
`email`	`string`	`defaultValue`, `placeholder`, `minLength`, `maxLength`
`url`	`string`	`defaultValue`, `placeholder`, `minLength`, `maxLength`
`phone`	`string`	`defaultValue`, `placeholder`, `minLength`, `maxLength`
`number`	`number`	`defaultValue`, `placeholder`, `min`, `max`, `step`. `step` defaults to `1`.
`date`	`string`	`defaultValue`, `min`, `max`, `step` in days. `step` defaults to `1`.
`datetime`	`string`	`defaultValue`, `min`, `max`, `step` in seconds. `step` defaults to `60`.
`select`	The configured option value	`defaultValue`, `placeholder`, `options: { label, value }[]`
`radio`	The configured option value	`defaultValue`, `options: { label, value }[]`
`multi-select`	An array of configured option values	`defaultValue`, `placeholder`, `options: { label, value }[]`
`file`	`File`	No `defaultValue`; set `required: false` to allow no file.
`checkbox`	`boolean`	`defaultValue`. Defaults to `false`.

Use YYYY-MM-DD date values and local YYYY-MM-DDTHH:mm date-time values. An optional empty number or file is null. An optional multi-select is []. Other optional empty text, date, and single-choice fields are "". TypeScript infers choice values as string-literal unions from the configured options. Every defaultValue must satisfy the field’s format, length, option, and min, max, or step constraints.

Trigger data

onDashboardRun emits:

interface DashboardRunEvent<TFields> {
  data: DashboardRunValues<TFields>
  triggeredAt: Date
  triggeredBy: {
    id: string
    email: string
    name: string
  }
}

onDashboardRun validates required values, email and URL formats, string lengths, configured options, and numeric and temporal min, max, and step constraints on the server before starting the automation. When you omit fields, data is an empty object.

Files

Add { name: "document", type: "file" } to let members select a file. The automation receives a File with its contents, filename, and media type. Files are stored directly in the run data. Each file field accepts one file; declare separate fields for separate uploads.

automations/review-document.automation.ts

import { automation, markSignificant, onDashboardRun } from "automate.ax"

export default automation("Review an uploaded document", () => {
  const run = onDashboardRun({
    title: "Upload document",
    fields: [{ name: "document", type: "file" }],
  })

  markSignificant(run)
})

Built-in triggers

Built-in actions

Runtime utilities

Integrations

Example

Run without fields

Form options

Field types

Trigger data

Files

​Example

​Run without fields

​Form options

​Field types

​Trigger data

​Files

Example

Run without fields

Form options

Field types

Trigger data

Files