Form Integration

Form Integration

Forms are the foundation of workflow automation in Aptiwise, capturing the data needed for intelligent routing, approval decisions, and automated processing. This guide covers dynamic form creation, advanced field types, and integration patterns.

📋 Overview

Aptiwise forms are tightly integrated with workflow logic, enabling:

• Dynamic field display based on user input
• Intelligent validation with business rules
• Automated routing based on form data
• Rich field types for complex data collection

🔤 Basic Field Types

Text and Content Fields

form:
  fields:
    - name: "employee_name"
      type: "text"
      label: "Employee Name"
      required: true
      validation:
        min_length: 2
        max_length: 50
        pattern: "^[A-Za-z\\s]+$"

    - name: "description"
      type: "textarea"
      label: "Request Description"
      required: true
      placeholder: "Provide detailed description..."
      validation:
        min_length: 20
        max_length: 1000

    - name: "contact_email"
      type: "email"
      label: "Contact Email"
      required: true
      validation:
        domain_whitelist: ["company.com", "partner.com"]

Numeric and Currency Fields

- name: "quantity"
  type: "number"
  label: "Quantity"
  required: true
  validation:
    min_value: 1
    max_value: 100
    step: 1

- name: "total_amount"
  type: "currency"
  label: "Total Amount"
  required: true
  currency: "USD"  # Optional: defaults to company setting
  validation:
    min: 0.01
    max: 50000

Date and Time Fields

- name: "start_date"
  type: "date"
  label: "Start Date"
  required: true
  validation:
    min_date: "today"
    max_date: "today + 1_year"

- name: "deadline"
  type: "datetime"
  label: "Project Deadline"
  required: true
  timezone_aware: true

🎛️ Selection and Choice Fields

Dropdown and Multi-Select

- name: "department"
  type: "select"
  label: "Department"
  required: true
  options:
    - value: "engineering"
      label: "Engineering"
    - value: "marketing"
      label: "Marketing"
    - value: "sales"
      label: "Sales"
    - value: "hr"
      label: "Human Resources"

- name: "skills_required"
  type: "multiselect"
  label: "Required Skills"
  required: false
  validation:
    min_selections: 1
    max_selections: 5
  options:
    - value: "python"
      label: "Python Programming"
    - value: "javascript"
      label: "JavaScript"
    - value: "data_analysis"
      label: "Data Analysis"

- name: "priority_level"
  type: "radio"
  label: "Priority Level"
  required: true
  options:
    - value: "low"
      label: "Low"
    - value: "medium"
      label: "Medium"
    - value: "high"
      label: "High"
    - value: "critical"
      label: "Critical"

Dynamic Options

- name: "project_manager"
  type: "select"
  label: "Project Manager"
  required: true
  # Dynamic options based on department
  options: |
    {% if department == 'engineering' %}
      {{ engineering_managers }}
    {% elif department == 'marketing' %}
      {{ marketing_managers }}
    {% else %}
      {{ all_managers }}
    {% endif %}

📎 File Upload Fields

Single and Multiple File Uploads

- name: "contract_document"
  type: "file_upload"
  label: "Contract Document"
  required: true
  accept: ".pdf,.doc,.docx"
  multiple: false
  validation:
    max_size: "10MB"

- name: "supporting_documents"
  type: "file_upload"
  label: "Supporting Documents"
  required: false
  accept: ".pdf,.jpg,.png,.doc,.docx"
  multiple: true
  validation:
    max_files: 5
    max_size_per_file: "5MB"
    total_max_size: "20MB"

📊 Advanced Field Types

Line Items (Repeatable Sections)

Perfect for itemized requests like purchase orders or expense reports:

- name: "purchase_items"
  type: "line_items"
  label: "Items to Purchase"
  required: true
  min_items: 1
  max_items: 20

  item_fields:
    - name: "item_description"
      type: "text"
      label: "Description"
      required: true
      validation:
        min_length: 5

    - name: "quantity"
      type: "number"
      label: "Qty"
      required: true
      validation:
        min_value: 1

    - name: "unit_price"
      type: "currency"
      label: "Unit Price"
      required: true
      validation:
        min: 0.01

    - name: "line_total"
      type: "currency"
      label: "Line Total"
      readonly: true
      calculated: true
      formula: "quantity * unit_price"

    - name: "category"
      type: "select"
      label: "Category"
      required: true
      options:
        - value: "office_supplies"
          label: "Office Supplies"
        - value: "equipment"
          label: "Equipment"
        - value: "software"
          label: "Software"

