CSV

Comma-Separated Values (CSV) is a simple and widely supported tabular file format.

ubConnect supports CSV-based data exchange with Sphinx-Needs in two directions:

  • Importing a CSV file to needs.json using command csv from-csv

  • Exporting needs.json to a CSV file using command csv to-csv

Details for these commands can be found under Usage.

CSV to Sphinx-Needs

Configuration Overview

The csv from-csv command imports a CSV file and generates a Sphinx-Needs compatible needs.json.

The configuration consists of the following components:

  1. CSV Input Settings: Where to find the CSV file and how to parse it

  2. Output Settings: Where to store the generated needs.json and how to form IDs

  3. Links & List Handling: Optional link resolution and list parsing

  4. Static Fields: Fields added to all created needs

  5. Field Mapping: How specific Sphinx-Needs fields read from CSV columns

Configurations can be provided in two ways:

  • TOML Configuration File: Define settings in a TOML file under the section

    [ubconnect.from_csv]. Relative paths in the TOML file are resolved relative to the TOML file’s location.

  • CLI Arguments and Options: Specify settings via CLI arguments and options.

    Note

    Mapping-related configurations are defined in the TOML file. Relative paths given as CLI arguments are resolved relative to the current working directory.

Basic Configuration

[ubconnect.from_csv]
csv_path = "input/requirements.csv"     # Required
outdir = "output"                       # Optional (default: ".")
id_prefix = "CSV_"                      # Optional (default: "CSV_")
delimiter = ","                         # Optional (default: ",")
encoding = "utf-8"                      # Optional (default: "utf-8")

# Optional: resolve relationships between items in the same CSV
# links_column = "links"                # Column holding linked IDs (without prefix)
# links_delimiter = ";"                 # Optional (default: ";")

# Optional: parse multiple values from cells
[ubconnect.from_csv.field_delimiters]
"Sections" = "|"  # If set, the values under '"Sections"' column are checked for this delimiter and split into lists

[ubconnect.from_csv.static_fields]
type = "req"                            # Default need type if CSV has no type column

[ubconnect.from_csv.mapping]
id = "id"
title = "title"
content = "content"
status = "status"
type = "type"
sections = "Sections"  # Example of mapping a need field to a specific CSV column name

Fields under [ubconnect.from_csv]:

CSV Input Settings:

  • csv_path: Path to the CSV file to import.

  • delimiter: The CSV delimiter character (default: ,, i.e. comma).

  • encoding: CSV file encoding (default: utf-8).

Note

csv_path must be provided either through the CLI argument or in the TOML configuration file.

Output Settings:

  • outdir: Output directory where needs.json is created (default: current directory).

  • id_prefix: Prefix added to every created need ID (default: CSV_).

Links & List Handling:

  • links_column: Name of the CSV column containing links to other items.

    If set, ubConnect creates a links field for each need and also resolves links_back.

  • links_delimiter: Delimiter used inside the links column to separate multiple linked IDs (default: ;).

  • field_delimiters: Delimiters for fields that contain multiple values, keyed by CSV column name.

    If a column is listed here, values in that column containing the specified delimiter are parsed into lists. For example, if the ‘Sections’ column is mapped to the ‘sections’ field and the ‘Sections’ column is listed with a delimiter of ‘|’, then a cell with value ‘Section 1|Section 2’ would be parsed into the list [‘Section 1’, ‘Section 2’] for the ‘sections’ field of the created need.

Note

  • The delimiter, links_delimiter, and field delimiters must be a single character.

  • The delimiter and links_delimiter are stripped of any surrounding whitespace before validation. If the resulting delimiter is empty, it defaults to a ‘,’ (for delimiter) or ‘;’ (for links_delimiter).

  • The field delimiters in field_delimiters must be configured as a single, non-empty character as written. Surrounding whitespace is not stripped automatically, so values like " | " are invalid; use "|" instead.

Static Fields:

  • static_fields: Key/value pairs added to every created need.

    By default, ubConnect provides type = 'req'.

Field Mapping

