IBM DOORS Next Generation (DNG)

Purpose

IBM DOORS Next Generation (DNG) is an enterprise requirements management platform.

The ubConnect DOORS NG connector is intended for bidirectional data exchange between DNG and Sphinx-Needs.

  • Today, it supports importing requirements from DNG via OSLC and exporting them into a Sphinx-Needs compatible needs.json file.

  • In the future, it is expected to support exporting/synchronizing Sphinx-Needs back to DNG.

Supported directions

  • DNG → Sphinx-Needs (implemented): ubconnect doors-ng from-doors-ng

  • Sphinx-Needs → DNG (planned): export/synchronization back to DNG (not implemented yet)

Limitations

  • Flattened view only: ubConnect currently imports artifacts as a flat list. DNG module hierarchy / document structure is not preserved.

  • No hierarchy reconstruction: A future version may translate module structure into Sphinx-Needs sections and/or parent-child relationships.

  • Links/relationships are not imported yet: Links between DNG artifacts (and the corresponding Sphinx-Needs links between needs) are not supported yet.

  • Sections are not yet modeled: The configuration key section_mapping exists, but it is currently only used as a hint to identify and skip section/heading artifacts.

Note

These limitations are expected to be resolved in future versions of ubConnect.

CLI usage

Import from DNG using a TOML configuration file:

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

Some connection and output settings can be overridden via CLI options (see Usage). Mapping-related settings must be configured in the TOML file.

Note

The DOORS NG connector requires an active ubConnect license. See License configuration.

Note

The Sphinx-Needs → DNG direction is planned, but there is no CLI/configuration for it yet.

DNG to Sphinx-Needs

This section documents the import direction DNG → Sphinx-Needs using ubconnect doors-ng from-doors-ng.

Configuration overview

The DOORS NG connector is configured under the TOML section:

  • [ubconnect.from_doors_ng.client]: connection and project selection

  • [ubconnect.from_doors_ng]: output settings and import behavior

  • [ubconnect.from_doors_ng.mapping.*]: field mapping rules

Configuration values support environment-variable expansion (e.g. ${DOORS_NG_USERNAME}). Relative paths (like outdir) are resolved relative to the TOML file location.

Basic configuration

