CSV Import/Export

Overview

CSV import/export enables bulk data operations in skillSYMS. Import learners, enrolments, and assessments from spreadsheets, or export data for external analysis and reporting.

Import Operations

Supported Import Types

Type	Purpose	Key Fields
Learners	Bulk registration	ID, name, contact
Enrolments	Programme assignment	Learner ID, programme, dates
Assessments	Historical results	Learner ID, module, outcome
Evidence Metadata	Link existing files	Learner ID, file reference

Import Process

1. Download Template: Get the correct format
2. Populate Data: Fill in your data
3. Upload CSV: Submit for processing
4. Preview: Review parsed data
5. Validate: Check for errors
6. Confirm: Execute the import
7. Review: Check results

Learner Import

Template Fields

Field	Required	Format	Description
id_number	Yes	13 digits	SA ID number
first_name	Yes	Text	Given name(s)
last_name	Yes	Text	Family name
date_of_birth	No	YYYY-MM-DD	Auto-extracted from ID
gender	No	M/F/O	Auto-extracted from ID
email	Yes	Email	Contact email
mobile	No	+27…	Mobile number
province	No	Code	Province code
employer	No	Text	Employer name

Example CSV

id_number,first_name,last_name,email,mobile
9001015009087,Thabo,Mokoena,thabo@example.com,+27821234567
9205235123080,Lerato,Ndlovu,lerato@example.com,+27831234567

Validation Rules

• ID numbers validated with Luhn algorithm
• Email format validation
• Duplicate checking (by ID and email)
• Required field validation

Enrolment Import

Template Fields

Field	Required	Format	Description
learner_id	Yes	ID/Email	Learner identifier
programme_code	Yes	Text	Programme code
start_date	Yes	YYYY-MM-DD	Enrolment start
expected_end	No	YYYY-MM-DD	Expected completion
funding_source	No	Code	Funding type

Example CSV

learner_id,programme_code,start_date,expected_end
9001015009087,PROG001,2024-01-15,2024-12-15
9205235123080,PROG001,2024-02-01,2025-01-31

Assessment Import

Template Fields

Field	Required	Format	Description
learner_id	Yes	ID/Email	Learner identifier
module_code	Yes	Text	Module code
assessment_type	Yes	Code	formative/summative
outcome	Yes	C/NYC	Competent/Not Yet Competent
assessment_date	Yes	YYYY-MM-DD	Date assessed
assessor_id	No	Email	Assessor identifier

Example CSV

learner_id,module_code,assessment_type,outcome,assessment_date
9001015009087,MOD001,summative,C,2024-06-15
9205235123080,MOD001,summative,NYC,2024-06-15

Export Operations

Available Exports

Export	Content	Format
Learner List	All learner data	CSV
Enrolment Report	Enrolment status	CSV
Assessment Summary	Assessment outcomes	CSV
Evidence List	Evidence metadata	CSV
Full Data Export	All tenant data	ZIP (multiple CSV)

Export via Web

1. Navigate to Reports → Export
2. Select export type
3. Choose fields to include
4. Apply filters (date, programme, status)
5. Generate export
6. Download when ready

Export via API

POST /api/v1/tenants/{slug}/exports
{
  "type": "learners",
  "format": "csv",
  "filters": {
    "programmeId": "prog-uuid",
    "status": "active"
  },
  "fields": ["id_number", "first_name", "last_name", "email", "programme", "status"]
}

API Reference

Start Import

POST /api/v1/tenants/{slug}/imports
Content-Type: multipart/form-data

file: [CSV file]
type: "learners"
options: {"dryRun": true}

Check Import Status

GET /api/v1/tenants/{slug}/imports/{import-id}

Response:

{
  "id": "import-uuid",
  "status": "validated",
  "totalRows": 150,
  "validRows": 148,
  "errors": [
    {"row": 45, "field": "id_number", "error": "Invalid ID format"},
    {"row": 89, "field": "email", "error": "Duplicate email"}
  ]
}

Confirm Import

POST /api/v1/tenants/{slug}/imports/{import-id}/confirm

Best Practices

Data Preparation

1. Clean Data: Remove formatting, special characters
2. Consistent Format: Use same date/number formats throughout
3. UTF-8 Encoding: Save as UTF-8 for special characters
4. No Empty Rows: Remove blank rows from CSV
5. Headers Required: First row must be headers

Large Imports

For imports over 1,000 rows:

• Split into batches of 1,000
• Allow time between batches
• Monitor for errors

Validation

Always use dry-run first:

{"dryRun": true}

Review all errors before confirming import.

Troubleshooting

Common Errors

Error	Cause	Solution
Invalid encoding	Wrong file encoding	Save as UTF-8
Missing headers	First row not headers	Add header row
Date format	Wrong date format	Use YYYY-MM-DD
Duplicate	Record already exists	Skip or update