# Student import

> How to import students from an XLSX file: the columns Cademí reads, analysis before processing, duplicates, rows with errors and subscriptions.

The import brings many students at once, from a spreadsheet. It is for people coming from another platform, or for a whole class from a company. Each row creates the student, if they do not exist, and gives them a delivery. You send the file in **Students > Imports**, review the analysis and only then process it.

**The most important rule:** the delivery must exist first. Each row points to a delivery by its product code. With no delivery for the code, the row gets an error.

## How it works

- Each row of the spreadsheet is **one student and one delivery**.
- If the student should get several deliveries, they appear on several rows.
- The delivery is found by the product code set on it, the same one a gateway sale would carry. See [Deliveries](https://help.cademi.cloud/en/vendas/entregas.md).

The access is a manual enrollment, the same as **Add delivery** in the profile. It shows in **Purchases** as a **Standalone delivery**, and the account controls that enrollment. The duration is the delivery's, counted from the enrollment start.

The import does not bring lesson progress, exam attempts or certificates from the old platform.

### The columns

The first row of the spreadsheet is the header, with these names. Cademí discards empty rows. A cell with only "0" counts as empty.

| Column | Required | What Cademí reads |
|---|---|---|
| `status` | Yes | Whether the row gives or switches off access. See below |
| `produto_id` | Yes | The product code set on the delivery. With no delivery for the code, the row gets an error |
| `cliente_email` | Yes | The student's email. With it, Cademí decides whether to create a record or use the existing one |
| `cliente_nome`, `cliente_celular`, `cliente_doc` | No | Name, phone and document. Name and phone are stored only when the row creates the student. The document is stored whenever the row gives access |
| `cliente_endereco`, `cliente_endereco_n`, `cliente_endereco_comp`, `cliente_endereco_bairro`, `cliente_endereco_cidade`, `cliente_endereco_estado`, `cliente_endereco_cep` | No | Address. Stored only on a student the row creates |
| `comecou_em` | No | When access started, in the `YYYY-MM-DD HH:MM:SS` format. If blank, access starts when the row is processed |
| `tags` | No | Tag names separated by semicolons. If a name does not exist, Cademí creates the tag during analysis |
| `codigo` | No | The order code on the old platform, so you can recognize the row later |
| `cliente_senha` | No | An initial password. It applies only if the row creates the student |
| `recorrencia_id`, `recorrencia_status` | No | The code and status of the subscription, when the row is a subscription. See below |

**The `status`** accepts what people usually write, in Portuguese or English:

- "Aprovado" (approved), "pago" (paid), "completo" (completed) and "concluído" give access.
- "Cancelado" (cancelled) switches off the access the student already had to that delivery.
- "Reembolso" (refund), "estorno", "chargeback" and "disputa" (dispute) also switch it off.
- Any other word leaves the row with an error.

**The `recorrencia_status`** decides instead of `status` when the row has a `recorrencia_id`. "Ativo" (active) and "trial" give access. "Cancelado" (cancelled) and "em atraso" (overdue) switch it off.

There is no duration or "days left" column: the time is the delivery's. The spreadsheet does not fill in the account's custom fields.

### Start date and subscriptions in a migration

- **Leave `comecou_em` blank** when everyone should start today. For example: a new class, or a migration where you give a fresh period.
- **Use the original purchase date** when the delivery's time should continue from the old platform. On a one-year delivery, someone who bought ten months ago is left with about two months. Whoever had already expired there stays expired here.
- **"N days after purchase" rules** also count from that date. The student arrives with open what they had already reached.
- **Subscriptions** need the `recorrencia_id`. It is how Cademí recognizes the same subscription when the gateway, once connected, reports the renewal or the cancellation.
- **A purchase after the import**, of the same delivery and with the same email, takes over the imported enrollment. From then on, the gateway controls that enrollment.

**Heads up: this is where most mistakes happen.** Rafa paid until June 30 on the old platform. You import his row as "cancelado", thinking it means "paid until". Result: Rafa's access closes right away. To end it on the right day, import as "aprovado" and schedule the end later, in the **Purchases** tab. See [Enrollments and access](https://help.cademi.cloud/en/alunos/matriculas-e-acessos.md).

## Step by step

1. Open **Students > Imports**.
2. Click **New import**.
3. Choose the file: an XLSX of up to 20 MB and 5,000 records, with the `status`, `produto_id` and `cliente_email` columns.
4. Click **Send file**.
5. Review the **Import Analysis** screen. The analysis runs on its own and puts each row in **Ready**, **With error** or **Ignored**. **Total** shows everything.
6. If there are rows **With error**, fix the cause (see below).
7. With no rows in error, click **Process**.

The ready rows go to the queue and the import becomes **Processed**. Use the analysis search to find a row by name, email or code.

How to fix a row with an error:

- **The delivery did not exist:** create the delivery and click **Reprocess analysis**. Cademí reads the same spreadsheet again.
- **The error is in the spreadsheet**, such as a wrong email or date: send the corrected file as a new import.

**The account's first import** needs a release by the Cademí team. The analysis runs, but when you process it the screen asks you to contact support. The following imports process directly.

The path of an import, from sending the file to processing it:

```mermaid
flowchart TD
    accTitle: The stages of an import
    accDescr: You send the file and the analysis runs on its own. If any row came out with an error, fix the cause and reprocess the analysis, or send a corrected file. With no errors, the account's first import waits for support to release it. Then you process it: the ready rows go to the queue and the students and enrollments are applied in the background. Ignored rows do not block.
    enviar["Send file"]
    analise["Import Analysis"]
    erro{"Any row With error?"}
    corrigir["Fix it and Reprocess analysis"]
    primeira{"Account's first import?"}
    suporte["Support releases it"]
    processar["Process"]
    fila["Students and enrollments in the background"]
    enviar --> analise
    analise --> erro
    erro -->|Yes| corrigir
    corrigir --> analise
    erro -->|No| primeira
    primeira -->|Yes| suporte
    primeira -->|No| processar
    suporte --> processar
    processar --> fila
    classDef destaque stroke:#ff005c,stroke-width:2px
    class processar destaque
```

**Ignored** rows do not count as errors: they do not block and give nothing.

Processing means Cademí accepted the rows. It does not mean every student can already sign in: records, enrollments and emails happen in the background. The **Download original file** and **Download analysis JSON** buttons stay on the screen, so you can keep what you sent and the result.

## Duplicates and ignored rows

The analysis decides by email and delivery. An ignored row is not a defect: it does not block processing and gives nothing.

| Situation | What happens |
|---|---|
| New email | Creates the student and the enrollment |
| The email exists and they do not have this delivery active | The same student gets the delivery. Name, password and profile stay as they are |
| The email exists and they already have this delivery active | Row ignored: **Already has active access** |
| Same email and same delivery twice in the file | The first row counts. The repeat is ignored: **Repeated in this spreadsheet** |
| Another import already queued this email for this delivery | Row ignored: **Already queued for processing** |
| Same email, different deliveries | Each row counts on its own |
| The student is in the trash, or the enrollment is no longer active | Does not count as "already has access". The row gives access again |

The import never changes the name, phone or password of a student who already exists. To fix those, edit the student in the profile.

## Rows with errors

| Failure | What to do |
|---|---|
| The row came out **With error** in the analysis: unknown status, unreadable date or `produto_id` with no delivery | A row with an error blocks the whole import. Create the delivery and use **Reprocess analysis**, or send a corrected file as a new import |
| The whole file was refused: unreadable, no rows, a required column missing or more than 5,000 records | Fix the file and send it again. For more rows, split them into files or contact support |
| The row was processed and failed afterwards. For example: the account reached its student limit | Free up seats and send those people in a new import. Students who already existed get the delivery even with the quota full. Only new students fail |
| The screen says imports are blocked | Cademí support switched the account's imports off. Ask for the block to be lifted |

## The welcome email

- **New students** get the account's import email, with the login and the password. This happens when that template is on in **Settings > Emails**.
- **Students who already existed** and only gained a delivery do not get this email or a new password.
- **With the template off**, Cademí creates the student with a password, but they do not know it. To sign in, they use the forgot-password link.

Before a large import, send yourself a test.

## Good to know

- **Student quota.** Each new student takes a seat of the plan. Check the free seats before a migration.
- **Deleting an import.** It is only possible before processing, and it does not undo what already went to the queue. The deleted import goes to the screen's **Trash** and can be restored.
- **A processed import.** It cannot be deleted. To undo the access, delete or deactivate the enrollments in each student's profile.
- **Tags created during analysis.** They stay even if the import is deleted or the row is ignored.
- **One spreadsheet per delivery.** Errors are easier to find and fix, and you avoid duplicate records.
- **No spreadsheet template.** The screen has no template to download. Build the file with the column names from the table above, without changing the header.

## Frequently asked questions

**"No delivery is configured for ID".** The value in `produto_id` matches the product code of no delivery in the account. Check the code on the delivery, or create the delivery. Then click **Reprocess analysis**.

**I imported and the students did not get the email.** Check that the import is **Processed** and that the import email template is on. Students who already existed do not get it. The account's first import waits for the support release.

**I want to keep the time each student had left.** Use the original purchase date in `comecou_em` and a delivery with the same duration as the old offer. Today's date would give the whole period again.

**I imported as "cancelado" and the student lost access.** "Cancelado" switches access off right away; it does not mean "paid until". In the student's **Purchases** tab, click the status of the row to activate it. Then schedule the end on the right day.