ReqIF

The ReqIF (Requirements Interchange Format) is a standard XML format to exchange requirements between different tools.

ubConnect supports two directions of ReqIF exchange with Sphinx-Needs:

  • Exporting Sphinx-Needs to ReqIF using command reqif to-reqif

  • Importing ReqIF to Sphinx-Needs using command reqif from-reqif

Details for these commands can be found under Usage.

Round-Trip Conversion

ubConnect aims to support round-trip conversion between Sphinx-Needs and ReqIF. This means that requirements can be exported from Sphinx-Needs to ReqIF format and then imported back to Sphinx-Needs without losing any information. To achieve this, it is essential to configure both export and import processes correctly, especially the field mappings.

Caution

The main purpose of the round-trip conversion is to link the requirements managed in Sphinx-Needs with external ALM tools that support ReqIF instead of modifying the requirements on both sides. The modification of requirements shall be done in their corresponding tools, either Sphinx-Needs or the ALM tool, depending on the defined single source of truth. To achieve this, ubConnect provides the configuration origin_field to track requirement’s source of the truth in a dedicated field during both export and import processes.

For example, a typical scenario could be:

  • System requirements are defined and managed in an ALM tool that supports ReqIF import/export and the ALM tool is the single source of truth for System requirements.

  • Software requirements are defined and managed in Sphinx-Needs within the project’s documentation and Sphinx-Needs is the single source of truth for Software requirements.

  • Users want to link Software requirements in Sphinx-Needs to System requirements in the ALM tool in the Sphinx-Needs project.

In this case, users can export the existing System requirements from the ALM tool to ReqIF format, then convert them into needs.json using the reqif from-reqif command to import into the Sphinx-Needs project. During this conversion, ubConnect records each requirement’s single source of truth in a dedicated field (e.g., origin). This allows ubConnect to identify which requirements originated from the ALM tool when exporting back to ReqIF later, ensuring that only Software requirements (managed in Sphinx-Needs) are exported while preserving the System requirements as reference links.

After that, users can define Software requirements in Sphinx-Needs and create links to the imported System requirements. Finally, users can export all Software requirements from Sphinx-Needs to ReqIF format using reqif to-reqif command, which can then be imported back into the ALM tool, preserving the links between Software and System requirements.

Sphinx-Needs to ReqIF

Configuration Overview

The reqif to-reqif command uses a flexible configuration system to map Sphinx-Needs fields to ReqIF attributes. This allows adapting generated ReqIF files to different ALM tools.

The configuration consists of three main components:

  1. Path Settings: Where to find and store files

  2. Field Mappings: How Sphinx-Needs fields map to ReqIF attributes

Configurations can be provided in two ways:

  • TOML Configuration File: Define settings in a TOML file under the section [ubconnect.to_reqif]. 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 that mapping-related configurations can only be defined in the TOML file. Relative paths given as CLI arguments are resolved relative to the current working directory.

Basic Configuration

[ubconnect.to_reqif]
# --- Input/Output Paths ---
needsjson_path   = "./relative/path/to/need.json"   # Path to needs.json (relative to this TOML file)
outpath          = "."                              # Output .reqif(z) file path (optional)

# --- Specification Metadata ---
name             = "Custom Specification Name"      # ReqIFSpecification name (default: "Needs")
prefix           = "all"                            # Specification prefix (default: "all")
group_types      = false                            # Group by need types (default: false)
reqifz           = false                            # Export as .reqifz (default: false)

# --- Identification & Origin ---
uuid_source      = "reqif_uuid"                     # Source for the UUID of ReqIF Spec-Object (default: "reqif_uuid")
origin_field     = "origin"                         # Field to track the origin of the requirement (default: "origin")
alm_tool         = "codebeamer"                     # Target ALM tool: "doors" or "codebeamer" (default: "codebeamer")

# --- Advanced Features ---
weblink_pattern  = "https://docs.example.com/{docname}.html#{id}"
# Pattern for generating a weblink variable for each need (for use in templates)
 editlink_pattern = "https://github.com/org/repo/edit/main/{docname}.rst#L{lineno}"
 # Pattern for generating an editlink attribute for each need
 import_date      = true                            # Add an import_date field to each exported requirement (default: false)

 # --- Rendered HTML content export (optional) ---
 html_dir         = "./_build/html"                 # Root dir of Sphinx HTML build output; enables HTML content extraction
 target_image_dir = "images"                       # Directory name inside ReqIFz for embedded images (requires reqifz=true)

  • needsjson_path: Path to the needs.json file to consume as the input.

Note

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

  • outpath: The path to the output .reqif or .reqifz file (optional, defaults to needs.reqif(z) in the same directory as the TOML configuration file).

  • name: The long name of the ReqIFSpecification (optional, defaults to “Needs”).

  • prefix: The prefix for the ReqIfSpecification (default: “all”). If group_types is enabled, the value will be the Sphinx-Needs type name.

  • group_types: Group needs by their types into multiple ReqIfSpecifications if set to true; otherwise, all needs are grouped into a single ReqIfSpecification (default: false).

Note

