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)

  • 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.

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.

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.

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.

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 three main components:

  1. Path Settings: Where to find and store files

  2. Field Values: Applied values for all imported needs

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

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

  • 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 JSON file per specification, named {specification_name}.json.

    For example, if the ReqIF file contains two specifications named Spec_A and Spec_B, ubConnect generates two files: Spec_A.json and Spec_B.json 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.

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

Depending on ALM tools, some ReqIF attributes may not have a direct mapping to Sphinx-Needs fields. Therefore, the mapping section defines how ReqIF attributes are mapped to Sphinx-Needs fields. Each mapping must be 1:1 (one ReqIF attribute maps to one need field):

Some attributes exported by ALM tools to ReqIF may not map directly to their original field names. For example, the ID attribute exported by CodeBeamer is exported as ReqIF.ForeignID in the ReqIF file instead of ID directly. In this case, the mapping should be defined as id = "ReqIF.ForeignID".

[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"                      # Maps to reqif type (default: "Type")
# additional mappings
reqif_status = "Status"                  # Additional mapping example
reqif_resolution = "Resolution"          # Another additional mapping example

Fields under mapping:

Mandatory mappings

The following mappings are mandatory for ubConnect to create needs from the ReqIF file. The type of these mappings are validated by ubConnect.

Note

These mappings have default values if not provided:

  • id: ReqIF attribute name for need ID (defaults to “ReqIF.ForeignID”)

  • title: ReqIF attribute name for need title (defaults to “ReqIF.Name”)

  • content: ReqIF attribute name for need content (defaults to “ReqIF.Text”)

  • reqif_type: The field to preserve the ReqIF item type in Sphinx-Needs (defaults to “Type”)

additional

Apart from the above-mentioned mappings, any other mappings defined in the mapping section for ReqIF attributes to Sphinx-Needs fields are considered as additional mappings.

Note

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

Static Fields Configuration

For need fields not mapped in Mapping Configuration, 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.

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

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

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

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