@memberjunction/scheduled-actions-server

A standalone Express server application that executes scheduled actions in the MemberJunction framework. This server exposes HTTP endpoints to trigger scheduled actions including AI-powered content autotagging, vectorization, Apollo data enrichment, and any custom scheduled actions defined in the MJ system.

For the broader Actions design philosophy (when to use Actions, thin wrapper patterns, anti-patterns), see the Actions CLAUDE.md in the parent directory.

Architecture

The server follows a simple request-driven architecture: an HTTP GET request arrives with a comma-delimited list of action options, the server initializes the MJ metadata layer (once per process lifetime), resolves the requested actions against a registry of runOption entries, and delegates execution to the ScheduledActionEngine from @memberjunction/scheduled-actions.

flowchart TD
    subgraph Client["HTTP Client"]
        style Client fill:#2d6a9f,stroke:#1a4971,color:#fff
        REQ["GET /?options=ScheduledActions,enrichaccounts"]
    end

    subgraph Server["Express Server (index.ts)"]
        style Server fill:#2d8659,stroke:#1a5c3a,color:#fff
        PARSE["Parse comma-delimited options"]
        MATCH["Match against runOptions registry"]
        EXEC["executeRunOption with concurrency guard"]
    end

    subgraph Init["Server Initialization (util.ts)"]
        style Init fill:#7c5295,stroke:#563a6b,color:#fff
        POOL["SQL ConnectionPool connect"]
        SETUP["setupSQLServerClient with config"]
    end

    subgraph Engine["ScheduledActionEngine"]
        style Engine fill:#b8762f,stroke:#8a5722,color:#fff
        ALL["ExecuteScheduledActions"]
        SINGLE["ExecuteScheduledAction by name"]
    end

    REQ --> PARSE --> MATCH --> EXEC
    EXEC -->|first call only| Init
    EXEC -->|"all" option| ALL
    EXEC -->|named action| SINGLE
    Init --> POOL --> SETUP

Source File Layout

| File | Purpose | |------|---------| | src/index.ts | Express app, route handler, runOption registry, exported action functions | | src/config.ts | Environment variable parsing via env-var and dotenv | | src/db.ts | SQL Server connection pool configuration (mssql) | | src/util.ts | One-time server initialization (handleServerInit) and timeout helper |

Installation

npm install @memberjunction/scheduled-actions-server

This package is typically deployed as a standalone server rather than imported as a library, but its action functions are exported for programmatic use.

Configuration

All configuration is driven by environment variables (loaded via dotenv):

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DB_HOST | Yes | -- | SQL Server hostname | | DB_PORT | No | 1433 | SQL Server port | | DB_USERNAME | Yes | -- | Database username | | DB_PASSWORD | Yes | -- | Database password | | DB_DATABASE | Yes | -- | Database name | | MJ_CORE_SCHEMA | Yes | -- | MemberJunction schema name (e.g., __mj) | | CURRENT_USER_EMAIL | Yes | -- | Email of the user context for action execution | | PORT | No | 8000 | HTTP server listen port | | METADATA_AUTO_REFRESH_INTERVAL | No | 3600000 | Metadata cache refresh interval in milliseconds |

Create a .env file in the package root or set these variables in your deployment environment.

Usage

Starting the Server

# Development mode with hot reload
npm run dev

# Development with debugging (inspector on port 4321)
npm run dev:debug

# Production mode
npm run start

HTTP API

GET /

Triggers one or more scheduled actions based on the options query parameter.

| Parameter | Type | Description | |-----------|------|-------------| | options | string | Comma-delimited list of action option names to execute |

# Run all registered actions
curl "http://localhost:8000/?options=all"

# Run only the MJ scheduled actions engine
curl "http://localhost:8000/?options=ScheduledActions"

# Run multiple specific actions
curl "http://localhost:8000/?options=enrichaccounts,enrichcontacts"

# Run content autotagging and vectorization
curl "http://localhost:8000/?options=autoTagAndVectorize"

Response format:

{ "Status": "Success" }

or

{ "Status": "Error" }

Available Action Options

| Option | Description | |--------|-------------| | all | Runs every registered action (excluding itself) sequentially | | ScheduledActions | Executes all scheduled actions defined in the MJ system via ScheduledActionEngine | | enrichaccounts | Runs the "Apollo Enrichment - Accounts" scheduled action | | enrichcontacts | Runs the "Apollo Enrichment - Contacts" scheduled action | | autoTagAndVectorize | Runs the "Autotag And Vectorize Content" scheduled action |

Concurrency Control

