# Events Form System - High-Level Documentation **Last Updated:** 2026-01-28 ## Overview This document provides a high-level understanding of how our events pages/form system works. It's designed for the sales team to understand what data we collect, how it flows to HubSpot, and how the system operates at events like Internorga and Intergastra. --- ## What Is This System? The events form system is a tablet-optimized lead capture tool used at conferences and trade shows. It allows our team to: - Collect contact information from leads at events - Scan business cards using the tablet camera to auto-fill forms - Assign leads to specific team members (owners) - Work offline and sync data when internet connection is restored - Automatically send all leads to HubSpot **Key Events:** - **Intergastra 2026** (February 7-11, 2026) - Stuttgart, Germany - **Internorga 2026** (March 13-17, 2026) - Hamburg, Germany --- ## How It Works - User Flow ### Step 1: Owner Selection When a team member opens the form on a tablet, they first see a grid of names. They select their name (e.g., "Felix", "Daniela", etc.) before handing the tablet to a lead. **Why:** This ensures every lead is assigned to the correct team member automatically. **Available Owners by Event:** **Intergastra 2026 (9 team members):** - Barti, Daniela, David, Felix, Freddie, Kathrin, Lena, Michael, Quirin **Internorga 2026 (12 team members):** - Barti, Constantin, Daniela, David, Felix, Freddie, Jakob, John, Lena, Michelle, Muhammed, Quirin ### Step 2: Form Display After owner selection, the form appears. The team member can hand the tablet to the lead to fill out, or they can fill it out themselves while talking to the lead. ### Step 3: Optional Business Card Scan Leads can use the "Visitenkarte scannen" (Scan Business Card) button to take a photo of their business card. The system automatically extracts: - Name (first and last) - Email address - Phone number - Company name - Job title The form auto-fills with this information, and the lead can review/edit it before submitting. ### Step 4: Form Submission When the form is submitted, the data is: 1. Validated (required fields checked) 2. Sent to HubSpot automatically 3. Assigned to the selected team member (owner) 4. Stored locally if offline (syncs automatically when online) ### Step 5: Success Confirmation After successful submission, a success message appears with an option to "Add Another" contact for quick re-entry. --- ## What Data Do We Collect? ### Required Fields (Must Be Filled) | Field Name | Description | Example | | ------------------------------ | ---------------------------------- | ----------------------------- | | **Kundentyp** (Customer Type) | New customer or existing customer | "Neukunde" or "Bestandskunde" | | **Vorname** (First Name) | Lead's first name | "Max" | | **Nachname** (Last Name) | Lead's last name | "Mustermann" | | **Unternehmensname** (Company) | Company name | "Muster GmbH" | | **E-Mail** (Email) | Email address | "max@beispiel.de" | | **Owner** (Hidden) | Team member who collected the lead | "Felix" | ### Optional Fields | Field Name | Description | Example | | -------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- | | **Anrede** (Salutation) | Mr./Mrs./Diverse | "Herr", "Frau", or "Divers" | | **Telefonnummer** (Phone) | Phone number | "+49 123 456789" | | **Position** (Job Title) | Job position | "Inhaber / Geschäftsführer", "HR / Schichtleitung", "Mitarbeiter", or "Sonstiges" | | **Interessiert an** (Interested In) | Features they're interested in (multi-select) | Schichtplanung, Zeiterfassung, Payroll Plus, etc. | | **Weitere Angaben** (Additional Notes) | Free text notes | Any additional information | ### Available "Interested In" Options All 13 options are available and sent to HubSpot. Leads can select multiple features they're interested in: 1. Schichtplanung (Shift Planning) 2. Zeiterfassung (Time Tracking) 3. Payroll Plus 4. Abwesenheiten (Absences) 5. Digitale Personalakte (Digital Employee File) 6. Dokumentenmanagement (Document Management) 7. AI Agent 8. QR-Code 9. Trinkgeld (Tips) 10. Personaldienstleister (Staffing Services) 11. Hardware Terminals 12. Events 13. Checklisten (Checklists) --- ## What Gets Sent to HubSpot? ### HubSpot Form Used **Form Name:** Event Lead Capture Form **Form GUID:** `e9d5fd47-6772-4c0a-943b-8f726afd8e4b` **Form Type:** HubSpot Forms API v3 (Secure) ### Fields Sent to HubSpot All form fields are sent to HubSpot with the following mappings: | Form Field | HubSpot Property | Notes | | ---------------- | ------------------ | ----------------------------------------- | | First Name | `firstname` | Direct mapping | | Last Name | `lastname` | Direct mapping | | Email | `email` | Primary identifier | | Company | `company` | Direct mapping | | Customer Type | `customer_type__c` | "Neukunde" or "Bestandskunde" | | Salutation | `salutation` | "Herr", "Frau", or "Divers" | | Phone | `phone` | Normalized format | | Job Title | `jobtitle` | Position selected | | Interested In | `interested_in__c` | Comma-separated list of selected features | | Additional Notes | `description` | Free text notes | ### Automatic Tracking Fields These fields are automatically set by the system (not visible in the form): | Field | HubSpot Property | Value | Purpose | | ------------ | --------------------------- | ----------------------------------- | ---------------------------------------------- | | Sign Up Type | `sign_up_type__c` | "Event Lead Capture" | Identifies this as an event lead | | Content | `content` | Event name (e.g., "Intergastra 26") | Tracks which event | | Lead Status | `hs_lead_status` | "NEW" | Marks as new lead | | Record Type | `record_type_id__dropdown_` | "012aa0000013oZCAAY" | Sets as "Inbound" record type | | Source | `source__c` | "Trade Fair" | Categorizes all event leads consistently | | Owner | `utm_medium__c` | Team member name (e.g., "Daniela") | Used by HubSpot workflow for lead distribution | ### UTM Tracking (If Available) If the form URL includes UTM parameters (e.g., from email campaigns), these are also captured: - `utm_source` → `source__c` - `utm_medium` → `utm_medium__c` - `utm_campaign` → `utm_campaign__c` - `utm_term` → `utm_term__c` - `utm_content` → `content__c` - `gclid` → `gclid__c` (Google Click ID) --- ## Owner Assignment Logic ### How Owners Are Tracked for Distribution 1. **Team member selects their name** from the grid before the form appears 2. **Form submission includes owner name** (e.g., "Felix", "Daniela") 3. **System sets `utm_medium__c`** to the owner name in HubSpot 4. **HubSpot workflow handles distribution** - A separate HubSpot workflow reads `utm_medium__c` and distributes leads using round robin or direct assignment logic ### Workflow-Based Distribution The system does NOT directly assign owners to contacts. Instead: - **Owner name is stored** in `utm_medium__c` field (e.g., "Daniela", "Felix") - **HubSpot workflow** reads `utm_medium__c` and assigns the contact to the appropriate team member - **Distribution method** can be configured in HubSpot (round robin, direct assignment, etc.) - **Benefits**: More flexible distribution logic, easier to change assignment rules without code changes ### Owner Name Format - Owner names are sanitized before being set to `utm_medium__c` - Only alphanumeric characters, spaces, and hyphens are allowed - Invalid characters are removed automatically - Owner name is logged for debugging purposes --- ## Business Card Scanning (OCR) - How It Works ### Overview The system uses Google Cloud Vision API to extract text from business card photos taken with the tablet camera. ### What Gets Extracted The OCR system attempts to extract: 1. **Name** → Split into first name and last name 2. **Email** → Validated for proper format 3. **Phone** → Normalized to international format (+49...) 4. **Company** → Recognizes German legal forms (GmbH, AG, UG, etc.) 5. **Job Title** → Matches common German/English job titles ### How It Works (High-Level) 1. **Photo Capture** - Lead takes photo of business card using tablet camera 2. **Image Processing** - Photo is sent to Google Cloud Vision API 3. **Text Extraction** - API extracts all text from the image 4. **Smart Parsing** - System uses multiple strategies to identify: - Which text is the name (usually top-left) - Which text is the company (usually center) - Which text is contact info (email, phone) - Which text is the job title 5. **Data Validation** - Extracted data is validated: - Email format checked - Phone number normalized - Names cleaned (removes titles like "Herr", "Dr.") 6. **Auto-Fill** - Form fields are automatically filled with extracted data 7. **Review & Edit** - Lead can review and edit any fields before submitting ### OCR Accuracy - **High accuracy** for standard business card layouts - **German-specific** - Recognizes German names, addresses, phone formats, company types - **Multi-strategy parsing** - Uses multiple methods to improve accuracy - **Confidence scoring** - System rates how confident it is in each extracted field ### What Happens If OCR Fails? - User-friendly error message displayed - Form remains available for manual entry - No data is lost - lead can still fill out form manually --- ## Offline Functionality ### How Offline Mode Works The form can work even without internet connection: 1. **Detection** - System detects when device is offline 2. **Local Storage** - Submissions are saved locally on the tablet 3. **Queue Management** - Up to 100 submissions can be queued 4. **Automatic Sync** - When internet connection is restored, all queued submissions are automatically sent to HubSpot 5. **Retry Logic** - Failed submissions are retried automatically (up to 10 attempts) ### User Experience - **Offline Indicator** - Shows when device is offline - **Queue Count** - Displays number of pending submissions - **Sync Status** - Shows when syncing is in progress - **Manual Retry** - Button to manually retry failed submissions --- ## Event URLs ### Intergastra 2026 **Primary URL:** `/events/intergastra-2026` **Short URLs:** `/intergastra-2026` or `/intergastra` (both redirect to primary) **With Owner Pre-Selected:** ``` https://www.ordio.com/events/intergastra-2026?owner=Felix ``` (Form appears immediately, skips owner selection screen) **Without Owner:** ``` https://www.ordio.com/events/intergastra-2026 ``` (Owner selection screen appears first) ### Internorga 2026 **Primary URL:** `/events/internorga-2026` **Short URLs:** `/internorga-2026` or `/internorga` (both redirect to primary) **With Owner Pre-Selected:** ``` https://www.ordio.com/events/internorga-2026?owner=Michael ``` **Without Owner:** ``` https://www.ordio.com/events/internorga-2026 ``` --- ## Key Configuration Values ### HubSpot Integration - **Portal ID:** `145133546` - **API Type:** Forms API v3 (Secure) - **Form GUID:** `e9d5fd47-6772-4c0a-943b-8f726afd8e4b` - **Authentication:** Bearer token (secure) ### OCR Integration - **Service:** Google Cloud Vision API - **Feature:** Document Text Detection - **Languages:** German (`de`) and English (`en`) - **Cost:** ~$1.50 per 1,000 images (first 1,000/month free) ### Image Requirements - **Max File Size:** 3MB (becomes ~4MB after encoding) - **Max Dimensions:** 20 megapixels (width × height) - **Min Dimensions:** 100×100 pixels - **Supported Formats:** JPEG, PNG, WebP --- ## Common Questions ### Q: What if a lead doesn't want to fill out the form? **A:** Team members can fill it out themselves while talking to the lead, or use the business card scanner for quick entry. ### Q: What if the tablet loses internet connection? **A:** The form works offline. All submissions are saved locally and automatically synced when connection is restored. ### Q: Can we change which team members appear in the owner list? **A:** Yes, but this requires a code update. Contact Hady with the event ID and new owner list. ### Q: What if OCR doesn't extract the data correctly? **A:** The form auto-fills with what it extracted, but all fields can be manually edited before submission. ### Q: How do we know which leads came from which event? **A:** The `content` field in HubSpot contains the event name (e.g., "Intergastra 26"). The `source__c` field is set to "Trade Fair" for all event submissions to categorize them consistently. ### Q: Can we add new events? **A:** Yes, but this requires adding a new URL route and owner list. Contact Hady. --- ## Troubleshooting ### Form Not Submitting - Check internet connection - Verify all required fields are filled - Check browser console for errors (if technical support needed) ### OCR Not Working - Ensure camera permissions are granted - Check that image is clear and well-lit - Verify business card is in focus - Try manual entry if OCR fails ### Owner Not Assigned - Verify `utm_medium__c` contains the correct owner name in HubSpot - Check that HubSpot workflow is configured to read `utm_medium__c` for distribution - Verify workflow is active and running correctly - Contact HubSpot admin if workflow needs to be set up or updated ### Offline Sync Not Working - Check internet connection - Verify device has storage space - Try manual retry button - Contact support if queue exceeds 100 submissions --- ## Summary The events form system is a comprehensive lead capture tool that: ✅ Collects all necessary contact information ✅ Automatically sends data to HubSpot ✅ Sets owner name in `utm_medium__c` for workflow-based distribution ✅ Works offline with automatic sync ✅ Scans business cards for quick entry ✅ Tracks which event leads came from All leads are automatically created in HubSpot with proper tracking. Owner name is set in `utm_medium__c` for HubSpot workflow to handle lead distribution (round robin or direct assignment). --- **Last Updated:** 2026-01-28 ## Duplicate Prevention The system includes multiple layers of duplicate prevention to ensure leads aren't submitted twice: 1. **Frontend Protection:** - Prevents rapid double-clicks on submit button - Minimum 2 seconds between submission attempts - Submit button disabled immediately on click 2. **API Endpoint Protection:** - Checks for duplicate submissions (same email + same event) within 5 minutes - If duplicate found, returns success without creating new contact - Logs duplicate detection for monitoring 3. **Offline Sync Protection:** - Hash-based duplicate detection in offline queue - Prevents duplicates when syncing offline submissions **If a contact appears twice in HubSpot:** - Check if submissions were more than 5 minutes apart (allowed) - Check if different events (allowed) - Check logs for duplicate detection events - Contact Hady if issue persists ## Interested In Field Format The "Interested In" field is sent to HubSpot in a specific format: - **Format:** Semicolon-separated (e.g., "Schichtplanung;Events") - **Not:** Comma-separated (e.g., "Schichtplanung,Events") **Value Validation:** - All 13 values are allowed in HubSpot - Invalid values (not in the allowed list) are automatically filtered out - Warnings are logged for filtered values **Maintained By:** Hady **Questions?** Contact: hady@ordio.com