prefix and group_types are related. If group_types is enabled, the prefix will be set to the Sphinx-Needs type name automatically. If group_types is disabled, the prefix can be specified to the preferred string.

  • reqifz: Export as .reqifz (zipped) if set to true; otherwise, export as plain XML file .reqif (default: false).

  • uuid_source: The source of the UUID for the ReqIF Spec-Object. It can be set to any Sphinx-Needs field name. If the specified field exists in a need, its value will be used as the UUID; otherwise, the need’s ID will be used as the identifier. This is useful to apply the preserved UUIDs to the generated ReqIF Spec-Object, as the requirements in the ReqIF file can be consistently identified across multiple import/export cycles.

  • origin_field: The field to track the origin of the requirement. It can be set to any Sphinx-Needs field name (default: “origin”). During conversion, if a need has this field defined and its value is External, the need will be considered as originating from an external source (e.g., an ALM tool such codebeamer or IBM Doors). Such needs will be treated as references and will not be exported to the ReqIF file. If a need does not have this field at all, it will be added and set to Sphinx-Needs automatically during the conversion.

    Note

    The value of this field is either Sphinx-Needs or External (case-insensitive) set by ubConnect.

  • alm_tool: The target ALM (Application Lifecycle Management) tool (default: “codebeamer”). Accepts either “doors” or “codebeamer”. Different ALM tools may require different field mappings and section configurations. This setting determines:

    • Default attribute mappings (e.g., title field mapping)

    • Default section configuration (section type and attributes)

    See ALM Tool Configuration for details on ALM-specific defaults.

  • weblink_pattern: (Optional) A URL pattern for generating a weblink jinja context variable for each exported need. The placeholders {docname}, {id} must be used. The pattern is rendered for each need and can be referenced in MiniJinja templates as the weblink variable.

  • editlink_pattern: (Optional) A URL pattern for generating an editlink field for each exported need. The placeholders {docname}, {lineno} must be used.

  • import_date: (Optional, default: false) If set to true, adds an import_date field to each exported requirement, containing the UTC timestamp of export.

  • html_dir: (Optional) Path to the Sphinx HTML build output directory. If set, ubConnect extracts the rendered HTML for each need’s content from <html_dir>/<docname>.html and exports it as ReqIF XHTML. This improves fidelity compared to plain text conversion.

    Note

    • html_dir requires the content mapping datatype to be xhtml.

    • html_dir cannot be used together with a template on the content field mapping.

  • target_image_dir: (Optional) Directory name for images inside the generated .reqifz archive. If set, ubConnect rewrites relative <img src> references in the extracted HTML and embeds the image files into the ReqIFz.

    Note

    target_image_dir requires both html_dir to be set and reqifz = true.

HTML Content Extraction (Sphinx HTML)

If you want to preserve rich formatting and images for the need content field, configure ubConnect to extract the already-rendered HTML from a Sphinx HTML build. This is controlled by html_dir and (optionally) target_image_dir.

How it works

  • For each exported need, ubConnect reads <html_dir>/<docname>.html and looks up the need table <table id="{need_id}">.

  • It extracts the content cell HTML (the row with class need content) and converts it to ReqIF-compliant XHTML.

  • If target_image_dir is set, relative <img src> paths are rewritten and the referenced image files are added as attachments to the .reqifz.

Limitations and fallbacks

  • Only the field mapped by the content mapping entry is extracted from HTML. Other XHTML fields (e.g., title) use the normal plain-text-to-XHTML conversion.

  • If a need has no docname or the rendered HTML cannot be found/parsed, ubConnect falls back to plain text conversion for that need’s content.

  • Image embedding requires reqifz = true. Plain .reqif files cannot contain attachments.

Example configuration

[ubconnect.to_reqif]
needsjson_path = "needs.json"
reqifz = true

# Extract rendered HTML content for the "content" field
html_dir = "./docs/_build/html"

# Embed referenced images into the ReqIFz under this directory
target_image_dir = "images"

ALM Tool Configuration

The alm_tool parameter allows you to specify the target Application Lifecycle Management (ALM) tool for the exported ReqIF file. Different ALM tools have different conventions for attribute names and hierarchical structures. ubConnect provides optimized defaults for each supported tool.

Supported ALM Tools

Codebeamer (alm_tool = "codebeamer")

Default configuration for Codebeamer ALM tool:

  • Title attribute: ReqIF.Name

  • Section type: Folder

  • Section attribute: ReqIF.Name (xhtml)

IBM DOORS (alm_tool = "doors")

Default configuration for IBM DOORS Classic/Next Generation:

  • Title attribute: ReqIF.ChapterName

  • Section type: Heading

  • Section attribute: ReqIF.ChapterName (xhtml)

Examples

For Codebeamer:

[ubconnect.to_reqif]
needsjson_path = "needs.json"
alm_tool = "codebeamer"      # Uses Codebeamer defaults

For IBM DOORS:

[ubconnect.to_reqif]
needsjson_path = "needs.json"
alm_tool = "doors"           # Uses DOORS defaults

The ALM tool setting affects both the default attribute mappings (see Mapping Configuration) and the default section configuration (see Section Configuration).

Mapping Configuration

When using the command reqif to-reqif, ubConnect converts Sphinx-Needs fields to ReqIF attribute names directly by default. However, some fields cannot be directly translated to ReqIF attributes for several reasons.

Data Type Compatibility Issues

Sphinx-Needs field data types are derived from JSON, such as boolean, string, int, and list. While ReqIF attributes support JSON-compatible data types, ReqIF also defines its own specific data types such as XHTML and Enum, which cannot be directly mapped from Sphinx-Needs fields.

ALM Tool Templates

ALM tools may require specific ReqIF attribute names to represent their internal fields. For example, CodeBeamer requires specific ReqIF attribute names to represent their internal fields such as ID and Type in their template called Requirement. If these fields are mapped directly, they may conflict with the ALM tool’s template.

Solution: Custom Mapping Configuration

Therefore, the mapping section defines how Sphinx-Needs fields are mapped to ReqIF attributes. Each mapping must be 1:1 (one Sphinx-Needs field maps to one ReqIF attribute). For convenience, some commonly used fields have been pre-defined by ubConnect. Those pre-defined mappings can be overridden by users as needed.

Configuration Structure

The following example shows how to customise mapping between Sphinx-Needs fields and ReqIF attributes:

[ubconnect.to_reqif.mapping.priority]
source_field = "priority"                 # Sphinx-Needs field to read from
target_attribute = "need_priority"        # ReqIF attribute to write to
datatype = "enum"                         # Data type in ReqIF

[ubconnect.to_reqif.mapping.result]
# source_field = "result"                 # Optional: Sphinx-Needs field to read from (defaults to the mapping key "result" if not provided)
target_attribute = "need_result"          # ReqIF attribute to write to
# datatype = "string"                     # Optional: Defaults to "string" if not provided

## pre-defined mappings by ubConnect ##
# [ubconnect.to_reqif.mapping.id]
# source_field = "id"
# target_attribute = "need_id"
# datatype = "string"

