@memberjunction/core-actions

The @memberjunction/core-actions package provides a comprehensive library of 100+ pre-built actions for the MemberJunction Actions framework. These actions cover AI integration, CRUD operations, communication, data transformation, file handling, visualization, workflow control, web interaction, and more. Each action is registered via @RegisterClass(BaseAction, ...) so it can be discovered and invoked by AI agents, workflow engines, and automation systems at runtime.

For background on when and how to use Actions vs. direct class imports, and the "thin wrapper" design philosophy, see the parent Actions CLAUDE.md.

Server-side only -- this package depends on Node.js APIs, database access, and server-side MJ infrastructure. Do not import it from Angular or other client-side code.

Installation

npm install @memberjunction/core-actions
Copy

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

Architecture

The package is organized into two layers: hand-written custom actions grouped by domain, and generated actions produced by the MJ CodeGen system. Both extend BaseAction from @memberjunction/actions and register themselves with the MJ class factory.

graph TD
    subgraph CoreActions["@memberjunction/core-actions"]
        direction TB
        IDX["index.ts\n(re-exports all actions)"]

        subgraph Custom["src/custom/ -- hand-written"]
            direction LR
            AI["ai/"]
            COMM["communication/"]
            CRUD["crud/"]
            DATA["data/"]
            FILES["files/"]
            INT["integration/"]
            LISTS["lists/"]
            MCP["mcp/"]
            SEC["security/"]
            UM["user-management/"]
            UTIL["utilities/"]
            VIZ["visualization/"]
            WEB["web/"]
            WF["workflow/"]
            DEMO["demo/"]
            CE["code-execution/"]
        end

        GEN["src/generated/\naction_subclasses.ts"]
        CFG["config.ts\n(API key loading)"]
    end

    subgraph Deps["Framework packages"]
        BASE["@memberjunction/actions-base"]
        ENG["@memberjunction/actions"]
        CORE["@memberjunction/core"]
        GLOBAL["@memberjunction/global"]
    end

    IDX --> Custom
    IDX --> GEN
    Custom --> ENG
    Custom --> BASE
    GEN --> ENG
    GEN --> BASE
    ENG --> BASE
    BASE --> CORE
    BASE --> GLOBAL

    style CoreActions fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Custom fill:#2d8659,stroke:#1a5c3a,color:#fff
    style Deps fill:#64748b,stroke:#475569,color:#fff
    style GEN fill:#7c5295,stroke:#563a6b,color:#fff
    style CFG fill:#b8762f,stroke:#8a5722,color:#fff
Copy

Base Classes

Several abstract base classes reduce duplication across related actions:

Generated Actions

The file src/generated/action_subclasses.ts contains actions produced by the MJ CodeGen system from natural-language UserPrompt descriptions stored in the database. Generated actions use a composition pattern -- they always extend BaseAction (never their parent action class) and invoke the parent action via ActionEngineServer.Instance.RunAction() at runtime. See the parent README for details on the generated/child action architecture.

Scheduled Geocoding (Scheduled Geocoding action)

src/custom/geo/scheduled-geocoding.action.ts is a safety-net maintenance action that finds records in geo-enabled entities (Entity.SupportsGeoCoding = 1) missing a RecordGeoCode row, retries failed geocoding attempts, and cleans up orphaned RecordGeoCode rows. Live geocoding-on-save runs inline via BaseEntity.OnSaveCompleted — this scheduled action is only needed to catch records inserted via bulk SQL imports or direct DB writes that bypass BaseEntity.Save().

The "find missing records" phase uses keyset (seek) pagination when the target entity has a single-column orderable PK (the common case for MJ entities). This keeps each page O(log N) regardless of how deep the iteration goes — important on multi-million-row entities like Tax Returns. Composite-PK entities fall back to StartRow-based OFFSET pagination automatically. See KEYSET_PAGINATION_GUIDE.md for the pattern.

Default cadence is Saturday 2 AM UTC (configured in metadata/scheduled-jobs/.geocoding-maintenance-job.json). Administrators can adjust the CronExpression per environment.

Configuration

External API keys used by certain actions (Perplexity, Google Custom Search, Gamma) are loaded from mj.config.cjs or environment variables via the config.ts module:

// mj.config.cjs
module.exports = {
  perplexityApiKey: 'pk-...',          // or PERPLEXITY_API_KEY env var
  gammaApiKey: 'sk-gamma-...',         // or GAMMA_API_KEY env var
  google: {
    customSearch: {
      apiKey: 'AIza...',               // or GOOGLE_CUSTOM_SEARCH_API_KEY
      cx: '017...',                    // or GOOGLE_CUSTOM_SEARCH_CX
    }
  }
};
Copy

Action Catalog

All 100+ actions organized by category. Each action is registered with @RegisterClass(BaseAction, "<name>").

AI (8 actions)

Actions for prompt execution, agent discovery, image generation, and content summarization.

Communication (3 actions)

Send messages via the MJ Communication Framework or webhook integrations.

CRUD (5 actions)

Entity record create, read, update, and delete operations. The mutation actions share logic through BaseRecordMutationAction.

Data Transformation (7 actions)

Parse, transform, aggregate, and explore structured data.

File Operations (8 actions)

Document generation, parsing, compression, and spreadsheet I/O.

File Storage (12 actions)

Granular cloud storage operations for Azure Blob, AWS S3, Google Cloud Storage, Google Drive, Dropbox, Box.com, and SharePoint. All extend BaseFileStorageAction.

Integration (5 actions)

HTTP, GraphQL, OAuth, rate limiting, and third-party service integrations.

List Management (6 actions)

