Skip to content
  • There are no suggestions because the search field is empty.

Creating and Testing Roleplay SCORM Packages

Overview

SCORM (Sharable Content Object Reference Model) packages allow Roleplay practice sessions to be embedded within Learning Management Systems (LMS). This guide walks you through creating, testing, and deploying Roleplay SCORM packages.

What You'll Learn

  • How to export Roleplay Environments as SCORM packages

  • Understanding the Roleplay SCORM architecture

  • Testing packages with ScormCloud

  • Deploying to your LMS

  • Troubleshooting common issues

Prerequisites

Before creating SCORM packages, ensure:

  • ✅ You have access to Rehearsal with appropriate permissions

  • ✅ You have authored at least one Roleplay Environment

  • ✅ Your organization has Roleplay enabled

  • ✅ Your LMS supports SCORM 1.2 or SCORM 2004

  • ✅ (Optional) SSO is configured if using authenticated access

Creating a SCORM Package

Step 1: Navigate to Environments

  1. Log into Rehearsal

  2. Go to Roleplay > Environments

  3. Select the environment you want to export

Step 2: Export as SCORM

Click the Export SCORM button (may be labeled "Export to LMS" in some versions)

Step 3: Configure Package Settings

Package Filename

  • Default: Uses the Environment name automatically

  • Customizable: Change if needed for your LMS organization

  • Auto-scrubbed: Special characters are removed to ensure LMS compatibility

Package Format

Choose between two SCORM standards:

Format

Best For

Compatibility

SCORM 1.2

Broader LMS compatibility

Older and modern LMS platforms

SCORM 2004

More advanced features

Modern LMS platforms


💡 Tip: Choose based on what your LMS best supports. When in doubt, start with SCORM 1.2.

Enable Grading

  • Default: Disabled (false)

  • When enabled: You must define a passing grade percentage

  • Impact:

    • ✅ With grading enabled: Course marked as "passed" or "failed" based on score threshold

    • ✅ Without grading: Course only marked as "completed"

    • Note: Score values are always saved to the LMS regardless of this setting

Step 4: Download Package

Click Export to download your .zip SCORM package file.

Understanding the Architecture

Roleplay's SCORM implementation uses a two-component architecture to work around browser limitations:

The Roleplay Relay (iframe)

Purpose: Acts as the SCORM communication layer

Location: Embedded in an iframe within the LMS page

Responsibilities:

    • Handles all SCORM-specific logic and LMS communication

    • Stores session state data (for resumption)

    • Manages completion data transmission

    • Provides launch button for the Roleplay Session

    • Remains visible in the LMS while the session runs

Key Feature: Keeps the Roleplay session agnostic to LMS standards, allowing the same session code to work across different integration methods.

The Roleplay Session (separate window)

Purpose: The actual practice session

Location: Launches in a separate top-level window (required due to browser limitations)

Characteristics:

    • Must run in its own window (cannot be in an iframe)

    • Direct path to the session preview page

    • Handles authentication (SSO or standard login)

    • Communicates back to the Relay via postMessage API

    • Limited UI when in "LMS mode" (only session-related pages)

How They Work Together

LMS Page

  └── Relay (iframe) ←→ Session (separate window)

         ↓

      SCORM API

         ↓

        LMS

  1. Launch: LMS embeds the Relay in an iframe on the course page

  2. Start: Learner clicks button in Relay to launch Session in new window

  3. Practice: Learner completes Roleplay session in the separate window

  4. Report: Session sends completion data to Relay via postMessage

  5. Update: Relay updates LMS via SCORM API

Why This Architecture?

  • Relay in iframe: Keeps it visible in the LMS context, reduces window clutter

  • Session in separate window: Technical requirement - the Roleplay session cannot function properly within an iframe due to browser security restrictions

  • Result: Cleaner UX with only 2 contexts (LMS page with Relay + Session window)

Session Management

Resuming Incomplete Sessions

Automatic Resume Logic:

    • When a session starts, the session ID is saved as "active" in the LMS

    • If the learner closes without completing, this ID persists

    • On next launch, the preview page automatically restarts the incomplete session

    • Prevents learners from accidentally starting multiple sessions

Clearing Active Sessions:

    • Active session is cleared only when analysis completes

    • Ensures incomplete work isn't lost

    • After completion, next launch will start a fresh session

Score Handling

Highest Score Wins:

    • LMS score is updated ONLY if the new score is higher than the existing score

    • Protects learners' best performance

    • Allows multiple attempts without penalty

Update Conditions:

    • ✅ First session (no existing score)

    • ✅ New score > Current LMS score

    • ❌ New score ≤ Current LMS score (no update)

Time Tracking

    • Only the current session time is sent to the LMS

    • LMS is responsible for accumulating total time across attempts

    • Time is sent on completion

Completion Status

