LMS data migration from a legacy LMS: data mapping and scripts

Featured image with an aqua pastel background and a wave pattern, showing the post title "LMS Data Migration: Data Mapping and Scripts"

LMS data migration from a legacy LMS: data mapping and scripts

LMS data migration works when you treat it as a mapping exercise, not a file copy. Users, courses, enrollments and completion records move as flat rows that you can script and reconcile. SCORM runtime state, xAPI statements and certificates need separate decisions, because many target systems cannot take them as they are.

This guide is for training providers moving off an aging LMS. It gives a field-level mapping table with the loss and risk of each row, plus a short Python script, tested on illustrative data, that transforms legacy CSV exports and prints a reconciliation report.

Key takeaways

  • Script users, courses, enrollments and completions. Decide SCORM runtime state, xAPI history and certificates separately.
  • Write the status mapping down: SCORM 1.2 has one status field, SCORM 2004 splits completion from success, and your target picks its own shape.
  • Check what the target can import before promising history. One vendor’s documentation says it cannot import views, attempts or scores.
  • Derive new IDs from legacy IDs so loads can be rerun, and require every run to balance.

What can you move in an LMS data migration, and what stays behind?

Four record types move cleanly: users, courses, enrollments and completions, because each is a flat row with a few fields. Three do not: SCORM runtime state, xAPI statements and certificates, because their meaning depends on the content, the learning record store or the issuing rules. Script the first group and decide the second.

Sort the legacy system into three buckets before writing code:

  • Script it: users, courses, enrollments, completion status, dates and scores.
  • Decide it: issued certificates, xAPI history, SCORM bookmarks and suspend data.
  • Rebuild it: assignment rules, automations, report definitions and email templates. These are configuration, not data.

How do you map legacy LMS fields to the new system?

Start from the target’s import template and work backward. For each target field, name the legacy source and what is lost. The table does this for the fields most training providers carry. Field names are generic examples, so replace them with your export’s headers, and spend your sign-off time on the last column.

Entity Legacy field (typical) Target field Loss or risk
User identity user_id, username New user reference plus a stored legacy ID Old IDs sit in printed certificates and reports. Without a crosswalk, history cannot be linked back.
Email email email (login and match key) Case, spaces and shared mailboxes merge or split people. Blank blocks the load.
Account status Codes such as A, S, T active, suspended, inactive Unknown codes. Reactivating a suspended or departed person by mistake.
Course course_id, title, version Course reference plus a stored legacy ID Versions merge. Retired courses are still needed for history.
Enrollment user_id, course_id, enrolled_on Enrollment record Duplicates after user merges. Retakes collapse unless the target models attempts.
Completion status and date lesson_status (or completion and success status), completed_on Completion, result, completed_on Compliance counts change if “failed” or “browsed” maps differently. Blank dates. Time zone shifts near midnight.
Score score_raw score, if the target accepts one Scale differences. Some targets import completions only.
Attempts and interactions Attempt rows, question responses Usually none: archive Question-level detail is lost. Keep the export.
Certificate Number, issued, expires, PDF Certificate record or archive Reissuing changes numbers and can break verification links.

Target limits are real. Thrive’s import documentation says its historical completion import takes three columns (user email, content ID, completion date), needs the user and content to exist first, and cannot import views, attempts or scores. Read your target’s equivalent page before promising anyone their history.

How do SCORM 1.2 and 2004 statuses map to one completion field?

They do not map one to one, so choose a target pair of completion and result and record the choice. The SCORM run-time reference lists one lesson status with six values in SCORM 1.2, and separate completion and success statuses in SCORM 2004. The mapping below is a working design, not part of either specification.

SCORM 1.2 lesson_status Target completion Target result Reasoning
passed completed passed Unambiguous.
completed completed none No pass or fail recorded.
failed in_progress failed Stays open for a retake. Change it if compliance counts a failed attempt as finished.
incomplete in_progress none Started, not finished.
browsed in_progress none Opened, not graded. Some teams prefer not_started.
not attempted not_started none Enrolled only.

Pro tip: Count before you map. Run a row count per status value on the real export before choosing the mapping. Vendor-specific values such as “done” and blank statuses show up there, and each needs a rule before the load.

What happens to SCORM runtime data, xAPI statements and certificates?

Treat each as its own decision. SCORM runtime data is content-specific state that rarely survives a move. xAPI statements can be replayed into a new learning record store, but the stored time changes. Certificates are records you either carry over unchanged or reissue under a documented rule.