# [ubconnect.to_reqif.mapping.title]
# source_field = "title"
# target_attribute = "ReqIF.Name"
# datatype = "xhtml"

# [ubconnect.to_reqif.mapping.content]
# source_field = "content"
# target_attribute = "ReqIF.Text"
# datatype = "xhtml"

# [ubconnect.to_reqif.mapping.status]
# source_field = "status"
# target_attribute = "need_status"
# datatype = "enum"

# [ubconnect.to_reqif.mapping.type]
# source_field = "type"
# target_attribute = "need_type"
# datatype = "enum"

# [ubconnect.to_reqif.mapping.prefix]
# source_field = "prefix"
# target_attribute = "ReqIF.Prefix"
# datatype = "string"
## pre-defined mappings by ubConnect ##

Configuration Parameters

Each mapping configuration consists of three parameters:

  • source_field: Sphinx-Needs field name to read from (optional, defaults to the mapping key if not provided)

  • target_attribute: ReqIF attribute name to write to

  • datatype: Data type in ReqIF (optional, defaults to “string” if not provided)

  • template: (Optional) A MiniJinja template string for rendering the value of this attribute. The template can ONLY reference the source_field and the special variables weblink if its pattern is defined. Only supported for attributes with datatype xhtml. Please refer to the Example 5: Advanced Features – Template, Weblink/Editlink Pattern, and import_date for an example of how to use this parameter.

  • value_map: (Optional) A table that translates Sphinx-Needs field values to ReqIF attribute values before export. Only supported for datatype = "enum" or datatype = "string". Cannot be combined with template. See Value Map (Explicit Value Translation) for details and examples.

Supported Data Types

The datatype parameter can be one of the following ReqIF data types:

  • string: Plain text values (converts from Sphinx-Needs string or array types)

  • xhtml: Rich text with HTML formatting (converts from Sphinx-Needs string type)

  • enum: Enumerated values with automatic discovery (converts from Sphinx-Needs string type)

  • integer: Integer numeric values (converts from Sphinx-Needs integer type)

  • boolean: Boolean true/false values (converts from Sphinx-Needs boolean type)

  • real: Floating-point numeric values (converts from Sphinx-Needs number type)

  • date: Date values (converts from Sphinx-Needs string type)

Note

Automatic Enum Discovery: When using enum, ubConnect automatically discovers all unique values from the specified Sphinx-Needs field and creates corresponding SpecType and SpecEnumeration entries in the generated ReqIF file. When value_map is provided, the mapped values (the right-hand side of the table) become the ReqIF enum long-names instead, and auto-discovery is skipped entirely.

Note

Data Type Conversion: The mapping between ReqIF data types and Sphinx-Needs data types is validated during conversion. For example, when exporting from Sphinx-Needs to ReqIF, a field with number type will be converted to a ReqIF attribute with real datatype, preserving the numeric value.

Value Map (Explicit Value Translation)

The value_map table translates Sphinx-Needs field values to the values written into the ReqIF attribute. This is useful when:

  • The vocabulary used in Sphinx-Needs differs from what the target ALM tool expects.

  • You want to control exactly which enum values are defined in the generated ReqIF file and how they are named.

Supported datatypes: "enum" and "string" only. Using value_map with any other datatype (e.g. "xhtml", "integer") is an error. Combining value_map with template is also an error because template already composes the full value from scratch.

How it works

  • Keys are Sphinx-Needs field values (what appears in your needs.json).

  • Values are the strings written into the ReqIF attribute.

For datatype = "enum":

The right-hand side values become the ReqIF enum LONG-NAME entries. Only the values listed in value_map are registered as valid enum entries. If a need’s field value is not a key in value_map, that attribute is skipped for that need and a warning is emitted.

When value_map is absent, ubConnect falls back to automatic discovery: all unique values present in the needs data are registered as enum entries, using the original value string as the LONG-NAME.

For datatype = "string":

If the need’s field value is found as a key in value_map, the corresponding mapped string is written. If the value is not found in the map, the original value is written unchanged.

Configuration examples

Enum with explicit value mapping:

[ubconnect.to_reqif.mapping.priority]
source_field = "priority"
target_attribute = "Priority"
datatype = "enum"

[ubconnect.to_reqif.mapping.priority.value_map]
"high"   = "High Priority"
"medium" = "Medium Priority"
"low"    = "Low Priority"

Only high, medium, and low are registered as ReqIF enum values. Any need whose priority field contains a different value will have that attribute skipped with a warning.

String with value translation:

[ubconnect.to_reqif.mapping.status]
source_field = "status"
target_attribute = "Status"
datatype = "string"

[ubconnect.to_reqif.mapping.status.value_map]
"open"     = "In Progress"
"closed"   = "Done"
"deferred" = "On Hold"

Needs whose status is not listed (e.g. "draft") will have the original value "draft" written to the ReqIF attribute.

Enum without value_map (auto-discovery):

[ubconnect.to_reqif.mapping.priority]
source_field = "priority"
target_attribute = "Priority"
datatype = "enum"
# No value_map: ubConnect discovers all unique values from needs data
Validation rules

  • value_map is only valid for datatype = "enum" or datatype = "string".

  • value_map and template cannot be set on the same mapping entry.

  • All keys and values must be strings (TOML string type). Boolean values (e.g. true) are rejected at config parse time.

Pre-defined Mappings

ubConnect provides pre-defined mappings for commonly used fields that can be overridden as needed. The default mappings vary based on the selected alm_tool.

Default Field Mappings (Codebeamer)

Source Field

Target Attribute

Data Type

id

need_id

string

title

ReqIF.Name

xhtml

content

ReqIF.Text

xhtml

status

need_status

enum

type

need_type

enum

prefix

ReqIF.Prefix

string
Default Field Mappings (DOORS)

Source Field

Target Attribute

Data Type

id

need_id

string

title

ReqIF.ChapterName

xhtml

content

ReqIF.Text

xhtml

status

need_status

enum

type

need_type

enum

prefix

ReqIF.Prefix

string

Note

The main difference between Codebeamer and DOORS mappings is the title field: Codebeamer uses ReqIF.Name while DOORS uses ReqIF.ChapterName.

