ubConnect

https://ubconnect.useblocks.com/stable
Admin
ubConnect is a standalone tool that bridges ALM systems like DOORS, Polarion, Codebeamer, and Jama...
Tokens:19,433
Snippets:261
Trust Score:7.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Complete ReqIF Configuration Example

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

A comprehensive example demonstrating all available configuration options for ubConnect's ReqIF integration, including file paths, static fields, section settings, mapping, links, and output format.

```ini
[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 = "req"            # 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"

```

--------------------------------

### RST Example Output - Index File

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Shows the content of an index.rst file generated with 'toctree' style, listing root-level section files.

```rst
.. _coffee_machine_requirements_index:

Coffee Machine Requirements Index
=================================

.. toctree::
   :maxdepth: 2

   coffee_machine_example
   external_data

```

--------------------------------

### ReqIF Export to DOORS with Default Settings

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Example configuration for exporting to DOORS using default settings. This applies DOORS-specific defaults for title mapping and section configuration.

```toml
[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

```

--------------------------------

### Configure String Links for Origin URLs

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Define how to render specific fields as clickable hyperlinks. This example sets up a link back to a CodeBeamer item using its ID.

```python
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"],
    }
}

```

--------------------------------

### Full ReqIF Export Configuration Example

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

A comprehensive configuration for ReqIF export, including all options: file paths, naming, grouping, compression, UUID source, origin field, ALM tool, section configuration, and custom field mappings.

```toml
[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"

```

--------------------------------

### Example needs.json Input for ReqIF Export

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

This JSON structure represents the input data for the ReqIF export, including need details, schema, and versioning information.

```json
{
  "created": "2026-02-02T22:28:59.019642",
  "current_version": "1.0",
  "versions": {
    "1.0": {
      "needs": {
        "REQ_001": {
          "id": "REQ_001",
          "title": "Advanced Feature Requirement",
          "type": "req",
          "status": "open",
          "content": "The system shall support advanced features.",
          "docname": "requirements/advanced",
          "lineno": 42
        }
      },
      "needs_schema": {
        "properties": {
          "id": {"field_type": "core", "type": "string"},
          "title": {"field_type": "core", "type": "string"},
          "type": {"field_type": "core", "type": "string"},
          "status": {"field_type": "core", "type": "string"},
          "content": {"field_type": "core", "type": "string"},
          "docname": {"field_type": "core", "type": ["string", "null"]},
          "lineno": {"field_type": "core", "type": ["integer", "null"]}
        }
      }
    }
  }
}

```

--------------------------------

### RST Example Output - Per-Section Hierarchy

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Illustrates the RST output structure when 'per_section' mode is used, showing nested headings for section hierarchy and directive usage for needs.

```rst
.. _coffee_machine_example:

Coffee Machine Example
======================

*Source: Coffee Machine Requirements*

.. _software_architecture:

Software Architecture
---------------------

.. req:: Architecture Overview
   :id: REQ_SO_002
   ...

.. _implementation:

Implementation
--------------

.. _rust_interface_implementations:

Rust Interface Implementations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. req:: Rust Binding
   :id: REQ_SO_005
   ...

```

--------------------------------

### Configure Static Fields in ubConnect

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Set default values for Sphinx-Needs fields that are not present in the ReqIF file. This example sets a default 'type' and adds a 'priority' field.

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

```

--------------------------------

### Configure Sphinx-Needs to ReqIF Export

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure the `reqif to-reqif` command using a TOML file to map Sphinx-Needs fields to ReqIF attributes. This setup is essential for adapting generated ReqIF files to different ALM tools.

```toml
[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)

```

--------------------------------

### Basic TOML Configuration for Jama Integration

Source: https://ubconnect.useblocks.com/stable/features/jama.html

Defines essential settings for connecting to Jama Connect and specifying output paths. Ensure sensitive credentials like username and password are provided securely, for example, via environment variables.

```toml
[ubconnect.from_jama]
# Jama Connect connection settings
url = "https://your.jamacloud.com"                    # Jama Connect instance URL
username = "${JAMA_USERNAME}"                         # Jama Connect username or client id for OAuth.
password = "${JAMA_PASSWORD}"                         # Jama Connect password or client secret for OAuth.
project_key = "pky"                                   # Jama Connect project key (string). Alternative to project_id (integer).
oauth = true                                          # Use OAuth for authentication (default: false)
# ssl_verify = false                                   # Disable SSL verification for self-signed certificates (default: true)

