Merging Open edX courses

 Sometimes it's necessary to merge two Open edX courses, and copying and pasting between the two courses can take a lot of effort. Fortunately there's a way that doesn't require this, by working directly with the course export files. Please note that this is a lengthy process with a lot of complexity to it. If you can merge your courses simply by copying and pasting content, you may want to consider doing that instead.

Before we begin, you'll need a few things:

  • Both courses must be in a semi-complete state, ready to be merged. This is a somewhat obvious statement, but any changes made while you're merging the export files will not be captured, so it's worth checking before you begin.
  • An archiving tool capable of extracting and compressing to and from .tar.gz archive files. If you do not have one, we recommend 7Zip for Windows. Mac OS users should be able to do this natively using Finder without requiring an additional application. This article was written using Windows instructions and screenshots, but they shouldn't be too different for Mac OS or Linux users.
  • An application capable of editing XML and JSON files. The screenshots in this article were taken using Sublime Text, which is available for all platforms, but you can use whatever you're most familiar with.

The basic process of the merging is as follows:

  1. Export both courses.
  2. Extract them from their archives.
  3. Copy content from one course to the other, providing the XML structure with information about the new materials.
  4. Compress the course again back to .tar.gz.
  5. Import the export file into a fresh course.

Let's go through step by step. In this example we have two courses, both alike in dignity: 'Merging Course 1' and 'Merging Course 2'.  We will merge them into a single course.

Export both courses

First, we need to export both courses. To do this, on each course go to Tools, Export, click the big blue Export Course Content button. (You'll need to wait a moment for it to go through the prep, compress, etc. steps) Once those are done, click the Download Exported Course button at the bottom left.

Once you have both export files downloaded, it's a good idea to move them into their own folder so you can work with them more easily. You should also make a note of which course is which, as they are assigned randomized IDs that can make it hard to keep track. In the example below, course jQhDjS is course 1 and course U1lMrE is course 2.

Merge the archives

The first thing you need to do is to extract the files (you'll probably have to do this twice for each course). My preference is to first extract the .tar.gz file 'here', which will give you the .tar file, and then extract the .tar file to a named folder. This is because each of these .tar files contains a folder titled 'course', and if you just extract it 'here' it will complain that the folder already exists.

However you end up doing it, the end result is you need the two folders with the course exports available in each. These files contain everything in your course. All your assets, settings, content... they're in these folders.

It's a good idea to open them up side by side if you can, so that you can quickly switch between the two.

Now that we've got them open, we can finally start merging these courses. In this case, I'm going to merge the course U1lMrE (course 2, on the left) into course jQhDjS (course 1, on the right). The order you do this in is mostly irrelevant, you just have to make sure you're always copying INTO the same course so that you end up with a single folder with all the content you need.

The first thing we need is our chapter folder. Open both chapter folders, and copy the contents from chapter in one course into the chapter folder on the other.

Now we need to tell the course that these new chapters (which are actually sections) exist. In each course, go into the course folder (found within the main course folder, it's a little confusing so check the gif below!) and open up course.xml.

Within course.xml is a listing of the sections (chapters) within the course. You want to copy the the chapters from the first course that you copied the files from, to the second. (Again, make sure you're always copying INTO the same course.) Remember to save once you have copied the chapters across.

Now that our chapters are copied and are part of the course structure, we need to copy a series of other folders in the same we we did our chapters folder. Copy the contents of the following folders:

  • html
  • drafts (if it exists, otherwise ignore it)
  • problem
  • sequential
  • static
  • vertical
  • video

Nearly done! Honest. You don't have to edit any more XML with these, as editing our chapters file told the course where to find all the content you're copying in this step.

Once those folders are copied, all of your assets and content will be in your course. The last thing we do before we move onto getting it back into Open edX is combine the grading criteria. You're going to want to review this once you're back in Studio, but for now the easiest thing to do is literally merge the two grading policies together. In the folder Policies there's another folder labelled Course. Within this folder is the file grading_policy.json. Open it for both courses.

You want to copy between the two, but being JSON you need to be sure that there's a comma between each entry in this file, as shown below. Then make sure there is NO comma on the final entry. Whee you are sure the file was copied across correctly and has the correct commas, save it.

Now that these are copied, we need to compress our file again. Head out to the root folder of the course that you've just copied everything to, and compress it back to a .tar file by selecting .tar as the Archive format.

Once you've got your .tar file, you want to compress it again. If you're on another system, you may be able to skip that step and compress it straight into a .tar.gz file instead. In this case, we take the .tar file and compress it again, this time using gzip as our Archive format.

Now you should have a .tar.gz archive of your course.

Back to Open edX

Now that you have a course archive, you will create a new course to house your new merged course. The usual rules apply here - give it the course number and run that you want it to have long-term, as you will not be able to change these later. Once your course exists, you need to go up to Tools and Import your newly created file.

Once your course has imported, if ll has gone well, you'll get your updated course outline with all your content. If it doesn't work, something's gone wrong with your merging process. Either go back through the steps looking for errors or contact support if you need help! If all looks good, proceed to the final steps below.

Now that your content is in, you're not done. You'll need to take the following steps:

  1. Review your content and test your links, particularly internal ones - if the proper steps haven't been taken to make the link point to internal pages within the course, those links may break or point to the old course.
  2. Review and alter your grading criteria - Earlier we joined the two grading criteria for these courses together, so right now your course can be passed by completing either half of the course. Your new course should have a new grading setup!
  3. Assign your graded content to your new grading.
  4. Rename your course (by default it takes on the name of the first course in the import process.)
  5. Rework your content - you've now got an introduction halfway through your course and two conclusions (if they were part of your course structure on both halves.) There's still a lot of content work to do now that your courses are joined together, in order to ensure your learners have a cohesive experience!