Section Configuration

ReqIF supports hierarchical structures through section objects (folders or headings). ubConnect can generate section spec-objects from the hierarchy information in your Sphinx-Needs data, using the sections and section_name fields.

Configuration Structure

The section configuration has two sub-fields:

[ubconnect.to_reqif.section]
type = "Folder"                              # The ReqIF spec-object-type name for sections

[[ubconnect.to_reqif.section.mappings]]
target_attribute = "ReqIF.Name"              # ReqIF attribute for section title
datatype = "xhtml"                           # Data type: "string" or "xhtml"

Configuration Parameters:

  • type: The name of the ReqIF spec-object-type used for section objects (e.g., “Heading”, “Folder”)

  • mappings: A list of attribute mappings for section objects. Each mapping contains:

    • target_attribute: The ReqIF attribute name to store the section title (required)

    • datatype: The data type for the attribute - only "string" or "xhtml" are supported (optional, defaults to “xhtml”)

Note

Section mappings only support "string" and "xhtml" datatypes. Other ReqIF datatypes (enum, integer, boolean, date, real) are not supported for section attributes.

ALM-Specific Defaults

If you don’t provide a section configuration, ubConnect uses ALM-specific defaults based on the alm_tool setting:

Codebeamer (alm_tool = "codebeamer")

[ubconnect.to_reqif.section]
type = "Folder"
[[ubconnect.to_reqif.section.mappings]]
target_attribute = "ReqIF.Name"
datatype = "xhtml"

IBM DOORS (alm_tool = "doors")

[ubconnect.to_reqif.section]
type = "Heading"
[[ubconnect.to_reqif.section.mappings]]
target_attribute = "ReqIF.ChapterName"
datatype = "xhtml"

How Sections Are Created

Sections are built from the sections and section_name fields in your needs data:

  • The sections field is an array of section names representing the hierarchy path

  • The last element of the sections array (sections[-1]) represents the top level of the hierarchy

  • The first element (sections[0]) represents the section closest to the need

  • The section_name field (if present) represents the need’s own section

Example Hierarchy:

{
  "REQ_001": {
    "id": "REQ_001",
    "title": "User Authentication",
    "sections": ["Security", "Requirements", "System"],
    "section_name": "Authentication"
  }
}

This creates the following hierarchy in ReqIF:

System                    # sections[-1] - Top level
└── Requirements          # sections[-2]
    └── Security          # sections[-3] or sections[0]
        └── Authentication  # section_name (if present)
            └── REQ_001     # The actual requirement

Custom Section Configuration

You can override the default section configuration:

[ubconnect.to_reqif]
needsjson_path = "needs.json"
alm_tool = "codebeamer"

# Custom section configuration
[ubconnect.to_reqif.section]
type = "CustomSection"                       # Custom section type name

[[ubconnect.to_reqif.section.mappings]]
target_attribute = "custom_section_attr"     # Custom attribute for section title
datatype = "string"                          # Use plain string instead of xhtml

Minimal Configuration

If you want to use ALM-specific defaults, you can omit the section configuration entirely:

[ubconnect.to_reqif]
needsjson_path = "needs.json"
alm_tool = "doors"      # Will automatically use DOORS section defaults

Partial Configuration

You can provide only the fields you want to customize, and ubConnect will use ALM-specific defaults for the rest:

[ubconnect.to_reqif]
alm_tool = "codebeamer"

# Only customize the section type, use ALM defaults for mappings
[ubconnect.to_reqif.section]
type = "CustomFolder"
# mappings will default to Codebeamer's: ReqIF.Name (xhtml)

Complete Export Configuration Examples

Example 1: Exporting to DOORS with Default Settings

[ubconnect.to_reqif]
needsjson_path = "needs.json"
outpath = "requirements.reqif"
name = "System Requirements"
alm_tool = "doors"

# DOORS-specific defaults are automatically applied:
# - Title maps to ReqIF.ChapterName
# - Sections use "Heading" type with ReqIF.ChapterName attribute

Example 2: Exporting to Codebeamer with Custom Mappings

[ubconnect.to_reqif]
needsjson_path = "needs.json"
outpath = "requirements.reqifz"
reqifz = true
alm_tool = "codebeamer"

# Custom field mappings (override defaults)
[ubconnect.to_reqif.mapping.priority]
source_field = "priority"
target_attribute = "CB_Priority"
datatype = "enum"

[ubconnect.to_reqif.mapping.assignee]
source_field = "assignee"
target_attribute = "CB_Assignee"
datatype = "string"

Example 3: Custom Section Configuration with DOORS

[ubconnect.to_reqif]
needsjson_path = "needs.json"
alm_tool = "doors"

# Override default DOORS section configuration
[ubconnect.to_reqif.section]
type = "CustomHeading"

[[ubconnect.to_reqif.section.mappings]]
target_attribute = "ReqIF.ChapterName"
datatype = "xhtml"

[[ubconnect.to_reqif.section.mappings]]
target_attribute = "Section_Description"
datatype = "string"

Example 4: Full Configuration with All Options

[ubconnect.to_reqif]
needsjson_path = "./data/needs.json"
outpath = "./output/requirements.reqifz"
name = "Software Requirements Specification"
prefix = "SW"
group_types = false
reqifz = true
uuid_source = "reqif_uuid"
origin_field = "origin"
alm_tool = "codebeamer"

# Section configuration
[ubconnect.to_reqif.section]
type = "Folder"

[[ubconnect.to_reqif.section.mappings]]
target_attribute = "ReqIF.Name"
datatype = "xhtml"

# Custom field mappings
[ubconnect.to_reqif.mapping.priority]
source_field = "priority"
target_attribute = "need_priority"
datatype = "enum"

[ubconnect.to_reqif.mapping.version]
source_field = "version"
target_attribute = "need_version"
datatype = "string"

[ubconnect.to_reqif.mapping.verified]
source_field = "verified"
target_attribute = "need_verified"
datatype = "boolean"

ReqIF to Sphinx-Needs

Configuration Overview