For csv from-csv, the mapping defines which CSV column header to use for each well-known Sphinx-Needs field.

Configuration structure:

[ubconnect.from_csv.mapping]
id = "ID"
title = "Title"
content = "Description"
status = "Status"
type = "Type"

Default mappings used by ubConnect (overridable):

Default Field Mappings (from-csv)

Need Field

CSV Column

id

id

title

title

content

content

status

status

type

type

Note

  • The created need ID is built as {id_prefix}{csv_id}.

  • Any additional CSV columns (not mapped to id/title/content/status/type) are imported as extra need fields. The field name is derived from the CSV header by lowercasing and replacing spaces with underscores.

  • Cell values are automatically type-converted where possible (boolean, int, float, JSON) and can be split into lists using field_delimiters.

Sphinx-Needs to CSV

Configuration Overview

The csv to-csv command exports a Sphinx-Needs compatible needs.json file to CSV.

The configuration consists of the following components:

  1. Path Settings: Where to find needs.json and where to write the CSV

  2. CSV Output Settings: Delimiter and encoding

  3. Links & List Handling: Optional inclusion of link fields and list serialization

  4. Field Mapping & Columns: How need fields map to CSV columns and how to order columns

Configurations can be provided in two ways:

  • TOML Configuration File: Define settings in a TOML file under the section [ubconnect.to_csv].

    Relative paths in the TOML file are resolved relative to the TOML file’s location.

  • CLI Arguments and Options: Specify settings via CLI arguments and options.

    Note

    Mapping-related configurations are defined in the TOML file. Relative paths given as CLI arguments are resolved relative to the current working directory.

Basic Configuration

[ubconnect.to_csv]
needsjson_path = "output/needs.json"      # Required
outpath = "output/needs.csv"              # Optional (default: "needs.csv")
delimiter = ","                           # Optional (default: ",")
encoding = "utf-8"                        # Optional (default: "utf-8")

include_links = true                      # Optional (default: true)
links_delimiter = ";"                     # Optional (default: ";")

# Optional: explicit column order (names must match the CSV header names)
# columns = ["ID", "Type", "Title", "Status", "Content", "links", "links_back"]

[ubconnect.to_csv.field_delimiters]
"Sections" = "|"  # If set, the values for 'Sections' column are separated by this delimiter when exporting lists to CSV

[ubconnect.to_csv.mapping]
id = "ID"
title = "Title"
content = "Content"
status = "Status"
type = "Type"
sections = "Sections"  # Example of mapping a need field to a specific CSV column name

Fields under [ubconnect.to_csv]:

Path Settings:

  • needsjson_path: Path to the needs.json file to export.

  • outpath: Path to the output CSV file (default: needs.csv).

Note

needsjson_path must be provided either through the CLI argument or in the TOML configuration file.

CSV Output Settings:

  • delimiter: The CSV delimiter character (default: ,, i.e. comma).

  • encoding: Output CSV encoding (default: utf-8).

Links & List Handling:

  • include_links: If set to false, the links and links_back fields are not exported (default: true).

  • links_delimiter: Delimiter used when serializing link lists to a single CSV cell (default: ;).

  • field_delimiters: Delimiters for fields that contain multiple values, keyed by CSV column name. If not set, list values are joined using ', '. If set, the values for that column are separated by this delimiter when exporting lists to CSV. For example, if a need has multiple sections and the ‘Sections’ column is mapped to the ‘sections’ field, then the sections will be joined into a single string with the specified delimiter when exporting to CSV.

Field Mapping & Columns:

  • mapping: Mapping from need field names to CSV column header names.

  • columns: Explicit CSV column order.

    Values must match the final CSV column header names (after applying mapping).

Field Mapping

For csv to-csv, the mapping defines which CSV header name is used for each exported need field.

Default mappings used by ubConnect (overridable):

Default Field Mappings (to-csv)

Need Field

CSV Column

id

ID

title

Title

content

Content

status

Status

type

Type

Note

Any need fields that are not listed in mapping are still exported as additional columns. In that case, the column header name is the original need field name.