
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 (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.
Tags :