Can you move SCORM bookmarks and suspend data?

Rarely, and it is usually not worth the effort. Suspend data is free-form space the content uses between sessions. The run-time reference above lists its smallest permitted maximum as 4096 characters in SCORM 1.2, 4000 in the SCORM 2004 2nd Edition and 64000 in the 3rd and 4th Editions, so the size an LMS accepts can differ between systems.

Only the same package at the same version can interpret those strings, so copying them is a gamble. Migrate completions, then decide per course whether in-progress learners finish on the old system or restart, and launch each package afterward to confirm completion registers.

How do you migrate xAPI statements and cmi5 registrations?

Replay them into the new store, or keep the old store read-only and query both. The xAPI data specification says statements are immutable, and that voiding does not destroy a statement but marks its evidence as disregarded. Copy voiding statements too, or the new store will count evidence the old one ignored.

The same specification says the store must set the “stored” property and overwrite any value it receives. Every replayed statement will therefore show the migration date as stored, while “timestamp” keeps the original event time. Report on timestamp, and keep the original statement IDs. Our xAPI guide for classroom activities covers statement structure.

cmi5 adds one more identifier: each enrollment has its own registration, and a retake gets a new one, as our cmi5 explainer for training providers describes. The cmi5 specification says the LMS must generate the registration value and pass it in the launch URL, so store the old registration IDs in the crosswalk instead of trying to reuse them.

What should you do about old certificates?

Carry over the number, issue date, expiry date and original PDF as an archive record, then decide whether the new system reissues or only references them. Reissuing usually changes the number, which can break a verification link printed on the old one. That is a policy decision for your compliance owner, not a technical default.

How do you write an LMS data migration script you can rerun?

Write a script that reads the legacy CSV exports, applies the mapping table, writes target-shaped files, and exits with an error unless the counts balance. Derive target IDs from legacy IDs, so rehearsals and the final load produce the same keys and a failed run costs nothing.

The script ran on Python 3.13 with only the standard library, on four invented CSV files: 10 users, 4 courses, 12 enrollments and 13 completion rows. The data is illustrative, with planted problems: a duplicate person, a missing email, an unknown status code, an impossible date, unknown references, a score of 140 and a completion with no enrollment. It is a teaching sketch with no database or API calls.

#!/usr/bin/env python3
# Usage: python3 migrate_lms.py SOURCE_DIR OUT_DIR  (reads legacy_*.csv, writes target_*.csv)
import csv, sys, uuid
from collections import Counter
from datetime import date
from pathlib import Path

NS = uuid.UUID("6f1c2a52-0b7e-4c43-9d57-3f0f6f4d1a10")  # fixed, so reruns give the same IDs
USER_STATUS = {"A": "active", "S": "suspended", "T": "inactive"}
LESSON = {"passed": ("completed", "passed"), "completed": ("completed", "none"),
          "failed": ("in_progress", "failed"), "incomplete": ("in_progress", "none"),
          "browsed": ("in_progress", "none"), "not attempted": ("not_started", "none")}

def rows(src, name):
    with open(Path(src) / f"legacy_{name}.csv", newline="", encoding="utf-8") as f:
        return list(csv.DictReader(f))

def ref(kind, *key):
    return str(uuid.uuid5(NS, kind + ":" + ":".join(key)))

