Forms Module Technical Specifications

Forms has two modes: standard forms (data collection) and survey expansion (campaign-driven research). They share the same infrastructure but serve different purposes.

Survey subsystem capabilities ├── AI analysis — Sentiment, themes, word frequency ├── Campaigns — Lifecycle, send tracking ├── Analytics — NPS / CSAT / CES, distributions, cross-tab ├── Templates — Pre-built library + instantiation └── Scheduling — Automated, deduplicated campaign sends

Event-driven integration: every meaningful action — a new submission, a completed payment, a template being used — triggers real-time updates in CRM, Helpdesk, Marketing, Billing, and Blueprint. No polling, no external middleware.

Classification via the platform AI bridge, with a graceful fallback:

Open-text responses are classified through the platform's AI bridge, which returns an overall breakdown (positive/neutral/negative), a per-response sentiment label with a confidence score, and any notable caveats about the sample size. If no AI provider is configured (or the call fails), analysis falls back to a neutral default rather than failing the request.

Theme extraction:

Responses are clustered into recurring themes via the same AI bridge. Each theme surfaces with a name, a short description, how frequently it appears, and a handful of representative example responses. Returns an empty list when AI is unavailable.

Word frequency:

Returns the top 100 most-mentioned words across all responses (filler words excluded), plus total and unique word counts. This computation is pure text processing — no AI call required.

Analysis options: analyses can be scoped to a date range, a specific text field, or a maximum number of submissions — so you can drill into a subset without recomputing everything.

Scores and distributions are calculated fresh from current submission data — no separate analytics database to keep in sync.

NPS scoring:

``` Promoter: score 9-10 Passive: score 7-8 Detractor: score 0-6

NPS = (promoters / total) × 100 − (detractors / total) × 100 ```

Overview metrics per form: total responses, completion rate (submissions ÷ views), average completion time, NPS (-100 to +100), CSAT average (1–5), and CES average (1–7), all filterable by date range.

Cross-tabulation: pivot any survey field against any other — row field × column field → a count matrix for each combination, e.g. NPS category by industry.

Campaign lifecycle:

draft → active → (paused) → completed

Send lifecycle:

queued → sent → delivered → opened → clicked → responded

Per-campaign stats tracked: total recipients, sent, delivered, opened, clicked, responded, bounced, failed, and response rate.

Response tokens: each recipient gets a unique, cryptographically secure, URL-safe tracking token generated at send time. When they respond, that response links back to their specific send record — enabling accurate per-recipient, per-campaign response tracking.

Scheduled campaign processing runs automatically: campaigns scheduled for a past date/time are activated, reminders go out to non-respondents, and expired survey links are cleaned up.

Templates store a reusable form configuration that can be instantiated into a brand-new, fully independent form:

1. Load the template (by ID or by a human-readable slug)
2. Deep-clone its configuration — the new form shares no references with the template
3. Apply any title/slug overrides
4. Create the new form as a draft, ready to edit
5. Track template usage for popularity/reporting

System templates ship seeded:

• NPS survey (Net Promoter Score 0-10)
• CSAT survey (Customer Satisfaction 1-5)
• CES survey (Customer Effort Score)
• Employee engagement survey
• Event feedback survey
• Product feedback survey
• Training evaluation survey
• Support quality survey

Scheduled campaign sends are processed automatically on an hourly cycle, with built-in protection against duplicate runs if multiple scheduler ticks overlap — so a scheduled send is never accidentally fired twice.

Send worker: processes multiple campaign sends concurrently, batching outbound sends for throughput while respecting provider rate limits.

Standard forms:

• Form definitions — field configuration, settings, form type
• Submission records — field values and submission metadata
• Impression tracking — used to compute completion rate
• Partial (in-progress) saves — resumable for 24 hours via a resume token

Survey expansion:

• Template library — reusable survey configurations
• Campaign records — audience, schedule, status
• Per-recipient send records — token, delivery status
• AI analysis results — linked back to the originating submission

Submission metadata per record: submission time, completion time, device type (desktop, tablet, mobile), and source details (IP, user agent, referrer, landing page, UTM parameters). Field answers are stored as a flexible structured object, so custom fields never require a schema change.