# Excel Workbooks: Reading Requirements Sheet by Sheet

> A requirements workbook is rarely one table. A typical file has a cover sheet, a list of numbered requirements under a two-row title, a data dictionary of fields, a sheet of test data, and a glossary.

Source: https://totalshiftleft.ai/help-center/product-documentation/requirements-excel-workbooks

> **Applies to:** All editions (requirements review is basic on Free; full on Professional and Enterprise) · Web app and Desktop app · A role that can edit the project

## Overview

A requirements workbook is rarely one table. A typical file has a cover sheet, a list of numbered requirements under a two-row title, a data dictionary of fields, a sheet of test data, and a glossary. Reading the whole workbook as one block of text mixes those together: test values turn into "requirements", the cover page is sent to the AI, and a 500-row list loses its row numbers.

Shift-Left Studio reads a workbook sheet by sheet. When the file is read, each sheet is classified by what it contains, and each kind of sheet is handled differently. Requirement lists are read one row at a time so every requirement keeps its sheet, row, column, and id. Field rules are read directly from a data dictionary without AI. Test data becomes data for generating tests, and glossary terms become project terms. Cover and notes sheets are left out.

You can see what each sheet was read as, why, and how sure Studio was — and change it if it is wrong.

## Key concepts

Each sheet is given one of these roles. The labels are the ones shown in the **Read as** drop-down.

| Role | How the sheet is used |
|---|---|
| **List of requirements — one per row** | Each row is read as one requirement, in batches, and keeps its row number and id. |
| **Text — read as a whole** | The sheet is read like a page of prose. Used for sheets Studio is not sure about. |
| **Decision table** | Read as a set of conditions and outcomes. |
| **Data dictionary — field rules** | Field rules (required, type, length, pattern, allowed values, default) are read directly from the cells, without AI. |
| **Error code list** | Used to find error and status codes. Not sent to the AI as requirements. |
| **Test data — not requirements** | Becomes sample data for generating tests. Never becomes requirements. |
| **Glossary** | Terms and synonyms are added to the project glossary. |
| **Not used** | Ignored — for example, a cover sheet or change log. |

Other terms:

- **Header row** — the row that holds the column names. Studio looks for it in the first 15 rows, so title blocks above the table are handled.
- **Confidence** — how sure Studio is of a detected role, shown as a percentage. A sheet below 60% is read as text, which is the safest reading.

## Before you begin

- Upload the workbook on the **Requirement Documents** tab. Excel (.xlsx, .xls) and CSV files are read this way; a CSV file is treated as a single sheet.
- Jira and Azure DevOps exports are recognized separately and are split per ticket instead.
- An AI provider must be configured to extract requirements from requirement-list, text, and decision-table sheets.

## Step 1 — See how the workbook was read

1. Upload the workbook. See [Working with Many Requirement Documents](/help-center/product-documentation/requirements-multiple-documents).
2. Once the file has been read, a chip appears under the document's name, for example "5 sheets · 1 list of requirements, 1 data dictionary, 1 test data, 1 glossary, 1 not used". Hover over it for the summary.
3. Click the chip. The dialog **Sheets in <file name>** opens.

The dialog has a row per sheet:

| Column | What it shows |
|---|---|
| **Sheet** | The sheet name and the main reason for its role, in words. |
| **Read as** | The role, with **Detected (82% sure)** or **Your choice** underneath. |
| **Header row** | The row used as column names, with the column names below it. |
| **Rows** | The number of rows in the sheet. |

## Step 2 — Correct a sheet's role

1. In the **Read as** column, open the drop-down for the sheet.
2. Choose the correct role.
3. Repeat for any other sheet.
4. Click **Save and read again**.

Your choice is labeled **Your choice** and sticks through every later reading of the file. To hand a sheet back to automatic detection, click **Use detected** under the role, then **Save and read again**.

> **Note:** You cannot change the sheets while the document is being read or extracted. Wait until its status is no longer in progress.

## Step 3 — Correct the header row

If the column names shown under **Header row** look wrong — for example, a title line was taken as the header — fix it:

1. Open the **Header row** drop-down for the sheet and choose the correct row (**Row 1** to **Row 15**).
2. Click **Save and read again**.

Studio also handles merged title cells and repeated or blank column names on its own: repeated names are numbered (for example, "Behaviour (2)") and blank headers are named by column letter.

## Step 4 — Apply the change to existing requirements

Saving re-reads the file straight away, and a confirmation appears: "Saved and the file was read again."

- If the document has already produced requirements, the message adds **Parse the document again to apply it to the requirements already extracted.** Existing requirements change only when you extract the document again. Select it on the document list and click **Extract selected (1)**, or use its **AI Parse** button.
- If a glossary sheet was read, the message says how many glossary terms were added.
- If test data was read, the message names the sheets it came from.

