Form Trigger — Configuration

Form Schema Drives the UI The form_schema property is the core configuration of the Form Trigger. BizFirstAI reads the schema and automatically generates a fully functional, validated HTML form page. You never need to write HTML or manage a separate form builder — the schema is the single source of truth for both UI generation and server-side validation.

Properties

Property	Type	Required	Default	Description
`form_schema`	JSON Schema Object	Required	None	A JSON Schema (Draft 7) definition of all form fields. Each property in the schema becomes a form field. Supports `type`, `title`, `description`, `enum` (dropdowns), `format` (email, date, uri), `minLength`, `maxLength`, `minimum`, `maximum`, and `required` arrays. See the schema section below for a full example.
`title`	String	Required	None	The form page heading displayed to the user, e.g., `"Employee Leave Request"`. Rendered as an H1 on the form page. Maximum 120 characters.
`description`	String	Optional	None	Introductory text shown to the user above the form fields. Supports Markdown. Use to explain the purpose of the form, what happens after submission, and any specific instructions.
`submit_button_label`	String	Optional	`"Submit"`	Text displayed on the form's submit button. Customize to reflect the action, e.g., `"Submit Leave Request"`, `"Send Onboarding Info"`, `"Raise Support Ticket"`.
`assigned_to`	Object	Optional	None (public link)	Specifies who should complete the form. Can be `{"type": "user", "user_id": "usr_..."}}`, `{"type": "email", "email": "user@example.com"}`, or `{"type": "role", "role": "hr_manager"}`. When set, only the specified user(s) can access the form URL. An email notification with the form link is sent automatically.
`expires_in_hours`	Integer	Optional	`null` (no expiry)	Number of hours after form generation before the link expires and the workflow auto-cancels or escalates. Example: `72` for a 3-day deadline. When the form expires, the `on_expiry` action is triggered.
`on_expiry`	Enum	Optional	`cancel`	Action to take when the form expires without submission. `cancel`: workflow execution is marked as cancelled. `escalate`: the workflow resumes via the `expired` output port, allowing escalation logic to be built. `reassign`: the form is reassigned to a backup user defined in `escalation_user`.
`allow_file_uploads`	Boolean	Optional	`false`	When `true`, the form renders a file upload control. Accepted file types and maximum size are configured in the `file_upload_config` sub-object. Uploaded files are stored securely in BizFirstAI's object storage and their URLs are provided in the output data.
`send_confirmation_email`	Boolean	Optional	`true`	When `true`, BizFirstAI sends a submission confirmation email to the submitter after the form is successfully submitted. The email includes the form title and a summary of submitted values.
`success_message`	String	Optional	`"Your submission has been received."`	Message displayed on the form page after successful submission. Supports Markdown. Use to set expectations: confirm what happens next, estimated processing time, or who to contact with questions.

Form Schema Example

Below is a complete form schema for an employee leave request form. Every property maps directly to a form field.

{
  "type": "object",
  "required": ["leave_type", "start_date", "end_date", "reason"],
  "properties": {
    "leave_type": {
      "type": "string",
      "title": "Leave Type",
      "enum": ["Annual Leave", "Sick Leave", "Parental Leave", "Bereavement Leave", "Unpaid Leave"]
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "title": "Leave Start Date"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "title": "Leave End Date"
    },
    "reason": {
      "type": "string",
      "title": "Reason / Notes",
      "description": "Optional context for your manager. Not required for Annual Leave.",
      "maxLength": 500
    },
    "covering_colleague": {
      "type": "string",
      "format": "email",
      "title": "Covering Colleague Email (optional)"
    }
  }
}

Supported Field Types

JSON Schema Type + Format	Rendered Field	Example
`string`	Single-line text input	Name, title, code
`string` + `format: email`	Email input with format validation	Contact email
`string` + `format: date`	Date picker	Start date, due date
`string` + `enum: [...]`	Dropdown select	Department, leave type
`string` + `maxLength > 100`	Multi-line textarea	Description, justification
`number` / `integer`	Numeric input	Amount, quantity
`boolean`	Checkbox	Confirm agreement, opt-in
`array` + `items.enum`	Multi-select checkboxes	Select multiple services

Form Links Are Single-Use by Default Each generated form URL is tied to a specific workflow execution instance and can only be submitted once. Attempting to submit the form a second time (or by a different user if assigned_to is set) returns a 409 Conflict response and does not resume the workflow.

Use expires_in_hours for SLA-Driven Processes For processes with service level agreements — such as support ticket intake (24-hour response SLA) or approval requests (48-hour window) — always configure expires_in_hours and set on_expiry: escalate. This allows the workflow to automatically escalate to a supervisor if the form is not submitted within the required window.