@memberjunction/actions-bizapps-lms

Learning Management System (LMS) integration actions for MemberJunction. This package provides a standardized, multi-provider interface for interacting with LMS platforms through the MemberJunction Actions framework, currently supporting LearnWorlds with an extensible architecture for additional providers.

For general Actions framework concepts, patterns, and the "Actions as boundaries" philosophy, see the Actions README and Actions CLAUDE.md. For shared BizApps patterns (credential management, provider base classes, multi-tenant support), see the BizApps README.

Architecture

The package follows a three-tier class hierarchy: a domain-level base class providing common LMS utilities, provider-specific base classes handling API authentication and communication, and individual action classes implementing specific operations.

graph TD
    subgraph Framework["MemberJunction Actions Framework"]
        BA[BaseAction
@memberjunction/actions]
    end

    subgraph Domain["Domain Layer"]
        BLMS[BaseLMSAction
Credential management
Progress calculation
Duration formatting
Enrollment status mapping]
    end

    subgraph Provider["Provider Layer"]
        LWBase[LearnWorldsBaseAction
API v2 authentication
Paginated requests
Date format conversion
Status mapping]
    end

    subgraph Actions["LearnWorlds Actions"]
        direction LR
        UM["User Management
GetUsers | GetUserDetails
CreateUser | GetUserProgress"]
        CM["Course Management
GetCourses | GetCourseDetails
GetCourseAnalytics"]
        EM["Enrollment Management
EnrollUser | GetUserEnrollments
UpdateUserProgress"]
        AM["Assessment & Certs
GetQuizResults
GetCertificates"]
    end

    BA --> BLMS
    BLMS --> LWBase
    LWBase --> UM
    LWBase --> CM
    LWBase --> EM
    LWBase --> AM

    style Framework fill:#64748b,stroke:#475569,color:#fff
    style Domain fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Provider fill:#7c5295,stroke:#563a6b,color:#fff
    style Actions fill:#2d8659,stroke:#1a5c3a,color:#fff
Copy

Credential Resolution Flow

All actions resolve API credentials through a consistent two-step process, checking environment variables first with a database fallback.

flowchart LR
    A[Action invoked
with CompanyID] --> B{Check env var
BIZAPPS_LEARNWORLDS
_CompanyID_API_KEY}
    B -- Found --> D[Use env credentials]
    B -- Not found --> C[Query CompanyIntegration
entity from database]
    C --> E{APIKey or
AccessToken
present?}
    E -- Yes --> F[Use DB credentials]
    E -- No --> G[Throw error:
No credentials found]
    D --> H[Build API request
with Bearer token]
    F --> H

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#b8762f,stroke:#8a5722,color:#fff
    style C fill:#7c5295,stroke:#563a6b,color:#fff
    style D fill:#2d8659,stroke:#1a5c3a,color:#fff
    style F fill:#2d8659,stroke:#1a5c3a,color:#fff
    style G fill:#64748b,stroke:#475569,color:#fff
    style H fill:#2d8659,stroke:#1a5c3a,color:#fff
    style E fill:#b8762f,stroke:#8a5722,color:#fff
Copy

Installation

npm install @memberjunction/actions-bizapps-lms
Copy

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

Setup

1. Create Integration Record

INSERT INTO Integration (Name, Description, NavigationBaseURL, ClassName)
VALUES ('LearnWorlds', 'LearnWorlds LMS Integration',
        'https://api.learnworlds.com', 'LearnWorldsIntegration');
Copy

2. Configure CompanyIntegration

INSERT INTO CompanyIntegration (CompanyID, IntegrationID, ExternalSystemID, IsActive)
VALUES (@CompanyID, @LearnWorldsIntegrationID, @SchoolDomain, 1);
-- ExternalSystemID: Your LearnWorlds school domain (e.g., 'myschool.learnworlds.com')
Copy

3. Set Environment Variables

# Format: BIZAPPS_LEARNWORLDS_{COMPANY_ID}_{CREDENTIAL_TYPE}
BIZAPPS_LEARNWORLDS_12345_API_KEY=lw_api_xxxxxxxxxxxxx
BIZAPPS_LEARNWORLDS_12345_SCHOOL_DOMAIN=myschool.learnworlds.com
Copy

Available Actions

User Management

Course Management

Enrollment Management

Assessment and Certificates

API Reference

Base Classes

BaseLMSAction

Abstract base class for all LMS actions. Provides:

• getCompanyIntegration(companyId, contextUser) - Resolves the CompanyIntegrationEntity for the given company, with internal caching
• getCredentialFromEnv(companyId, credentialType) - Reads credentials from environment variables using the BIZAPPS_{PROVIDER}_{COMPANY_ID}_{TYPE} pattern
• getAPICredentials(integration) - Two-step credential resolution (environment variables first, then database)
• calculateProgressPercentage(completed, total) - Computes progress as a rounded percentage
• formatDuration(seconds) - Converts seconds to human-readable format (e.g., 2h 15m 30s)
• mapEnrollmentStatus(status) - Normalizes provider-specific statuses to standard values: active, completed, expired, suspended, unknown

LearnWorldsBaseAction

LearnWorlds-specific base class extending BaseLMSAction. Provides:

• makeLearnWorldsRequest<T>(endpoint, method, body, contextUser) - Authenticated HTTP request to the LearnWorlds v2 API with Bearer token, error parsing, and JSON handling
• makeLearnWorldsPaginatedRequest<T>(endpoint, params, contextUser) - Auto-paginating wrapper that collects all pages of results, respecting MaxResults limits
• parseLearnWorldsDate(dateString) - Handles both ISO strings and Unix epoch timestamps (seconds)
• mapUserStatus(status) - Maps LearnWorlds statuses to active | inactive | suspended
• mapLearnWorldsEnrollmentStatus(enrollment) - Determines enrollment status from boolean flags (completed, expired, suspended, active)
• calculateProgress(progressData) - Extracts percentage, completed/total units, and time spent from LearnWorlds progress objects

Action Parameters

Every action requires the CompanyID input parameter (inherited from BaseLMSAction). Additional parameters are action-specific, documented in the sections below.

GetLearnWorldsUsersAction

Input Parameters:

Output Parameters:

GetLearnWorldsUserDetailsAction

Input Parameters:

Output Parameters:

GetLearnWorldsUserProgressAction

Input Parameters:

Output Parameters:

GetLearnWorldsCoursesAction

Input Parameters:

Output Parameters:

GetLearnWorldsCourseDetailsAction

Input Parameters:

Output Parameters:

EnrollUserAction

Input Parameters:

Output Parameters:

GetUserEnrollmentsAction

Input Parameters:

Output Parameters:

UpdateUserProgressAction

Input Parameters:

Output Parameters:

GetCourseAnalyticsAction

Input Parameters:

Output Parameters:

GetCertificatesAction

Input Parameters:

Output Parameters:

GetQuizResultsAction

Input Parameters:

Output Parameters:

Exported Interfaces

The package exports several TypeScript interfaces for strong typing:

• LearnWorldsUser - User profile with status, role, tags, custom fields, and course statistics
• LearnWorldsUserDetails - Extended user profile with enrollment details, achievements, and account settings
• UserEnrollment - Individual course enrollment with progress, grade, and certificate data
• CourseProgress - Detailed progress for a single course including unit-level breakdown
• UnitProgress - Progress within a course module/section
• LessonProgress - Individual lesson progress with type-specific fields (video watch time, quiz scores, assignment grades)
• UserLearningProgress - Aggregated learning progress across all courses with analytics
• LearnWorldsCourse - Full course metadata including pricing, structure, enrollment data, and learning outcomes
• CourseCatalogSummary - Catalog-level statistics with category, level, language, enrollment, and price breakdowns

Usage Examples

Get Active Students with Course Statistics

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

const engine = ActionEngineServer.Instance;
const result = await engine.RunAction({
    ActionName: 'GetLearnWorldsUsersAction',
    Params: [
        { Name: 'CompanyID', Value: 'company-123' },
        { Name: 'Role', Value: 'student' },
        { Name: 'Status', Value: 'active' },
        { Name: 'IncludeCourseStats', Value: true },
        { Name: 'SortBy', Value: 'last_login' },
        { Name: 'SortOrder', Value: 'desc' }
    ],
    ContextUser: currentUser
});

if (result.Success) {
    const users = result.Params.find(p => p.Name === 'Users')?.Value;
    const summary = result.Params.find(p => p.Name === 'Summary')?.Value;
    console.log(`Found ${users.length} active students`);
    console.log(`Average courses per student: ${summary.averageCoursesPerUser}`);
}
Copy

Track User Learning Progress

const result = await engine.RunAction({
    ActionName: 'GetLearnWorldsUserProgressAction',
    Params: [
        { Name: 'CompanyID', Value: 'company-123' },
        { Name: 'UserID', Value: 'user-456' },
        { Name: 'IncludeUnitDetails', Value: true },
        { Name: 'IncludeLessonDetails', Value: true }
    ],
    ContextUser: currentUser
});

if (result.Success) {
    const progress = result.Params.find(p => p.Name === 'UserProgress')?.Value;
    console.log(`Completed ${progress.coursesCompleted} of ${progress.totalCourses} courses`);
    console.log(`Overall progress: ${progress.overallProgressPercentage}%`);

    for (const course of progress.courses) {
        if (course.status === 'in_progress') {
            console.log(`  ${course.courseTitle}: ${course.progressPercentage}%`);
        }
    }
}
Copy

Search Course Catalog

const result = await engine.RunAction({
    ActionName: 'GetLearnWorldsCoursesAction',
    Params: [
        { Name: 'CompanyID', Value: 'company-123' },
        { Name: 'SearchText', Value: 'JavaScript' },
        { Name: 'Status', Value: 'published' },
        { Name: 'Level', Value: 'beginner' },
        { Name: 'MaxPrice', Value: 100 }
    ],
    ContextUser: currentUser
});

if (result.Success) {
    const courses = result.Params.find(p => p.Name === 'Courses')?.Value;
    for (const course of courses) {
        console.log(`${course.title} - $${course.price} (${course.totalEnrollments} students)`);
    }
}
Copy

Create User and Enroll in Courses

const result = await engine.RunAction({
    ActionName: 'CreateUserAction',
    Params: [
        { Name: 'CompanyID', Value: 'company-123' },
        { Name: 'Email', Value: 'new.student@example.com' },
        { Name: 'FirstName', Value: 'Jane' },
        { Name: 'LastName', Value: 'Smith' },
        { Name: 'Role', Value: 'student' },
        { Name: 'SendWelcomeEmail', Value: true },
        { Name: 'EnrollInCourses', Value: ['course-101', 'course-202'] }
    ],
    ContextUser: currentUser
});

if (result.Success) {
    const summary = result.Params.find(p => p.Name === 'Summary')?.Value;
    console.log(`Created user: ${summary.email}`);
    console.log(`Enrolled in ${summary.coursesEnrolled} of ${summary.totalCoursesRequested} courses`);
}
Copy

Adding New Providers

The package is designed for extensibility. To add support for a new LMS provider:

1. Create a provider directory: src/providers/{provider-name}/
2. Create a provider base class extending BaseLMSAction with provider-specific authentication and API communication
3. Implement individual action classes extending the provider base class
4. Map provider-specific data formats to the shared interfaces (LearnWorldsUser, CourseProgress, etc.)
5. Export everything from provider and actions index files
6. Re-export the new provider from src/index.ts

src/
  base/
    base-lms.action.ts          # Domain base class (shared)
  providers/
    learnworlds/                # Existing provider
      learnworlds-base.action.ts
      actions/
        get-users.action.ts
        ...
    moodle/                     # New provider
      moodle-base.action.ts
      actions/
        get-users.action.ts
        ...
  index.ts
Copy

Dependencies

Related Packages

• @memberjunction/actions - Actions execution engine
• @memberjunction/actions-base - Base classes and type definitions
• @memberjunction/actions-bizapps-accounting - Accounting system integrations (QuickBooks, etc.)
• @memberjunction/actions-bizapps-crm - CRM system integrations

Building

# Build this package
cd packages/Actions/BizApps/LMS
npm run build

# Watch mode for development
npm run watch
Copy