[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_"

Note

If you do not define mapping, ubConnect applies a default mapping for id and title (Identifier → id, Name → title).

Default mapping behavior

ubConnect uses an internal default mapping (_DEFAULT_MAPPING) to ensure that a minimal Sphinx-Needs need can be created even when you do not provide a mapping section.

How it works:

  • During config initialization, ubConnect merges the default mapping with your configured [ubconnect.from_doors_ng.mapping.*] entries.

  • Your mapping entries take precedence over the defaults.

Default entries:

  • id: source_attribute = "Identifier" → target_field = "id"

  • title: source_attribute = "Name" → target_field = "title"

Examples:

  • If you do not configure any mapping, ubConnect will still generate needs with an id and title.

  • If you configure [ubconnect.from_doors_ng.mapping.title] yourself, your source_attribute overrides the default Name mapping.

Note

The default mapping is applied in addition to any configured mapping entries. It does not restrict you from mapping more fields (e.g. content, type, status).

All configuration options

Connection options ([ubconnect.from_doors_ng.client])

  • host (string, required)

    Base URL of the DNG server, e.g. https://localhost:9443.

  • ssl_verify (bool, default: true)

    Verify the server TLS certificate. Set to false only for self-signed certificates on local test servers.

  • username (string, required)

    DNG username. You can use ${DOORS_NG_USERNAME}.

  • password (string, required)

    DNG password. You can use ${DOORS_NG_PASSWORD}.

  • jts_context (string, default: "jts")

    JTS context root (rarely changed).

  • rm_context (string, default: "rm")

    RM application context root (rarely changed).

  • project (string, required)

    Project area name in DNG.

  • component (string, required)

    Component name within the project.

  • configuration (string, required)

    Configuration name (stream or baseline) within the component.

Import/output options ([ubconnect.from_doors_ng])

  • outdir (string/path, default: "output")

    Output directory for the generated needs.json.

  • id_prefix (string, default: "DOORS_")

    Prefix added to every generated Sphinx-Needs ID.

  • allowed_artifact_types (list[string], optional)

    Restricts which artifact types are fetched from DNG.

    • If omitted or empty, ubConnect fetches all artifact types.

    • If provided, only the specified artifact types are queried and converted.

    The values are human-readable DNG artifact type names (as shown by the DNG type system).

    Important

    ubConnect fails fast with a clear error message if:

    • a configured type name does not exist in the project, or

    • multiple DNG types share the same human-readable name (name collision).

  • mapping (table-of-tables, optional)

    Field mapping rules from DNG artifacts to Sphinx-Needs fields. See Mapping options ([ubconnect.from_doors_ng.mapping.<name>]).

  • section_mapping (table, optional)

    Reserved for future hierarchy support.

    Current behavior:

    • If set, artifacts whose resolved type name matches section_mapping.source_type are treated as section/heading artifacts and skipped.

    Fields:

    • source_type (string): artifact type name representing a section (e.g. "Heading")

    • source_attribute (string): reserved for future use

Mapping options ([ubconnect.from_doors_ng.mapping.<name>])

Mapping is a dictionary of entries keyed by an arbitrary logical name. Each entry describes how to read one DNG attribute and write it into one Sphinx-Needs field.

Each mapping entry supports:

  • source_attribute (string, required)

    Human-readable DNG attribute name.

    Common built-ins:

    • Identifier → resolves to OSLC dcterms:identifier

    • Title → resolves to OSLC dcterms:title

    • Name → resolves to OSLC rdfs:label (via the DNG type system)

    • Description → resolves to OSLC dcterms:description

    • Created → resolves to OSLC dcterms:created

    • Modified → resolves to OSLC dcterms:modified

    • Creator → resolves to OSLC dcterms:creator

    • Artifact Type → special alias that reads OSLC oslc:instanceShape and resolves it to a human-readable type name via the DNG type system

    Custom DNG attributes can also be resolved via the type system.

  • target_field (string, required)

    Target Sphinx-Needs field name (e.g. id, title, content, type, status).

  • value_map (table/dict, optional)

    Optional value transformation map, typically used for enumerations.

  • on_unmapped_value (string, optional; default: "error")

    Controls behavior when value_map is present but the source value is not a key.

    Allowed values:

    • "error": abort conversion with exit code 1

    • "skip": skip the artifact and log a warning; emit a summary at the end

    • "pass-through": keep the raw value as-is

Performance notes

DNG OSLC queries are extremely slow without an OSLC where clause. Selecting fewer fields (e.g. select=dcterms:identifier) does not avoid the server-side scan.

ubConnect therefore queries DNG per artifact type using indexed equality filters:

  • oslc.where = oslc:instanceShape=<shape_uri>

This is also why the connector requires a working DNG type system: it provides the mapping between type names and shape URIs.

Example configurations

Example 1: Minimal import (defaults)

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

Example 2: Fast import of selected artifact types

Use this when you only need a subset of types (faster, smaller needs.json):

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

Example 3: Mapping with enumeration conversion and unmapped handling

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

Example 4: Skipping section/heading artifacts (flat export)

If your DNG project contains headings/sections that you do not want in a flat export, configure section_mapping.source_type to match the artifact type name used for headings:

[ubconnect.from_doors_ng]
section_mapping = { source_type = "Heading" }

Sphinx-Needs to DNG

This direction is planned but not implemented yet.

Expected scope (future)

  • Export Sphinx-Needs needs into DNG artifacts

  • Optional synchronization workflows (e.g. single source of truth + linking)

  • Configurable field/type mapping similar to the import direction

Once implemented, this section will document the CLI command(s) and the TOML configuration for exporting/synchronizing data back to DNG.