@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

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

Base Classes

Several abstract base classes reduce duplication across related actions:

Base Class	Location	Purpose
`BaseRecordMutationAction`	`crud/base-record-mutation.action.ts`	Shared parameter extraction, entity loading, error analysis for Create/Update/Delete
`BaseFileStorageAction`	`files/base-file-storage.action.ts`	Common storage-provider resolution for all `File Storage: *` actions
`BaseFileHandlerAction`	`utilities/base-file-handler.ts`	Multi-source file loading (Storage, URL, direct data)

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:

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

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.

Registration Name	Class	Description
`Execute AI Prompt`	`ExecuteAIPromptAction`	Run a named MJ AI prompt with variable substitution and optional model/temperature overrides
`SummarizeContentAction`	`SummarizeContentAction`	Summarize text content using AI
`Find Candidate Agents`	`FindCandidateAgentsAction`	Discover AI agents suitable for a task
`Find Candidate Actions`	`FindCandidateActionsAction`	Discover actions suitable for a task
`Find Best Agent`	`FindBestAgentAction`	Select the single best agent for a task
`Find Best Action`	`FindBestActionAction`	Select the single best action for a task
`Load Agent Spec`	`LoadAgentSpecAction`	Load full specification for an AI agent
`Generate Image`	`GenerateImageAction`	Generate images using AI models

Communication (3 actions)

Send messages via the MJ Communication Framework or webhook integrations.

Registration Name	Class	Description
`__SendSingleMessage`	`SendSingleMessageAction`	Send a single message through any configured provider (email, SMS, etc.)
`Slack Webhook`	`SlackWebhookAction`	Post messages to Slack via incoming webhooks
`Teams Webhook`	`TeamsWebhookAction`	Post messages to Microsoft Teams via incoming webhooks

CRUD (5 actions)

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

Registration Name	Class	Description
`CreateRecordAction`	`CreateRecordAction`	Create a new entity record
`GetRecordAction`	`GetRecordAction`	Retrieve a single entity record by primary key
`GetRecordsAction`	`GetRecordsAction`	Retrieve multiple entity records with filtering
`UpdateRecordAction`	`UpdateRecordAction`	Update an existing entity record
`DeleteRecordAction`	`DeleteRecordAction`	Delete an entity record by primary key

Data Transformation (7 actions)

Parse, transform, aggregate, and explore structured data.

Registration Name	Class	Description
`CSV Parser`	`CSVParserAction`	Parse CSV with configurable delimiters, headers, and type coercion
`JSON Transform`	`JSONTransformAction`	Transform JSON using JSONPath queries
`XML Parser`	`XMLParserAction`	Parse XML to JSON with namespace and attribute control
`Aggregate Data`	`AggregateDataAction`	Group-by aggregation (sum, avg, count, min, max) with having clauses
`Data Mapper`	`DataMapperAction`	Map fields between data structures using template expressions
`Explore Database Schema`	`ExploreDatabaseSchemaAction`	Retrieve entity metadata and schema information
`Run Ad-hoc Query`	`RunAdhocQueryAction`	Execute ad-hoc SQL queries against entity data

File Operations (8 actions)

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

Registration Name	Class	Description
`PDF Generator`	`PDFGeneratorAction`	Generate PDFs from HTML or Markdown content
`PDF Extractor`	`PDFExtractorAction`	Extract text and metadata from PDF files
`Excel Reader`	`ExcelReaderAction`	Read data from Excel files with multi-sheet support
`Excel Writer`	`ExcelWriterAction`	Create formatted Excel files from structured data
`File Compress`	`FileCompressAction`	Compress files into ZIP archives
`File Storage: Get File Content`	`GetFileContentAction`	Read file content from MJ storage
`List Storage Accounts`	`ListStorageAccountsAction`	List available storage provider accounts
`Search Storage Files`	`SearchStorageFilesAction`	Search across storage providers by name or metadata

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.

Registration Name	Class	Description
`File Storage: List Objects`	`ListObjectsAction`	List objects in a container/bucket
`File Storage: Get Object`	`GetObjectAction`	Download an object from storage
`File Storage: Get Object Metadata`	`GetMetadataAction`	Retrieve object metadata
`File Storage: Get Download URL`	`GetDownloadUrlAction`	Generate a download URL (SAS/presigned)
`File Storage: Get Upload URL`	`GetUploadUrlAction`	Generate an upload URL
`File Storage: Check Object Exists`	`ObjectExistsAction`	Check if an object exists
`File Storage: Check Directory Exists`	`DirectoryExistsAction`	Check if a directory/prefix exists
`File Storage: Copy Object`	`CopyObjectAction`	Copy an object within or across containers
`File Storage: Move Object`	`MoveObjectAction`	Move an object (copy + delete)
`File Storage: Delete Object`	`DeleteObjectAction`	Delete an object from storage
`File Storage: Create Directory`	`CreateDirectoryAction`	Create a directory/prefix
`File Storage: Delete Directory`	`DeleteDirectoryAction`	Delete a directory/prefix