Status Updates:

    • In Progress: Session launched but not completed

    • Completed: Analysis finished and shown to learner

    • Passed/Failed: Based on grading settings (if enabled)

Important: Completion status is only sent when the learner views their analysis. Closing before analysis means the session remains incomplete.

Deploying to Your LMS

Import Process

The exact steps vary by LMS platform, but generally:

  1. Navigate to your course/module in your LMS

  2. Look for "Add Content", "Import Package", or similar option

  3. Upload the SCORM .zip file

  4. Configure assignment settings (due dates, attempts allowed, etc.)

  5. Publish/make available to learners

Launch Options

Recommended Configuration: Launch the SCORM package in an iframe within the LMS page

Mode

Description

Impact on Roleplay

Recommendation

Inline/iframe

Opens Relay within the LMS page

✅ Relay shows in iframe, Session opens in separate window

✅ Recommended - Cleaner UX, Relay stays visible

Popup Window

Opens Relay in popup window

❌ Relay in popup, Session in another popup

Less ideal - creates 2 separate windows

💡 Best Practice: Configure your LMS to launch the SCORM package inline/in an iframe. This keeps the Relay visible in the LMS context while the Roleplay Session runs in its separate window, providing a cleaner learner experience.

Authentication

With SSO:

    • User is automatically authenticated when launched from LMS

    • No additional login required

    • Seamless experience

Without SSO:

    • User must log in when Roleplay Session opens

    • Session state management still works

    • Remembers logged-in users on shared devices (consider security implications)

Testing with ScormCloud

ScormCloud is a free testing platform for SCORM packages. Use it to verify your package before deploying to your production LMS.

Setting Up ScormCloud

  1. Navigate to https://app.cloud.scorm.com/sc/guest/SignInForm

  2. Create a free account if you don't have one

  3. Log in to your ScormCloud dashboard

Uploading Your Package

  1. Click the green Add Content button (top right corner)

  2. Click Choose file and select your SCORM .zip file

  3. Click Import Course

  4. Wait for upload to complete

Reviewing Import Results

After import, you'll see your course sandbox:

Check for Issues:

    • ✅ Parser logs: Should be empty (errors here need addressing)

    • ✅ Learning Standard: Confirms SCORM version (1.2 or 2004)

    • ✅ Initial Status: Completion, Success, and Score will show "unknown"

    • ✅ Total Time: Should show 0s initially

Launching Your Course

  1. Click the green Launch button

  2. First launch: May show "Popup Blocked" message

    • Allow popups, or change to "same window" in course settings

    • Click Launch Course again in the popup window

Testing Scenarios

Test 1: Incomplete Session

Steps:

    1. Launch from LMS

    2. Start Roleplay session

    3. Close without completing at least one turn

Expected Results:

    • ❌ Completion: Incomplete

    • ❌ Score: 0 or unknown

    • ⚠️ Time: May show window open time, but not meaningful

Test 2: Complete Session (First Attempt)

Steps:

    1. Launch from LMS

    2. Complete at least one turn

    3. Wait for analysis to complete

    4. View the results

Expected Results:

    • ✅ Completion: Complete

    • ✅ Score: Shows session score

    • ✅ Time: Shows time spent in session

Test 3: Second Attempt (Higher Score)

Steps:

    1. Launch again

    2. Complete session with higher score

Expected Results:

    • ✅ Score: Updates to new higher score

    • ✅ Time: Adds new session time to total

Test 4: Second Attempt (Lower Score)

Steps:

    1. Launch again

    2. Complete session with lower score

Expected Results:

    • ✅ Score: Remains unchanged (keeps highest)

    • ✅ Time: Still adds new session time to total

Viewing Debug Logs

To see detailed SCORM communication:

    1. Scroll to the Debug Log section in the Course Sandbox

    2. Click on the latest log entry

    3. Review SCORM API calls and data values

What to look for:

    • cmi.core.score.raw: The score value

    • cmi.core.lesson_status: Completion status (completed, incomplete, passed, failed)

    • cmi.core.session_time: Time spent in session

    • Any error messages or failed API calls

Best Practices

Naming Conventions

Descriptive Names:

    • ✅ Sales-Negotiation-Q1-2026.zip

    • ✅ Customer-Service-Phone-Basics.zip

    • ❌ environment-export.zip

    • ❌ test123.zip

Consider:

    • Course/module name in your LMS

    • Department or audience

    • Version or date if multiple exports

Choosing SCORM Version

Choose SCORM 1.2 When

Choose SCORM 2004 When

Maximum compatibility needed

Using modern LMS with advanced features

Uncertain about LMS capabilities

Need detailed completion tracking

Simple pass/fail or completion

Using sequencing or prerequisites

Working with older LMS

LMS documentation recommends 2004

Grading Strategy

Enable Grading When:

    • ✅ You want pass/fail distinction in LMS

    • ✅ You have a clear performance threshold

    • ✅ Learners need to meet minimum standards

