@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, Tavily) 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
  tavilyApiKey: 'tvly-...',            // or TAVILY_API_KEY env var
  google: {
    customSearch: {
      apiKey: 'AIza...',               // or GOOGLE_CUSTOM_SEARCH_API_KEY
      cx: '017...',                    // or GOOGLE_CUSTOM_SEARCH_CX
    }
  }
};
Copy

Choosing a web-search provider

Agents that do web research (Research Agent, Sage, the Web Research skill) are granted both the Perplexity Search and Google Custom Search actions, and are instructed to prefer Perplexity and fall back if one returns a missing-API-key error. Credential whichever you have:

New deployments should configure perplexityApiKey. Google's stated successor, Vertex AI Search, is not a drop-in: it uses service-account auth against a data store over your own content and does not return public web results, so it produces neither of the two values this config expects and there is no MJ action for it. Deployments that already have Custom Search access can keep using it through 2026 and add perplexityApiKey whenever convenient — configuring both is supported.

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.

Chief of Staff / agent governance (8 actions)

Actions used by the Chief of Staff agent (and other autonomous agents) to manage their own policy, schedule, coordination and user-scoped communication. All of them bind to ContextUser -- an agent can only act on, and read for, the calling user. The four * My * actions extend BaseUserScopedCommunicationAction and are also registered under a __-prefixed alias (for example __ManageMyEmailInbox).

The mailbox actions run through the enterprise provider's app-level credential (Microsoft Graph or Gmail) and the gate in BaseUserScopedCommunicationAction: the caller's email domain must match the provider's AllowedEmailDomains, the provider's EnterpriseScopeMode must allow personal mailboxes (otherwise the action falls back to the user's MJ: AI Bridge Agent Identities utility inbox), and the provider's mailbox-access preflight must succeed. The per-user OAuth service described below is a separate, not-yet-wired path to the same mailboxes.

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.

Create Mermaid Diagram renders in headless Chromium, which the playwright dependency does not install. Install one on the host with npx playwright install chromium, or set MJ_CHROMIUM_EXECUTABLE_PATH to an existing binary. Without one the action returns BROWSER_UNAVAILABLE.

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.

Per-user OAuth 2.0 (3LO) service -- prototype

CommunicationUserOAuthService (src/custom/ai/communication-oauth-service.ts) is a BaseSingleton that lets an individual user connect their own Microsoft Graph or Google Workspace mailbox to MJ through three-legged OAuth, instead of the app-level credential the mailbox actions above use today. It is not an action; it is a service a host (MJServer route, test harness) drives directly.

Status: prototype, off by default. Gates 1 to 3 are administrator settings on MJ: Communication Providers: AllowUserDelegatedOAuth (bit, default 0), AllowedEmailDomains and AllowedOAuthTenantIDs (both comma-separated, optional). ReadProviderUserOAuthGates(providerEntity) lifts them into the gate fields of a ProviderUserOAuthPolicyConfig; the caller adds the OAuth client settings (endpoints, client id, redirect URI, scopes), which are not yet stored anywhere. Unless an administrator sets AllowUserDelegatedOAuth = 1 on a provider, no user can initiate a personal OAuth flow. See "Current limitations" below before relying on it.

Flow

sequenceDiagram
    participant Host as Host (route / caller)
    participant Svc as CommunicationUserOAuthService
    participant IdP as Microsoft / Google
    participant Store as IUserDelegatedCredentialStore

    Host->>Svc: InitiateAuthorizationFlow(policy, contextUser)
    Svc->>Svc: Gate 1, Gate 2 (contextUser.Email)
    Svc-->>Host: AuthorizationUrl + State (PKCE S256, 10-minute session)
    Host->>IdP: redirect user, user consents
    IdP-->>Host: code + state
    Host->>Svc: HandleOAuthCallback({ state, code, policy, contextUser, transport })
    Svc->>Svc: state valid, same user, Gate 1 again
    Svc->>IdP: transport.ExchangeAuthorizationCode (code + code_verifier)
    Svc->>Svc: Gate 2 (token email), Gate 3, Gate 4
    Svc->>Store: StoreUserDelegatedCredential(...)
    Svc-->>Host: OAuthCallbackResult (CredentialID, PrincipalEmail)
Copy

1. Initiate -- InitiateAuthorizationFlow(policy, contextUser) checks Gates 1 and 2, generates a PKCE S256 verifier/challenge pair (GeneratePkcePair) and a random state, keeps them in an in-memory session for 10 minutes, and returns an OAuthInitiateResult whose AuthorizationUrl includes code_challenge, code_challenge_method=S256 and login_hint.
2. Consent -- the host redirects the browser to AuthorizationUrl; the identity provider redirects back with code and state.
3. Callback -- HandleOAuthCallback(params) consumes the session (one use), rejects an expired or unknown state (INVALID_OR_EXPIRED_STATE) or a different calling user (STATE_USER_MISMATCH), exchanges the code through the injected IOAuthTokenTransport, runs Gates 2 through 4 against the verified token identity, and stores the result.
4. Store -- the credential is written through IUserDelegatedCredentialStore.StoreUserDelegatedCredential under the name UserOAuth3LO:<provider>:<ownerUserId> with ownerUserId inside the encrypted values. See @memberjunction/credentials for the owner-binding rules.
5. Disconnect -- DisconnectAndRevokeUserOAuth(params) revokes the refresh (or access) token at the provider when the transport implements RevokeToken, then deactivates the stored credential and wipes its token values. Revocation failure at the provider is reported in RevokedAtProvider but does not stop the local deactivation.

The four gates

Gates 2 and 3 are opt-in narrowing; Gates 1 and 4 always apply. All result codes are the CommunicationOAuthResultCode union.

Injection points

• ProviderUserOAuthPolicyConfig -- the caller builds this: ProviderName, the four gate fields, ClientId/ClientSecret, AuthorizationEndpoint, TokenEndpoint, optional RevocationEndpoint, RedirectUri, Scopes.
• IOAuthTokenTransport (required on callback) -- ExchangeAuthorizationCode must return a VerifiedOAuthTokenExchangeResult whose PrincipalEmail and TenantID come from a verified source (id_token claims or the provider's userinfo endpoint), because Gates 2 to 4 trust them. RevokeToken is optional.
• IUserDelegatedCredentialStore (optional) -- defaults to CredentialEngine.Instance from @memberjunction/credentials, which owns credential naming (UserOAuth3LO:<provider>:<ownerUserId>), owner binding, the required credential type, encryption and audit logging. Inject another store only for tests.

Current limitations

• No stored OAuth client settings and no admin UI beyond the generated form. The gate fields live on MJ: Communication Providers (editable through its generated Explorer form), but ClientId, ClientSecret, endpoints, RedirectUri and Scopes still come from the caller.
• No built-in transport and no routes. IOAuthTokenTransport has no shipped implementation. The file header mentions /api/v1/communication-oauth/initiate and /callback, but no MJServer routes exist yet; a host must build them with ApiRoute() and call the service.
• No consumer of the stored token. The Microsoft Graph and Gmail communication providers still authenticate with app-level credentials; a connected 3LO credential is stored but not yet used by any mailbox action.
• Pending sessions are process-local. The initiate/callback session map lives in memory, so both calls must reach the same process, and a restart drops in-flight authorizations.

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