Integration (5 actions)

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

Registration Name	Class	Description
`HTTP Request`	`HTTPRequestAction`	Make HTTP requests with auth, headers, and body support
`GraphQL Query`	`GraphQLQueryAction`	Execute GraphQL queries and mutations
`OAuth Flow`	`OAuthFlowAction`	Handle OAuth 2.0 authorization flows
`API Rate Limiter`	`APIRateLimiterAction`	Rate-limit outbound API calls
`Gamma Generate Presentation`	`GammaGeneratePresentationAction`	Generate presentations via the Gamma API

List Management (6 actions)

Manage MJ lists and list membership for entities.

Registration Name	Class	Description
`Add Records to List`	`AddRecordsToListAction`	Add one or more records to a list
`Remove Records from List`	`RemoveRecordsFromListAction`	Remove records from a list
`Create List`	`CreateListAction`	Create a new list with optional initial records
`Get List Records`	`GetListRecordsAction`	Retrieve records from a list with filtering
`Get Record List Membership`	`GetRecordListMembershipAction`	Find which lists contain a specific record
`Update List Item Status`	`UpdateListItemStatusAction`	Bulk-update status on list items

MCP (5 actions)

Interact with external Model Context Protocol (MCP) servers.

Registration Name	Class	Description
`Execute MCP Tool`	`ExecuteMCPToolAction`	Execute a tool on a connected MCP server
`List MCP Tools`	`ListMCPToolsAction`	List available tools from MCP servers
`Sync MCP Tools`	`SyncMCPToolsAction`	Synchronize MCP tool definitions to MJ metadata
`Test MCP Connection`	`TestMCPConnectionAction`	Test connectivity to an MCP server
`MCPToolAction`	`MCPToolAction`	Generic MCP tool invocation wrapper

Security (1 action)

Registration Name	Class	Description
`Password Strength`	`PasswordStrengthAction`	Evaluate password strength using zxcvbn

User Management (5 actions)

Registration Name	Class	Description
`CreateUserAction`	`CreateUserAction`	Create a new MJ user
`CreateEmployeeAction`	`CreateEmployeeAction`	Create a new employee record
`AssignUserRolesAction`	`AssignUserRolesAction`	Assign roles to a user
`CheckUserPermissionAction`	`CheckUserPermissionAction`	Check if a user has a specific permission
`ValidateEmailUniqueAction`	`ValidateEmailUniqueAction`	Validate that an email address is unique

Utilities (6 actions)

Miscellaneous server-side utilities.

Registration Name	Class	Description
`__VectorizeEntity`	`VectorizeEntityAction`	Create AI vector embeddings for entity records
`__RunExternalChangeDetection`	`ExternalChangeDetectionAction`	Detect changes in external data sources
`__BusinessDaysCalculator`	`BusinessDaysCalculatorAction`	Calculate business days between dates
`__IPGeolocation`	`IPGeolocationAction`	Look up geographic location by IP address
`__CensusDataLookup`	`CensusDataLookupAction`	Query US Census Bureau data
`__QRCode`	`QRCodeAction`	Generate QR code images

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.

Registration Name	Class	Description
`__CreateSVGChart`	`CreateSVGChartAction`	Bar, line, pie, scatter, and area charts via D3
`__CreateSVGDiagram`	`CreateSVGDiagramAction`	Flowcharts and process diagrams
`__CreateSVGWordCloud`	`CreateSVGWordCloudAction`	Word cloud visualizations via d3-cloud
`__CreateSVGNetwork`	`CreateSVGNetworkAction`	Force-directed network graphs via d3-force
`__CreateSVGInfographic`	`CreateSVGInfographicAction`	Multi-section infographics with icons and data
`__CreateSVGSketchDiagram`	`CreateSVGSketchDiagramAction`	Hand-drawn style diagrams via Rough.js
`__CreateMermaidDiagram`	`CreateMermaidDiagramAction`	Render Mermaid diagram definitions to SVG

Web (6 actions)

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

Registration Name	Class	Description
`__WebSearch`	`WebSearchAction`	Search the web via DuckDuckGo with rate limiting
`__WebPageContent`	`WebPageContentAction`	Extract content from a web page
`__URLLinkValidator`	`URLLinkValidatorAction`	Validate that a URL is reachable
`__URLMetadataExtractor`	`URLMetadataExtractorAction`	Extract OpenGraph/meta tags from a URL
`Perplexity Search`	`PerplexitySearchAction`	AI-powered search via Perplexity API
`Google Custom Search`	`GoogleCustomSearchAction`	Search via Google Custom Search API

Workflow Control (5 actions)

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

Registration Name	Class	Description
`Conditional`	`ConditionalAction`	Branch execution based on a JavaScript condition
`Loop`	`LoopAction`	Iterate over collections or numeric ranges
`Parallel Execute`	`ParallelExecuteAction`	Run multiple actions concurrently
`Retry`	`RetryAction`	Retry a failed action with configurable attempts and backoff
`Delay`	`DelayAction`	Pause execution for a specified duration

