@memberjunction/actions-bizapps-formbuilders

Form builder and survey platform integration actions for MemberJunction. This package provides a unified interface across four major form/survey platforms, enabling AI agents, workflows, and applications to programmatically retrieve responses, analyze submissions, and manage forms through the MemberJunction Actions framework.

This package is part of the BizApps Actions collection within the broader MemberJunction Actions Framework. For core action architecture, design philosophy, and when to use actions versus direct code, see the Actions CLAUDE.md.

Architecture

The package follows a three-tier class hierarchy: a shared base class providing common form operations, provider-specific base classes handling API authentication and data normalization, and individual action classes implementing specific operations.

graph TD
    subgraph Framework["Actions Framework"]
        BA["BaseAction<br/>@memberjunction/actions"]
    end

    subgraph Base["Shared Base Layer"]
        BFBA["BaseFormBuilderAction<br/>Credential management, CSV export,<br/>statistics helpers, response normalization"]
    end

    subgraph Providers["Provider Base Classes"]
        TF["TypeformBaseAction<br/>Bearer token auth<br/>Axios + rate limiting"]
        JF["JotFormBaseAction<br/>API key (query param)<br/>Regional endpoints"]
        SM["SurveyMonkeyBaseAction<br/>OAuth 2.0 Bearer<br/>Paginated responses"]
        GF["GoogleFormsBaseAction<br/>OAuth 2.0 Bearer<br/>Read-only API"]
    end

    subgraph Actions["Action Classes (34 total)"]
        TFA["Typeform Actions (10)"]
        JFA["JotForm Actions (8)"]
        SMA["SurveyMonkey Actions (8)"]
        GFA["Google Forms Actions (4)"]
    end

    subgraph Shared["Shared Utilities"]
        FCP["FileContentProcessor<br/>PDF, Excel, Word,<br/>image extraction"]
    end

    BA --> BFBA
    BFBA --> TF
    BFBA --> JF
    BFBA --> SM
    BFBA --> GF
    TF --> TFA
    JF --> JFA
    SM --> SMA
    GF --> GFA
    TFA -.-> FCP

    style Framework fill:#64748b,stroke:#475569,color:#fff
    style Base fill:#2d6a9f,stroke:#1a4971,color:#fff
    style TF fill:#7c5295,stroke:#563a6b,color:#fff
    style JF fill:#7c5295,stroke:#563a6b,color:#fff
    style SM fill:#7c5295,stroke:#563a6b,color:#fff
    style GF fill:#7c5295,stroke:#563a6b,color:#fff
    style TFA fill:#2d8659,stroke:#1a5c3a,color:#fff
    style JFA fill:#2d8659,stroke:#1a5c3a,color:#fff
    style SMA fill:#2d8659,stroke:#1a5c3a,color:#fff
    style GFA fill:#2d8659,stroke:#1a5c3a,color:#fff
    style FCP fill:#b8762f,stroke:#8a5722,color:#fff

Supported Platforms

Platform	Auth Method	Actions	Capabilities
Typeform	Bearer token (personal access token)	10	Full CRUD: responses, forms, file content
JotForm	API key (query parameter)	8	Full CRUD: submissions, forms
SurveyMonkey	OAuth 2.0 Bearer token	8	Full CRUD: responses, surveys, collectors
Google Forms	OAuth 2.0 Bearer token	4	Read-only: responses, form details

Installation

npm install @memberjunction/actions-bizapps-formbuilders

This package is part of the MemberJunction monorepo. When working within the monorepo, add the dependency to your package’s package.json and run npm install at the repository root.

Actions Reference

Typeform Actions (10)

