Form Builder Guide

The InnoQualis Form Builder allows you to create custom, dynamic forms for Deviations and CAPAs. This comprehensive guide covers everything you need to know.

Overview

Form templates allow you to customize the structure and fields of deviation and CAPA forms. Templates consist of:

Templates: Top-level form definitions
Sections: Logical groupings of fields
Fields: Individual form inputs with various types

Quick Start

Accessing the Form Builder

Option A: Via Admin Settings

Navigate to /admin
Click on "Deviation Forms" or "CAPA Forms" tab
Start creating your template

Option B: From Form Creation

Go to /deviations/new or /capa (create mode)
Click "Create Template" in the Form Configuration section
Build your template in the modal

Creating Your First Template

Click "Create Template" or "Add Template"
Enter Template Details:
- Name: e.g., "Standard Manufacturing Deviation Form"
- Description: Brief description of when to use this template
- Set as Default: Check if this should be the default template
Add Sections:
- Click "Add Section"
- Enter section name and description
- Sections help organize your form logically
Add Fields to Sections:
- Click "Add Field" within a section
- Select field type (Text, Date, Select, etc.)
- Enter field name (internal) and label (displayed)
- Configure validation and options as needed
Save Template:
- Click "Save Template"
- Your template is now available for use

Using Templates in Forms

For Deviations:

Go to /deviations/new
In "Form Configuration", select a template from the dropdown
Fill out the dynamic fields that appear
Submit as usual

For CAPAs:

Go to /capa and click "Create CAPA"
In "Form Configuration", select a template
Fill out the dynamic fields
Submit as usual

Field Types

1. Text (`text`)

Single-line text input.

Use for: Names, codes, identifiers

Configuration Example:

{
  "field_type": "text",
  "name": "product_name",
  "label": "Product Name",
  "description": "Enter the product name",
  "is_required": true,
  "configuration": {
    "min_length": 1,
    "max_length": 255,
    "pattern": "^[A-Za-z0-9\\s-]+$"
  }
}

2. Textarea (`textarea`)

Multi-line text input.

Use for: Long descriptions, notes

Configuration Example:

{
  "field_type": "textarea",
  "name": "detailed_description",
  "label": "Detailed Description",
  "description": "Provide a detailed description",
  "is_required": true,
  "configuration": {
    "min_length": 10,
    "max_length": 5000,
    "rows": 6
  }
}

3. Select (`select`)

Dropdown selection with predefined options.

Use for: Predefined choices

Configuration Example:

{
  "field_type": "select",
  "name": "severity_level",
  "label": "Severity Level",
  "description": "Select the severity level",
  "is_required": true,
  "configuration": {
    "options": ["Low", "Medium", "High", "Critical"]
  },
  "default_value": "Medium"
}

4. Number (`number`)

Numeric input with min/max validation.

Use for: Quantities, measurements

Configuration Example:

{
  "field_type": "number",
  "name": "batch_number",
  "label": "Batch Number",
  "description": "Enter the batch number",
  "is_required": true,
  "configuration": {
    "min": 1,
    "max": 999999,
    "step": 1
  }
}

5. Date (`date`)

Date picker input.

Use for: Dates, deadlines

Configuration Example:

{
  "field_type": "date",
  "name": "occurrence_date",
  "label": "Occurrence Date",
  "description": "When did this occur?",
  "is_required": true,
  "configuration": {
    "format": "YYYY-MM-DD",
    "min_date": null,
    "max_date": null
  }
}

6. Boolean (`boolean`)

Checkbox/switch input.

Use for: Yes/No questions, flags

Configuration Example:

{
  "field_type": "boolean",
  "name": "requires_immediate_action",
  "label": "Requires Immediate Action",
  "description": "Check if immediate action is required",
  "is_required": false,
  "default_value": false
}

7. Document Picker (`document_picker`)

Multi-select document picker.

Use for: Linking related documents

Configuration Example:

{
  "field_type": "document_picker",
  "name": "related_documents",
  "label": "Related Documents",
  "description": "Select related documents",
  "is_required": false,
  "configuration": {
    "allow_multiple": true,
    "filter_by_type": null
  },
  "default_value": []
}

8. CAPA Picker (`capa_picker`)

Multi-select CAPA picker (for deviation forms).

Use for: Linking related CAPAs

Configuration Example:

{
  "field_type": "capa_picker",
  "name": "related_capas",
  "label": "Related CAPAs",
  "description": "Select related CAPAs",
  "is_required": false,
  "configuration": {
    "allow_multiple": true,
    "filter_by_status": null
  },
  "default_value": []
}

