Import/Export

Administrator guide for importing and exporting student, class, and nucleus data.

Overview

The Import/Export page allows you to:

• Export students, classes, and nuclei in CSV or JSON for backup or analysis
• Import students via CSV or JSON file, with line-by-line validation
• Download templates (empty) for manual fill-in and batch import

Access restricted to Administrators (ADMIN role).

---

Export

1. Go to Import/Export → Export tab
2. Select the entity: Students, Classes, or Nuclei
3. Select the format: CSV or JSON
4. Click Download

The generated file includes all fields from the current schema, including studentId, status, and timestamps. Students with status: DELETED are not included.

CSV Format

Flat columns. Phones expanded into 6 columns (phone1Number, phone1Qualifier, …). Address in 7 columns (addressStreet, addressNumber, …). Booleans as Yes/No.

Column	Type	Description
studentId	UUID	Unique identifier (export only)
Nome completo	string	displayName
Data de nascimento	YYYY-MM-DD	birthDate
Responsável	string	guardianName
Turma	string	Class name (resolved automatically)
Região	string	nucleusRegion (7 colors)
Participa do Núcleo	Yes/No	nucleusParticipates
phone1Number	digits	Primary phone
phone1Qualifier	string	Qualifier (Mother, Father, etc.)
addressStreet	string	Street
…		(remaining address, allergies, special needs fields)

JSON Format

Natural nested structure, identical to the Student type:

[
  {
    "studentId": "uuid",
    "displayName": "João Silva",
    "guardianName": "Maria Silva",
    "birthDate": "2020-01-15",
    "phones": [{ "number": "11999999999", "qualifier": "Mãe" }],
    "address": {
      "street": "Rua Principal",
      "number": "123",
      "complement": "",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01001000"
    },
    "classId": "uuid-da-turma",
    "nucleusParticipates": true,
    "nucleusRegion": "Azul",
    "nucleusName": "Azul Centro",
    "allergies": null,
    "specialNeeds": null,
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
]

---

Import

Flow

1. Go to Import/Export → Import tab
2. Drag a .csv or .json file into the upload zone, or click to select
3. The format is detected automatically
4. Select Preview (dry-run) to see what will be imported without saving
5. Review the 3 sections:
   • ✅ Ready rows — will be imported
   • ⚠️ Possible duplicates — check/uncheck which ones to import
   • ❌ Error rows — always skipped
6. Click Import

Preview (dry-run)

Before importing, enable "Preview" to see exactly what will happen. No data is saved in dry-run mode.

The preview shows:

• Number of valid rows (✅)
• Possible duplicates with checkbox per row (⚠️)
• Validation errors with child name + message in Portuguese (❌)
• Summary: "Import X students (Y duplicates selected, Z skipped due to errors)"

Validation Rules

Rule	Error
displayName required	"Nome completo é obrigatório"
guardianName required	"Responsável é obrigatório"
birthDate format YYYY-MM-DD	"Data de nascimento inválida. Use o formato AAAA-MM-DD"
Turma must exist	"Turma 'X' não encontrada. Turmas disponíveis: Berçário, Infantil, …"
Região invalid	"Região inválida. Use: Azul Celeste, Azul, Amarela, …"
Invalid phone	"Telefone X: número inválido"
Max 3 phones	"Máximo de 3 telefones por aluno"

Duplicate Detection

The system checks whether a student already exists with a similar name (edit distance ≤ 2) AND the same birth date or same guardian. Duplicates are shown as ⚠️ warnings — you decide whether to import or skip each one.

Accepted Formats

CSV: auto-detected delimiter (, ; or tab). UTF-8 encoding (BOM handled automatically). Dates in Excel format (serial number) are converted automatically.

JSON: nested format (with phones as array and address as object) or flat format (with phone1Number, addressStreet, etc.). Both are normalized automatically.

After Import

• Students are created locally (IndexedDB) and queued for synchronization
• The StatusIndicator will show the number of pending sync items
• If there are errors, you can download a CSV with only the error rows + _erro column

Limits

• Maximum file size: 10 MB
• Maximum rows per import: 1000

---

Templates

1. Go to Import/Export → Templates tab
2. Select the entity: Students, Classes, or Nuclei
3. Select the format: CSV or JSON
4. Click Download template

The CSV template includes:

• Header with all fields
• One example row with formatted values ((11) 98765-4321, Yes, Berçário)
• File name: neemias-template-estudantes-v1.1.0.csv

The JSON template is an empty array [].

---

Troubleshooting

Problem	Solution
"Formato não reconhecido"	Check that the file is valid .csv or .json. Formats are detected automatically.
"Turma 'X' não encontrada"	The class name in the CSV must match an existing class exactly. Register the class in Classes first.
Dates appear as numbers	Excel may save dates as serial numbers. The importer converts automatically. If it fails, save the CSV as "CSV UTF-8" in Excel.
Accented characters broken	Save the file as UTF-8. In Excel: "Save As" → "CSV UTF-8 (comma delimited)".
Phones not recognized	The parser accepts any format: (11) 98765-4321, 11987654321, 11 98765-4321. Digits are extracted automatically.

---

Field Reference

The complete field list is derived from the current schema. See app/src/modules/importExport/fieldManifest.ts for the canonical definition. To add a new field to the system, follow the Extending Student Fields guide.