Action Class	Registration Name	Description
GetTypeformResponsesAction	GetTypeformResponsesAction	Retrieve responses with filtering, pagination, and auto-paginate support
GetSingleTypeformResponseAction	GetSingleTypeformResponseAction	Retrieve a specific response by token
GetTypeformStatisticsAction	GetTypeformStatisticsAction	Calculate aggregate analytics (completion rates, distributions, top answers)
ExportTypeformCSVAction	ExportTypeformCSVAction	Export responses to CSV format with optional metadata
WatchNewTypeformResponsesAction	WatchNewTypeformResponsesAction	Poll for new submissions since a given timestamp
GetTypeformAction	GetTypeformAction	Retrieve complete form configuration and field definitions
GetTypeformFormsAction	GetTypeformFormsAction	List all forms in a workspace
TypeformGetFileContentAction	TypeformGetFileContentAction	Download and process file upload answers (PDF, Excel, Word, images)
CreateTypeformAction	CreateTypeformAction	Create new forms programmatically with fields, settings, and logic
UpdateTypeformAction	UpdateTypeformAction	Modify existing forms with safe merge mode

JotForm Actions (8)

Action Class	Registration Name	Description
GetJotFormSubmissionsAction	GetJotFormSubmissionsAction	Retrieve submissions with filtering and pagination
GetSingleJotFormSubmissionAction	GetSingleJotFormSubmissionAction	Retrieve a specific submission by ID
GetJotFormStatisticsAction	GetJotFormStatisticsAction	Calculate aggregate analytics from submissions
ExportJotFormCSVAction	ExportJotFormCSVAction	Export submissions to CSV format
WatchNewJotFormSubmissionsAction	WatchNewJotFormSubmissionsAction	Poll for new submissions since a given timestamp
GetJotFormAction	GetJotFormAction	Retrieve form details and questions
CreateJotFormAction	CreateJotFormAction	Create new forms with questions and properties
UpdateJotFormAction	UpdateJotFormAction	Modify existing form configuration

SurveyMonkey Actions (8)

Action Class	Registration Name	Description
GetSurveyMonkeyResponsesAction	GetSurveyMonkeyResponsesAction	Retrieve responses with date range and status filtering
GetSingleSurveyMonkeyResponseAction	GetSingleSurveyMonkeyResponseAction	Retrieve a specific response by ID
GetSurveyMonkeyStatisticsAction	GetSurveyMonkeyStatisticsAction	Calculate aggregate analytics from responses
ExportSurveyMonkeyCSVAction	ExportSurveyMonkeyCSVAction	Export responses to CSV format
WatchNewSurveyMonkeyResponsesAction	WatchNewSurveyMonkeyResponsesAction	Poll for new responses since a given timestamp
GetSurveyMonkeyAction	GetSurveyMonkeyAction	Retrieve survey details and configuration
CreateSurveyMonkeyAction	CreateSurveyMonkeyAction	Create new surveys with pages and questions
UpdateSurveyMonkeyAction	UpdateSurveyMonkeyAction	Modify existing survey properties

Google Forms Actions (4)

Action Class	Registration Name	Description
GetSingleGoogleFormsResponseAction	GetSingleGoogleFormsResponseAction	Retrieve a specific response by ID
GetGoogleFormsStatisticsAction	GetGoogleFormsStatisticsAction	Calculate aggregate analytics from responses
ExportGoogleFormsCSVAction	ExportGoogleFormsCSVAction	Export responses to CSV format
GetGoogleFormAction	GetGoogleFormAction	Retrieve form details, questions, and quiz settings

Note: Google Forms API is read-only. There are no endpoints for creating or updating forms programmatically.

Common Data Model

All providers normalize their responses into a shared FormResponse interface, enabling provider-agnostic processing downstream.

classDiagram
    class FormResponse {
        +string responseId
        +string formId
        +Date submittedAt
        +boolean completed
        +FormAnswer[] answerDetails
        +Record answers
        +metadata
        +calculatedFields
        +hiddenFields
    }

    class FormAnswer {
        +string fieldId
        +string fieldType
        +string question
        +answer
        +string[] choices
    }

    class FormStatistics {
        +number totalResponses
        +number completedResponses
        +number partialResponses
        +number completionRate
        +number averageCompletionTime
        +Record responsesByDate
        +topAnswers
    }

    FormResponse --> FormAnswer : answerDetails

    style FormResponse fill:#2d6a9f,stroke:#1a4971,color:#fff
    style FormAnswer fill:#7c5295,stroke:#563a6b,color:#fff
    style FormStatistics fill:#2d8659,stroke:#1a5c3a,color:#fff