The reqif from-reqif command uses a flexible configuration system to map ReqIF attributes to Sphinx-Needs fields. This allows adapting to ReqIF files from different ALM tools.

The configuration consists of these main components:

  1. Path Settings: Where to find and store files

  2. Output Format: Choose between JSON or RST output

  3. Field Values: Applied values for all imported needs

  4. Attribute Mappings: How ReqIF attributes map to need fields

  5. Section Detection (optional): How headings/folders are detected and converted into hierarchy

All configuration can be defined in a TOML file under the section [ubconnect.from_reqif].

Attention

When using reqif from-reqif, make sure the id field is exported to ReqIF as defined in the to-reqif mapping configuration.

Basic Configuration

The basic configuration requires only one mandatory field:

Attention

All paths are relative to the location of the TOML configuration file.

[ubconnect.from_reqif]
reqif_path = "./relative/path/to/your.reqif"      # Optional: Relative to the location of this TOML file
reqifz = false
outdir = "./output"                               # Optional: Output directory for generated files
id_prefix = "REQ_"                                # Prefix for need IDs (default: "REQ_")
back_links = false                                # Optional: Enable/disable backlink generation (default: false)
uuid_target = "reqif_uuid"                        # Optional: The target field for the UUID of ReqIF Spec-Object (default: "reqif_uuid")
origin_field = "origin"                           # Optional: The field to track the origin of the requirement (default: "origin")
images_target_dir = "./_static/reqif_attachments" # Optional: Export ReqIFZ attachments (e.g., images) to this directory
images_ref_dir = "_static/reqif_attachments"      # Optional: Prefix used to rewrite XHTML <object data="..."> / <img src="..."> references
output_format = "json"                            # Optional: Output format "json" or "rst" (default: "json")

  • reqif_path: Path to the ReqIFZ/ReqIF file to import

Note

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

  • reqifz: Set to true if the provided file is a ReqIFZ (zipped) file; otherwise, set to false for plain XML ReqIF files (default: false).

  • outdir: Output directory for generated files (optional, defaults to the directory where the TOML configuration file is located). When a ReqIF file contains multiple specifications, ubConnect generates one file per specification.

    For example, if the ReqIF file contains two specifications named Spec_A and Spec_B, ubConnect generates two files in the specified output directory.

  • id_prefix: Prefix used for need IDs (defaults to REQ_). If a need ID already starts with the specified prefix, no additional prefix will be added. This helps avoid concatenation of the prefix multiple times when importing the same ReqIF file repeatedly.

  • back_links: Enable or disable backlinks generation (defaults to false). See Links Configuration for details. This option creates backward links automatically for each forward link defined in the ReqIF file. As Sphinx-Needs does not take backward links into account when importing needs.json, it is mainly for the user’s convenience.

  • uuid_target: The target field for the UUID of ReqIF Spec-Object. It can be set to any unused Sphinx-Needs field name (defaults to reqif_uuid). When importing, the UUID from the ReqIF Spec-Object will be preserved in the specified need field. This can be later used as the source for the UUID when exporting back to ReqIF using Configuration Overview. By doing so, the requirements in the ReqIF file can be consistently identified across multiple import/export cycles.

  • origin_field: The field to track the origin of the requirement. It can be set to any Sphinx-Needs field name (default: “origin”). During the conversion, if a requirement from the ReqIF file has this attribute defined and its value is Sphinx-Needs, the requirement will be considered as originating from Sphinx-Needs. In this case, the requirement with this field set to Sphinx-Needs will be ignored when exporting to needs.json. If a requirement does not have this attribute at all, it will be added and set to External automatically during the conversion.

    Note

    The value of this field is either Sphinx-Needs or External (case-insensitive) set by ubConnect.

  • output_format: The output format for the converted requirements (defaults to json). Supported values are:

    • json: Exports to needs.json files that can be imported using Sphinx-Needs needimport directive.

    • rst: Exports to RST files containing native Sphinx-Needs directives, eliminating the need for needimport.

RST Output Format

When output_format = "rst" is set, ubConnect generates RST files containing native Sphinx-Needs directives instead of JSON files. This provides several benefits:

  1. Git-friendly reviews: Each need can be in its own file, enabling clean diffs when requirements change.

  2. Build simplicity: Native RST without needimport indirection.

  3. Toctree integration: Generated files can be integrated into the Sphinx documentation tree.

[ubconnect.from_reqif]
reqif_path = "./requirements.reqif"
output_format = "rst"

[ubconnect.from_reqif.rst]
mode = "per_need"               # "single_file" | "per_section" | "per_need"
filename_pattern = "{id}.rst"   # {id}, {type}, {title_slug}, {uuid}, {section}
index_style = "toctree"         # "toctree" | "include"

[ubconnect.from_reqif.mapping.type]
source_attribute = "Type"

[ubconnect.from_reqif.mapping.type.value_map]
req  = "Functional Requirement"
spec = "SPECIFICATION"

RST Configuration Options:

  • mode: Controls how requirements are organized into files.

    • single_file: All requirements in a single RST file (default).

    • per_section: One file per ReqIF section/heading.

    • per_need: One file per requirement (best for git history/reviews).

  • filename_pattern: Pattern for generating filenames when using per_need mode. Supports placeholders: {id}, {type}, {title_slug}, {uuid}, {section}.

    Note

    • The filename_pattern is only applicable when mode is set to per_need.

    • The {section} placeholder is derived from the need item’s section_name field (if available) else root is used as the default value.

  • index_style: How to generate the index file when using per_section or per_need modes.

    • toctree: Generate a toctree directive (default).

    • include: Generate include directives.

Mapping with Value Translation

To translate ReqIF attribute values to Sphinx-Needs field values during import, use a structured mapping entry with source_attribute and value_map:

[ubconnect.from_reqif.mapping.type]
source_attribute = "Type"         # ReqIF attribute whose value is read

[ubconnect.from_reqif.mapping.type.value_map]
req  = "Functional Requirement"   # sn_value = reqif_value
spec = "SPECIFICATION"

