Skip to content
Orbit guides

Import requirements from a CSV file

Requirements can be entered one by one on Release → Requirements → New requirement, or many at once with Import CSV (in the ⋯ menu next to New requirement). This page explains the file format, the rules and the steps. A ready-to-edit sample is at the end of this page.

Who can import: QA Leads, Project Admins and System Admins. Viewers and QA Engineers can read and export only.

File format

Section titled “File format”
  • Encoding: UTF-8, comma-separated. A first row with column names is required.
  • Columns: they can be in any order, and their names are not case-sensitive.
Column Required Rule
key Yes Jira-style: capital letters or digits, a hyphen, then digits, e.g. SHOP-101. Pattern ^[A-Z][A-Z0-9]*-[0-9]+$, at most 64 characters. Lower case is turned into upper case.
title Yes 1–300 characters.
feature No 1–100 characters. Best to use the same value as the tests’ @feature tag, so the list can be filtered by feature.
priority No P1, P2, P3 or P4, or empty.
url No A link to the requirement in your tracker, starting with http:// or https://, at most 2,000 characters.
  • Values with a comma go inside double quotes, e.g. "Invoices need a signed-in customer, otherwise access is refused". A double quote inside a quoted value is written twice ("").
  • Extra columns from an export: the requirements export adds status, coverage and linked_tests. Import ignores these three, so an exported file can be edited and imported again. Any other unknown column makes the whole file refused.
  • Limits:
    • at most 2,000 rows and 1 MB per file;
    • rows that are completely empty are skipped.

What an import does

Section titled “What an import does”
  • Upsert by key:
    • a new key creates a requirement (status active, source csv);
    • a key that already exists is updated with the values in the file.
  • Columns left out keep their value. A column missing from the file keeps the stored value. For example, a file with only key,title changes titles and nothing else.
  • Rows with errors are skipped. The other rows are still imported. Typical row errors:
    • a bad key;
    • an empty or too long title;
    • an unknown priority;
    • a key that appears twice in the file (the later row is refused);
    • the key of an archived requirement (restore it first).
  • Description is not in the CSV. Add or edit it on the requirement’s page.
  • Audit: every import is audited (requirement.import) with the counts created, updated, unchanged and with errors.

Steps

Section titled “Steps”
  1. Open Release → Requirements in the project, open the ⋯ menu (More actions for requirements) and choose Import CSV.
  2. Choose Choose a CSV file and pick the file. Orbit shows a preview at once and writes nothing yet:
    • the counts (new, updated, unchanged, errors);
    • every row with its line number and result;
    • Only rows with errors filters the table.
  3. Fix the file if needed and pick it again, or go on.
  4. Choose Import N requirements. Rows with errors are skipped.
  5. Link tests to the requirements in the workload code with a tag @req:<KEY>, e.g. test('a customer signs in @req:SHOP-101', …). Coverage appears after the next catalog sync and runs.

Tips

Section titled “Tips”
  • Start from an export (Export CSV, in the same ⋯ menu) of the current list, edit it in a spreadsheet, save as CSV (UTF-8), and import it back.
  • Spreadsheet programs may save with a semicolon separator or another encoding in some regions. Choose “CSV UTF-8 (comma delimited)”.
  • A value that starts with =, +, - or @ is exported with a leading ' so spreadsheets do not run it as a formula. Import removes that quote again.

Sample file

Section titled “Sample file”

Copy these lines into a text editor and save them as requirements.csv (UTF-8):

key,title,feature,priority,url
SHOP-101,A customer signs in with email and password,authentication,P1,https://example.com/req/SHOP-101
SHOP-102,A signed-in customer sees their own name,authentication,P2,
SHOP-103,A wrong password is refused without locking the account,authentication,P2,
SHOP-201,A customer adds a product to the cart,cart,P1,https://example.com/req/SHOP-201
SHOP-202,A customer removes an item from the cart,cart,P3,
SHOP-301,A customer reads only their own invoices,invoices,P1,
SHOP-302,"Invoices need a signed-in customer, otherwise access is refused",invoices,P2,
SHOP-401,An admin creates renames and deletes a brand,brands,P3,