Authentication and Credentials

All form builder actions use a secure credential resolution chain. Credentials are never passed as direct action parameters; instead, they are resolved from environment variables or the MemberJunction Company Integrations entity.

Credential Resolution Order

1. Environment variables (company-specific): BIZAPPS_{PROVIDER}_{COMPANY_ID}_{CREDENTIAL_TYPE}
2. Environment variables (default): BIZAPPS_{PROVIDER}_{CREDENTIAL_TYPE}
3. Database (Company Integrations entity): AccessToken, APIKey fields

Environment Variable Examples

# Typeform - Personal access token
export BIZAPPS_TYPEFORM_API_TOKEN=tfp_your_token_here
export BIZAPPS_TYPEFORM_12345_API_TOKEN=tfp_company_specific_token

# JotForm - API key
export BIZAPPS_JOTFORM_API_KEY=your_jotform_api_key
export BIZAPPS_JOTFORM_12345_API_KEY=company_specific_key

# SurveyMonkey - OAuth 2.0 access token
export BIZAPPS_SURVEYMONKEY_ACCESS_TOKEN=your_oauth_token

# Google Forms - OAuth 2.0 access token
export BIZAPPS_GOOGLE_FORMS_ACCESS_TOKEN=your_google_oauth_token

# OAuth2 client credentials (for token refresh)
export BIZAPPS_TYPEFORM_CLIENT_ID=your_client_id
export BIZAPPS_TYPEFORM_CLIENT_SECRET=your_client_secret

Database Configuration

Store credentials in the Company Integrations entity linked to the appropriate Integration record:

-- 1. Create Integration record for the platform
INSERT INTO Integration (Name, Description, NavigationBaseURL, ClassName)
VALUES ('Typeform', 'Typeform form builder', 'https://api.typeform.com', 'TypeformIntegration');

-- 2. Link to Company with credentials
INSERT INTO CompanyIntegration (CompanyID, IntegrationID, AccessToken, IsActive)
VALUES (@CompanyID, @IntegrationID, 'tfp_your_token', 1);

Usage Examples

Retrieving Form Responses

import { ActionEngineServer } from '@memberjunction/actions';

const engine = ActionEngineServer.Instance;

// Get Typeform responses with date filtering
const result = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'Get Typeform Responses'),
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-123' },
        { Name: 'FormID', Type: 'Input', Value: 'abc123' },
        { Name: 'Since', Type: 'Input', Value: '2024-01-01T00:00:00Z' },
        { Name: 'GetAllPages', Type: 'Input', Value: true }
    ],
    ContextUser: currentUser
});

if (result.Success) {
    const responses = result.Params.find(p => p.Name === 'Responses')?.Value;
    console.log(`Retrieved ${responses.length} responses`);
}

Exporting Responses to CSV

const exportResult = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'Export JotForm Responses to CSV'),
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-123' },
        { Name: 'FormID', Type: 'Input', Value: '240123456789' },
        { Name: 'IncludeMetadata', Type: 'Input', Value: true }
    ],
    ContextUser: currentUser
});

const csvData = exportResult.Params.find(p => p.Name === 'CSVData')?.Value;

Creating a Form Programmatically

const createResult = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'Create Typeform'),
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-123' },
        { Name: 'Title', Type: 'Input', Value: 'Customer Feedback Survey' },
        {
            Name: 'Fields', Type: 'Input', Value: [
                {
                    type: 'short_text',
                    title: 'What is your name?',
                    ref: 'name'
                },
                {
                    type: 'rating',
                    title: 'How satisfied are you?',
                    ref: 'satisfaction',
                    properties: { steps: 5, shape: 'star' }
                },
                {
                    type: 'long_text',
                    title: 'Any additional feedback?',
                    ref: 'feedback'
                }
            ]
        }
    ],
    ContextUser: currentUser
});

