> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.superpath.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Preparing Your Historic Import File

# 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 | Required? | Format | Notes |
|---|---|---|---|
| `email` | Always | A valid email address | Must match an existing person in SuperPath. Matching is case-insensitive |
| `date_started` | Only when there's no completion date | `YYYY-MM-DD` | If blank on a completed row, it defaults to the completion date |
| `date_completed` | No | `YYYY-MM-DD` | Filled in → the record imports as **completed**. Blank → it imports as **in progress** |
| `score` | No | `0–100` | Course files only. Blank defaults to **100** on completed rows; on in-progress rows it records a partial score |
| `percentage_complete` | No | `0–99` | Course files only, used on in-progress rows (blank defaults to **0**). Ignored on completed rows — they always import at 100% |

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.