# Directory path to store needs.json file (relative to this config file)
outdir = "output"

# Prefix for need IDs
id_prefix = "JAMA_"                                   # (e.g., "JAMA_PKY-REQ-001")

# Include relationships between items as links
include_relationships = true

# Filter items by type key (optional)
item_type_filter =  ['REQ', 'SPEC']

# Enables round-trip sync with original Jama items
track_global_id = true                                # Store Jama globalId as :global_id: extra option in needs

```

--------------------------------

### Map ReqIF Attributes in ubConnect

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure ubConnect's TOML file to map ReqIF attributes to Sphinx-Needs fields. This example maps the item ID to both the 'id' and 'origin_link' fields.

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

```

--------------------------------

### Minimal DNG Client and Import Configuration

Source: https://ubconnect.useblocks.com/stable/features/doors_ng.html

This configuration sets up the basic connection to a DNG server and specifies the output directory for imported data. It includes essential client details and default import settings.

```toml
[ubconnect.from_doors_ng.client]
host = "https://localhost:9443"
ssl_verify = false  # opt-in: disable only for self-signed dev server certificates
username = "${DOORS_NG_USERNAME}"
password = "${DOORS_NG_PASSWORD}"
jts_context = "jts"  # default
rm_context = "rm"    # default
project = "Test (Requirements)"
component = "Test (Requirements)"
configuration = "Test (Requirements) Initial Stream"

[ubconnect.from_doors_ng]
outdir = "./output"

```

--------------------------------

### Make Binaries Executable

Source: https://ubconnect.useblocks.com/stable/basics/installation.html

After downloading the ubConnect binary, use the `chmod +x` command to make it executable on Linux and macOS systems.

```bash
chmod +x ubconnect-linux-x64-0.16.0
chmod +x ubconnect-linux-arm64-0.16.0
chmod +x ubconnect-darwin-arm64-0.16.0
```

--------------------------------

### Configure Proxy Settings

Source: https://ubconnect.useblocks.com/stable/basics/ublicense.html

Add this section to `ubconnect.toml` to specify an HTTP CONNECT proxy if system proxies are not detected or fail. Replace `<proxy-domain-or-ip>` with your proxy server details.

```toml
[proxy]
https = "<proxy-domain-or-ip>"

```

--------------------------------

### Run DNG Import Command

Source: https://ubconnect.useblocks.com/stable/features/doors_ng.html

Execute the ubConnect DNG import command using a TOML configuration file. Some settings can be overridden via CLI options.

```bash
rye run ubconnect doors-ng from-doors-ng --config ubproject.toml

```

--------------------------------

### Configure Section Hierarchy Path (Modes 2/3)

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Set `path_field` to store the section hierarchy as a single string field on each need when using section detection. This example shows configuration for 'Folder' type sections.

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

```

--------------------------------

### Configure Online License

Source: https://ubconnect.useblocks.com/stable/basics/ublicense.html

Place this TOML configuration in `ubconnect.toml` to set your license key and user email for online activation. Ensure the file is in the correct directory for your operating system.

```toml
[license]
key = "AAAAA-BBBBB-CCCCC-DDDDD"
user = "mail@example.com"

```

--------------------------------

### Basic DNG Connector Configuration

Source: https://ubconnect.useblocks.com/stable/features/doors_ng.html

Configure the DOORS NG connector for client connection and output settings. Supports environment variable expansion for sensitive values.

```toml
[ubconnect.from_doors_ng.client]
host = "https://localhost:9443"
ssl_verify = false  # opt-in: disable only for self-signed dev server certificates
username = "${DOORS_NG_USERNAME}"
password = "${DOORS_NG_PASSWORD}"
jts_context = "jts"  # default
rm_context = "rm"    # default
project = "Test (Requirements)"
component = "Test (Requirements)"
configuration = "Test (Requirements) Initial Stream"