Manage MJ lists and list membership for entities.

MCP (5 actions)

Interact with external Model Context Protocol (MCP) servers.

Security (1 action)

User Management (5 actions)

Utilities (6 actions)

Miscellaneous server-side utilities.

Visualization (7 actions)

Generate SVG charts, diagrams, and infographics using D3 and Rough.js. All produce self-contained SVG markup suitable for embedding in HTML or saving as files.

Web (6 actions)

Search the web, extract page content, and validate URLs.

Workflow Control (5 actions)

Orchestrate action execution with branching, iteration, parallelism, and retry logic.

Code Execution (1 action)

Interactive Forms (6 actions)

The lifecycle for runtime-author entity forms (form-role ComponentSpec + EntityFormOverride). See /plans/interactive-forms/phase-2-runtime-loop.md for the full architecture and security model. Mutation actions enforce ownership checks (User → caller, Role → membership, Global → admin).

Demo (6 actions)

Reference implementations useful for testing and learning.

Generated (2 actions)

AI-generated entity-specific child actions. These are maintained by CodeGen and should not be manually edited.

Usage Examples

Executing an Action via the Engine

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

const engine = ActionEngineServer.Instance;

// Send an email
const result = await engine.RunAction({
    ActionName: '__SendSingleMessage',
    Params: [
        { Name: 'Provider', Value: 'SendGrid' },
        { Name: 'MessageType', Value: 'Email' },
        { Name: 'From', Value: 'noreply@example.com' },
        { Name: 'To', Value: 'user@example.com' },
        { Name: 'Subject', Value: 'Hello' },
        { Name: 'Body', Value: '<p>Hello from MJ</p>' }
    ],
    ContextUser: currentUser
});
Copy

CRUD Operations

// Create a record
const createResult = await engine.RunAction({
    ActionName: 'CreateRecordAction',
    Params: [
        { Name: 'EntityName', Value: 'Contacts' },
        { Name: 'Fields', Value: { FirstName: 'Jane', LastName: 'Doe', Email: 'jane@example.com' } }
    ],
    ContextUser: currentUser
});

// Get a record
const getResult = await engine.RunAction({
    ActionName: 'GetRecordAction',
    Params: [
        { Name: 'EntityName', Value: 'Contacts' },
        { Name: 'PrimaryKey', Value: { ID: 'abc-123' } }
    ],
    ContextUser: currentUser
});
Copy

AI Prompt Execution

const aiResult = await engine.RunAction({
    ActionName: 'Execute AI Prompt',
    Params: [
        { Name: 'PromptName', Value: 'Summarize Text' },
        { Name: 'Variables', Value: { text: 'Long article content...' } },
        { Name: 'TemperatureOverride', Value: 0.3 }
    ],
    ContextUser: currentUser
});
Copy

Workflow Control

// Conditional branching
const condResult = await engine.RunAction({
    ActionName: 'Conditional',
    Params: [
        { Name: 'Condition', Value: 'amount > 1000' },
        { Name: 'Context', Value: { amount: 1500 } },
        { Name: 'TrueAction', Value: { ActionName: 'Slack Webhook', Params: { /* ... */ } } },
        { Name: 'FalseAction', Value: { ActionName: 'Delay', Params: { Duration: 5000 } } }
    ],
    ContextUser: currentUser
});

// Parallel execution
const parallelResult = await engine.RunAction({
    ActionName: 'Parallel Execute',
    Params: [
        { Name: 'Actions', Value: ['Action1', 'Action2', 'Action3'] }
    ],
    ContextUser: currentUser
});
Copy

Data Transformation

// Parse CSV
const csvResult = await engine.RunAction({
    ActionName: 'CSV Parser',
    Params: [
        { Name: 'CSVData', Value: 'Name,Age\nAlice,30\nBob,25' },
        { Name: 'HasHeaders', Value: true }
    ],
    ContextUser: currentUser
});

// Aggregate data
const aggResult = await engine.RunAction({
    ActionName: 'Aggregate Data',
    Params: [
        { Name: 'Data', Value: [{ dept: 'Eng', salary: 100000 }, { dept: 'Eng', salary: 120000 }] },
        { Name: 'GroupBy', Value: 'dept' },
        { Name: 'Aggregations', Value: { avgSalary: 'avg:salary', count: 'count:*' } }
    ],
    ContextUser: currentUser
});
Copy

Action Execution Flow

The following diagram illustrates how an action invocation flows from caller through the engine to this package's registered classes.

sequenceDiagram
    participant Caller as Caller (Agent / Workflow)
    participant Engine as ActionEngineServer
    participant Factory as MJGlobal.ClassFactory
    participant Action as CoreAction subclass
    participant Service as Underlying Service

    Caller->>Engine: RunAction({ ActionName, Params, ContextUser })
    Engine->>Factory: Resolve registered class for ActionName
    Factory-->>Engine: Action instance
    Engine->>Action: InternalRunAction(params)
    Action->>Action: Extract & validate parameters
    Action->>Service: Delegate to service / framework class
    Service-->>Action: Result
    Action->>Action: Build ActionResultSimple + output params
    Action-->>Engine: { Success, Message, ResultCode }
    Engine-->>Caller: ActionResult

    note over Action,Service: Actions are thin wrappers.
Business logic lives in service classes.
Copy

Dependencies

MemberJunction Packages

Third-Party Libraries

Related Packages

• @memberjunction/actions-base -- Base classes, interfaces, and metadata engines
• @memberjunction/actions -- Server-side action execution engine
• Parent Actions README -- Framework overview, generated actions guide, and best practices
• Parent Actions CLAUDE.md -- Design philosophy and development guidelines