The value_map table uses Sphinx-Needs values as keys and ReqIF values as values. At runtime, ubConnect looks up the incoming ReqIF value and writes the corresponding Sphinx-Needs value to the need field. Values not found in the map are written as-is.

When the mapped field is type, the Sphinx-Needs directive (e.g. .. req:: or .. spec::) is also updated accordingly.

Deprecated since version rst.type_mapping: The [ubconnect.from_reqif.rst.type_mapping] table is deprecated and will be removed in a future release. Use structured mapping entries with value_map instead (see above).

CLI Override:

The output format can also be specified via CLI:

ubconnect reqif from-reqif requirements.reqif --output-format rst --outdir ./docs/source/requirements

The following two options handle attachments (e.g., images) embedded in ReqIFZ files:

Note

Attachment export and XHTML rewriting only apply when importing a .reqifz (reqifz = true). Plain .reqif files do not contain attachments.

  • images_target_dir: If set and reqifz = true, ubConnect exports all ReqIFZ attachments (e.g., PNG files referenced via <object data=...> in XHTML) into this directory. The directory is created if it does not exist. If not set, attachments are not exported.

  • images_ref_dir: If set and ReqIFZ attachments are available, ubConnect rewrites XHTML references in imported rich-text fields. For example <object data="14973639-1.png"> becomes <object data="_static/reqif_attachments/14973639-1.png">.

Attachments and Images (ReqIFZ)

Some ALM tools embed images (and other binary assets) into .reqifz files as attachments and reference them inside rich-text fields via HTML/XHTML tags such as <object data="...">.

ubConnect supports this workflow with two separate configuration options:

  • images_target_dir (filesystem path): Where ubConnect writes the attachment files to disk. This is resolved relative to the TOML file location.

  • images_ref_dir (HTML path prefix): The prefix that ubConnect injects into rich-text HTML when rewriting references. This must match how your final rendered HTML can reach the exported files.

Example for a Sphinx documentation project

If your configuration file lives under docs/ within a Sphinx documentation project (or you otherwise want the attachments to be shipped with your docs), a common setup is:

conf.py
html_static_path = ['_static']
ubproject.toml
[ubconnect.from_reqif]
reqif_path = "./requirements.reqifz"
reqifz = true

# Write images into the Sphinx "_static" folder (so they get copied into the built HTML)
images_target_dir = "./source/_static/reqif_attachments"

# Reference them the same way Sphinx serves static assets in HTML output
images_ref_dir = "_static/reqif_attachments"
Notes

  • Rewriting only happens if the referenced filename matches an attachment name (exact match).

  • If you set images_ref_dir but not images_target_dir, ubConnect can rewrite references but will not export any files.

  • If you set images_target_dir but not images_ref_dir, ubConnect will export files but will keep the original data=... / src=... references unchanged.

Mapping Configuration

The mapping section defines how ReqIF attributes are mapped to Sphinx-Needs fields.

The 1:N mapping model is supported: a single ReqIF attribute can be mapped to multiple Sphinx-Needs fields simultaneously, but each Sphinx-Needs field can only receive values from one ReqIF attribute. With 1:N mapping, users can leverage needs_string_links to achieve Linking Back to the Original Source

Note

If multiple mapping entries target the same Sphinx-Needs field (case-insensitive), ubConnect raises an error during configuration validation.

Warning

Field names in the mapping must match the regex [A-Za-z0-9_-]+. Defining the same field in both mapping and static_fields is not allowed.

Configuration Structure

The following example shows a typical mapping configuration:

[ubconnect.from_reqif.mapping]
id = "ReqIF.ForeignID"                   # Maps to need ID (default: "ReqIF.ForeignID")
title = "ReqIF.Name"                     # Maps to need title (default: "ReqIF.Name")
content = "ReqIF.Text"                   # Maps to need content (default: "ReqIF.Text")
reqif_type = "Type"                      # Preserves the ReqIF item type (default: "Type")
# additional mappings
reqif_status = "Status"                  # Custom field example
reqif_resolution = "Resolution"          # Custom field example

Note

Some ALM tools export attributes under names that differ from the original field names. For example, CodeBeamer exports the item ID as ReqIF.ForeignID rather than ID. Always use the attribute name exactly as it appears in the ReqIF file.

Configuration Parameters

Mandatory mappings

The following fields are required for ubConnect to construct needs from the ReqIF file. All of them have default values and can be omitted if the defaults are appropriate.

  • id: ReqIF attribute name for the need ID (default: "ReqIF.ForeignID")

  • title: ReqIF attribute name for the need title (default: "ReqIF.Name")

  • content: ReqIF attribute name for the need content (default: "ReqIF.Text")

  • reqif_type: ReqIF attribute whose value is stored as the ReqIF item type in Sphinx-Needs (default: "Type")

Additional mappings

Any other key–value pairs in the mapping section are treated as additional mappings. They are not type-validated, giving full flexibility for project-specific custom fields.

Linking Back to the Original Source

A common use case is to preserve a clickable reference back to the original item in the source ALM tool so that readers of the Sphinx-Needs documentation can navigate to it directly.

Because needs.json stores plain data values, it cannot encode a rendered hyperlink on its own. Instead, the hyperlink must be constructed at documentation build time by Sphinx-Needs, using the needs_string_links configuration option. This option instructs Sphinx-Needs to match a stored field value against a regular expression and render the result as a clickable link.

The recommended approach is:

  1. Use the 1:N mapping capability to map the ReqIF attribute that carries the item identifier (e.g., ReqIF.ForeignID) to a dedicated Sphinx-Needs field (e.g., origin_link) in addition to the id field.

  2. Configure needs_string_links in conf.py to convert the stored identifier into a hyperlink pointing to the ALM tool.

The field name (origin_link in the examples below) is fully customisable – choose any name that is meaningful in your project.

conf.py

needs_string_links = {
    # Render a clickable link back to the originating Codebeamer item
    "origin_link": {
        "regex": r"^(?P<value>\w+)$",
        "link_url": "<your_codebeamer_url>/{{value}}",
        "link_name": "CodeBeamer item #{{value}}",
        "options": ["origin_link"],
    }
}

ubConnect TOML configuration

