Form Builder

The Form Builder lets you create customizable form templates for each module (Deviations, CAPAs, Audits). All three module types are managed from a single unified Form Builder section with a type selector dropdown.

Open the Form Builder

1. On the left sidebar, select Admin.
2. In the admin sidebar under Templates & Forms, select Form Builder.
3. Use the type selector dropdown at the top to switch between:
   • Deviation form templates
   • CAPA form templates
   • Audit form templates

The template list displays all existing form templates for the selected type, showing their name, description, default status, active status, and available actions.

Basic Settings (Deviation and CAPA only)

When Deviation or CAPA is selected in the type selector, a Basic Settings card appears above the template list. It is not shown for Audit.

Type	Setting	Default	Range
Deviation	Default due-in days	30 days	1-365
CAPA	Default due-in days	30 days	1-365

This value seeds a new record’s due date when the record does not set one explicitly: a deviation’s due date defaults to its date_reported/date_detected plus this many days, and a CAPA action defaults the same way from its creation date. Changing the setting only affects records created afterward — it does not retroactively move the due date on existing records.

1. Open the Form Builder and select Deviation or CAPA from the type selector.
2. In the Basic Settings card, enter a number of days (1-365).
3. Select Save.

Create a form template

1. On the template list, select Create Template.
2. Enter a Name for the template.
3. Enter a Description that explains the template’s purpose.
4. Check Is Default to use this template automatically when users create new records.
5. Check Is Active to make the template available immediately.
6. Add sections and fields as described below.
7. Select Save.

Add a section

Sections group related fields under a heading.

1. In the template editor, select Add Section.
2. Enter the section Name (the heading users see).
3. Enter an optional Description to display below the heading.
4. Set the Order Index to control display order (lower numbers appear first).
5. Check Is Required if users must complete this section.

Add a field to a section

1. Within a section, select the field type from the field type selector.
2. Configure the field properties:

Property	Description
Field Type	The type of input control (see supported types below)
Name	Internal field identifier used by the API
Label	Display label shown to users
Description	Helper text displayed below the field
Order Index	Controls display order within the section
Is Required	Whether users must fill in this field
Is Visible	Whether the field is shown (hidden fields can store defaults)
Default Value	Pre-populated value for new records
Enable AI Suggestion	Saved with the field; see Field-level AI suggestion flag below — no form currently reads it
Configuration	Type-specific settings (for example, dropdown options or file size limits)

Supported field types

Field Type	Description	Configuration Options
text	Single-line text input	—
textarea	Multi-line text area	—
select	Dropdown menu	options: Array of choice strings
multi_select	Multi-select list (more than one choice)	options: Array of choice strings
number	Numeric input	—
date	Date picker	—
datetime	Date and time picker	—
boolean	Checkbox (true/false)	—
document_picker	Multi-select document chooser with search	—
capa_picker	Multi-select CAPA chooser with search and status filters	Status filter options: open, in_progress, closed, draft
deviation_picker	Multi-select deviation chooser with search	—
image	Image upload with drag-and-drop, preview, and captions	allowed_types, max_size_mb, allow_multiple
file	File upload	allowed_types, max_size_mb, allow_multiple

Document picker

The document picker field provides a search input to filter documents by title or status, a multi-select list showing matching documents, and selected document tags with individual remove buttons.

CAPA picker

The CAPA picker field provides a search input with debounced API-powered search (searches by ID, title, status, or description), status filter checkboxes (open, in_progress, closed, draft), a multi-select list showing matching CAPAs with creation date and linked deviation count, and selected CAPA tags with individual remove buttons.

Image upload

The image upload field provides a drag-and-drop zone for image files, click-to-browse file selection, configurable allowed file types (default: jpg, jpeg, png, gif), configurable maximum file size (default: 10 MB), an image preview grid with thumbnails, optional caption input per image, and individual image removal.

Edit a form template

1. On the template row, select Edit.
2. Modify the template name, description, sections, or fields as needed.
3. Drag fields using the grip handle to reorder them.
4. Select Save.

Caution

Editing a template that is in use affects all future records created with that template. Existing records retain their original field values, and those values stay visible on the record — see Where the answers appear.

Where the answers appear

Everything a custom field collects is stored on the record and shown back in three places.

On the record page. Deviation and CAPA records show a Custom fields section, titled with the name of the form template the record was created under. Fields appear under their own section headings, in the order the template defines, with the label you gave them.