Code Execution (1 action)

Registration Name	Class	Description
`__ExecuteCode`	`ExecuteCodeAction`	Execute sandboxed code snippets

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).

Registration Name	Class	Description
`__GetEntitySchemaForForm`	`GetEntitySchemaForFormAction`	Read-only: returns the curated form-relevant schema for an entity (FKs resolved, value lists annotated, audit fields stripped).
`__GetDefaultFormScaffoldForEntity`	`GetDefaultFormScaffoldForEntityAction`	Read-only: produces a working form-role `ComponentSpec` mirroring the CodeGen Angular default layout. The agent’s baseline.
`__GetActiveFormForEntity`	`GetActiveFormForEntityAction`	Read-only: returns the resolved Active override + full applicable-variants list for the (entity, calling-user) pair.
`__CreateInteractiveForm`	`CreateInteractiveFormAction`	Net-new only. Inserts Component v1.0.0 + Active User-scope Override. Fails `ALREADY_EXISTS` if the user already has an Active override for the entity.
`__ModifyInteractiveForm`	`ModifyInteractiveFormAction`	Branches on the pointed-to Component status: Pending → modify in place; Active → new Pending Component v(N+1) + sibling Pending Override. Always User-scope-clamped.
`__ActivateInteractiveFormVersion`	`ActivateInteractiveFormVersionAction`	Promotes a Pending override to Active; atomically demotes the prior sibling Active.
`__RevertInteractiveForm`	`RevertInteractiveFormAction`	Re-points an Active override at an older Component row in the same Name lineage. Pure UPDATE; no new rows.

Demo (6 actions)

Reference implementations useful for testing and learning.

Registration Name	Class	Description
`__GetWeather`	`GetWeatherAction`	Retrieve weather data for a location
`__GetStockPrice`	`GetStockPriceAction`	Look up stock price information
`__CalculateExpression`	`CalculateExpressionAction`	Evaluate mathematical expressions
`__ColorConverter`	`ColorConverterAction`	Convert between color formats (hex, RGB, HSL)
`__TextAnalyzer`	`TextAnalyzerAction`	Analyze text for word count, readability, etc.
`__UnitConverter`	`UnitConverterAction`	Convert between measurement units

Generated (2 actions)

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

Registration Name	Class	Description
`Create Conversation Record`	`Create_Conversation_Record_Action`	Create a Conversations entity record (child of Create Record)
`Get AI Model Cost`	`Get_AI_Model_Cost_Action`	Look up cost information for an AI model (child of Get Record)

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

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

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

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

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

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.<br/>Business logic lives in service classes.

Dependencies

MemberJunction Packages

Package	Purpose
`@memberjunction/actions`	`BaseAction` class and `ActionEngineServer`
`@memberjunction/actions-base`	`ActionResultSimple`, `RunActionParams`, `ActionParam` types
`@memberjunction/core`	`Metadata`, `RunView`, `BaseEntity`, logging utilities
`@memberjunction/global`	`RegisterClass` decorator
`@memberjunction/ai`	AI model abstraction layer
`@memberjunction/ai-prompts`	`AIPromptRunner` for prompt execution
`@memberjunction/ai-core-plus`	`AIPromptParams`, `AIPromptEntityExtended`
`@memberjunction/aiengine`	`AIEngine` singleton for model/prompt discovery
`@memberjunction/communication-engine`	Message sending infrastructure
`@memberjunction/communication-types`	`Message` type definitions
`@memberjunction/storage`	Cloud storage provider abstraction
`@memberjunction/export-engine`	Data export utilities
`@memberjunction/ai-vector-sync`	Vector embedding synchronization
`@memberjunction/ai-mcp-client`	MCP server communication
`@memberjunction/code-execution`	Sandboxed code execution
`@memberjunction/external-change-detection`	External change tracking
`@memberjunction/content-autotagging`	Content categorization

Third-Party Libraries

Library	Used By
`d3-scale`, `d3-shape`, `d3-cloud`, `d3-force`, `d3-hierarchy`	Visualization actions (SVG charts, word clouds, networks)
`roughjs`	Sketch-style diagram rendering
`mermaid`	Mermaid diagram rendering
`pdfkit`	PDF generation
`pdf-parse`	PDF text extraction
`exceljs`	Excel read/write
`papaparse`	CSV parsing
`xml2js`, `xpath`, `@xmldom/xmldom`	XML parsing
`marked`, `turndown`	Markdown/HTML conversion
`jsdom`	Server-side DOM for web content extraction
`mammoth`	Word document conversion
`archiver`, `unzipper`	File compression
`axios`	HTTP requests
`jsonpath-plus`, `jmespath`	JSON querying
`nunjucks`	Template rendering
`zxcvbn`	Password strength analysis
`zod`	Configuration schema validation
`cosmiconfig`	Config file loading

@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