@memberjunction/actions-bizapps-crm

Customer Relationship Management (CRM) integration actions for MemberJunction. This package provides 22 HubSpot CRM actions covering contact, company, deal, and activity management, built on a provider-extensible architecture that supports multi-tenant credential management.

This package is part of the BizApps actions family within the MemberJunction Actions Framework. See those documents for framework-level patterns, the action design philosophy, and shared conventions across all BizApps integrations.

Architecture

The package uses a three-tier class hierarchy: a domain-level base class for all CRM providers, a provider-specific base class for HubSpot, and individual action classes for each operation.

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

    subgraph CRM["CRM Domain Layer"]
        BCRM["BaseCRMAction<br/>Credential management, validation helpers,<br/>date/phone formatting, status mapping"]
    end

    subgraph HubSpot["HubSpot Provider Layer"]
        HSB["HubSpotBaseAction<br/>API auth, pagination,<br/>search, batch ops, associations"]
    end

    subgraph Actions["HubSpot Actions (22 total)"]
        direction LR
        CC["Contact Actions<br/>Create, Update, Get,<br/>Search, Delete, Merge"]
        CO["Company Actions<br/>Create, Update, Get,<br/>Search, Associate"]
        DA["Deal Actions<br/>Create, Update, Get,<br/>Search, By Contact, By Company"]
        AA["Activity Actions<br/>Log Activity, Create Task,<br/>Update Task, Get Activities,<br/>Get Upcoming Tasks"]
    end

    BA --> BCRM
    BCRM --> HSB
    HSB --> CC
    HSB --> CO
    HSB --> DA
    HSB --> AA

    style Framework fill:#64748b,stroke:#475569,color:#fff
    style CRM fill:#2d6a9f,stroke:#1a4971,color:#fff
    style HubSpot fill:#b8762f,stroke:#8a5722,color:#fff
    style Actions fill:#2d8659,stroke:#1a5c3a,color:#fff

Credential Resolution Flow

All actions resolve credentials through a two-step lookup: environment variables first, database fallback second. This supports both development and production deployment patterns.

flowchart LR
    A["Action receives<br/>CompanyID param"] --> B["Look up<br/>CompanyIntegration<br/>entity"]
    B --> C{"Env var<br/>exists?"}
    C -->|Yes| D["Use env var<br/>BIZAPPS_HUBSPOT_<br/>{ID}_ACCESS_TOKEN"]
    C -->|No| E{"DB credentials<br/>exist?"}
    E -->|Yes| F["Use AccessToken /<br/>APIKey from entity"]
    E -->|No| G["Throw error:<br/>no credentials"]

    style A fill:#64748b,stroke:#475569,color:#fff
    style B fill:#2d6a9f,stroke:#1a4971,color:#fff
    style C fill:#b8762f,stroke:#8a5722,color:#fff
    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
    style E fill:#b8762f,stroke:#8a5722,color:#fff
    style F fill:#2d8659,stroke:#1a5c3a,color:#fff
    style G fill:#7c5295,stroke:#563a6b,color:#fff

Installation

npm install @memberjunction/actions-bizapps-crm

This package is server-side only. It is typically consumed by MJAPI or other server-side hosts that register actions via the MemberJunction class factory.

Configuration

1. Create Integration Record

Register HubSpot as an integration in your MemberJunction database:

INSERT INTO Integration (Name, Description, NavigationBaseURL, ClassName)
VALUES ('HubSpot', 'HubSpot CRM Integration',
        'https://api.hubapi.com', 'HubSpotIntegration');

2. Link to Company

Create a CompanyIntegration record for each tenant/company that uses HubSpot:

INSERT INTO CompanyIntegration (CompanyID, IntegrationID, ExternalSystemID, IsActive)
VALUES (@CompanyID, @HubSpotIntegrationID, @HubSpotPortalID, 1);

3. Set Credentials

Credentials are resolved from environment variables first, then from database fields.

Environment variables (recommended):

# OAuth access token (preferred)
BIZAPPS_HUBSPOT_{COMPANY_ID}_ACCESS_TOKEN=your_access_token