def main(src, out):
    rej, warn, n = [], [], Counter()
    bad = lambda *a: rej.append(a)
    users, by_email, merged_into = {}, {}, {}
    for r in rows(src, "users"):                       # users: normalize, merge duplicates
        r["email"] = r["email"].strip().lower()
        if not r["email"]: bad("user", r["user_id"], "no_email"); continue
        if r["status"] not in USER_STATUS: bad("user", r["user_id"], "unknown_status:" + r["status"]); continue
        old = by_email.get(r["email"])
        if old:                                        # latest login survives; the other ID goes in the crosswalk
            keep, drop = sorted((old, r), key=lambda u: u["last_login"])[::-1]
            merged_into = {d: keep["user_id"] if k == drop["user_id"] else k for d, k in merged_into.items()}
            merged_into[drop["user_id"]] = keep["user_id"]; n["users_merged"] += 1; r = keep
        by_email[r["email"]] = r
    for r in by_email.values():
        ids = [r["user_id"]] + [d for d, k in merged_into.items() if k == r["user_id"]]
        users[r["user_id"]] = {"user_ref": ref("user", r["user_id"]), "email": r["email"], "status": USER_STATUS[r["status"]],
                               "legacy_ids": "|".join(ids)}
    courses = {r["course_id"]: ref("course", r["course_id"]) for r in rows(src, "courses")}
    who = lambda uid: merged_into.get(uid, uid)

    enrol = {}                                         # enrollments: check references, drop duplicates
    for r in rows(src, "enrollments"):
        uid, cid = who(r["user_id"]), r["course_id"]
        try: start = date.fromisoformat(r["enrolled_on"])
        except ValueError: bad("enrollment", r["enrollment_id"], "bad_date"); continue
        if uid not in users: bad("enrollment", r["enrollment_id"], "unknown_user:" + r["user_id"]); continue
        if cid not in courses: bad("enrollment", r["enrollment_id"], "unknown_course:" + cid); continue
        if (uid, cid) in enrol: n["enrollments_merged"] += 1; start = min(start, enrol[uid, cid]["enrolled_on"])
        enrol[uid, cid] = {"enrollment_ref": ref("enrollment", uid, cid), "user_ref": users[uid]["user_ref"],
                           "course_ref": courses[cid], "enrolled_on": start, "implied": "no"}

    comp = []                                          # completions: map status, keep records with no enrollment
    for r in rows(src, "completions"):
        uid, cid, kid = who(r["user_id"]), r["course_id"], r["completion_id"]
        if uid not in users or cid not in courses: bad("completion", kid, "unknown_user_or_course"); continue
        if r["lesson_status"] not in LESSON: bad("completion", kid, "unknown_status:" + r["lesson_status"]); continue
        status, result = LESSON[r["lesson_status"]]
        done = date.fromisoformat(r["completed_on"]) if r["completed_on"] else None
        if status == "completed" and not done: bad("completion", kid, "completed_without_date"); continue
        score = r["score_raw"]
        if score and not 0 <= float(score) <= 100: warn.append(("completion", kid, "score_out_of_range:" + score)); score = ""
        if (uid, cid) not in enrol:
            enrol[uid, cid] = {"enrollment_ref": ref("enrollment", uid, cid), "user_ref": users[uid]["user_ref"],
                               "course_ref": courses[cid], "enrolled_on": done, "implied": "yes"}
            n["enrollments_implied"] += 1
        comp.append({"enrollment_ref": enrol[uid, cid]["enrollment_ref"], "completion_status": status, "result": result,
                     "score": score, "completed_on": done or "", "legacy_id": kid})

    for name, data in (("users", users.values()), ("enrollments", enrol.values()), ("completions", comp)):
        with open(Path(out) / f"target_{name}.csv", "w", newline="") as f:
            w = csv.DictWriter(f, fieldnames=list((data := list(data))[0])); w.writeheader(); w.writerows(data)

    ok, rc = True, Counter(k for k, _, _ in rej)       # reconciliation: source = loaded + merged + rejected
    print(f"{'entity':<12}{'source':>7}{'loaded':>8}{'merged':>8}{'rejected':>9}{'implied':>8}  balanced")
    for ent, kind, loaded, merged, implied in (("users", "user", len(users), n["users_merged"], 0),
            ("enrollments", "enrollment", len(enrol) - n["enrollments_implied"], n["enrollments_merged"], n["enrollments_implied"]),
            ("completions", "completion", len(comp), 0, 0)):
        src_n = len(rows(src, ent)); same = src_n == loaded + merged + rc[kind]; ok &= same
        print(f"{ent:<12}{src_n:>7}{loaded:>8}{merged:>8}{rc[kind]:>9}{implied:>8}  {'yes' if same else 'NO'}")
    known = {u["user_ref"] for u in users.values()}
    orphans = sum(e["user_ref"] not in known for e in enrol.values()); ok &= orphans == 0
    print(f"enrollments with no loaded user: {orphans}\n\nREJECTED")
    print("\n".join(f"  {k:<11}{i:<6}{why}" for k, i, why in rej) + "\n\nWARNINGS (loaded, review)")
    print("\n".join(f"  {k:<11}{i:<6}{why}" for k, i, why in warn))
    return 0 if ok else 1

if __name__ == "__main__":
    sys.exit(main(sys.argv[1], sys.argv[2]))

Running python3 migrate_lms.py sample out printed this report and exited with code 0:

entity       source  loaded  merged rejected implied  balanced
users            10       7       1        2       0  yes
enrollments      12       7       1        4       2  yes
completions      13       9       0        4       0  yes
enrollments with no loaded user: 0

