Importing Data (Migrations)

Our CSV importers

We support various imports of data as part of data migrations and can run these on your behalf, if data is provided in the required format.

The importers can be found under Advanced Actions > Import.

Please see this link to access example templates for our supported imports, including:

• Users
• Cohorts (Organizations and Sub-Groups)
• Quiz questions (Single Choice, Multiple Choice, Boolean, Drag to Order, Fill in the Blank, Matching Order)
• Quizzes
• Lessons
• Courses
• Groups (Learning Paths)
• Course Enrollments

Each CSV file has several example rows present to help you understand the expected data format for each importer.

Always download a fresh copy of the relevant template before preparing an import, as templates may be updated when importer functionality changes.

Some clients may have custom fields that are not included in the standard templates. Your implementation team will advise if these are required.

Importer details

Column headers must match the templates exactly. Do not rename, remove, reorder, or add spaces to column names, as this may cause imports to fail. For example, VideoURL  will not work where the template expects VideoUrl .

The templates demonstrate which fields are required and which are optional. In many cases, only a Title is required, with additional fields available to provide more configuration or content.

We strongly recommend using ExternalId  values from your source platform to maintain relationships between records. This can be particularly helpful where there is a risk of having more than one item with the same title, which can be common with Quiz questions. ExternalId  values must be unique within each importer.

Some fields, such as Curriculum and Questions, require JSON arrays. Refer to the templates for examples.

Within JSON arrays, related records can usually be linked using either a Title or an ExternalId , though ExternalId  is preferred.

Any date values must use the format MM-DD-YYYY  or YYYY-MM-DD .

Boolean values are not case-sensitive, so TRUE  or true  and FALSE  or false  will all work.

Any referenced records in the migration data must already exist in the system. For example, import Lessons before importing Courses that reference those Lessons.

After an import completes, review the import results for any skipped or failed rows. An import can complete while individual rows contain errors that still need to be resolved.

Importer-specific details

Slug

A Slug will be auto-generated if left blank.

Tags

Any items added to TagComposition  must already have been added to the system as an exact match.

Cohort

In the Group, Course, Lesson or Quiz CSVs, Cohort  is a reference field used to identify which Cohort owns the content. This is optional and rarely used.

In the Users template, Cohort  and CohortAsOwner  refer to the Organizations or Sub-Groups that the user is a member or owner of.

Course Enrollment imports

The Course Enrollment importer can be used both to create new enrollments and update existing enrollments. An import row is not automatically skipped simply because the learner is already enrolled on the Course.

This is particularly important when importing progress:

• Progress  is provided as a decimal, e.g. 0.85  represents 85% complete.
• If the learner is not already enrolled, the importer will create the enrollment. If Progress is blank, the new enrollment starts at 0%.
• If the learner is already enrolled and Progress is blank, their existing progress is left unchanged.
• If the learner is already enrolled and a Progress value is provided, the import can update their existing progress using the supplied value.

This means Course Enrollment imports should be prepared carefully when working with existing learners. Leaving Progress blank is the safer option where you want to create or confirm enrollments without changing progress already recorded in Shapeshift.