# Or private app API key
BIZAPPS_HUBSPOT_{COMPANY_ID}_API_KEY=your_api_key

# Optional OAuth fields
BIZAPPS_HUBSPOT_{COMPANY_ID}_REFRESH_TOKEN=your_refresh_token
BIZAPPS_HUBSPOT_{COMPANY_ID}_CLIENT_ID=your_client_id
BIZAPPS_HUBSPOT_{COMPANY_ID}_CLIENT_SECRET=your_client_secret

Database fallback: store credentials in the AccessToken, APIKey, or RefreshToken columns of the CompanyIntegration entity.

Available Actions

Contact Management

Action	Class	Description
Create Contact	CreateContactAction	Creates a new contact with email validation and optional company association
Update Contact	UpdateContactAction	Updates an existing contact’s properties
Get Contact	GetContactAction	Retrieves a single contact by ID with optional associations
Search Contacts	SearchContactsAction	Searches contacts with filters, sorting, pagination, and date ranges
Delete Contact	DeleteContactAction	Deletes (archives) a contact
Merge Contacts	MergeContactsAction	Merges duplicate contacts into a single record

Company Management

Action	Class	Description
Create Company	CreateCompanyAction	Creates a new company record
Update Company	UpdateCompanyAction	Updates an existing company’s properties
Get Company	GetCompanyAction	Retrieves a single company by ID
Search Companies	SearchCompaniesAction	Searches companies with flexible filter criteria
Associate Contact to Company	AssociateContactToCompanyAction	Links contacts to companies with batch support and primary designation

Deal Management

Action	Class	Description
Create Deal	CreateDealAction	Creates a new deal/opportunity
Update Deal	UpdateDealAction	Updates deal properties and pipeline stage
Get Deal	GetDealAction	Retrieves deal details with associations, timeline, and metrics
Search Deals	SearchDealsAction	Searches deals with flexible filter criteria
Get Deals by Contact	GetDealsByContactAction	Retrieves all deals associated with a contact
Get Deals by Company	GetDealsByCompanyAction	Retrieves all deals associated with a company

Activity Management

Action	Class	Description
Log Activity	LogActivityAction	Logs calls, emails, meetings, or notes with contact/company/deal associations
Create Task	CreateTaskAction	Creates a task with subject, priority, due date, and owner
Update Task	UpdateTaskAction	Updates an existing task’s properties
Get Activities by Contact	GetActivitiesByContactAction	Retrieves all activities for a specific contact
Get Upcoming Tasks	GetUpcomingTasksAction	Gets upcoming/overdue tasks filtered by owner, status, and priority

Usage Examples

Creating a Contact

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

const engine = ActionEngineServer.Instance;
const result = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'CreateContactAction')!,
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-uuid' },
        { Name: 'Email', Type: 'Input', Value: 'jane.doe@example.com' },
        { Name: 'FirstName', Type: 'Input', Value: 'Jane' },
        { Name: 'LastName', Type: 'Input', Value: 'Doe' },
        { Name: 'Company', Type: 'Input', Value: 'Acme Corp' },
        { Name: 'JobTitle', Type: 'Input', Value: 'VP of Sales' },
        { Name: 'LifecycleStage', Type: 'Input', Value: 'lead' },
        { Name: 'AssociateWithCompanyId', Type: 'Input', Value: 'hubspot-company-id' }
    ],
    ContextUser: contextUser
});

if (result.Success) {
    const summary = result.Params.find(p => p.Name === 'Summary')?.Value;
    console.log(`Created contact ${summary.contactId} at ${summary.portalUrl}`);
}

Searching Contacts

const result = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'SearchContactsAction')!,
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-uuid' },
        { Name: 'LifecycleStage', Type: 'Input', Value: 'lead' },
        { Name: 'CreatedAfter', Type: 'Input', Value: '2025-01-01' },
        { Name: 'SortBy', Type: 'Input', Value: 'createdate' },
        { Name: 'SortOrder', Type: 'Input', Value: 'DESC' },
        { Name: 'Limit', Type: 'Input', Value: 50 }
    ],
    ContextUser: contextUser
});