REJECTED
  user       U005  no_email
  user       U010  unknown_status:X
  enrollment E008  bad_date
  enrollment E010  unknown_course:C99
  enrollment E011  unknown_user:U011
  enrollment E012  unknown_user:U010
  completion K009  completed_without_date
  completion K011  unknown_user_or_course
  completion K012  unknown_user_or_course
  completion K013  unknown_status:done

WARNINGS (loaded, review)
  completion K010  score_out_of_range:140

A second run produced byte-identical files, which is what the derived IDs are for. Three choices are worth copying. Merged duplicates are counted, not hidden. A completion with no enrollment creates an enrollment flagged as implied, because dropping a passed course erases a record someone may need. Rejections never load silently. The script does not touch SCORM runtime data, xAPI statements, certificates or passwords.

How do you reconcile an LMS data migration load?

Reconcile on three levels: counts that must balance, references that must resolve, and a sample that a person checks against the source. Counts and references are automated and pass or fail. The sample catches what rules cannot, such as a status that mapped correctly but means something different to the business.

Check Pass condition If it fails
Count balance Source rows equal loaded plus merged plus rejected, per entity Rows vanished or doubled. Fix first.
Reference integrity Every enrollment points to a loaded user and course Orphans, usually caused by a rejected parent record.
Status distribution Target status counts match source counts through the mapping table A mapping row is wrong or a status is unmapped.
Reject review Every reject has a reason code and an owner Silent data loss.
Control sample A person compares sampled learners, source against target, including dates near midnight Correct in form, wrong in meaning.

Agree the sample size with your compliance owner before the rehearsal. Record any field the target cannot import as an accepted loss with a name beside it.

How do you cut over without losing recent completions?

Load history first, rehearse on a copy, then run a short final load for changes since the last extract. Because IDs derive from legacy IDs, the final load can rerun the full export and land on the same records instead of duplicating them. Keep the old system readable until reconciliation is signed off.

Freeze enrollments in the old system during the final window if you can. Keep every raw export and the crosswalk, the only map from old IDs in old emails, PDFs and reports to new records. If the destination is a TMS plus LMS pair, decide which system owns enrollments first. Our TMS vs LMS architecture guide explains that split.

Pro tip: Rehearse until rejects are explainable, not zero. Some legacy rows are genuinely bad. Make sure every reject has a reason code and an owner who chose to fix it at the source, fix it in the script or accept it. Zero rejects on a first run usually means weak validation.

What should you do next?

Count the rows per status value in your legacy export and fill in the mapping table for your own fields. The gaps are your decision list. Then adapt the script to your CSV headers and run it on a copy until the report balances and every reject has an owner.

If you are still choosing the destination, ask each vendor in writing for its import template, its limits on history (scores, attempts, certificates) and its SCORM and xAPI behavior. SimpliTrain’s integrations page says it supports SCORM-compliant content, and its homepage FAQ says its team handles data migration from legacy systems without listing data types, so ask for the mapping spec there too.

Frequently asked questions

Can you migrate SCORM completion data from one LMS to another?

Yes for completion records: status, date and sometimes score, exported as CSV or through an API. No for runtime state such as bookmarks and suspend data. Check the target’s limits first, because some import completions only and drop scores and attempts.

How long does LMS data migration take?

No universal number is honest. Time depends on source systems, data quality, rehearsal loads and the target’s import limits. One vendor’s documentation says large completion datasets go through a staging step that can take up to four to six weeks, so ask your target vendor early.

What data should you migrate to the new LMS?

Migrate users, course records, enrollments and completions, with dates and scores where the target accepts them. Archive attempt-level detail and old reports. Rebuild assignment rules, automations and templates. Decide certificates and xAPI history separately, based on what audits and customers require.

Should you migrate old xAPI statements into the new learning record store?

Only if reports need continuity. Otherwise keep the old store read-only and query it when needed. Statements are immutable and the new store sets its own stored time, so replayed records carry the migration date as stored. Keep statement IDs and report on timestamp.

Can you migrate user passwords between LMS platforms?

Do not plan on it. Most systems store passwords as one-way hashes in their own formats, and a hash cannot be converted to a different scheme. Use single sign-on where the customer has it, or send set-password invitations after the load.

Alert: mundrisoftcareers.com is not affiliated with Mundrisoft Solutions. Beware of fake job offers and trust only our official recruitment channels.