[ubconnect.from_reqif.mapping]
id = "ReqIF.ForeignID"              # Populates the need ID
origin_link = "ReqIF.ForeignID"     # Also stores the raw ID for hyperlink rendering

With this setup, the same ReqIF.ForeignID value is written to both the id field and the origin_link field. Sphinx-Needs then uses needs_string_links to render origin_link as a hyperlink in the generated documentation, pointing back to the original item in the ALM tool.

Static Fields Configuration

For need fields not mapped in Mapping Protocol, the static_fields section allows you to add fields and their values that will be applied to all needs created from the ReqIF file:

[ubconnect.from_reqif.static_fields]
type = "req"                             # Type of needs (default: "req")
# additional static_fields
priority = "high"                        # Another additional field example

Fields under static_fields:

Mandatory Fields

The following static fields are mandatory for ubConnect to apply the value for each need created from the ReqIF file. The type of these fields are validated by ubConnect.

Note

These static fields have default values if not provided

  • type: Sphinx-Needs Type assigned to all imported needs (defaults to “req”)

additional

Apart from the above-mentioned static fields, any others defined in the static_fields section are considered as additional static fields.

Note

The additional static field accepts any key-value pairs without type validation. This flexibility allows adding custom static fields, but users should ensure the values are appropriate for their use case.

Mapping vs. Static Fields — Precedence

When the same Sphinx-Needs field name appears in both mapping and static_fields, ubConnect raises a configuration validation error:

# ERROR: 'type' is defined in both mapping and static_fields
[ubconnect.from_reqif.mapping.type]
source_attribute = "Type"
[ubconnect.from_reqif.mapping.type.value_map]
req = "Functional Requirement"

[ubconnect.from_reqif.static_fields]
type = "req"                # conflict — validation error

The rule is: a field can only have one source. If it is in mapping, it is populated per-object from the ReqIF attribute (with optional value_map translation). If it is in static_fields, the same value is applied to every imported need.

Note

When you configure mapping.type, ubConnect automatically removes the default static_fields["type"] = "req" entry to avoid a conflict. You do not need to remove static_fields.type manually — it is only an error if you explicitly set it in the config alongside a mapping.type entry.

Section Detection (Hierarchy)

ReqIF specifications often contain hierarchical structures (sections/headings) represented by heading-like Spec-Objects.

ubConnect can preserve this hierarchy when importing to Sphinx-Needs.

To control how section nodes are detected (and to support parent items that have children), configure the optional section block under [ubconnect.from_reqif.section].

When enabled, ubConnect:

  • Detects section nodes while processing the ReqIF SPEC-HIERARCHY.

  • Stores hierarchy metadata in the resulting needs.json using the fields sections (list of ancestor section names) and section_name (name of the immediate section).

  • Renders nested RST directives for child needs into the parent’s content field.

Note

If [ubconnect.from_reqif.section] is not configured, ubConnect falls back to Mode 0:

  • No section detection is performed.

  • All relevant ReqIF spec-objects are imported as needs (requirement items), regardless of hierarchy or whether they have children.

  • The ReqIF SPEC-HIERARCHY is ignored entirely; no section metadata (sections, section_name) is computed or stored.

  • A warning is logged to indicate that no section configuration is present.

This means all spec-objects are emitted as flat needs, and any parent/child relationships or hierarchy information is lost. This is a change from previous versions, which would consider nodes with the children as parent nodes and only emit leaf nodes as needs.

If you want hierarchy from ReqIF and present them in nested needs without detecting headings/sections, use Mode 1 by configuring the section block appropriately. See Operating Modes for details.

In Mode 2, all non-section nodes are emitted as needs, including non-section nodes that have children (i.e., non-section parent nodes). These parent nodes are preserved and can contain nested requirements.

sections and section_name are stored in the exported JSON only when section detection is enabled. They are not emitted as directive options in the nested RST content.

If you want the section hierarchy to be visible in the generated RST (for example when importing via needimport), configure path_field. This adds an additional need field that is rendered as a directive option.

Configuration Parameters

The section configuration supports two detection modes:

  1. Type-name-based detection

    (default): Match the Spec-Object-Type LONG-NAME against type_value.

  2. Attribute-value-based detection

    Some ReqIF exports use a shared Spec-Object-Type for both headings and requirements, and encode the distinction in a dedicated attribute (for example Type). In that case, set type_attribute.

    [ubconnect.from_reqif.section]
type_value = "Folder"          # Required (together with name_attribute)
name_attribute = "ReqIF.Name"   # Required (together with type_value)

# Optional: enable attribute-value-based detection
# type_attribute = "Type"

  • type_value: The discriminator value that identifies a Spec-Object as a section node.

  • If type_attribute is empty, ubConnect compares type_value against the Spec-Object-Type

    LONG-NAME.

  • If type_attribute is set, ubConnect compares type_value against the value of the

    attribute named by type_attribute.

  • type_attribute: Optional. LONG-NAME of the ReqIF attribute whose value is used to detect

    section nodes (for example "Type").

  • name_attribute: LONG-NAME of the ReqIF attribute whose value becomes the section name.

  • path_field: Optional. Name of the need field to populate with the ancestor hierarchy path.

    • Format: outermost to innermost ancestor names, joined by " > " (space, >, space), for example "System > Subsystem A".

    • For needs that have no ancestors, the value is an empty string "".

    • Can be used standalone (without type_value or container_as_need). In Mode 0, the path is built from ancestor node titles in the ReqIF hierarchy tree — each spec-object is still emitted flat but carries its ancestor path in path_field.

    • When used with section detection (Modes 2/3), the path is built from detected section names.

    • The name used for each path segment follows this priority:

      1. name_attribute — if set in [section]

      2. mapping.title — fallback when name_attribute is not configured, or absent/empty on this node

      3. untitled-<spec-object-identifier> — fallback when both attributes above are absent/empty

    Note

    Choose a field name that does not conflict with other configured fields (for example origin_field, uuid_target, any keys in mapping/static_fields, or the internal hierarchy fields sections and section_name).

  • container_as_need: Optional boolean (default: false). When true, section/container nodes are emitted as needs rather than being discarded. This enables two new operating modes (see Operating Modes below).

    When container_as_need = true:

    • The need type of each container node is overridden to the value of type_for_need after static_fields have been applied.

    • For nodes that lack the configured mapping id attribute, the ReqIF Spec-Object IDENTIFIER (UUID) is used as a fallback for the need ID (prefixed with id_prefix).

  • type_for_need: Required when container_as_need = true. The Sphinx-Needs type assigned to emitted container needs (for example "req"). Must be a non-empty string and must not be set without container_as_need = true.

