@memberjunction/scheduled-actions

Scheduling engine for MemberJunction that enables recurring or one-time future execution of any defined action using cron expressions. The engine extends BaseEngine from @memberjunction/core, caching scheduled action metadata as a singleton and evaluating cron-based timing to determine which actions are due for execution.

For the broader Actions design philosophy — including when to use Actions vs. direct class imports, and the “thin wrapper” principle — see the parent Actions CLAUDE.md.

Installation

npm install @memberjunction/scheduled-actions

This package is server-side only. It depends on @memberjunction/sqlserver-dataprovider for dynamic SQL parameter evaluation and @memberjunction/actions for action execution.

Architecture

ScheduledActionEngine is a singleton that loads two entity collections on Config(): Scheduled Actions and Scheduled Action Params. At execution time, it evaluates each action’s cron expression against the current time, maps scheduled action params to the underlying action’s expected params (resolving static values and SQL statements), and delegates execution to ActionEngineServer.

flowchart TD
    subgraph Caller["Caller (Server / Cron Job)"]
        TRIGGER["ExecuteScheduledActions(contextUser)"]
    end

    subgraph SAE["ScheduledActionEngine"]
        CONFIG["Config() -- load metadata"]
        EVAL["Evaluate CronExpression\nfor each active action"]
        MAP["MapScheduledActionParamsToActionParams"]
    end

    subgraph ParamResolution["Parameter Resolution"]
        STATIC["Static: parse JSON or use raw value"]
        SQL["SQL Statement: execute via SQLServerDataProvider"]
    end

    subgraph AES["ActionEngineServer"]
        RUN["RunAction(action, params, contextUser)"]
    end

    TRIGGER --> CONFIG --> EVAL
    EVAL -->|action is due| MAP
    MAP --> STATIC
    MAP --> SQL
    MAP -->|ActionParam array| RUN

    style Caller fill:#2d6a9f,stroke:#1a4971,color:#fff
    style SAE fill:#7c5295,stroke:#563a6b,color:#fff
    style ParamResolution fill:#b8762f,stroke:#8a5722,color:#fff
    style AES fill:#2d8659,stroke:#1a5c3a,color:#fff

Execution Sequence

sequenceDiagram
    participant Caller
    participant SAE as ScheduledActionEngine
    participant AES as ActionEngineServer
    participant DB as SQLServerDataProvider

    Caller->>SAE: ExecuteScheduledActions(contextUser)
    SAE->>AES: Config(false, contextUser)
    SAE->>SAE: Config(false, contextUser) -- load metadata

    loop For each ScheduledAction
        SAE->>SAE: IsActionDue(action, now)
        alt Action is due
            loop For each ScheduledActionParam
                alt ValueType == Static
                    SAE->>SAE: SafeJSONParse(value) or raw string
                else ValueType == SQL Statement
                    SAE->>DB: ExecuteSQL(sql)
                    DB-->>SAE: query result
                end
            end
            SAE->>AES: RunAction(action, params, contextUser)
            AES-->>SAE: ActionResult
        end
    end

    SAE-->>Caller: ActionResult[]

Key Concepts

Scheduled Action Entity

Each scheduled action record links to an underlying MJ Action and defines when it should execute. The entity includes these fields:

Field	Type	Description
Name	string	Unique name identifying the scheduled action
Description	string | null	Optional description of what this scheduled action does
ActionID	string	Foreign key to the Actions entity — the action to execute
Type	'Daily' | 'Weekly' | 'Monthly' | 'Yearly' | 'Custom'	Schedule type; non-Custom types auto-generate the cron expression on save
CronExpression	string | null	Cron expression for timing; auto-maintained unless Type is Custom
Timezone	string	Timezone for schedule evaluation (defaults to UTC)
Status	'Pending' | 'Active' | 'Disabled' | 'Expired'	Only active actions are eligible for execution
IntervalDays	number | null	Interval in days (used for certain schedule types)
DayOfWeek	string | null	Day of week for Weekly schedules
DayOfMonth	number | null	Day of month for Monthly/Yearly schedules
Month	string | null	Month for Yearly schedules
CustomCronExpression	string | null	User-provided cron expression for Custom type

The MJScheduledActionEntityExtended class (from @memberjunction/core-entities) overrides Save() to auto-generate the CronExpression from Type, DayOfWeek, DayOfMonth, and Month whenever the type is not Custom. It also adds a Params property that the engine populates during Config().

Scheduled Action Params

Each param maps a scheduled action’s input to the underlying action’s expected parameter:

Field	Type	Description
ScheduledActionID	string	Foreign key to the parent scheduled action
ActionParamID	string	Foreign key to the Action Params entity — which param to populate
ValueType	'Static' | 'SQL Statement'	How the value is resolved at execution time
Value	string | null	Either a literal value / JSON string, or a SQL query
Comments	string | null	Optional notes about this parameter mapping

Parameter Resolution

At execution time, each scheduled action param is resolved based on its ValueType:

• Static — The Value is first attempted as JSON via SafeJSONParse(). If parsing succeeds (returns non-null), the parsed object is used. Otherwise, the raw string value is passed through. This allows both scalar values ("42") and structured data ('{"key": "value"}').

• SQL Statement — The Value is executed against SQL Server via SQLServerDataProvider.ExecuteSQL(). The query result becomes the parameter value. This enables dynamic parameter population at runtime (e.g., SELECT COUNT(*) FROM Users WHERE Active = 1).

Cron Expression Evaluation

The engine uses the cron-parser library to evaluate cron expressions. The static IsActionDue() method parses the expression, computes the next execution time from the evaluation time, and returns true if the next execution is at or before the current time.