const formUrl = createResult.Params.find(p => p.Name === 'FormURL')?.Value;

Watching for New Responses

// Poll for new SurveyMonkey responses
const watchResult = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'Watch for New SurveyMonkey Responses'),
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-123' },
        { Name: 'SurveyID', Type: 'Input', Value: 'survey-456' },
        { Name: 'LastCheckedTimestamp', Type: 'Input', Value: '2024-06-01T00:00:00Z' },
        { Name: 'OnlyCompleted', Type: 'Input', Value: true }
    ],
    ContextUser: currentUser
});

const hasNew = watchResult.Params.find(p => p.Name === 'HasNewResponses')?.Value;
const newResponses = watchResult.Params.find(p => p.Name === 'NewResponses')?.Value;

File Content Processing

The package includes a FileContentProcessor utility used by the Typeform GetFileContentAction to intelligently extract content from file upload answers. It supports multiple file formats:

Format	Processing	Output
PDF	Text extraction via pdf-parse	Plain text
Excel (.xlsx, .xls)	Sheet parsing via exceljs	Structured JSON
Word (.docx, .doc)	Text extraction via mammoth	Plain text
Images	Base64 encoding	Base64 string (for LLM vision)
Text/JSON/XML/CSV	UTF-8 decoding	Plain text
Other binary	Base64 encoding	Base64 string

Error Handling

All actions return consistent error information through the ActionResultSimple interface:

Result Code	Description
SUCCESS	Operation completed successfully
MISSING_FORM_ID	Required FormID parameter was not provided
MISSING_API_TOKEN	No API credentials could be resolved
MISSING_CONTEXT_USER	Context user is required for credential lookup
ERROR	General error (check Message for details)

Each provider automatically handles platform-specific HTTP errors:

• 401 - Invalid or expired API token
• 403 - Insufficient permissions / scope
• 404 - Form or response not found
• 429 - Rate limit exceeded (automatic retry with exponential backoff)

Rate Limiting

All providers include built-in rate limit handling with automatic retry:

• Respects Retry-After headers when provided
• Falls back to 60-second wait when no header is present
• Adds 100ms delays between pagination requests to avoid hitting limits
• JotForm: Regional endpoints (US, EU, HIPAA) for data residency compliance

Dependencies

Package	Purpose
@memberjunction/actions	Action engine and BaseAction class
@memberjunction/actions-base	ActionParam types and base interfaces
@memberjunction/core	RunView, Metadata, UserInfo, logging
@memberjunction/core-entities	CompanyIntegrationEntity for credential lookup
@memberjunction/global	@RegisterClass decorator
axios	HTTP client for all provider API calls
exceljs	Excel file parsing in FileContentProcessor
mammoth	Word document text extraction
pdf-parse	PDF text extraction

Related Packages

• @memberjunction/actions - Action execution engine
• @memberjunction/actions-base - Base classes and interfaces
• @memberjunction/core-actions - Pre-built core actions
• @memberjunction/actions-bizapps-accounting - Accounting integrations
• @memberjunction/actions-bizapps-lms - LMS integrations
• @memberjunction/actions-bizapps-crm - CRM integrations

Adding a New Provider

To integrate a new form/survey platform:

1. Create provider directory: src/providers/{platform}/
2. Implement a provider base class extending BaseFormBuilderAction with:
   • formPlatform and integrationName properties
   • Axios instance with authentication and rate limit interceptors
   • API client methods for the provider’s endpoints
   • Response normalization to the shared FormResponse interface
   • Provider-specific error handling
3. Create individual action classes in src/providers/{platform}/actions/
4. Export all classes from src/providers/{platform}/index.ts
5. Add the provider export to src/index.ts