Skip to content

Home

Jump to bottom
Anders Weinstein edited this page Jul 21, 2023 · 22 revisions

How to Migrate a Course

This guide will outline the process for migrating a course from legacy OLI into Torus. At a high level, the process consists of using this digest tool to convert the XML content into a JSON format that Torus can ingest and upload media assets to S3.

Prerequisites

  • NodeJS 16+, Yarn, Git
  • SVN URL and read-access to the repository of the course you want to migrate
  • AWS S3 access key & secret with read/write access

Procedure

  1. Make sure you have all the necessary dependencies installed

    > node -v
v16.13.2

> yarn -v
1.22.17

> git --version
git version 2.32.0

  2. Clone the course-digest repository and download dependencies

    git clone https://github.com/Simon-Initiative/course-digest.git
cd course-digest
yarn

  3. Create .env file and configure S3 access for media upload

    touch .env && nano .env

    Enter the following variables with the correct substituted values

    AWS_ACCESS_KEY_ID=<some access id>
AWS_SECRET_ACCESS_KEY=<some secret access key>
MEDIA_BUCKET_NAME=<some s3 bucket name>

    If using nano, press Ctrl+w to save and Ctrl+x to exit.

  4. Checkout the SVN repository of the course you wish to migrate into Torus

    svn co https://svn.oli.cmu.edu/svn/some/course/branch/v1_0_0 some_course_v1_0_0

  5. Run the course digest tool

    npm start -- convert --inputDir <local svn course dir> --mediaUrlPrefix <https://MEDIA_URL/media>

    NOTES:

    • The inputDir should be the path to the svn course checked out in the earlier step

    • Output will go into folder inputDir-out alongside inputDir. Include --outputDir <path to output dir> for a different location.

    • The mediaUrlPrefix will be used to reference uploaded media assets in converted course content. The prefix can be constructed from the torus configuration variable MEDIA_URL by replacing "<MEDIA_URL>" with its value in the template https://<MEDIA_URL>/media. If using S3, the url prefix has the form https://BUCKET-NAME.S3_SERVER_DOMAIN_NAME/media

    • The convert operation will ask you if you want to create a zip archive (required for torus ingestion) and if you want to upload media assets. An archive can always be created later by simply creating a zip of the outputDir and media assets can be uploaded later by running the upload operation if you choose no for these. To run the upload operation after conversion:

      npm start -- upload --mediaManifest <outputDir/_media-manifest.json>

    • Advanced: Webcontent Bundle Option. By default, the directory tree structure of webcontent files is not preserved through migration. However, embedded HTML pages or activities may rely on the structure of the webcontent space to load supporting asset files via relative urls. For this case, use flag --webContentBundle <bundleName> (abbreviation -w) to optionally upload all webcontent files into a tree-structured "bundle" identified by the given bundleName. Embedded activities will be migrated to load the root document from this tree-structured bundle so relative references from that document should still work as in legacy OLI.

    • Command line flags may be abbreviated as follows:

      • -i for --inputDir
      • -o for --outputDir
      • -p for --mediaUrlPrefix
      • -m for --mediaManifest
      • -w for --webContentBundle
      • 'convert' is the default operation and may be omitted.

Once you have a zip digest created and your media assets have been uploaded, you can ingest the zip into Torus as an administrator under Admin > V2 Ingest Course Project.

Clone this wiki locally