Manual Trigger — Configuration

Minimal Configuration Required The Manual Trigger node has very few required settings — in its simplest form, you only need to save the node with no properties set and the workflow is immediately triggerable from the portal. Additional configuration adds input validation, role restrictions, and controlled response behavior to production-grade workflows.

Properties

Property	Type	Required	Default	Description
`input_schema`	JSON Schema Object	Optional	None	A JSON Schema (Draft 7) definition of the expected input payload. When defined, the portal renders a dynamic form from this schema, allowing non-technical users to fill in structured data before triggering. Also used for input validation — requests not matching the schema are rejected with a `400 Bad Request` response.
`allowed_roles`	Array of Strings	Optional	All authenticated users	List of BizFirstAI role names that are permitted to trigger this workflow. Example: `["hr_manager", "hr_admin", "super_admin"]`. If the calling user's role is not in this list, the trigger returns `403 Forbidden`. Leave empty to allow any authenticated user.
`response_mode`	Enum	Optional	`onReceived`	Controls the HTTP response timing. `onReceived`: responds immediately with the execution ID after the workflow starts (asynchronous). `lastNode`: holds the connection and returns the last node's output when the workflow completes (synchronous, suitable for shorter workflows).
`response_data`	Object / Expression	Optional	`{"status": "started", "execution_id": "{{ $trigger.execution_id }}"}`	The response body returned to the caller when `response_mode` is `onReceived`. Accepts a static JSON object or a BizFirst expression. Typical use is to return the execution ID so the caller can poll for status.
`require_authentication`	Boolean	Optional	`true`	When `true` (the default), the caller must supply a valid BizFirstAI API token or session cookie. Setting this to `false` makes the workflow publicly triggerable — use with extreme caution and only for non-sensitive workflows.
`description`	String	Optional	None	A human-readable description displayed in the portal trigger dialog. Helps users understand what the workflow does and what input data to provide. Supports Markdown formatting.
`trigger_label`	String	Optional	`"Run Workflow"`	The label displayed on the trigger button in the portal UI. Customize to reflect the business action, e.g., `"Start Onboarding"`, `"Generate Invoice"`, `"Submit for Approval"`.

Input Schema Configuration

The input_schema property accepts a standard JSON Schema Draft 7 object. BizFirstAI uses this schema for two purposes: generating a portal form UI for human triggering, and validating API-triggered payloads. Below is an example schema for an employee onboarding trigger:

{
  "type": "object",
  "required": ["employee_name", "employee_email", "department", "start_date"],
  "properties": {
    "employee_name": {
      "type": "string",
      "title": "Full Name",
      "description": "Employee's legal full name"
    },
    "employee_email": {
      "type": "string",
      "format": "email",
      "title": "Work Email Address"
    },
    "department": {
      "type": "string",
      "title": "Department",
      "enum": ["Engineering", "Finance", "HR", "Operations", "Sales", "Marketing"]
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "title": "Start Date"
    },
    "manager_email": {
      "type": "string",
      "format": "email",
      "title": "Manager Email (optional)"
    }
  }
}

Role Configuration

Role names in allowed_roles must exactly match the role slugs defined in your BizFirstAI workspace settings under Settings > Roles & Permissions. Role matching is case-sensitive.

Example Role Slug	Typical Use
`hr_manager`	HR department managers — can trigger onboarding, offboarding, and HR change workflows
`finance_admin`	Finance team — can trigger invoice generation, payment runs, and reconciliation workflows
`super_admin`	Platform administrators — can trigger any workflow regardless of other role restrictions
`developer`	Engineering team — can trigger workflows in non-production environments for testing

Expression Support

Property	Expression Support	Notes
`response_data`	Full expression support	Can reference trigger metadata such as `{{ $trigger.execution_id }}`, `{{ $trigger.triggered_by }}`, and `{{ $trigger.triggered_at }}`.
`input_schema`	No expression support	Schema is a static design-time definition. Dynamic schema generation is not supported.
`allowed_roles`	No expression support	Role list is evaluated at design time. Cannot be dynamically computed per request.

Best Practice: Always Define input_schema in Production For any workflow used by non-developers, define an input_schema. It prevents malformed data from entering the workflow, provides a user-friendly form in the portal, and makes the workflow self-documenting — new users can understand what data the workflow needs just by looking at the form labels and descriptions.

Public Triggers Are a Security Risk Setting require_authentication: false exposes your workflow to the public internet. Only use this for completely non-sensitive operations and consider adding rate limiting at the infrastructure level. For any workflow that accesses internal systems, always keep authentication enabled.