Each runOption entry has a maxConcurrency property (default: 1). If a request arrives while the maximum number of concurrent executions is already in progress for a given option, that option is skipped and an error is logged. This prevents resource exhaustion from overlapping long-running jobs.

flowchart LR
    subgraph Guard["Concurrency Guard"]
        style Guard fill:#2d6a9f,stroke:#1a4971,color:#fff
        CHECK{"currentRuns < maxConcurrency?"}
        INC["currentRuns++"]
        RUN["Execute action"]
        DEC["currentRuns-- (finally)"]
        SKIP["Log error, return false"]
    end

    CHECK -->|Yes| INC --> RUN --> DEC
    CHECK -->|No| SKIP

Programmatic Usage

The package exports its action functions for use from other Node.js code:

import {
    runAll,
    runScheduledActions,
    enrichAccounts,
    enrichContacts,
    autotagAndVectorize,
    runScheduledAction
} from '@memberjunction/scheduled-actions-server';

// Execute all registered actions
const allSuccess = await runAll();

// Execute a specific named scheduled action
const result = await runScheduledAction('My Custom Scheduled Action');

// Execute built-in actions individually
await runScheduledActions();
await enrichAccounts();
await enrichContacts();
await autotagAndVectorize();

Server Initialization

The server initializes the MJ metadata layer exactly once per process lifetime via handleServerInit(). This function:

1. Connects the mssql connection pool to SQL Server
2. Configures the MJ SQL Server data provider with the schema name and optional auto-refresh interval
3. Sets a flag to prevent re-initialization on subsequent requests

The SQL connection pool uses a 5-minute request timeout (300000ms) to accommodate long-running scheduled actions.

API Reference

Types

runOption

type runOption = {
    name: string;
    description?: string;
    run: (initServer: boolean) => Promise<boolean>;
    maxConcurrency?: number;
    currentRuns?: number;
}

Defines a named action option that can be triggered via HTTP or programmatically.

Exported Functions

| Function | Signature | Description | |----------|-----------|-------------| | runAll | () => Promise<boolean> | Runs all registered actions (excluding all itself) sequentially | | runScheduledActions | () => Promise<boolean> | Executes all MJ scheduled actions via ScheduledActionEngine | | enrichAccounts | () => Promise<boolean> | Runs the "Apollo Enrichment - Accounts" scheduled action | | enrichContacts | () => Promise<boolean> | Runs the "Apollo Enrichment - Contacts" scheduled action | | autotagAndVectorize | () => Promise<boolean> | Runs the "Autotag And Vectorize Content" scheduled action | | runScheduledAction | (actionName: string) => Promise<boolean> | Runs a single named scheduled action |

All functions return true on success and false on failure. Errors are logged via MJ's LogError and LogStatus utilities.

Build and Development

# Build TypeScript to dist/
npm run build

# Watch mode for development
npm run watch

# Run linting (ESLint + TypeScript type checking)
npm run lint

# Clean build artifacts
npm run clean

# Create deployment ZIP (node_modules + dist + package.json)
npm run zip

Dependencies

MemberJunction Packages

| Package | Purpose | |---------|---------| | @memberjunction/core | Core metadata, logging (LogStatus, LogError), Metadata class | | @memberjunction/core-entities | Entity type definitions | | @memberjunction/actions | Action framework base classes | | @memberjunction/scheduled-actions | ScheduledActionEngine for executing scheduled actions | | @memberjunction/sqlserver-dataprovider | SQL Server data provider, UserCache, setupSQLServerClient | | @memberjunction/ai | AI integration framework | | @memberjunction/ai-openai | OpenAI model driver | | @memberjunction/ai-mistral | Mistral AI model driver | | @memberjunction/ai-vectors-pinecone | Pinecone vector database integration | | @memberjunction/ai-vector-sync | Vector synchronization utilities | | @memberjunction/actions-apollo | Apollo data enrichment actions | | @memberjunction/actions-content-autotag | Content autotagging action |

Third-Party

| Package | Purpose | |---------|---------| | express | HTTP server framework | | mssql | SQL Server client (connection pooling, query execution) | | dotenv | .env file loading | | env-var | Type-safe environment variable parsing with defaults | | typescript | TypeScript compiler |

Related Packages

| Package | Relationship | |---------|-------------| | @memberjunction/scheduled-actions | Core engine that this server wraps -- contains ScheduledActionEngine | | @memberjunction/actions | Base action framework used by all action implementations | | @memberjunction/actions-apollo | Apollo enrichment action implementations invoked by this server | | @memberjunction/actions-content-autotag | Content autotagging action invoked by this server |