9. Deviation Picker (`deviation_picker`)

Multi-select deviation picker (for CAPA forms).

Use for: Linking related deviations

Configuration Example:

{
  "field_type": "deviation_picker",
  "name": "related_deviations",
  "label": "Related Deviations",
  "description": "Select related deviations",
  "is_required": false,
  "configuration": {
    "allow_multiple": true,
    "filter_by_status": null
  },
  "default_value": []
}

10. Image (`image`)

Image upload with preview.

Use for: Evidence, photos

Configuration Example:

{
  "field_type": "image",
  "name": "evidence_images",
  "label": "Evidence Images",
  "description": "Upload evidence images",
  "is_required": false,
  "configuration": {
    "allowed_types": ["jpg", "jpeg", "png", "gif"],
    "max_size_mb": 10,
    "allow_multiple": true
  },
  "default_value": []
}

11. File (`file`)

File upload.

Use for: Documents, attachments

Configuration Example:

{
  "field_type": "file",
  "name": "supporting_documents",
  "label": "Supporting Documents",
  "description": "Upload supporting documents",
  "is_required": false,
  "configuration": {
    "allowed_types": ["pdf", "doc", "docx", "xls", "xlsx"],
    "max_size_mb": 25,
    "allow_multiple": true
  },
  "default_value": []
}

Complete Template Examples

Standard Manufacturing Deviation Form

{
  "name": "Standard Manufacturing Deviation Form",
  "description": "Comprehensive form for manufacturing deviations",
  "is_default": true,
  "is_active": true,
  "sections": [
    {
      "name": "Product Information",
      "description": "Details about the affected product",
      "order_index": 0,
      "is_required": true,
      "fields": [
        {
          "field_type": "text",
          "name": "product_name",
          "label": "Product Name",
          "description": "Name of the affected product",
          "order_index": 0,
          "is_required": true,
          "is_visible": true,
          "configuration": {
            "max_length": 255
          }
        },
        {
          "field_type": "text",
          "name": "batch_number",
          "label": "Batch Number",
          "description": "Batch or lot number",
          "order_index": 1,
          "is_required": true,
          "configuration": {
            "pattern": "^[A-Z0-9-]+$"
          }
        },
        {
          "field_type": "number",
          "name": "quantity_affected",
          "label": "Quantity Affected",
          "description": "Number of units affected",
          "order_index": 2,
          "is_required": false,
          "configuration": {
            "min": 0,
            "step": 1
          }
        }
      ]
    },
    {
      "name": "Deviation Details",
      "description": "Detailed information about the deviation",
      "order_index": 1,
      "is_required": true,
      "fields": [
        {
          "field_type": "date",
          "name": "occurrence_date",
          "label": "Occurrence Date",
          "description": "When did the deviation occur?",
          "order_index": 0,
          "is_required": true,
          "configuration": {
            "format": "YYYY-MM-DD"
          }
        },
        {
          "field_type": "select",
          "name": "deviation_category",
          "label": "Deviation Category",
          "description": "Category of deviation",
          "order_index": 1,
          "is_required": true,
          "configuration": {
            "options": [
              "Documentation",
              "Process",
              "Equipment",
              "Material",
              "Environmental",
              "Personnel",
              "Other"
            ]
          }
        },
        {
          "field_type": "textarea",
          "name": "detailed_description",
          "label": "Detailed Description",
          "description": "Provide a detailed description of the deviation",
          "order_index": 2,
          "is_required": true,
          "configuration": {
            "min_length": 20,
            "max_length": 5000,
            "rows": 8
          }
        },
        {
          "field_type": "boolean",
          "name": "requires_immediate_action",
          "label": "Requires Immediate Action",
          "description": "Check if immediate action is required",
          "order_index": 3,
          "is_required": false,
          "default_value": false
        }
      ]
    },
    {
      "name": "Evidence and Documentation",
      "description": "Supporting evidence and related documents",
      "order_index": 2,
      "is_required": false,
      "fields": [
        {
          "field_type": "image",
          "name": "evidence_images",
          "label": "Evidence Images",
          "description": "Upload photos of the deviation",
          "order_index": 0,
          "is_required": false,
          "configuration": {
            "allowed_types": ["jpg", "jpeg", "png"],
            "max_size_mb": 10,
            "allow_multiple": true
          },
          "default_value": []
        },
        {
          "field_type": "document_picker",
          "name": "related_documents",
          "label": "Related Documents",
          "description": "Select related SOPs or documents",
          "order_index": 1,
          "is_required": false,
          "configuration": {
            "allow_multiple": true
          },
          "default_value": []
        },
        {
          "field_type": "file",
          "name": "supporting_files",
          "label": "Supporting Files",
          "description": "Upload additional supporting files",
          "order_index": 2,
          "is_required": false,
          "configuration": {
            "allowed_types": ["pdf", "doc", "docx", "xls", "xlsx"],
            "max_size_mb": 25,
            "allow_multiple": true
          },
          "default_value": []
        }
      ]
    }
  ]
}