Operating Modes

The combination of type_value and container_as_need selects one of four operating modes:

Mode

type_value

container_as_need

Behaviour

0

not set

false (default)

All nodes emitted flat; no hierarchy metadata. A warning is logged.

1

not set

true

Nodes with children become container needs (structural detection). Leaf nodes are nested inside the nearest container.

2

set

false (default)

Section nodes are detected by type and discarded. Only non-section leaf nodes are emitted, with their nesting preserved.

3

set

true

Section nodes are detected by type and emitted as container needs.

Note

Mode 0 (no section config) is a legacy fallback. In previous releases, nodes with children were silently considered as sections/headings and discarded. Now all nodes are emitted flat and a warning is logged. Configure one of the other modes explicitly for predictable behaviour.

Setting path_field in Mode 0 populates each need with its ancestor path from the ReqIF hierarchy tree.

Examples

Type-name-based detection (Mode 2 — sections discarded)

Use this when headings/folders use a dedicated Spec-Object-Type (for example Spec-Object-Type LONG-NAME equals "Folder"):

[ubconnect.from_reqif.section]
type_value = "Folder"
name_attribute = "ReqIF.Name"
Attribute-value-based detection (Mode 2 — sections discarded)

Use this when headings and requirements share the same Spec-Object-Type and are distinguished by an attribute value (for example attribute Type equals "Folder" for headings):

[ubconnect.from_reqif.section]
type_value = "Folder"
type_attribute = "Type"
name_attribute = "ReqIF.Name"
Structural container detection (Mode 1)

Use this when every node that has children in the hierarchy should become a container need, regardless of its spec-object type. Section nodes do not need a dedicated type or attribute.

[ubconnect.from_reqif.section]
container_as_need = true
type_for_need = "section"

For nodes that lack the configured id mapping attribute (e.g. heading objects in tools that only give an ID to leaf requirements), ubConnect falls back to the ReqIF Spec-Object IDENTIFIER (UUID) prefixed with id_prefix.

Typed container detection (Mode 3)

Use this when section nodes should be emitted as needs and can be identified by type:

[ubconnect.from_reqif.section]
type_value = "Heading"
name_attribute = "ReqIF.Name"
container_as_need = true
type_for_need = "section"

# Alternatively, use attribute-based detection:
# type_attribute = "ItemType"
Section hierarchy path as a field (Modes 2/3)

To store the section hierarchy as a single string field on each need when using section detection, set path_field:

[ubconnect.from_reqif.section]
type_value = "Folder"
name_attribute = "ReqIF.Name"
path_field = "hierarchy_path"

For a requirement located under Root → SubFolder, ubConnect sets:

  • hierarchy_path = "Root > SubFolder"

Hierarchy path without section detection (Mode 0)

To track each node’s position in the ReqIF hierarchy without section detection, set only path_field:

[ubconnect.from_reqif.section]
path_field = "hierarchy_path"

In this mode, every spec-object is emitted as a flat need. The hierarchy_path field records the ancestor path derived from node titles in the ReqIF tree.

For a hierarchy Root → SubFolder → Requirement, ubConnect sets:

  • Root: hierarchy_path = "" (no ancestors)

  • SubFolder: hierarchy_path = "Root"

  • Requirement: hierarchy_path = "Root > SubFolder"

The name used for each path segment follows this priority:

  1. name_attribute — if set in [section]

  2. mapping.title — fallback when name_attribute is not configured, or absent/empty on this node

  3. untitled-<spec-object-identifier> — fallback when both attributes above are absent/empty

You can override the attribute used for path segment names without enabling section detection:

[ubconnect.from_reqif.section]
path_field = "hierarchy_path"
name_attribute = "ReqIF.ChapterName"

Note

When name_attribute differs from mapping.title, path segment names will differ from the need’s title field.

Complete Configuration Example

Here’s a complete configuration example showing all available options:

[ubconnect.from_reqif]
reqif_path = "./requirements.reqifz"
reqifz = true
outdir = "./docs/source"
id_prefix = "SYS_"
back_links = true
output_format = "rst"

[ubconnect.from_reqif.static_fields]
type = "requirement"
status = "new"

[ubconnect.from_reqif.section]
type_value = "Folder"
type_attribute = "Type"           # Optional; omit for type-name-based detection
name_attribute = "ReqIF.Name"
container_as_need = false         # Set to true to emit section nodes as needs (Mode 3)
# type_for_need = "section"       # Required when container_as_need = true

[ubconnect.from_reqif.mapping]
id = "ReqIF.ForeignID"
title = "ReqIF.Name"
content = "ReqIF.Text"
reqif_type = "Type"
reqif_status = "Status"

[ubconnect.from_reqif.mapping.type]
source_attribute = "Type"

[ubconnect.from_reqif.mapping.type.value_map]
req = "Functional Requirement"

[ubconnect.from_reqif.links]
links = ["<SpecRelationType1_ID>"]

[ubconnect.from_reqif.rst]
mode = "per_need"
filename_pattern = "{id}.rst"
index_style = "toctree"

Performance Diagnostics

For large datasets (10K+ needs), the to-reqif export may take several seconds. Use --verbose to see a per-phase timing breakdown:

ubconnect reqif to-reqif --config ubproject.toml --verbose

The output includes timing for each internal phase:

create_reqif_bundle timing:
  parse_need_items: 0.023s
  create_spec_objects: 0.821s
  build_hierarchy: 0.232s
  TOTAL: 1.175s
XML serialization: 0.223s

This helps identify which phase dominates the export time for your specific dataset.