Form (PbotForm)

PbotForm pauses workflow execution to collect structured input from an external party. Unlike PbotApproval (which collects a decision from an internal reviewer), PbotForm collects data from anyone — customers, vendors, partners.

Basic Usage

json

{
  "type": "PbotForm",
  "properties": {
    "expected_keys": ["shipping_address", "delivery_date", "special_instructions"],
    "ttl_seconds": 86400,
    "reminder_intervals": [3600, 7200]
  }
}

When execution reaches this step, the run pauses and waits for form submission.

Properties Reference

Property	Type	Required	Description
`expected_keys`	string[]	Yes	Fields the form expects. Submission must include these keys
`ttl_seconds`	number	No	Time-to-live — how long the form stays open before expiring (default: no expiration)
`reminder_intervals`	number[]	No	Seconds after creation to send reminders. `[3600, 7200]` sends reminders at 1 hour and 2 hours

Submission Flow

sequenceDiagram participant Workflow participant Engine participant External Workflow->>Engine: PbotForm step Engine->>Engine: Run status → "paused" Note over External: Receives form link<br/>(via your app/email) External->>Engine: POST /forms/:runId/:stepIndex/submit Engine->>Engine: Validate expected_keys Engine->>Engine: Run status → "running" Engine->>Workflow: Resume with form data in context

Submitting Form Data

bash

curl -X POST http://localhost:3009/forms/{runId}/0/submit \
  -H "X-Org-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_address": "123 Main St, City, ST 12345",
    "delivery_date": "2025-02-15",
    "special_instructions": "Leave at door"
  }'

POST/forms/:runId/:stepIndex/submit

Submit form data for a paused PbotForm step.

GET/forms/pending

List all pending form requests across the organization.

Context After Submission

The submitted data is added directly to the execution context. Each key from the submission becomes accessible via @path:

json

{
  "type": "schedule_delivery",
  "properties": {
    "address": "@shipping_address",
    "date": "@delivery_date",
    "notes": "@special_instructions"
  }
}

TTL and Expiration

When ttl_seconds is set, the form expires after the specified duration. If the form is not submitted before expiration, the workflow run fails with a timeout error.

Use TTL for time-sensitive workflows where stale input would be harmful — for example, a vendor onboarding form that's only valid for 24 hours.

Reminder Intervals

The reminder_intervals array specifies when reminders should be sent (in seconds after the form is created). This triggers reminder webhook events that your application can use to send follow-up notifications.

json

{
  "reminder_intervals": [3600, 7200, 43200]
}

This sends reminders at 1 hour, 2 hours, and 12 hours after the form is created.

PbotForm vs External Forms

Hyphen has two form mechanisms:

Feature	PbotForm	External Forms
Purpose	Collect input within a workflow	Standalone data collection
Tied to a run	Yes — pauses and resumes a workflow	No — independent
Created via	Workflow step	`POST /external-forms`
Submissions	Single submission resumes the run	Multiple submissions collected
Best for	Vendor provides shipping details mid-workflow	Customer feedback survey

→ Next: Custom Table