Standard CAPA Form

{
  "name": "Standard CAPA Form",
  "description": "Comprehensive CAPA form with corrective and preventive actions",
  "is_default": true,
  "is_active": true,
  "sections": [
    {
      "name": "CAPA Overview",
      "description": "Basic information about the CAPA",
      "order_index": 0,
      "is_required": true,
      "fields": [
        {
          "field_type": "deviation_picker",
          "name": "related_deviations",
          "label": "Related Deviations",
          "description": "Select deviations this CAPA addresses",
          "order_index": 0,
          "is_required": false,
          "configuration": {
            "allow_multiple": true
          },
          "default_value": []
        },
        {
          "field_type": "date",
          "name": "target_completion_date",
          "label": "Target Completion Date",
          "description": "Expected completion date",
          "order_index": 1,
          "is_required": true,
          "configuration": {
            "format": "YYYY-MM-DD"
          }
        }
      ]
    },
    {
      "name": "Root Cause Analysis",
      "description": "Analysis of the root cause",
      "order_index": 1,
      "is_required": true,
      "fields": [
        {
          "field_type": "select",
          "name": "root_cause_category",
          "label": "Root Cause Category",
          "description": "Category of root cause",
          "order_index": 0,
          "is_required": true,
          "configuration": {
            "options": [
              "Man",
              "Machine",
              "Method",
              "Material",
              "Measurement",
              "Environment"
            ]
          }
        },
        {
          "field_type": "textarea",
          "name": "root_cause_description",
          "label": "Root Cause Description",
          "description": "Detailed description of the root cause",
          "order_index": 1,
          "is_required": true,
          "configuration": {
            "min_length": 20,
            "max_length": 5000,
            "rows": 6
          }
        }
      ]
    },
    {
      "name": "Corrective Actions",
      "description": "Actions to correct the immediate issue",
      "order_index": 2,
      "is_required": true,
      "fields": [
        {
          "field_type": "textarea",
          "name": "corrective_action_description",
          "label": "Corrective Action Description",
          "description": "Describe the corrective action",
          "order_index": 0,
          "is_required": true,
          "configuration": {
            "min_length": 10,
            "max_length": 5000,
            "rows": 6
          }
        },
        {
          "field_type": "date",
          "name": "corrective_action_due_date",
          "label": "Corrective Action Due Date",
          "description": "When should this action be completed?",
          "order_index": 1,
          "is_required": true,
          "configuration": {
            "format": "YYYY-MM-DD"
          }
        },
        {
          "field_type": "text",
          "name": "responsible_party",
          "label": "Responsible Party",
          "description": "Who is responsible for this action?",
          "order_index": 2,
          "is_required": true,
          "configuration": {
            "max_length": 255
          }
        }
      ]
    }
  ]
}

Best Practices

Template Organization

Use Descriptive Names: "Standard Manufacturing Deviation Form" vs "Form 1"
Organize by Use Case: Create templates for different scenarios
Set Clear Descriptions: Help users know when to use each template

Section Structure

Logical Grouping: Group related fields together
Order Matters: Put most important sections first
Clear Section Names: "Product Information" vs "Section 1"

Field Design

Clear Labels: Use descriptive labels users will understand
Help Text: Add descriptions to guide users
Required Fields: Mark only truly required fields
Default Values: Provide sensible defaults where appropriate

Validation

Text Fields: Set appropriate min/max lengths
Number Fields: Define min/max ranges
Select Fields: Provide all necessary options
File Uploads: Set reasonable size limits

Managing Templates

Clone a Template

Find the template in the admin page
Click "Clone"
Modify as needed
Save with a new name

Set Default Template

Click "Set as Default" on any template
This becomes the default for new forms
Only one default can exist at a time

Activate/Deactivate

Templates can be activated or deactivated
Inactive templates won't appear in selectors
Existing forms retain their template even if deactivated

Edit Template

Click "Edit" on any template
Modify sections and fields
Save changes
Note: Changes only affect new forms, not existing ones

Troubleshooting

Template Not Appearing