• A field the template asks for but the record left blank reads Not answered, rather than being hidden. An auditor can tell the difference between a question that was skipped and one that was never asked.
• An asterisk marks a field the template requires as it stands now. A field you make required later shows the asterisk on older records too, which does not mean those records skipped a mandatory question.
• Answers to file, image and picker fields read as record references (#12, #13), not as values someone typed.

In the register exports. The CSV and Excel exports for Deviations and CAPAs append one column per custom field, after the standard columns. The column set comes from the templates actually used by the records being exported, so tenants with several templates get every column that applies. Both the Deviation and the CAPA PDF include them too, but cap them at six — a PDF is a summary, and a page of thirty narrow columns is not readable. The CAPA PDF keeps its existing “CAPA ID” / “Title” / “Status” / “Created” / “Due Date” headers rather than switching to the CSV/Excel column names, so a saved export template does not change shape. Use CSV or Excel when you need every field.

In the audit trail. Creating a Deviation or CAPA through a custom form records the answers in the trail alongside the standard fields, grouped under custom_form_fields. Editing a Deviation’s custom answers (PUT /deviations/{id}/form-data) records the same way, with both the prior and the new values, so the trail shows what changed and not just that it did.

Fields you remove later

Deleting a field from a template does not delete the answers already recorded against it. Records created before the change show those answers under Recorded under fields since removed, so nothing an operator entered disappears from a record after the fact.

Renaming a field’s label changes how it reads on every record, including older ones — the record always displays the label the template carries now.

Changing a field’s type after records exist does not reinterpret older answers — the value is shown as it was stored. The same applies to narrowing a dropdown’s options: an answer that is no longer an offered choice still displays.

Note

Values are read back through the template each time a record is opened. A record created under a template that has since been deleted still shows its answers.

Clone a form template

1. On the template row, select Clone.
2. A copy of the template is created with a modified name (for example, “Copy of Original Template”).
3. Select Edit on the cloned template to customize it.

Tip

Cloning is useful when you need a variation of an existing template for a specific department or process. Clone the base template and modify only the fields that differ.

Set the default template

1. On the template row, select Set as Default.
2. The selected template becomes the default for its module.

Only one template per module can be the default at a time. The default template is automatically used when users create new records in the corresponding module.

Preview a form template

1. On the template row, select the Preview icon (eye icon).
2. Review how the form appears to end users in the preview modal, including all sections and field types.
3. Close the preview to return to the template list.

Download a template definition

1. On the template row, select Download.
2. The template definition file saves to your computer.

Use downloaded definitions for backup, documentation, or transfer to another environment.

Field-level AI suggestion flag

Each field can be marked Enable AI Suggestion while editing a template. The setting is saved with the field, but no form today reads it to change what’s shown — checking it does not currently add an AI suggestion trigger to that field. Live AI suggestions on the deviation form come from a separate, form-wide mechanism (severity classification and similar-deviation matches as you type) rather than from this per-field flag — see AI Assistant — AI suggestions on other forms. Leave the flag unchecked unless your organization is tracking which fields are candidates for a future per-field suggestion feature.

Practical example: Build a custom deviation form for line clearance failures

Your manufacturing site needs a deviation form specifically for line clearance failures, with fields that differ from general deviations.

1. Open the Form Builder and select Deviation from the type selector.
2. Select Create Template and name it “Line Clearance Failure”.
3. Add a section named “Failure Details” (required, order index 1):
   • Add a select field labeled “Production Line” with options: Line A, Line B, Line C, Packaging Line 1.
   • Add a select field labeled “Failure Type” with options: Residue Found, Wrong Label, Cross-Contamination, Equipment Not Cleared.
   • Add a textarea field labeled “Description of Finding” (required).
   • Add an image field labeled “Photographic Evidence” (allow multiple, max 10 MB).
4. Add a section named “Impact Assessment” (required, order index 2):
   • Add a select field labeled “Batch Impact” with options: Single Batch, Multiple Batches, No Batch Impact.
   • Add a document_picker field labeled “Affected SOPs” to link relevant procedures.
   • Add a boolean field labeled “Product Release Hold Required”.
5. Optionally check Enable AI Suggestion on the “Description of Finding” field to flag it as a future AI-suggestion candidate — this does not change the form’s behavior today (see Field-level AI suggestion flag).
6. Set the template as active and select Save.

Now when operators report a line clearance failure, they see a focused form with exactly the fields they need — reducing data entry time and improving consistency.

Permissions

Action	Required Permission
View form templates	Admin role
Create, edit, or delete templates	Admin role
Set default template	Admin role