[ubconnect.from_doors_ng]
outdir = "./output"
id_prefix = "DOORS_"

```

--------------------------------

### Fast Import of Selected Artifact Types

Source: https://ubconnect.useblocks.com/stable/features/doors_ng.html

Use this configuration when you only need a subset of artifact types for a faster and smaller `needs.json` import. Ensure connection details and desired artifact types are correctly specified.

```toml
[ubconnect.from_doors_ng.client]
host = "https://localhost:9443"
username = "${DOORS_NG_USERNAME}"
password = "${DOORS_NG_PASSWORD}"
jts_context = "jts"  # default
rm_context = "rm"    # default
project = "Test (Requirements)"
component = "Test (Requirements)"
configuration = "Test (Requirements) Initial Stream"

[ubconnect.from_doors_ng]
outdir = "./output"
id_prefix = "DOORS_"
allowed_artifact_types = ["User Requirement", "System Requirement", "Standard"]

```

--------------------------------

### Configure ReqIF Import

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Use this TOML configuration to specify the path to your ReqIF file, output directory, and other import settings. All paths are relative to the TOML file's location.

```toml
[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")

```

--------------------------------

### TOML Configuration for CSV Import

Source: https://ubconnect.useblocks.com/stable/features/csv.html

Configure the `csv from-csv` command using a TOML file. Settings include input file path, output directory, ID prefix, delimiters, and field mappings. Relative paths in the TOML file are resolved relative to the TOML file's location.

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

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

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

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

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


```

--------------------------------

### List Jama Item Types with URL and Credentials

Source: https://ubconnect.useblocks.com/stable/features/jama.html

List all item types available in a Jama instance using the command line. Provide connection details via URL, username, and password.

```bash
ubconnect jama list-types --url https://your.jamacloud.com \
   --username "$JAMA_USERNAME" --password "$JAMA_PASSWORD"

```

--------------------------------

### Basic ReqIF Export Configuration

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure ubConnect to export needs to a ReqIFz file, extracting rendered HTML content and embedding images.

```ini
[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"

```

--------------------------------

### Minimal ReqIF Export Configuration

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

A minimal configuration to use ALM-specific defaults for ReqIF export. Omitting section configuration allows ubConnect to apply tool defaults.

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

```

--------------------------------

### Configure Offline License

Source: https://ubconnect.useblocks.com/stable/basics/ublicense.html

Use this TOML configuration for offline licenses. The `file` property points to the license file, and `user` is still required. The `key` property is not needed for offline licenses.

```toml
[license]
file = "ActivationFile.skm"
user = "mail@example.com"

```

--------------------------------

### Configure RST Output Format

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Set the output format to 'rst' and configure specific RST generation options like mode and filename pattern.

```ini
[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"

```

--------------------------------

### ReqIF Import CLI Override

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Override the output format and directory for ReqIF imports directly from the command line.

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

```

--------------------------------

### IBM DOORS ReqIF Export Configuration

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure ubConnect for ReqIF export with default settings optimized for IBM DOORS.

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

```

--------------------------------

### Sphinx Configuration for Attachments

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure Sphinx to handle static files, which is necessary for serving exported ReqIF attachments.

```python
html_static_path = ['_static']

```

--------------------------------

### List Jama Item Types with Config File and JSON Output

Source: https://ubconnect.useblocks.com/stable/features/jama.html

List all item types available in a Jama instance using a configuration file and specify JSON as the output format.

```bash
ubconnect jama list-types --config ubproject.toml --format json

```

--------------------------------

### Check Jama Connection with Config File and OAuth

Source: https://ubconnect.useblocks.com/stable/features/jama.html

Verify Jama instance credentials using a configuration file and OAuth authentication.

```bash
ubconnect jama check --config ubproject.toml --oauth

```

--------------------------------

### Enable Verbose REQIF Export

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Use the `--verbose` flag with the `to-reqif` command to enable detailed timing breakdowns for each phase of the export process. This is useful for diagnosing performance issues with large datasets.

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

```

--------------------------------

### Structural Container Detection (Mode 1)

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure this when any node with children should become a container need, regardless of its type. Requires `container_as_need = true` and `type_for_need` to be set.

```ini
[ubconnect.from_reqif.section]
container_as_need = true
type_for_need = "req"

```

--------------------------------

### Configure ReqIF Export with Advanced Features

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Use this TOML configuration to enable advanced ReqIF export features like custom weblink/editlink patterns, import dates, and content templating with MiniJinja.

```toml
[ubconnect.to_reqif]
needsjson_path = "needs.json"
outpath = "needs.reqif"
name = "Advanced Features Test"
weblink_pattern = "https://docs.example.com/{docname}.html#{id}"
editlink_pattern = "https://github.com/org/repo/edit/main/{docname}.rst#L{lineno}"
import_date = true

[ubconnect.to_reqif.mapping.content]
source_field = "content"
target_attribute = "ReqIF.Text"
datatype = "xhtml"
template = "{{'The original need is from' ~ weblink ~ 'Its content is the following:' ~ content }}"

```

--------------------------------

### Configure Jama Connect Connection Settings

Source: https://ubconnect.useblocks.com/stable/features/jama.html

Defines connection details for your Jama Connect instance within a TOML configuration file for the `ubconnect.to_jama` section. Ensure sensitive credentials like username and password are provided securely, potentially via environment variables.

```toml
[ubconnect.to_jama]
# Jama Connect connection settings
url = "https://your.jamacloud.com"                    # Jama Connect instance URL
username = "${JAMA_USERNAME}"                         # Jama Connect username or client id for OAuth.
password = "${JAMA_PASSWORD}"                         # Jama Connect password or client secret for OAuth.
project_key = "pky"                                   # Jama Connect project key (string). Alternative to project_id (integer).
oauth = true                                          # Use OAuth for authentication (default: false)

```

--------------------------------

### ubConnect Configuration for ReqIF Attachments

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure ubConnect to export and reference attachments from ReqIFZ files. 'images_target_dir' specifies where to save attachments, and 'images_ref_dir' sets the HTML path prefix for references.

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

```

--------------------------------

### Codebeamer ReqIF Export Configuration

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure ubConnect for ReqIF export with default settings optimized for Codebeamer.

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

```

--------------------------------

### Configure Hierarchy Path (Mode 0)

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

To track each node’s position in the ReqIF hierarchy without section detection, set only `path_field`. Every spec-object is emitted as a flat need, with `hierarchy_path` recording the ancestor path.

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

```

--------------------------------

### Configure CSV Export Settings

Source: https://ubconnect.useblocks.com/stable/features/csv.html

Set up the export of Sphinx-Needs data to a CSV file. Specify paths, delimiters, encoding, and link handling. Relative paths are resolved relative to the TOML file's location.

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

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

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

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

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

```

--------------------------------

### Configure ReqIF Links

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Map Sphinx-Needs link fields to ReqIF SpecRelationType IDs. This allows ubConnect to populate Sphinx-Needs link fields based on SpecRelations defined in the ReqIF file.

```ini
[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

```

--------------------------------

### Configure Jama Connect Export Settings

Source: https://ubconnect.useblocks.com/stable/features/jama.html

Set various parameters for exporting data to Jama Connect, such as SSL verification, input file paths, and default item types.

```toml
ssl_verify = false
needsjson_path = "output_dir/needs.json"
item_type_id = 123456
parent_item_id = 234567
track_global_id = true
skip_relationships = true
dry_run = false
create_missing_types = true
create_picklist_option = true
```

--------------------------------

### Configure CSV Import Field Mapping

Source: https://ubconnect.useblocks.com/stable/features/csv.html

Define how CSV column headers map to Sphinx-Needs fields for importing data. Ensure CSV headers match the specified values.

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

```

--------------------------------

### Configure Section Detection (Mode 3)

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Use this configuration when section nodes should be emitted as needs and can be identified by type. It specifies the type value, name attribute, and enables container-as-need functionality.

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

# Alternatively, use attribute-based detection:
# type_attribute = "ItemType"

```

--------------------------------

### String Mapping with Value Translation

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure a string mapping with value translations. If a source value is not found in the map, the original value will be used.

```toml
[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"

```

--------------------------------

### Mapping with Enumeration Conversion and Unmapped Handling

Source: https://ubconnect.useblocks.com/stable/features/doors_ng.html

Configure custom mappings for specific fields, including converting enumeration values and defining how unmapped values should be handled. This allows for flexible data transformation during import.

```toml
[ubconnect.from_doors_ng.client]
host = "https://localhost:9443"
username = "${DOORS_NG_USERNAME}"
password = "${DOORS_NG_PASSWORD}"
jts_context = "jts"  # default
rm_context = "rm"    # default
project = "Test (Requirements)"
component = "Test (Requirements)"
configuration = "Test (Requirements) Initial Stream"

[ubconnect.from_doors_ng]
outdir = "./output"
id_prefix = "DOORS_"

[ubconnect.from_doors_ng.mapping.id]
source_attribute = "Identifier"
target_field = "id"

[ubconnect.from_doors_ng.mapping.title]
source_attribute = "Name"
target_field = "title"

[ubconnect.from_doors_ng.mapping.type]
source_attribute = "Artifact Type"
target_field = "type"
on_unmapped_value = "pass-through"

[ubconnect.from_doors_ng.mapping.type.value_map]
"User Requirement" = "req"
"System Requirement" = "spec"

```

--------------------------------

### Configure ReqIF Section Detection

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Enables hierarchical section detection from ReqIF SPEC-HIERARCHY. This configuration is required to preserve section metadata and structure in the imported needs.

```ini
[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
```

--------------------------------

### Check Jama Connection with URL and Credentials

Source: https://ubconnect.useblocks.com/stable/features/jama.html

Verify Jama instance credentials by performing a lightweight API call. Provide connection details via URL, username, and password.

```bash
ubconnect jama check --url https://your.jamacloud.com \
   --username "$JAMA_USERNAME" --password "$JAMA_PASSWORD"

```

--------------------------------

### Configure ReqIF Type Mapping and Static Fields

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Defines how ReqIF attributes map to ubConnect fields and sets static values. Avoids conflicts by ensuring a field is sourced from either mapping or static fields, not both.

```ini
[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
```

--------------------------------

### REQIF Export Phase Timing Breakdown

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

The verbose output provides timing information for internal phases such as parsing need items, creating specification objects, and building the hierarchy. This helps pinpoint which part of the export process is taking the longest.

```text
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

```

--------------------------------

### Type-Name Based Section Detection (Mode 2)

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure this when your ReqIF headings use a dedicated Spec-Object-Type. Sections are discarded in this mode.

```ini
[ubconnect.from_reqif.section]
type_value = "Folder"
name_attribute = "ReqIF.Name"

```

--------------------------------

### Custom Section Configuration for ReqIF Export

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configures custom section types and attribute mappings for ReqIF export. Use this to override default section handling for specific ALM tools.

```toml
[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

```

--------------------------------

### Configure Jama Type Mappings

Source: https://ubconnect.useblocks.com/stable/features/jama.html

Customize the mapping between Jama Connect item types and Sphinx-Needs types. Each mapping must be one-to-one.

```toml
[ubconnect.from_jama.type_mapping]
IMPL = "impl"
STY = "spec"
CMP = "req"
TC = "test"

```

--------------------------------

### Enum Mapping with Auto-Discovery

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Configure an enum mapping without an explicit value map. ubConnect will automatically discover all unique values from the needs data.

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

```

--------------------------------

### Custom Section Configuration with DOORS

Source: https://ubconnect.useblocks.com/stable/features/reqif.html

Overrides default DOORS section configuration for ReqIF export. Specifies a custom section type and custom mappings for section attributes.

```toml
[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"

```

--------------------------------

### Configure Jama Field Mappings

Source: https://ubconnect.useblocks.com/stable/features/jama.html

Customize the mapping between Jama Connect fields and Sphinx-Needs fields by defining the mapping in the TOML configuration file.

```toml
[ubconnect.from_jama.mapping]
id = "documentKey"
title = "name"
content = "description"
status = "status"

```
Tokens:
Raw