Check if template is marked as "Active"
Verify you're looking in the correct form type (Deviation vs CAPA)
Refresh the page

Fields Not Showing

Ensure template is selected in form
Check if fields are marked as "Visible"
Verify template has sections and fields

Validation Errors

Check field configuration (min/max, patterns)
Verify required fields are filled
Check file size limits for uploads

Can't Set Default

Only one default template allowed
Unset existing default first
Then set new default

Advanced Features

AI Suggestions

Enable AI-powered value suggestions for fields:

Set enable_ai_suggestion: true
Specify ai_suggestion_field (e.g., "description")
AI will suggest values based on form context

Conditional Fields

Use is_visible to control field visibility:

Fields can be hidden by default
Show/hide based on other field values (requires frontend logic)

Link related documents, deviations, or CAPAs:

Use document_picker for documents
Use deviation_picker for deviations (CAPA forms)
Use capa_picker for CAPAs (deviation forms)

Template Structure Reference

Basic Template JSON Structure

{
  "name": "Template Name",
  "description": "Template description",
  "is_default": false,
  "is_active": true,
  "sections": [
    {
      "name": "Section Name",
      "description": "Section description",
      "order_index": 0,
      "is_required": false,
      "fields": [
        {
          "field_type": "text",
          "name": "field_name",
          "label": "Field Label",
          "description": "Help text",
          "order_index": 0,
          "is_required": true,
          "is_visible": true,
          "configuration": {},
          "default_value": null
        }
      ]
    }
  ]
}

API Usage

Creating a Template

POST /api/admin/deviation-form-templates/
# or
POST /api/admin/capa-form-templates/

{
  "name": "My Custom Template",
  "description": "Template description",
  "is_default": false,
  "is_active": true,
  "sections": [...]
}

Using a Template in Forms

When creating a deviation or CAPA, include:

{
  "title": "Deviation Title",
  "description": "Description",
  "form_template_id": 1,
  "form_data": {
    "product_name": "Product XYZ",
    "batch_number": "BATCH-123",
    "quantity_affected": 100
  },
  "related_document_ids": [1, 2, 3],
  "related_deviation_ids": [4, 5],
  "attachment_ids": [10, 11]
}

Migration Notes

When updating templates:

Existing forms retain their original template structure
Changes to templates only affect new forms
Clone templates to create variations
Set is_default to make a template the default for new forms

Overview​

Quick Start​

Accessing the Form Builder​

Creating Your First Template​

Using Templates in Forms​

For Deviations:​

For CAPAs:​

Field Types​

1. Text (text)​

2. Textarea (textarea)​

3. Select (select)​

4. Number (number)​

5. Date (date)​

6. Boolean (boolean)​

7. Document Picker (document_picker)​

8. CAPA Picker (capa_picker)​

9. Deviation Picker (deviation_picker)​

10. Image (image)​

11. File (file)​

Complete Template Examples​

Standard Manufacturing Deviation Form​

Standard CAPA Form​

Best Practices​

Template Organization​

Section Structure​

Field Design​

Validation​

Managing Templates​

Clone a Template​

Set Default Template​

Activate/Deactivate​

Edit Template​

Troubleshooting​

Template Not Appearing​

Fields Not Showing​

Validation Errors​

Can't Set Default​

Advanced Features​

AI Suggestions​

Conditional Fields​

Related Items​

Template Structure Reference​

Basic Template JSON Structure​

API Usage​

Creating a Template​

Using a Template in Forms​

Migration Notes​

Overview

Quick Start

Accessing the Form Builder

Creating Your First Template

Using Templates in Forms

For Deviations:

For CAPAs:

Field Types

1. Text (`text`)

2. Textarea (`textarea`)

3. Select (`select`)

4. Number (`number`)

5. Date (`date`)

6. Boolean (`boolean`)

7. Document Picker (`document_picker`)

8. CAPA Picker (`capa_picker`)

9. Deviation Picker (`deviation_picker`)

10. Image (`image`)

11. File (`file`)

Complete Template Examples

Standard Manufacturing Deviation Form

Standard CAPA Form

Best Practices

Template Organization

Section Structure

Field Design

Validation

Managing Templates

Clone a Template

Set Default Template

Activate/Deactivate

Edit Template

Troubleshooting

Template Not Appearing

Fields Not Showing

Validation Errors

Can't Set Default

Advanced Features

AI Suggestions

Conditional Fields

Related Items

Template Structure Reference

Basic Template JSON Structure

API Usage

Creating a Template

Using a Template in Forms

Migration Notes