## Step 5 — Check which rows produced nothing

For each requirement-list sheet, the dialog shows how many rows produced a requirement, for example "**Requirements**: 48 of 50 rows produced a requirement." Below it, each row that produced nothing is listed with its row number (as Excel shows it), its id if it has one, and its text.

Use this list to find rows that were skipped. Common causes are a row that is really a heading, a row with no requirement text, or wording the AI could not turn into a rule. Fix the row in the workbook and upload it again, or add the rule by hand with **Add without a file → Write one requirement**.

## Understanding the results

What each role produces, and where you see it:

| Role | What it produces | Where you see it |
|---|---|---|
| List of requirements | One requirement per row, with the sheet, row, column, and your id (from an id column such as "Req ID") | The review list — for example `Rules.xlsx › Rules › row 14 › Requirement` with `BR-014` |
| Data dictionary | Field rules quoted from the cells, with sheet, row, and column | The review list. These are sent to review and are not approved automatically. |
| Decision table | Conditions and outcomes read as requirements | The review list |
| Error code list | Expected error and status codes | Used when rules and tests are generated |
| Test data | Sample data (fixtures) and data sets for generating tests | The **Data for Generating Tests** tab, where the workbook is listed with "Test data sheets of a requirements document: …" |
| Glossary | Project glossary terms and synonyms | Used to match terms when reading documents |
| Text | Requirements read from the sheet as a whole | The review list |
| Not used | Nothing | — |

Notes:

- The workbook appears on the **Data for Generating Tests** tab for reference only. You cannot delete it or change its sheets there; the file belongs to the **Requirement Documents** tab.
- A glossary term you entered by hand is never overwritten by a glossary sheet.
- Test data, glossary, and cover sheets are never sent to the AI as requirement text, which also keeps AI usage down.

## Troubleshooting

| Symptom | Why it happens | What to do |
|---|---|---|
| No sheet chip appears on the workbook | The file has not been read yet, or it is a Jira/Azure DevOps export handled per ticket. | Wait for the file to be read, or click the **Extract text** button on its row. |
| A requirements sheet was read as **Text — read as a whole** | Detection was less than 60% sure. | Change it to **List of requirements — one per row** and save. |
| Requirements are missing their id | The id column was not recognized or the header row is wrong. | Check the column names under **Header row** and correct the header row. |
| Test values appear as requirements | The sheet was classified as a requirement list. | Change it to **Test data — not requirements**, save, and extract again. |
| Saving changes nothing in the review list | Existing requirements change only on the next extraction. | Extract the document again. |
| "This document is being read right now…" | The file is being read or extracted. | Wait until it finishes, then change the sheets. |
| Many rows are listed as producing nothing | The sheet may contain headings or notes between requirements, or the header row is wrong. | Check the header row; move notes out of the list; re-upload. |

## Best practices

- Put one requirement per row with an id column (for example "Req ID") and a requirement text column. This gives the best recall and traceability.
- Keep test data, glossary, and cover information on their own sheets rather than mixing them into the requirement list.
- Open the sheet map after every new workbook upload and confirm each role before you extract, so you do not spend AI calls on the wrong reading.
- Review data-dictionary rules like any other requirement; they are quoted from your cells but still need a person's approval.
- Use the "rows that produced nothing" list as a checklist after each extraction.

## FAQ

**Does Studio use AI to read the data dictionary?**
No. Field rules are read directly from the cells, so each rule quotes the cell it came from.

**Why is a low-confidence sheet read as text instead of guessed?**
Reading a sheet as text is the safe fallback: it may produce fewer structured requirements, but it will not turn test data or notes into requirements by mistake.

**Can I change a sheet's role on the Data for Generating Tests tab?**
No. The sheet map is read-only there; change it from the **Requirement Documents** tab.

## Related articles

- [Working with Many Requirement Documents](/help-center/product-documentation/requirements-multiple-documents)
- [Duplicates and Conflicts Across Requirement Documents](/help-center/product-documentation/requirements-cross-document-duplicates-and-conflicts)
- [Importing and Reviewing Requirements](/help-center/product-documentation/importing-and-reviewing-requirements)
- [Coverage and Extraction Fidelity](/help-center/product-documentation/coverage-and-fidelity)
- [Requirements Traceability Matrix](/help-center/product-documentation/requirements-traceability-matrix)

## For administrators (self-hosted installations)

| Setting | Default | What switching it does |
|---|---|---|
| `RIE_SHEET_CLASSIFICATION_ENABLED` | `true` | `false` stops sheet-by-sheet reading; workbooks are read as one block of text. |
| `RIE_ROW_WISE_EXTRACTION_ENABLED` | `true` | `false` reads a requirement-list sheet as one block instead of row by row. |