> ## Documentation Index
> Fetch the complete documentation index at: https://help.hflow.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Assessments

> Creating, editing, importing, and understanding assessments in hFlow.

This feature allows teachers and admins to record **scheduled** reading assessments (BOY, MOY, EOY), optional median-based (three-passage) entry, domain comprehension and ACTFL levels, and to use **bulk gradebook** entry or **CSV import** for a class.

For how **accuracy**, **fluency (WCPM)**, and median-based scores are calculated. See [Language metrics](/hflow/language-metrics). For background on the ACTFL Proficiency Scale versus your program’s charts and forms. See [ACTFL proficiency scale (overview)](/hflow/actfl-proficiency-scale).

## How to open the gradebook

1. In the header, click **Assessments**.
2. Choose **language**, **school year**, **grade**, and **class** using the filters at the top, or apply a [shortcut](/hflow/shortcuts) you saved on Students or a report.
3. Use period tabs or cards to view or edit scores for BOY, MOY, and EOY.

## How to add or edit a scheduled assessment

1. From **Students** ([student home page](/hflow/students/student-home-page)) or the **Assessments** page, choose **Add assessment** or open an existing scheduled assessment.
2. Enter **Total words**, **Correct words**, and **Time** (seconds), or complete all three passages when **Median-based assessment** is enabled.
3. Set **Reading comprehension** and **Reading ACTFL**, and expand **Listening**, **Speech**, and **Writing** when you need those domains.
4. Review **Grade-level overall**: the app computes a single level (**Below**, **Approaching**, or **At Grade**) from the skill scores you entered, using only domains that have a value, then rounding the average to a whole level.
5. Turn on **Manual override** only if the stored overall must differ from that calculation. If you change **any** reading or language skill value (comprehension or ACTFL on reading, listening, speech, or writing), the override is cleared and the overall is recomputed.
6. **ACTFL overall (composite)** is **read-only**. It is the average of the four ACTFL levels you entered (each 1–9), rounded to one decimal for storage and band mapping, with a short band label (for example `2.5 - NM` or `3 - NH` when the value is a whole number). It updates whenever any of those ACTFL fields change.

Click **Save Changes** (or **Add Assessment** on a new row) to store scores, tier, **grade-level overall**, and **ACTFL composite** on the assessment.

## How to use bulk gradebook entry

1. From **Assessments**, open bulk entry for the desired **language**, **grade**, and **class** context.
2. For each period, use the **G. overall** column to leave the level on **Auto** (follows the same rules as the modal) or choose a fixed level. The **ACTFL Σ** column shows the composite for that row; it is not editable here.
3. If you edit comprehension or any domain ACTFL field after choosing a fixed overall, **Auto** is applied again for that cell (manual override is cleared), matching the assessment modal.

Bulk save runs the same server checks as editing one cell at a time; median (three-passage) rows duplicate shared skill fields and grade-level overall across all three passages so totals stay aligned.

## Import assessments from CSV

Bulk import is the fastest way to load many scores after your roster exists.

1. On **Assessments**, set **language**, **grade**, and **class** to match the students in your file.
2. Click **Import CSV**.
3. Click the **?** help control in the import header for the full column list (same rules summarized below).
4. Upload your CSV, confirm the row count, and click **Proceed**.
5. Review successes and failures. Download **Successes** or **Failures** if you need to fix rows and re-upload.

Re-uploading updates existing assessments for the same student, school year, period, and language. It does not create duplicate rows.

If the wrong file was imported or the entire batch must be reversed, **owners** and **admins** open **Configuration → CSV Imports** and use **Review undo**. Undo is blocked once anyone **edits** an assessment that the file created or updated, for example changing a score in the gradebook after import. **Teachers** should alert your hFlow owner or admin right away and avoid editing those scores until undo is checked. Details: [CSV imports and undo](/hflow/configuration/csv-imports).

<Note>
  Maximum **500 rows** per file. Split larger schools across multiple uploads. Median-based three-passage CSV import is not enabled. Use **Bulk Entry → Use Median** in the app, or omit the `passage` column.
</Note>

### Required columns (every row)

* `first_name`, `last_name`, `school_year`, `grade`, `language`, `period`

### Optional: student matching

* `middle_name`, `student_code`, `tested_at`

### Optional: scores (at least one score column per row)

**Reading fluency / accuracy** (use all three together, or omit all three):

* `total_words`, `errors`, `total_time`, `comprehension` (`Good`, `Partial`, `Low`, or blank)

**ACTFL levels** (1–9 or recognized level names):

* `reading_actfl_level`, `listening_actfl_level`, `writing_actfl_level`, `speech_actfl_level`

**Domain comprehension** (`at_grade`, `approaching`, `below`, or blank):

* `listening_comprehension`, `writing_comprehension`, `speech_comprehension`

### Matching and updates

* Students match by first name, last name, and optional middle name (case-insensitive) in the same grade and school year.
* If several students share the same name, include `student_code` on those rows.
* **New** assessment → creates a row; **existing** → updates values; duplicate rows in one file → first row wins.

Checkpoints are not imported. Add them from the [student home page](/hflow/students/student-home-page).

For a full first-time workflow. See [Getting started](/hflow/getting-started).

## Read-only gradebook cards

When **Show Reading Only** is off, a scheduled assessment with reading metrics but no listening, speaking, or writing results appears as a reading-focused card (Err / Tot / Time, accuracy, WCPM, comprehension, reading ACTFL) with a short note that those language skills were not reported. After you add any listening, speaking, or writing value and save, the card returns to the full layout with domain rows. Hover **View/Edit** works the same as on other assessment cards.

## Exports and print

Overall language level and ACTFL composite are stored for use in the app. **Print students** and **org-wide data downloads** follow your school’s export settings; bulk assessment CSV is import-focused in the gradebook flow described above.