Cron format (6 fields):

second  minute  hour  day-of-month  month  day-of-week
  0       0      0       *            *        *

Schedule types auto-generate these expressions:

• Daily: 0 0 0 * * ? — midnight every day
• Weekly: 0 0 0 ? * {DayOfWeek} — midnight on the specified day
• Monthly: 0 0 0 {DayOfMonth} * ? — midnight on the specified day of month
• Yearly: 0 0 0 {DayOfMonth} {Month} ? — midnight on the specified day and month
• Custom: Uses the manually provided cron expression

Usage

Executing All Due Scheduled Actions

The primary use case is running all scheduled actions that are due at the current time:

import { ScheduledActionEngine } from '@memberjunction/scheduled-actions';
import { UserInfo } from '@memberjunction/core';

async function runDueActions(contextUser: UserInfo) {
    const engine = ScheduledActionEngine.Instance;

    // Execute all actions whose cron expressions indicate they are due
    const results = await engine.ExecuteScheduledActions(contextUser);

    for (const result of results) {
        if (result.Success) {
            console.log(`Action succeeded: ${result.Message}`);
        } else {
            console.error(`Action failed: ${result.Message}`);
        }
    }
}

Executing a Specific Scheduled Action by Name

To run a single scheduled action directly, bypassing the cron check if no expression is set:

import { ScheduledActionEngine } from '@memberjunction/scheduled-actions';

async function runSpecificAction(contextUser: UserInfo) {
    const engine = ScheduledActionEngine.Instance;

    // Throws if the named action does not exist
    // Skips cron evaluation if CronExpression is null
    const result = await engine.ExecuteScheduledAction('Daily Sales Report', contextUser);

    if (result?.Success) {
        console.log('Report generated successfully');
    }
}

Refreshing Cached Metadata

The engine caches scheduled actions and their params. Force a refresh when metadata has changed:

const engine = ScheduledActionEngine.Instance;

// Force reload from database
await engine.Config(true, contextUser);

// Inspect loaded data
const actions = engine.ScheduledActions;      // MJScheduledActionEntityExtended[]
const params = engine.ScheduledActionParams;  // ScheduledActionParamEntity[]

Checking If an Action Is Due

The static IsActionDue method can be used independently to test cron expression evaluation:

import { ScheduledActionEngine } from '@memberjunction/scheduled-actions';

const isDue = ScheduledActionEngine.IsActionDue(scheduledAction, new Date());
if (isDue) {
    console.log(`${scheduledAction.Name} is due for execution`);
}

API Reference

ScheduledActionEngine

Singleton engine extending BaseEngine<ScheduledActionEngine>. Access via ScheduledActionEngine.Instance.

Properties

Property	Type	Description
Instance	ScheduledActionEngine	Static singleton accessor
ScheduledActions	MJScheduledActionEntityExtended[]	All loaded scheduled actions (with Params populated)
ScheduledActionParams	ScheduledActionParamEntity[]	All loaded scheduled action parameter mappings

Methods

Method	Signature	Description
Config	(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider) => Promise<boolean>	Load or refresh scheduled action metadata from the database. Automatically associates params with their parent actions via AdditionalLoading.
ExecuteScheduledActions	(contextUser: UserInfo) => Promise<ActionResult[]>	Evaluate all scheduled actions against the current time and execute those that are due. Returns results for each executed action.
ExecuteScheduledAction	(actionName: string, contextUser: UserInfo) => Promise<ActionResult>	Execute a specific scheduled action by name. Throws if not found. Skips cron evaluation if CronExpression is null.
IsActionDue	static (scheduledAction: MJScheduledActionEntityExtended, evalTime: Date) => boolean	Determine whether a scheduled action’s cron expression indicates it is due at the given evaluation time.

Protected Methods

Method	Signature	Description
MapScheduledActionParamsToActionParams	(scheduledAction: MJScheduledActionEntityExtended) => Promise<ActionParam[]>	Resolve all param mappings for a scheduled action, handling both Static and SQL Statement value types.
ExecuteSQL	(sql: string) => Promise<unknown>	Execute a SQL query via SQLServerDataProvider and return the result. Logs errors and returns null on failure.
AdditionalLoading	(contextUser?: UserInfo) => Promise<void>	Post-load hook that associates ScheduledActionParams with their parent ScheduledActions via the Params property.

Dependencies

MemberJunction Packages

Package	Purpose
@memberjunction/core	BaseEngine, Metadata, UserInfo, LogError, IMetadataProvider
@memberjunction/core-entities	MJScheduledActionEntityExtended, ScheduledActionParamEntity entity classes
@memberjunction/actions-base	MJActionEntityExtended, ActionParam, ActionResult, RunActionParams types
@memberjunction/actions	ActionEngineServer — executes actions through the full pipeline
@memberjunction/core-actions	Core action implementations (ensures built-in actions are registered)
@memberjunction/core-entities-server	Server-side entity extensions
@memberjunction/global	SafeJSONParse utility
@memberjunction/sqlserver-dataprovider	SQLServerDataProvider for executing dynamic SQL parameter queries

Third-Party

Package	Purpose
cron-parser	Parses and evaluates cron expressions to determine execution timing

Related Packages

Package	Relationship
@memberjunction/scheduled-actions-server	Express server that wraps this engine, exposing HTTP endpoints for triggering scheduled actions
@memberjunction/actions	Server-side action execution engine that this package delegates to for running actions
@memberjunction/actions-base	Shared types and base engine classes used by the action framework
@memberjunction/core-actions	Built-in action implementations that can be scheduled