Disable Grading When:

    • ✅ You only need completion tracking

    • ✅ All practice is valuable regardless of score

    • ✅ You want to reduce learner anxiety

Setting Passing Grade:

    • Consider your learner population's typical performance

    • Start with 70% if uncertain

    • Can be adjusted in future exports

Testing Strategy

Before Production:

    1. ✅ Test in ScormCloud first

    2. ✅ Test in your LMS staging environment

    3. ✅ Have a colleague test as a learner

    4. ✅ Test multiple attempts (higher and lower scores)

    5. ✅ Test incomplete session resumption

    6. ✅ Verify gradebook updates correctly

After Deployment:

    • Monitor first few learner attempts

    • Collect feedback on UX

    • Check for any support requests

    • Review LMS analytics

Version Control

Recommendation: Keep track of SCORM package versions

  • Include version or date in package name

  • Keep source Environment documented

  • Note any custom debug mode changes

  • Document LMS-specific settings used

Troubleshooting

Enabling Debug Mode

Debug mode provides verbose logging in the browser console for both the Relay and Session windows.

Manual Debug Mode: For staging or production packages:

    1. Unzip the SCORM package

    2. Open data/environment.json

    3. Add or change: "debug": true

    4. Re-zip the package

    5. Upload to LMS

Viewing Logs:

    • Open browser console (F12 or Cmd+Option+I)

    • Look in both the Relay window and Session window

    • Errors will always log; debug mode adds detailed info

Common Issues

Issue: Session Not Resuming

Symptoms: Learner expects to resume but starts a new session

Possible Causes:

    • Previous session was completed (active session was cleared)

    • LMS data was reset manually

    • Different user logged in

Solution:

    • Check debug logs for active session ID

    • Verify LMS suspend data contains session ID

    • Ensure user authentication is consistent

Issue: Score Not Updating in LMS

Symptoms: LMS shows old score despite new session completion

Possible Causes:

    • New score is lower than existing score (expected behavior)

    • SCORM API call failed

    • LMS doesn't display scores immediately

Solutions:

    • ✅ Check debug logs for SCORM SetValue calls

    • ✅ Verify new score is actually higher

    • ✅ Check LMS gradebook vs course player (may differ)

    • ✅ Confirm LMS is set to accept scores from SCORM packages

Issue: Completion Not Marked

Symptoms: Learner completed session but LMS shows incomplete

Possible Causes:

    • Learner closed before viewing analysis

    • SCORM communication failed

    • LMS requires specific completion criteria

Solutions:

    • ✅ Ensure learner views analysis page completely

    • ✅ Check debug logs for completion status SetValue

    • ✅ Verify LMS completion criteria settings

    • ✅ Check that grading is configured correctly if using pass/fail

Issue: Popup Blocked

Symptoms: Session window doesn't open when clicking the launch button in the Relay

Cause: Browser popup blocker is preventing the Session window from opening

Solutions:

    • Instruct learners to allow popups for your LMS domain and Rehearsal domain

    • Ensure the SCORM package is launched in iframe mode (recommended), not as a popup

    • Check browser security settings and whitelist required domains

    • Provide clear instructions to learners about allowing popups for Roleplay

Issue: Audio/Video Not Working

Symptoms: Microphone or camera permissions denied in the Roleplay Session

Solutions:

    • Ensure HTTPS is being used (required for media access)

    • Check browser permissions for the Rehearsal domain

    • Note: Media permissions are needed for the Session window (separate window), not the Relay iframe

    • Verify the learner's browser allows media access for the Rehearsal domain

Getting Additional Help

Information to Provide:

  • SCORM package filename and version

  • LMS platform and version

  • Browser and version

  • Debug logs from both Relay and Session windows

  • Screenshots of the issue

  • Steps to reproduce

Additional Resources

SCORM Standards

Frequently Asked Questions

Q: Can learners access the same session outside the LMS? A: If they have direct Rehearsal access, yes. The LMS tracks separately from direct access.

Q: How many attempts can learners make? A: This is controlled by your LMS settings, not the SCORM package. Configure in your LMS.

Q: What happens if a learner's session is interrupted (internet loss, browser crash)? A: The session ID is saved, and they'll be prompted to resume on next launch.

Q: Can I update a SCORM package after deployment? A: Yes, but learner progress may be affected. Test thoroughly. Consider creating new assignment for major changes.

Q: Does the package work offline? A: No, Roleplay requires an internet connection to reach the Rehearsal servers for the session.

Q: Can I customize the Relay window appearance? A: Not in v1. The Relay uses standard Rehearsal branding.

Q: What data is stored in the LMS? A: Completion status, score, time spent, and session ID (for resumption). Full session data stays in Rehearsal.

Changelog

Version

Date

Changes

1.0

Jan 2026

Initial knowledgebase article created

 

Need help? Submit a ticket to Customer Solutions for assistance with SCORM package creation and deployment.