Calculated Fields

- name: "subtotal"
  type: "currency"
  label: "Subtotal"
  readonly: true
  calculated: true
  formula: "sum(purchase_items.line_total)"

- name: "tax_amount"
  type: "currency"
  label: "Tax Amount"
  readonly: true
  calculated: true
  formula: "subtotal * tax_rate"

- name: "grand_total"
  type: "currency"
  label: "Grand Total"
  readonly: true
  calculated: true
  formula: "subtotal + tax_amount"

🔄 Conditional Field Display

Show/Hide Based on Other Fields

- name: "expense_type"
  type: "select"
  label: "Expense Type"
  required: true
  options:
    - value: "travel"
      label: "Travel & Transportation"
    - value: "meals"
      label: "Meals & Entertainment"
    - value: "equipment"
      label: "Equipment Purchase"

# Travel-specific fields
- name: "travel_destination"
  type: "text"
  label: "Travel Destination"
  required: true
  show_if: "expense_type == 'travel'"

- name: "travel_dates"
  type: "date_range"
  label: "Travel Dates"
  required: true
  show_if: "expense_type == 'travel'"

# Meal-specific fields
- name: "meal_attendees"
  type: "textarea"
  label: "Meal Attendees"
  required: true
  show_if: "expense_type == 'meals'"
  placeholder: "List attendees and their companies"

- name: "business_meal_purpose"
  type: "textarea"
  label: "Business Purpose"
  required: true
  show_if: "expense_type == 'meals'"

# Equipment-specific fields
- name: "equipment_category"
  type: "select"
  label: "Equipment Category"
  required: true
  show_if: "expense_type == 'equipment'"
  options:
    - value: "computer"
      label: "Computer/Laptop"
    - value: "monitor"
      label: "Monitor/Display"
    - value: "furniture"
      label: "Office Furniture"

- name: "equipment_justification"
  type: "textarea"
  label: "Business Justification"
  required: true
  show_if: "expense_type == 'equipment'"

Complex Conditional Logic

- name: "manager_approval_required"
  type: "checkbox"
  label: "Manager approval required"
  readonly: true
  calculated: true
  value: |
    {% if total_amount > 1000 or expense_type == 'travel' %}
      true
    {% else %}
      false
    {% endif %}

- name: "approval_documentation"
  type: "file_upload"
  label: "Approval Documentation"
  required: true
  show_if: "manager_approval_required == true"
  accept: ".pdf,.doc,.docx"

🎯 Real-World Form Examples

IT Equipment Request Form

name: "IT Equipment Request"
description: "Request for IT equipment and software"

form:
  sections:
    - name: "requestor_info"
      title: "Requestor Information"
      fields:
        - name: "employee_id"
          type: "text"
          label: "Employee ID"
          required: true
          readonly: true
          default: "${current_user.employee_id}"

        - name: "department"
          type: "select"
          label: "Department"
          required: true
          default: "${current_user.department}"

    - name: "equipment_details"
      title: "Equipment Details"
      fields:
        - name: "equipment_type"
          type: "radio"
          label: "Equipment Type"
          required: true
          options:
            - value: "laptop"
              label: "Laptop/Computer"
            - value: "monitor"
              label: "Monitor"
            - value: "software"
              label: "Software License"
            - value: "other"
              label: "Other Equipment"

        - name: "laptop_specs"
          type: "select"
          label: "Laptop Specifications"
          required: true
          show_if: "equipment_type == 'laptop'"
          options:
            - value: "standard"
              label: "Standard (Office Work)"
            - value: "development"
              label: "Development (Programming)"
            - value: "design"
              label: "Design (Graphics/Video)"

        - name: "software_details"
          type: "line_items"
          label: "Software Requirements"
          show_if: "equipment_type == 'software'"
          min_items: 1
          item_fields:
            - name: "software_name"
              type: "text"
              label: "Software Name"
              required: true
            - name: "license_type"
              type: "select"
              label: "License Type"
              options:
                - value: "individual"
                  label: "Individual License"
                - value: "team"
                  label: "Team License"
            - name: "annual_cost"
              type: "currency"
              label: "Annual Cost"

    - name: "justification"
      title: "Business Justification"
      fields:
        - name: "business_need"
          type: "textarea"
          label: "Business Need"
          required: true
          placeholder: "Explain why this equipment is needed..."

        - name: "productivity_impact"
          type: "select"
          label: "Expected Productivity Impact"
          required: true
          options:
            - value: "low"
              label: "Low Impact"
            - value: "medium"
              label: "Medium Impact"
            - value: "high"
              label: "High Impact"
            - value: "critical"
              label: "Critical for Role"

