Preparing Your Historic Import File

In this article:

• Overview
• The columns
• Completed and in-progress rows
• Course files vs Pathway files
• Formatting rules
• Worked examples
• FAQs
• Who can do this

Overview

The Historic Import wizard accepts a CSV file with one row per person per completion. This article covers every column, the difference between completed and in-progress rows, and the formatting rules the file must follow. If you haven't run an import before, start with How to Import Historic Learning Records — this is the companion reference for building the file itself.

Always start from the template the wizard generates on its Template step: it has the correct headings for the learning you selected and two example rows showing the format. Replace the examples with your data and save as .csv.

The columns

Column headings are matched case-insensitively, and common variations are recognised automatically — for example Email Address, Start Date, Completed, Completion Date, Percentage and Percent all work. Any column SuperPath doesn't recognise is ignored, and the wizard shows a warning naming it so you can catch typos.

Completed and in-progress rows

The date_completed cell decides what kind of record each row creates:

• Completed row — date_completed is filled in. The record is created as completed on that date, with the score you supply (or 100 if blank). If date_started is blank, the start date is set to the completion date.
• In-progress row — date_completed is blank. The record is created as in progress, back-dated to date_started (which is required for these rows). For a course, percentage_complete records how far along the person was and score can carry a partial quiz score; for a Pathway, the person is simply enrolled with their steps still to complete.

A file can freely mix completed and in-progress rows, but each person can appear on at most one in-progress row per file (and once per completion date for completed rows) — extra rows are skipped as duplicates.

Course files vs Pathway files

• Course files carry all five columns.
• Pathway files carry only email, date_started and date_completed — the template omits score and percentage_complete entirely, because Pathways don't record a score and per-step progress is never reconstructed from a percentage. If a Pathway file contains values in either column, the wizard blocks the upload and asks you to remove them.

Formatting rules

• Dates are YYYY-MM-DD only — for example 2024-02-14. Other formats (like 14/02/2024) are rejected, which protects you from day/month ambiguity when migrating between systems.
• Dates can't be in the future, and the start date can't be after the completion date. Dates are read in your organisation's timezone.
• Save as .csv — the upload only accepts CSV files. In Excel or Google Sheets use File → Save As / Download → CSV.
• Commas inside values are fine as long as the cell is quoted ("Smith, Jane") — spreadsheet tools do this automatically when they save CSVs.
• Maximum 5,000 rows per file. Larger exports need to be split — the wizard tells you if your file is over the limit.
• Blank lines are skipped, and files exported with unusual encodings (such as a leading byte-order mark) are handled automatically.

Worked examples

A course file mixing completed and in-progress history:

email,date_started,date_completed,score,percentage_complete
jane.doe@example.com,2024-01-10,2024-02-14,88,100
sam.lee@example.com,2023-11-02,2023-11-02,,
priya.sharma@example.com,2025-06-10,,58,35

Row 1 imports as completed with a score of 88 — the 100 in the percentage column is ignored, since completed rows always import at 100%. Row 2 imports as completed with the default score of 100, started and completed the same day. Row 3 has no completion date, so it imports as in progress at 35% with a partial score of 58.

A Pathway file:

email,date_started,date_completed
jane.doe@example.com,2024-01-10,2024-02-14
sam.lee@example.com,2025-03-01,

Row 1 enrols Jane and completes the whole Pathway — including every step — on 14 February 2024. Row 2 enrols Sam as in progress from 1 March 2025.

FAQs

Do I need a column for the course or Pathway?
No. You select the learning in the wizard, so the file doesn't identify it — that's also why each file covers exactly one course or Pathway.

What score should I use if my old LMS didn't record one?
Leave the score cell blank — completed rows default to 100.

Can the same person appear more than once?
Yes, with different completion dates — for example an annual compliance course completed in 2023, 2024 and 2025 is three rows. Rows with the same email and the same completion date are treated as duplicates and skipped.

My dates are in another format — do I have to convert them?
Yes, to YYYY-MM-DD. In a spreadsheet, select the column and apply a custom date format of yyyy-mm-dd before saving as CSV.

Who can do this

Owners and Admins can run historic imports. Managers, Content Managers, People Managers, Instructors, Employees and Restricted users cannot — the Historic Import screens are hidden for them and the underlying API rejects the requests.

Updated on: 07/08/2026