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.

The main purpose of the round-trip conversion is to link the requirements managed in Sphinx-Needs with external ALM tools that support ReqIF.

For example, a typical scenario could be:

System requirements are defined and managed in an ALM tool that supports ReqIF import/export.
Software requirements are defined and managed in Sphinx-Needs within the project’s documentation.
Users want to link Software requirements in Sphinx-Needs to System requirements in the ALM tool.

In this case, users can export the existing System requirements from the ALM tool to ReqIF format, then convert them into needs.json, the data format to be imported into Sphinx-Needs project, by using reqif from-reqif command.

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:

Path Settings: Where to find and store files
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]
needsjson_path = "./relative/path/to/need.json"  # Optional: Path relative to this TOML file
outpath = "."                                    # Optional: Output .reqif(z) file path
name = "Custom Specification Name"               # Optional: ReqIFSpecification name (default: "Needs")
prefix = "all"                                   # Optional: Specification prefix (default: "all")
group_types = false                              # Optional: Group by need types (default: false)
reqifz = false                                   # Optional: Export as .reqifz (default: false)
uuid_source = "reqif_uuid"                       # Optional: The source for the UUID of ReqIF Spec-Object (default: "reqif_uuid")

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.

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)

Supported Data Types¶

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

string: Plain text values
xhtml: Rich text with HTML formatting
enum: Enumerated values with automatic discovery

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.

Pre-defined Mappings¶

ubConnect provides pre-defined mappings for commonly used fields that can be overridden as needed:

Default Field Mappings¶
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`

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:

Path Settings: Where to find and store files
Field Values: Applied values for all imported needs
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")

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_)
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.

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.

Links Configuration¶

In ReqIF, the links between requirements are represented as SpecRelations. There are no direct ReqIF attributes that could serve as link field names in Sphinx-Needs. Therefore, ubConnect provides the mappings between Sphinx-Needs link fields and ID of SpecRelationType. By doing so, the corresponding Sphinx-Needs link fields are populated based on the SpecRelations defined in the ReqIF file.

[ubconnect.from_reqif.links]
tests = ["SpecRelationType1_ID"]           # Map SpecRelations typed by SpecRelationType1 to 'tests' field
depends_on = ["SpecRelationType2_ID"]      # Map SpecRelations typed by SpecRelationType2 to 'depends_on' field
implements = ["SpecRelationType3_ID"]      # Map SpecRelations typed by SpecRelationType3 to 'implements' field

Link Field Mappings

Each key in the links section represents a Sphinx-Needs link field name, and the value is a list of SpecRelationType IDs from the ReqIF file. When a SpecRelation with one of these types is found, a link will be created in the corresponding Sphinx-Needs field.

Back Links Generation

When back_links = true is set in the main configuration, ubConnect automatically generates backward links for each forward link. The backward link field name is created by appending _back to the original field name.

For example: - If a forward link is created in the depends_on field from Requirement A to Requirement B - A backward link will be automatically created in the depends_on_back field from Requirement B to Requirement A

Note

IDs of SpecRelationType: These IDs can be found in the ReqIF file’s SpecRelationType elements. Different ALM tools may use different naming conventions for these IDs.

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>"]