strapi-form-handler-plugin

A Strapi 5 plugin that integrates Salesforce Pardot form handlers directly into the Strapi admin panel. Create, import, and manage Pardot form handlers and their fields without leaving your CMS.

Features

• Pardot lifecycle sync — Automatic create/update/delete of Pardot form handlers and fields via document-service middlewares
• Transactional safety — Pardot handler is created first on create; if Strapi save fails, the Pardot handler is rolled back. Delete removes from Strapi first, then Pardot (best-effort)
• User-friendly error messages — Pardot API errors are mapped to clear, actionable messages (e.g. "A form handler with this name already exists")
• Inline validation — Campaign and folder fields show inline errors when left empty
• Custom fields — Combobox selects for Pardot campaigns, folders, and prospect fields with forwardRef support
• Form handler import — Browse and import existing Pardot form handlers into Strapi (single or batch)
• Structured logging — All operations logged with [pardot], [form-handler], [pardot-auth], [form-import] prefixes for production debugging via CloudWatch
• Session-cached prefetch — Campaigns, folders, and field types prefetched on plugin init and cached in session storage
• Auto-injected tracking fields — Automatically adds tracking_url, prospect_analytics_url, and UTM fields when creating form handler fields

Requirements

• Strapi v5.x
• Node.js 20
• A Salesforce account with Pardot (Account Engagement) access

Installation

npm install strapi-form-handler-plugin

Configuration

Environment Variables

Add the following to your .env file:

PARDOT_CLIENT_ID=your_connected_app_client_id
PARDOT_CLIENT_SECRET=your_connected_app_client_secret
PARDOT_USERNAME=your_salesforce_username
PARDOT_PASSWORD=your_salesforce_password
PARDOT_BUSINESS_UNIT_ID=your_pardot_business_unit_id
SALESFORCE_DOMAIN_URL=https://login.salesforce.com

Plugin Registration

Enable the plugin in config/plugins.js:

module.exports = {
  'strapi-form-handler-plugin': {
    enabled: true,
  },
};

Architecture

Pardot Lifecycle Sync

All Pardot sync logic lives inside the plugin via document-service middlewares registered in server/src/register.ts. The host app's src/index.js has no form handler logic.

| Action | Ordering | Rollback | |---|---|---| | Create | Pardot handler + fields created first → Strapi saves with Pardot IDs | Pardot handler rolled back if Strapi save fails | | Update | Pardot updated first (idempotent) → Strapi saves | Pardot state is valid for retry | | Delete | Strapi deletes first → Pardot handler removed (best-effort) | Orphaned handler logged for manual cleanup |

Services

| Service | Description | |---|---| | formLifecycle | Orchestrates Pardot create/update/delete with validation, field preparation, UTM assignment, and user-friendly error mapping | | pardot | Core Pardot v5 API client with auth retry, rate limit detection, structured logging, and error message normalization | | pardotAuth | OAuth token management for Salesforce/Pardot | | formImport | Fetches and imports Pardot form handlers into Strapi |

Peer Dependencies

The plugin requires @strapi/utils and @radix-ui/react-tooltip as peer dependencies to ensure instanceof checks work correctly with the host app's error classes and the Combobox tooltip context is shared.

Custom Fields

| Field | Plugin ID | Type | Description | |---|---|---|---| | campaignSelect | strapi-form-handler-plugin.campaignSelect | string | Combobox of Pardot campaigns | | folder-select | strapi-form-handler-plugin.folder-select | string | Combobox of Pardot folders | | field-types-select | strapi-form-handler-plugin.field-types-select | string | Combobox of Pardot prospect fields |

Usage in a Schema

{
  "attributes": {
    "campaign": {
      "type": "customField",
      "customField": "plugin::strapi-form-handler-plugin.campaignSelect"
    }
  }
}

API Routes

All routes are admin-only (require authentication):

| Method | Path | Description | |---|---|---| | GET | /strapi-form-handler-plugin/campaigns | List Pardot campaigns | | GET | /strapi-form-handler-plugin/folders | List Pardot folders | | GET | /strapi-form-handler-plugin/field-types | List Pardot prospect field types | | GET | /strapi-form-handler-plugin/prefetch | Fetch all in one call | | GET | /strapi-form-handler-plugin/form-handlers | List all Pardot form handlers | | POST | /strapi-form-handler-plugin/form-handlers/import | Import a Pardot form handler into Strapi |

Log Prefixes

All strapi.log.* calls use consistent prefixes for filtering in CloudWatch or any log aggregator:

| Prefix | Source | |---|---| | [pardot] | Pardot API calls (requests, responses, errors, timing) | | [pardot-auth] | OAuth token lifecycle | | [form-handler] | Form create/update/delete lifecycle and rollbacks | | [form-import] | Pardot → Strapi import operations |

Development

# Build the plugin
npm --prefix src/plugins/strapi-form-handler-plugin run build

# Watch for changes during development
npm --prefix src/plugins/strapi-form-handler-plugin run watch

# Verify the plugin
npm --prefix src/plugins/strapi-form-handler-plugin run verify

License

MIT