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

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

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

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

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 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