Why Common Cartridge to Open edX migration is a course-by-course project
If your courses are exported as IMS Common Cartridge packages from another LMS, the short answer is this: cc2olx can convert the course structure and text, but images, assessments and styling need checking and rebuilding after conversion. How much work that takes depends on how many courses you have and which content types they use. Plan the migration as a set of separate course projects, each with its own validation, before anyone considers a bulk import.
Open edX is built on edx-platform, which is licensed under the GNU Affero General Public License version 3 and built on Python, JavaScript and Django. Two services matter for this work. Studio is where course teams author and review content, and the LMS is where learners take courses. Converted courses have to land in a running Studio and LMS, so the platform setup is a shared prerequisite that comes before any course is touched. The edx-platform maintainers recommend running Open edX in production through a service provider or with Tutor, and Tutor is the usual route for a self-hosted instance.
The per-course work starts after conversion. Open each course in Studio and check the section, subsection and unit hierarchy against the source package. Trace every image reference, because images do not convert and must be re-uploaded and linked again. Review each quiz, survey or graded item and rebuild it with the Open edX component that matches its behavior, then check grading settings. Finally, preview the course as a learner in the LMS, since styling from the source LMS will not carry over and needs to be re-applied or dropped.
Decide early which courses to keep, which to rebuild by hand and which to retire, because those choices drive most of the effort. Confirm with your platform team which Open edX release you will deploy, since the project supports only the latest named release at any one time, and Verawood is the current named release. Pick one representative course with images, assessments and custom styling as a pilot, and use what it teaches you to write the checklist for the rest of the catalog. Ask any partner for a quote built on the list of courses and content types, not on a total course count.
What maps cleanly from Common Cartridge to Open edX
This table compares each part of a Common Cartridge export with its closest Open edX counterpart and states whether the conversion is expected to be direct, to need manual rework, or to be confirmed against the cc2olx version your team uses. Read the notes before scheduling a test import, because most cleanup effort usually sits in assessments, links, images and LTI tools. Treat every direct entry as a hypothesis to verify on a sample course.
| Source capability | Open edX equivalent | Migration notes |
|---|---|---|
| Course structure (modules and sequencing) | Sections, subsections and units in Studio course outline | Expected direct for module order. Confirm nesting depth and placement of items against the cc2olx version in use. |
| HTML text content | HTML text components inside units | Expected direct for basic markup. Confirm how inline styles, scripts and embedded frames are handled, then review pages visually. |
| Links to web pages and course resources | HTML hyperlinks in text components | Manual rework likely for internal links. Confirm whether links to other exported resources resolve, and repoint them to Open edX units or files. |
| Assessment items | Problem components with grading settings | Confirm which question types the converter maps. Expect manual rework for unsupported types, point values, feedback and answer keys. |
| Media and images | Course assets and uploaded image or video files | Images do not convert. Plan to re-upload them, then relink each reference. Confirm handling of audio and video in the converter. |
| LTI links | LTI components that point to an external tool | Manual rework expected. The destination must register the tool, and launch URLs, keys and secrets must be supplied again. Confirm converter output. |
| Source-LMS-specific extensions | No direct equivalent in most cases | Manual rework or removal. Inventory vendor metadata and proprietary tags in the export before estimating the cleanup work. |
| Due dates, release dates and grading settings | Subsection dates, graded flags and course grading policy | Confirm which settings the export carries. Set availability and grading policy in Studio after import, then test a learner path. |
What converts with cc2olx and what does not, including images
The cc2olx converter reads an IMS Common Cartridge package and produces Open edX course content that you then bring into Studio. Treat its output as a first pass, not a finished course. What converts depends on the item types in your source package and on the converter version you run. Images need a plan of their own. Do not assume they arrive intact, correctly placed or linked to the right location. Before the full run, decide for each image group whether it will be re-uploaded to Studio assets, relinked to a stable location, or rebuilt inside Studio as text or components.
Test a representative sample course first. Choose one module that includes the content types you depend on most, such as rich text pages, quizzes, embedded media, external tool links and at least one image-heavy page. Export that module from the source LMS, run the converter in a non-production Open edX instance, import the result into Studio and walk it as both an author and a learner. Record every page that loses content, changes layout or shows a broken image. Confirm the current cc2olx behavior for your package version against the converter's own documentation and your test export, because conversion rules change between versions and this page does not list them.
Read the converter output and logs as an inventory of decisions. Warnings about skipped resources, unrecognized item types or references to files missing from the package are the items that will reach learners if nobody acts on them. Group the warnings by content type and by file reference, so the course team can see which problems repeat. Then compare the item count in the source manifest with the number of units and components in the imported course outline. Any mismatch is a gap you must explain before the full migration, not after launch.
Decide per content type whether to convert, rebuild in Studio or retire. Convert when the item is plain text or simple structure and the imported result matches the source on your test. Rebuild when the item is interactive, assessment-heavy or depends on precise layout, because authoring it again is often easier to verify than repairing converted markup. Retire content that is out of date, duplicated or tied to a tool you will not run. Keep one tracker, owned by the course team, that records the decision and the reviewer for each item. Ask any partner quoting this work to price converted and rebuilt items separately, since rebuilds drive most of the effort.
For images, inventory every asset before the pilot. Note which files are packaged, which point to external hosts that may disappear, and which carry meaning that text cannot replace, such as diagrams or charts. Re-upload to Studio is the safest option when the original files are available. Relinking only works if the target location will remain in place. Rebuilding suits diagrams that carry instructional meaning. Check alt text and image sizing in your test as well, because these are often lost silently. Sign off image handling per course, not per platform, and keep the sign-off with the decision tracker.
Documented import paths for Common Cartridge content
Common Cartridge content moves through four stages: conversion, course import, a running target instance and a version check against source code. Each stage produces a different artifact, so each needs a named owner and a clear acceptance check before the next stage starts.
The cc2olx converter
cc2olx converts a Common Cartridge export into an Open edX course package. A migration engineer runs it in a staging environment, not on a production instance. The output is the converted package plus a record of what the converter could not map. Before planning the work, confirm with the team where the converter's documentation is published and which Common Cartridge item types it handles. Image references are a known gap in this path, so list every image the source course uses and plan how each will be restored.
Studio course import
Studio course import loads the converted package into a course in an Open edX Studio instance. A course author with the right course permissions, often working with a Studio administrator, runs the import. It produces a course in Studio with its structure, components and settings, not a live course for learners. Check internal links, component types, grading settings, and missing assets section by section. Treat the imported course as a draft until the author has reviewed every unit against the source course.
Tutor for the target instance
Tutor is the official Docker-based Open edX distribution and supports Kubernetes deployments. A platform engineer uses it to stand up the target instance that receives the course, so the team controls the hosting. The output is a running Studio and LMS. Confirm the release before building anything, because Open edX supports only the latest named release. Verawood is the current named release, published on 30 July 2026, so conversion and import tests should run against the same release that production will use.
The edx-platform repository
The edx-platform repository holds the source code for Studio and the LMS and is licensed under the GNU Affero General Public License version 3. Engineers use it as the reference for command names, options and supported versions for the release in use, not as a copy-and-paste guide. The output is a verified reference, recorded in the migration runbook. Check the repository and the release notes for the target release before writing any procedure, and have the team confirm each command against those official sources.
Cleanup needed before learners see the course
A successful import is not the finish line. After cc2olx has created the course in Studio, the team has a structure that resembles the source package, but nothing in it has been checked from a learner's point of view. Start with links and media, because images do not convert and every image reference in HTML components, units and course pages must be found, re-uploaded and verified in the LMS preview. Then check internal links, since some may still point at source-LMS addresses or at content that did not carry across.
Next, review the course outline. Confirm that sections, subsections and units sit under the right parents and appear in the intended order, and that nothing has been left unassigned. Review grading settings for each graded component, including graded flags, weights and grade ranges, and compare them with the source course. Due dates and release dates deserve a separate pass, because they can shift when time zones or calendar values are interpreted during import. Make each change in Studio, then reload the outline and compare it against the source export.
Layout comes next. Custom HTML, inline styles and source-platform CSS usually need rework so pages match the current Studio and LMS themes and render correctly on common screen sizes. Remove leftover source-LMS references as well: hostnames, login and enrollment links, forum or tool URLs, and branding text inside component bodies and descriptions. Search the exported course content for the source domain and for the source platform's name, and treat every hit as a task with an owner and a status.
Finally, run a review loop before any learner access. Subject-matter experts should check content accuracy, sequencing and assessments in the LMS preview, not only in Studio, and record their findings against specific units. Run an accessibility check on the rendered pages, covering alt text, heading order, link text, captions and color contrast, using the standard your organization has adopted. Define an acceptance checklist for each course before the import begins, with named owners and sign-off from the subject-matter expert and the course owner, so that the team knows what done means.
How the migration sequence runs: inventory, pilot, parallel run and cutover
The sequence moves each Common Cartridge course through a tested conversion, a supervised parallel run and a controlled switch of enrollments and grades, so that every course reaches Open edX with a named owner, a signed-off review and a documented fallback. The source LMS is retired only after the agreed exit criteria are met.
Inventory every Common Cartridge package
Your team exports every Common Cartridge package from the source LMS and records, for each one, the course owner, enrollment and active learner counts, last access date, linked external tools and whether the course is still taught. Course owners confirm or correct the record. Each course then receives one disposition: migrate, rebuild or retire. The step is done when every package has a named owner and a disposition in a signed inventory that the migration team and the business owners both hold.
Select a pilot course
The team chooses one course that represents the content types in the inventory, such as text pages, quizzes, graded problems and discussion prompts, and that a named owner is willing to review closely. The team agrees pass criteria with the owner before any conversion runs: which structure must survive, which graded components must score correctly and which images must be re-uploaded by hand. The step is done when a pilot selection record lists the course, the owner and the written pass criteria.
Run cc2olx and Studio import in Tutor
Engineers stand up a non-production Tutor environment on the Open edX release you plan to run in production. They convert the pilot package with cc2olx into OLX, then import the result into Studio. Every conversion warning and import error is logged with the item it affects, and images are listed as manual work because they do not convert. The step is done when the import completes in the non-production instance and the error log is complete enough for the next step to act on it.
Fix and review the converted course
Engineers correct broken internal links, unit and section structure, problem settings and grading weights in Studio, and re-upload images. Repeatable fixes go into a conversion script or checklist, so the same correction applies to later batches. The course owner then reviews the course in the Studio preview and walks through it as a learner would. The step is done when the owner signs off against the pass criteria and the fix log is saved with the pilot record.
Migrate courses in batches
The team groups the remaining courses into batches by content type and shared dependencies, then runs the scripted conversion, import and fix checklist from the pilot against each batch. Owners review each course before it is marked ready. Batch size follows the review capacity you confirm with your course owners, and the timing of each batch depends on course volume. The step is done when every migrated course has a sign-off and a batch log records any exceptions.
Run the parallel period and agree the rollback plan
For a period agreed in advance, the source LMS and Open edX both serve the migrated courses. Learners and instructors are told which system holds the authoritative grades during that period. The team compares enrollments, progress and grades between the two systems and logs every difference. Before the cutover begins, the team writes a rollback plan that names the conditions for reverting, the decision maker, and the steps to restore source access. The step is done when exit criteria are met and the rollback plan is approved.
Cut over enrollments and grades
The team stops writes in the source LMS, exports enrollments and grades, and loads them into Open edX. Engineers check record counts and compare sampled grades against the source export. Learner access then moves to Open edX, and the source LMS is set to read-only. If the agreed conditions for rollback are met, the team follows the approved plan to restore the source. The step is done when counts and sampled grades match, learners can reach their courses and the cutover log is signed by the migration lead and the course owners.
Decommission the source LMS
After the agreed retention period, the team archives the Common Cartridge packages, grade exports and the source configuration according to your records policy, then removes the source LMS and its access paths. Retention periods and archive formats come from your compliance and records owners, not from the migration plan. The step is done when the archive is verified, the source is shut down and the decommissioning record is filed with the inventory.
What drives the cost and duration of a Common Cartridge migration
This table lists the factors that change how much work a Common Cartridge to Open edX migration takes and how long it runs. Read each row as a question to answer before a quote: what the driver changes, and what the written scope should state. The main takeaway is that package count, content type and review capacity usually matter more than the conversion step itself.
| Driver | Why it matters | What to ask for in a quote |
|---|---|---|
| Number of courses and packages | Each Common Cartridge package is converted, checked and imported separately, so effort grows with the count and with how many packages share content. | The exact list of packages, a count of courses per package, and whether shared resources are to be deduplicated. |
| Image-heavy or interactive content | Images do not convert through cc2olx and must be re-attached or re-uploaded by hand. Interactive items may need rebuilding as native Open edX components. | An inventory of image-bearing units and interactive items, and a statement of which items are rebuilt, replaced or dropped. |
| Assessment complexity | Quizzes, question banks, timed tests and graded assignments often need manual mapping to Open edX problem types and grading settings before scores are trustworthy. | The assessment types in scope, the grading policy to preserve, and who verifies scores against the source course. |
| Required rebuilds in Studio | Converted courses frequently need restructuring, unit layout fixes and broken link repairs in Studio before learners see them. | A stated rebuild allowance per course or per unit, and a definition of what counts as a rebuild versus a fix. |
| Review and sign-off capacity | Subject matter experts must confirm content, and the client must approve each course. Slow reviewers extend the schedule more than technical work does. | Named reviewers, review rounds included, the sign-off method, and what happens when a review round is missed. |
| Grades and enrollment cutover | Learner grades, enrollments and certificate status must be handled at the point of switching over, and that step needs a rollback plan. | Whether grade and enrollment data migrate or are rebuilt, the cutover window, and the rollback steps in writing. |
| Hosting setup for Tutor | A Tutor environment must be provisioned and running before import, and it must be sized and secured within your infrastructure. | Who provisions the environment, the target infrastructure, and whether hosting setup is in scope or a separate project. |
| Completeness and versioning of source packages | Missing files, broken internal links or unknown source LMS versions add investigation time before conversion can begin. | A check of each package for completeness, the source LMS and export version recorded, and a list of known gaps to be resolved by the client. |
What usually goes wrong in a Common Cartridge migration and how to prevent it
Common Cartridge conversions tend to fail in a few predictable places, and most of the failures only show up once instructors or learners use the course. Each card names one failure, what to check, and the step in the sequence or cleanup section that prevents it. Run every check against a pilot import before the live cutover.
Assuming images convert automatically
Images are the known gap in cc2olx conversion, so pages that depend on a picture can arrive with missing or broken assets. Before the full import, list every converted unit that references an image, then compare the list with the source package. Re-upload each image to the course or to a content library, and record each rebuilt asset in the cleanup checklist. Confirm the result in the Studio preview before you move to the pilot.
Broken links after import
Links in converted text and components can still point to addresses from the source LMS, and internal references may not resolve once the course sits in your Open edX instance. Search the converted units for old hostnames and resource paths, then repoint each link to a location you control. Test external links from your own network, because an address that worked on the source platform may not resolve from your environment. Repeat this search after every re-import.
Untested grading
Graded components, weights and point values are the settings instructors notice first when they are wrong. Compare the graded sections in the source course with the grading policy and graded components in the converted course. Then submit test attempts from a learner account and confirm that scores reach the gradebook as expected. Run these checks on the pilot course and have the instructor sign off on a sample of results before the cutover begins.
Leftover source-LMS content
A converted course can include draft units, placeholder sections and labels written for the source platform, and learners will see them if the course is opened as it arrives. Review each section in Studio using the visibility settings a learner would see, then remove or hide placeholders and confirm that the outline matches the intended structure. Check the result from a learner account, not an author account, and record the review in the cleanup section's checklist.
Unclear sign-off ownership
A migrated course usually needs approval from a subject owner, an instructional designer and someone responsible for the platform, but projects often leave it unclear who signs what. Name one approver for each course and one for the cutover before the pilot starts. Write down what each approval covers, such as content, grading, links and learner visibility. Attach the pilot results to each sign-off so the decision can be traced later.
Cutover with no rollback path
A cutover with no fallback forces teams to repair live enrollments under pressure. Before the cutover, decide what the fallback is, such as keeping the source course available until the Open edX course is accepted, and how enrollments and progress would be handled if you revert. Rehearse the fallback during the pilot. Confirm with the course owner which learner data travels with course content, since learner data typically does not move with a course export.
Common questions before migrating Common Cartridge courses to Open edX
How much does it cost to migrate Common Cartridge courses to Open edX?
The cost depends on the written scope, which DeployOpen agrees with you before work starts. DeployOpen does not publish a price list, so a quote follows from the scope. The main drivers are the number of courses, the volume of media, the mix of assessment types, the amount of cleanup needed before learners see each course, and whether DeployOpen also sets up the target Open edX environment. Your own costs include staff time from course owners and reviewers, plus the infrastructure you run Open edX on, which recurs. Ask for a quote that separates one-time conversion and cleanup work from recurring hosting and support, and that lists what you must provide, such as export files and reviewer availability.
How long does a Common Cartridge to Open edX migration take?
The timeline varies with the size and condition of the export, so it cannot be stated in general terms. The biggest factors are how many courses you are moving, how much manual cleanup each one needs, how many images must be re-added or relinked, and how many review rounds your subject-matter experts require. The readiness of the target environment matters as well, since a Tutor-based Open edX instance that is already running and secured removes setup work from the schedule. Ask for a timeline in the written scope that ties each phase to a named deliverable and to decisions your team must make, so delays in reviews are visible early.
What does our team need to provide for a Common Cartridge migration?
Your team supplies the source material and the decisions that only your organization can make. Expect to provide the Common Cartridge export files for every course in scope, access to the source system if you need to confirm how content was built, and named course owners who can review converted content. You also need a target Open edX environment with Studio access, a decision on how images and missing media will be handled, and a rule for mapping assessments that do not convert cleanly. Plan reviewer time for each course, because learners should not see a course until its owner has signed off on structure, content and assessments.
Can our own team migrate Common Cartridge courses to Open edX without a partner?
Yes, a capable internal team can run the conversion without a partner, but the work is more than running a converter. The edx-platform maintainers recommend running Open edX in production through a service provider or with Tutor, because bare-metal installation is complex and receives limited community support. Your team needs skills in Linux, Docker, Tutor, Studio and course design, along with enough time to test, clean up and review every course. Weigh those skills and hours against a fixed-scope engagement. Many teams start with one pilot course to measure effort before deciding how to staff the rest.
Do images and assessments convert when moving Common Cartridge courses to Open edX?
Images are the known gap: they do not convert automatically, so each one must be re-uploaded or relinked before the course is ready for learners. Assessments depend on the question types in your export and how the converter maps them, so some will carry over and others will need rebuilding in Studio. Review every quiz, graded item and rubric against the source course, and check that point values, feedback and answer keys survive the move. Record each item that needed manual work, because that list becomes your estimate of cleanup effort and the basis for the quote. Confirm the mapping for your own export before promising any assessment outcome to course owners.
How do we confirm cc2olx works with our Common Cartridge export?
Test the converter on a representative sample before committing to the full set. Choose a course that includes your typical structure, media, quizzes and any special content, export it from the source system, and convert it with cc2olx into a non-production Open edX instance. Compare the result in Studio against the original, section by section, and record every missing image, broken link, misplaced unit or altered assessment. Check the converter output and logs for warnings. If the sample converts cleanly, repeat the test on a course with the most complex content. Share the results with your team so the scope reflects what the converter actually does with your exports.
What happens to learner data and grades during a Common Cartridge migration?
A Common Cartridge package carries course content and structure, so the converter is aimed at moving course material, not learner records. Enrollments, submitted answers, grades and completion history generally stay in the source system unless you export them separately, so confirm this against the converter documentation and your own export. Decide early what happens to historical grades, whether they are archived, reported or imported through a separate process, and who approves that decision. Involve your privacy and records team, since learner data carries retention and access obligations. Put that data work in the written scope if DeployOpen is handling it, or keep it with your team if it is not.
How DeployOpen scopes and delivers a Common Cartridge migration
DeployOpen scopes a Common Cartridge migration from the course exports you hold, then runs the cc2olx conversion into a self-hosted Open edX instance you control. Each course is checked for what converted, what did not, and what needs cleanup before learners see it. The work ends with documentation your team can use to repeat the steps on future exports.
How we scope
- The written scope lists the Common Cartridge packages, the course count and the target Open edX instance.
- It separates content that the converter carries across from content that must be rebuilt or re-added by hand.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before any conversion starts.
How we build
- Each export is inspected and converted with cc2olx in a non-production Open edX environment first.
- Image handling is planned as its own step, because the converter does not carry images across.
- Course structure, unit titles and internal links are checked against the source before a course moves forward.
How we hand over
- Each course gets a cleanup log listing the fixes made, the open items and the owner who must review them.
- Conversion steps and commands are documented so your team can repeat them against a new export.
- Learners see a course only after your reviewers approve it in Studio and the LMS.
How we support
- Post-migration fixes, such as broken links or re-added images, can run under a retainer agreed in writing.
- Open edX supports only the latest named release, so upgrades are scoped as separate work when you move forward.
- Ongoing support and continuous testing are available as retainers, with scope and timing confirmed in writing.
