# Form Inventory Maintenance Guide

**Last Updated:** 2025-11-28

Guide for maintaining the form inventory as forms are added, modified, or deprecated.

## When to Update the Inventory

### Add New Forms

Update inventory when:

- New acquisition form is added to the website
- New HubSpot form is created and integrated
- New API endpoint for form submission is created
- Form is moved to a new location

### Modify Existing Forms

Update inventory when:

- Form ID changes
- Form location changes
- HubSpot form GUID changes
- Form purpose/type changes
- Form handler logic changes

### Deprecate Forms

Update inventory when:

- Form is removed from the website
- Form is replaced by a new form
- Form is no longer used for acquisition

## Files to Update

### 1. `docs/forms/form-audit-inventory.json`

**Location:** `docs/forms/form-audit-inventory.json`

**Structure:**

```json
{
  "audit_date": "YYYY-MM-DD",
  "total_forms": {
    "hubspot_embedded": 1,
    "custom_html": 15,
    "api_based": 8
  },
  "acquisition_forms": {
    "hubspot_embedded": [...],
    "custom_html": [...],
    "api_based": [...]
  },
  "form_guids": {...}
}
```

**Update Process:**

1. Open `docs/forms/form-audit-inventory.json`
2. Add/modify form entry in appropriate category
3. Update `total_forms` counts
4. Update `audit_date` to current date
5. Update `form_guids` if new HubSpot form GUID added

**Required Fields for Each Form:**

- `form_id` or `formId` - Unique form identifier
- `form_name` - Descriptive form name
- `type` - Form type (hubspot_embedded, custom_html, api_based)
- `purpose` - What the form is used for
- `file` - File path where form is located
- `page_locations` - Array of page URLs or "Component" if included in multiple pages
- `hubspot_form_guid` - HubSpot form GUID (if applicable)
- `gtm_tracking_id` - Unique GTM tracking identifier

### 2. `docs/forms/form-ids-reference.md`

**Location:** `docs/forms/form-ids-reference.md`

**Update Process:**

1. Add form to appropriate section (HubSpot Embedded, Custom HTML, API-Based)
2. Include in table with:
   - GTM Tracking ID
   - Form ID
   - Action/Endpoint
   - HubSpot GUID
   - Location
3. Update GTM trigger configuration section if needed

### 3. `docs/forms/form-audit-report.md`

**Location:** `docs/forms/form-audit-report.md`

**Update Process:**

1. Update form counts in "Executive Summary"
2. Add form to appropriate table in form type section
3. Update "Form Distribution by Type" counts
4. Update "Page Location Mapping" if form location changes
5. Update `audit_date` in header

## Form Entry Template

### HubSpot Embedded Form

```json
{
  "form_id": "ad1036ce-33ec-463b-adde-2fa546324c8a",
  "form_name": "Form Name",
  "portal_id": "145133546",
  "region": "eu1",
  "target_container": "#form-container",
  "type": "hubspot_embedded",
  "purpose": "Form purpose",
  "file": "v2/base/include_form-example.php",
  "page_locations": ["/page1", "/page2"],
  "gtm_tracking_id": "hubspot-form-name"
}
```

### Custom HTML Form

```json
{
  "form_id": "demo-form",
  "form_name": "Form Name",
  "action": "/form-hs",
  "type": "custom_html",
  "purpose": "Form purpose",
  "file": "v2/base/include_form-example.php",
  "page_locations": "Component (included in multiple pages)",
  "hubspot_form_guid": "9b93ee13-fad2-4ce8-8ea2-4e588932af2a",
  "gtm_tracking_id": "form-name"
}
```

### API-Based Form

```json
{
  "endpoint": "submit-template.php",
  "form_name": "Form Name",
  "type": "api_based",
  "purpose": "Form purpose",
  "file": "v2/api/submit-template.php",
  "hubspot_form_guid": "11e392f7-aece-4969-8c39-402ee6cb2330",
  "form_guid_constant": "TEMPLATE",
  "gtm_tracking_id": "api-form-name"
}
```

## Deprecating Forms

When a form is deprecated:

1. **Mark as deprecated in inventory:**

   ```json
   {
     "form_id": "old-form",
     "deprecated": true,
     "deprecated_date": "2025-11-28",
     "replaced_by": "new-form-id",
     "notes": "Replaced by new form on 2025-11-28"
   }
   ```

2. **Update form counts:**

   - Remove from active counts
   - Add to deprecated section (if maintaining history)

3. **Update documentation:**

   - Note deprecation in audit report
   - Update form IDs reference (move to deprecated section)

4. **Remove GTM tracking:**
   - Remove tracking code from form file
   - Archive GTM triggers/tags (don't delete - keep for history)
   - Update GTM documentation

## Running the Audit Script

The form audit script can help identify new forms:

```bash
python3 scripts/audit-forms.py
```

**Note:** The script provides a starting point but may miss:

- Forms in JavaScript files
- Dynamically created forms
- Forms with non-standard patterns

**Always manually verify** script results and add missing forms.

## Validation Checklist

Before committing inventory updates:

- [ ] All required fields present
- [ ] Form IDs are unique
- [ ] GTM tracking IDs are unique and descriptive
- [ ] HubSpot form GUIDs are correct
- [ ] Page locations are accurate
- [ ] Form counts match actual forms
- [ ] Audit date updated
- [ ] JSON syntax valid (use JSON validator)
- [ ] Markdown files formatted correctly
- [ ] No duplicate entries

## Version Control

**Commit Message Format:**

```
docs(forms): Add/Update/Deprecate form [form-name]

- Added form: [form-id] in [location]
- Updated form: [form-id] - [change description]
- Deprecated form: [form-id] - replaced by [new-form-id]
```

## Quarterly Audit

Perform comprehensive audit quarterly:

1. **Run audit script:**

   ```bash
   python3 scripts/audit-forms.py
   ```

2. **Manual verification:**

   - Check all form include files
   - Check all API endpoints
   - Verify HubSpot form GUIDs
   - Test all forms

3. **Update all documentation:**

   - `form-audit-inventory.json`
   - `form-ids-reference.md`
   - `form-audit-report.md`

4. **Review GTM configuration:**
   - Verify all triggers still work
   - Check for orphaned triggers/tags
   - Update trigger conditions if needed

## Contact

For questions about form inventory maintenance:

- Review this guide
- Check `docs/forms/form-audit-inventory.json` for examples
- Contact: hady@ordio.com