Importing Data

Issue Log Workbench imports spreadsheet rows as issue records.

File Requirements

Format	Extension	Notes
CSV	.csv	UTF-8 or UTF-8-BOM encoded; comma-delimited
Excel	.xlsx	Multi-sheet workbooks supported; optionally specify a sheet name

The first row must be a header row. Each subsequent row becomes one Issue object.

Note

If you have an older binary Excel workbook in .xls format, resave it as .xlsx before importing. The current import path is designed around modern Open XML workbooks.

Column Name Conventions

The importer recognises common column header variants automatically:

Canonical Field	Auto-detected aliases
title	name, issue, subject
category	category
issue_type	type, issue type, issuetype
status	status, state
priority	priority, severity
description	description, desc, detail
example	example
comment	comment, comments
markdown_notes	notes, note, markdown_notes

Column names are matched case-insensitively and leading/trailing spaces are stripped.

Status and Priority Normalisation

Common spreadsheet values are normalised automatically:

Status

Spreadsheet value	Normalised to
open, new	imported
triaged	triaged
review, in_review	in_review
done, complete, completed, fixed	resolved
closed, wontfix	closed
(anything else)	imported

Priority

Spreadsheet value	Normalised to
critical, blocker, urgent	critical
high, major, p1	high
medium, p2	medium
low, minor, trivial, p3	low
p0	critical
(anything else)	unknown

Using the Import UI

1. Navigate to Import in the top navigation bar.
2. Click Choose file and select your CSV or XLSX file.
3. For XLSX files, optionally enter the Sheet Name.
4. For CSV files, the column mapping section appears automatically with your detected headers.
5. Columns that match a known alias are pre-mapped.
6. Use the dropdowns to map unrecognised columns to the correct field.
7. Select — Skip — to ignore a column.
8. For XLSX files, the server still auto-detects common header names, but the browser-side mapping helper is more limited than it is for CSV.
9. If needed, enter a manual JSON mapping in the provided text area.
10. Example: {"Issue Name":"title","Sev":"priority"}
11. Click Import.
12. Review the result summary for created rows, skipped rows, warnings, and validation issues.

Using the API Directly

# Import a CSV file
curl -X POST http://127.0.0.1:8000/api/imports/ \
  -F "file=@/path/to/issues.csv"

# Import a specific sheet from an XLSX file
curl -X POST http://127.0.0.1:8000/api/imports/ \
  -F "file=@/path/to/issues.xlsx" \
  -F "sheet_name=Sheet2"

# Provide a custom column map as JSON
curl -X POST http://127.0.0.1:8000/api/imports/ \
  -F "file=@/path/to/issues.csv" \
  -F 'column_map={"Issue Name":"title","Sev":"priority"}'

The import response includes:

• created_count
• skipped_count
• warnings
• row_errors
• preview

Duplicate Detection

If an imported row has a title that already exists in the database, a warning is added to the result but the row is still imported. You can review duplicates manually after import.

Skipped Rows

Rows are skipped if:

• All cells are empty or contain only whitespace
• No title value can be found after column mapping

The import result reports the skipped count and any row-level validation details that were captured.