if (result.Success) {
    const contacts = result.Params.find(p => p.Name === 'Contacts')?.Value;
    const summary = result.Params.find(p => p.Name === 'Summary')?.Value;
    console.log(`Found ${summary.totalResults} contacts`);
    console.log('By lifecycle stage:', summary.resultStats.byLifecycleStage);
}

Logging an Activity

const result = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'LogActivityAction')!,
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-uuid' },
        { Name: 'ActivityType', Type: 'Input', Value: 'CALL' },
        { Name: 'Subject', Type: 'Input', Value: 'Follow-up call' },
        { Name: 'Body', Type: 'Input', Value: 'Discussed renewal terms' },
        { Name: 'Status', Type: 'Input', Value: 'COMPLETED' },
        { Name: 'DurationMilliseconds', Type: 'Input', Value: 900000 },
        { Name: 'ContactIds', Type: 'Input', Value: ['contact-id-1'] },
        { Name: 'DealIds', Type: 'Input', Value: ['deal-id-1'] }
    ],
    ContextUser: contextUser
});

Retrieving a Deal with Associations

const result = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'GetDealAction')!,
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-uuid' },
        { Name: 'DealId', Type: 'Input', Value: 'hubspot-deal-id' },
        { Name: 'IncludeAssociations', Type: 'Input', Value: true },
        { Name: 'IncludeTimeline', Type: 'Input', Value: true }
    ],
    ContextUser: contextUser
});

if (result.Success) {
    const summary = result.Params.find(p => p.Name === 'Summary')?.Value;
    console.log(`Deal: ${summary.dealName}, Stage: ${summary.dealStage}`);
    console.log(`Amount: ${summary.amount}, Days open: ${summary.metrics.daysOpen}`);
    console.log(`Overdue: ${summary.metrics.isOverdue}`);
}

Getting Upcoming Tasks

const result = await engine.RunAction({
    Action: engine.Actions.find(a => a.Name === 'GetUpcomingTasksAction')!,
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'company-uuid' },
        { Name: 'OwnerId', Type: 'Input', Value: 'owner-id' },
        { Name: 'DaysAhead', Type: 'Input', Value: 14 },
        { Name: 'IncludeOverdue', Type: 'Input', Value: true },
        { Name: 'Statuses', Type: 'Input', Value: ['NOT_STARTED', 'IN_PROGRESS'] }
    ],
    ContextUser: contextUser
});

if (result.Success) {
    const summary = result.Params.find(p => p.Name === 'Summary')?.Value;
    console.log(`Total tasks: ${summary.totalTasks}`);
    console.log(`Overdue: ${summary.overdueCount}, Due today: ${summary.dueTodayCount}`);
    console.log('By due date:', summary.byDueDate);
}

API Reference

Base Classes

BaseCRMAction

Abstract base class for all CRM actions. Provides:

Method	Description
getCompanyIntegration(companyId, contextUser)	Looks up and caches the CompanyIntegration entity for a given company
getCredentialFromEnv(companyId, credentialType)	Resolves credentials from environment variables using BIZAPPS_{PROVIDER}_{ID}_{TYPE} format
getAPICredentials(integration)	Resolves API credentials with env-var-first, database-fallback strategy
getAPIBaseURL(integration)	Returns the base URL for API calls (from CustomAttribute1 or provider default)
formatCRMDate(date)	Formats a Date to ISO 8601 string
parseCRMDate(dateString)	Parses an ISO 8601 string to Date
formatPhoneNumber(phone)	Normalizes phone numbers toward E.164 format
isValidEmail(email)	Validates email format with a regex check
mapDealStatus(stage)	Maps CRM-specific deal stage names to 'open' | 'won' | 'lost' | 'unknown'
mapActivityType(type)	Maps activity type strings to 'call' | 'email' | 'meeting' | 'task' | 'note' | 'other'

HubSpotBaseAction

Provider-specific base class extending BaseCRMAction. Adds HubSpot v3 API support:

Method	Description
makeHubSpotRequest<T>(endpoint, method, body, contextUser)	Makes an authenticated request to the HubSpot CRM v3 API
makeHubSpotPaginatedRequest<T>(endpoint, params, contextUser)	Handles cursor-based pagination with configurable MaxResults limit
searchHubSpotObjects<T>(objectType, filters, properties, contextUser)	Executes a HubSpot search API call with filter groups
batchCreateHubSpotObjects<T>(objectType, objects, contextUser)	Batch-creates objects in HubSpot
batchUpdateHubSpotObjects<T>(objectType, updates, contextUser)	Batch-updates objects in HubSpot
associateObjects(fromType, fromId, toType, toId, assocType, contextUser)	Creates an association between two HubSpot objects
getAssociationTypeId(fromType, toType)	Returns the default HubSpot association type ID for a given pair
mapHubSpotProperties(hubspotObject)	Flattens a HubSpot object’s properties map alongside id, createdAt, updatedAt, archived

Common Parameters

Every action accepts at minimum:

Parameter	Type	Required	Description
CompanyID	Input	Yes	The MemberJunction CompanyIntegration company identifier

Most actions also produce:

Parameter	Type	Description
Summary	Output	Structured summary of the operation result

Result Codes

Actions return standardized result codes:

Code	Meaning
SUCCESS	Operation completed successfully
PARTIAL_SUCCESS	Batch operation with some failures (e.g., associating multiple contacts)
VALIDATION_ERROR	Missing or invalid input parameters
DUPLICATE_CONTACT	Contact with the given email already exists
DEAL_NOT_FOUND	Requested deal ID does not exist
NOT_FOUND	Requested resource does not exist
ERROR	General operation failure

Source Structure

src/
  index.ts                          # Package entry point
  base/
    base-crm.action.ts              # BaseCRMAction - domain base class
  providers/
    hubspot/
      index.ts                      # HubSpot provider exports
      hubspot-base.action.ts        # HubSpotBaseAction - provider base class
      actions/
        index.ts                    # Action barrel exports
        create-contact.action.ts    # Contact CRUD
        update-contact.action.ts
        get-contact.action.ts
        search-contacts.action.ts
        delete-contact.action.ts
        merge-contacts.action.ts
        create-company.action.ts    # Company management
        update-company.action.ts
        get-company.action.ts
        search-companies.action.ts
        associate-contact-to-company.action.ts
        create-deal.action.ts       # Deal management
        update-deal.action.ts
        get-deal.action.ts
        search-deals.action.ts
        get-deals-by-contact.action.ts
        get-deals-by-company.action.ts
        log-activity.action.ts      # Activity management
        create-task.action.ts
        update-task.action.ts
        get-activities-by-contact.action.ts
        get-upcoming-tasks.action.ts

Dependencies

Package	Purpose
@memberjunction/actions	BaseAction class and ActionEngineServer
@memberjunction/actions-base	ActionParam, RunActionParams, ActionResultSimple types
@memberjunction/core	UserInfo, Metadata, RunView
@memberjunction/core-entities	CompanyIntegrationEntity for credential lookup
@memberjunction/global	@RegisterClass decorator for class factory registration

Related Packages

• @memberjunction/actions-bizapps-accounting - Accounting system integrations (QuickBooks, etc.)
• @memberjunction/actions-bizapps-lms - Learning management system integrations (LearnWorlds, etc.)
• @memberjunction/actions - Actions execution engine
• @memberjunction/actions-base - Base classes and type definitions

Adding New Providers

To add a new CRM provider (e.g., Salesforce):

1. Create a provider directory: src/providers/salesforce/
2. Create a provider base class extending BaseCRMAction:
   • Set crmProvider and integrationName
   • Implement provider-specific authentication and request methods
3. Add individual action classes in src/providers/salesforce/actions/
4. Register each action with @RegisterClass(BaseAction, 'ActionName')
5. Export from provider index.ts and the package root index.ts
6. Configure Integration and CompanyIntegration records for the new provider