@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
@memberjunction/actions"]
    end

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

    subgraph Providers["Provider Base Classes"]
        TF["TypeformBaseAction
Bearer token auth
Axios + rate limiting"]
        JF["JotFormBaseAction
API key (query param)
Regional endpoints"]
        SM["SurveyMonkeyBaseAction
OAuth 2.0 Bearer
Paginated responses"]
        GF["GoogleFormsBaseAction
OAuth 2.0 Bearer
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
PDF, Excel, Word,
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
Copy

Supported Platforms

Installation

npm install @memberjunction/actions-bizapps-formbuilders
Copy

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)

JotForm Actions (8)

SurveyMonkey Actions (8)

Google Forms Actions (4)

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
Copy

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
Copy

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);
Copy

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`);
}
Copy

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;
Copy

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;
Copy

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;
Copy

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:

Error Handling

All actions return consistent error information through the ActionResultSimple interface:

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

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