Purchase Request with Vendor Management

name: "Purchase Request"
description: "Request for goods and services purchase"

form:
  fields:
    - name: "vendor_selection"
      type: "radio"
      label: "Vendor Selection"
      required: true
      options:
        - value: "existing"
          label: "Existing Approved Vendor"
        - value: "new"
          label: "New Vendor (Requires Approval)"

    - name: "existing_vendor"
      type: "select"
      label: "Select Vendor"
      required: true
      show_if: "vendor_selection == 'existing'"
      # Populated from vendor database
      options: "{{ approved_vendors }}"

    - name: "new_vendor_info"
      type: "section"
      label: "New Vendor Information"
      show_if: "vendor_selection == 'new'"
      fields:
        - name: "vendor_name"
          type: "text"
          label: "Vendor Name"
          required: true

        - name: "vendor_contact"
          type: "email"
          label: "Vendor Contact Email"
          required: true

        - name: "vendor_website"
          type: "url"
          label: "Vendor Website"
          required: false

        - name: "vendor_qualification"
          type: "file_upload"
          label: "Vendor Qualification Documents"
          required: true
          accept: ".pdf,.doc,.docx"
          multiple: true

    - name: "purchase_items"
      type: "line_items"
      label: "Items to Purchase"
      required: true
      min_items: 1
      item_fields:
        - name: "item_name"
          type: "text"
          label: "Item Name"
          required: true
        - name: "quantity"
          type: "number"
          label: "Quantity"
          required: true
        - name: "unit_cost"
          type: "currency"
          label: "Unit Cost"
          required: true
        - name: "total_cost"
          type: "currency"
          label: "Total Cost"
          readonly: true
          calculated: true
          formula: "quantity * unit_cost"

    - name: "delivery_requirements"
      type: "section"
      label: "Delivery Requirements"
      fields:
        - name: "delivery_address"
          type: "textarea"
          label: "Delivery Address"
          required: true
          default: "{{ company.default_address }}"

        - name: "required_by_date"
          type: "date"
          label: "Required By Date"
          required: true
          validation:
            min_date: "today + 3_days"

📊 Form Analytics and Optimization

Form Performance Metrics

form_analytics:
  track_metrics:
    - field_completion_rates
    - form_abandonment_points
    - validation_error_frequency
    - completion_time_per_section

  optimization_insights:
    - suggest_field_reordering
    - identify_confusing_fields
    - recommend_help_text_additions
    - highlight_unnecessary_fields

A/B Testing for Forms

form_variants:
  - name: "standard_layout"
    percentage: 50
    layout: "single_column"

  - name: "optimized_layout"
    percentage: 50
    layout: "multi_column"
    features:
      - progressive_disclosure
      - smart_defaults
      - inline_validation

🚀 Best Practices

Form Design Principles

1. Progressive Disclosure: Show fields as needed, not all at once
2. Smart Defaults: Pre-populate fields when possible
3. Clear Labels: Use descriptive, non-technical language
4. Helpful Validation: Provide clear error messages and guidance

Performance Optimization

1. Lazy Loading: Load complex field options only when needed
2. Client-Side Validation: Provide immediate feedback
3. Conditional Rendering: Only render visible fields
4. Data Caching: Cache frequently used dropdown options

User Experience

1. Mobile Responsiveness: Ensure forms work on all devices
2. Keyboard Navigation: Support tab navigation
3. Save Draft: Allow users to save and return to forms
4. Clear Progress: Show form completion progress

---

Next Steps:

• Learn about SLA Tracking for timeout handling
• See form integration in Real Examples