Jama Connect

Jama Connect is a platform enterprise tool used by engineering and product development teams for requirements management and traceability.

ubConnect integrates with Jama Connect to enable bidirectional synchronization of requirements between Sphinx-Needs and Jama Connect.

ubConnect supports two directions of Jama Connect integration with Sphinx-Needs:

  • Exporting Sphinx-Needs to Jama Connect using command jama to-jama

  • Importing from Jama Connect to Sphinx-Needs using command jama from-jama

Details for these commands can be found under Usage.

Round-Trip Synchronization

ubConnect aims to support round-trip synchronization between Sphinx-Needs and Jama Connect. This means that requirements can be exported from Sphinx-Needs to Jama Connect 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 synchronization is to link the requirements managed in Sphinx-Needs with Jama Connect instead of modifying the requirements on both sides. The modification of requirements shall be done in their corresponding tools, either Sphinx-Needs or the Jama Connect, depending on the defined single source of truth. To achieve this, ubConnect provides the configuration global_id 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 Jama Connect and it 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 Jama Connect in the Sphinx-Needs project.

In this case, users can convert the existing System requirements from Jama Connect into needs.json using the jama from-jama command then import into the Sphinx-Needs project. During this conversion, ubConnect records each requirement’s single source of truth in a dedicated field (global_id). This allows ubConnect to identify which requirements originated from Jama Connect when exporting back to Jama Connect 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 Jama Connect using jama to-jama command while preserving the links between Software and System requirements.

Sphinx-Needs to Jama Connect

Configuration Overview

The ubConnect jama to-jama command uses a flexible configuration system to enable Sphinx-Needs to Jama Connect integration.

The configuration consists of the following components:

  1. Jama Connect Settings: Connection details to the Jama Connect instance

  2. Path Settings: Where to find needs.json file

  3. Round-Trip & Relationship Settings: Options for round-trip sync and relationships

  4. Test Settings: Options for testing without making changes

  5. Field Mappings: How Sphinx-Needs fields map to Jama Connect fields

  6. Type Mappings: How Sphinx-Needs types map to Jama Connect item typeKeys

Configurations can be provided in two ways:

  • TOML Configuration File: Define settings in a TOML file under the section [ubconnect.to_jama]. Relative paths in the TOML file are resolved relative to the TOML file’s location.

  • CLI Arguments and Options: Specify some 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_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)

# Path to needs.json file (relative to this config file)
needsjson_path = "output_dir/needs.json"

# Default Jama item type ID for created items (optional)
item_type_id = 123456                                 # Check your Jama instance for available item types

# Relationship type ID for creating links between items
# Check your Jama instance for available relationship types
# relationship_type_id = 1

# Parent item ID under which to create new items (optional)
parent_item_id = 234567                               # Check your Jama instance for available items

# Enables round-trip sync with original Jama items
# When true, uses the :global_id: option from needs when creating items in Jama
track_global_id = true

# Skip creating relationships (useful for testing)
skip_relationships = true

# Dry run mode - simulate without making changes
dry_run = false

# Whether to create missing item types in Jama instance based on type_mapping values
create_missing_types = true

Fields under [ubconnect.to_jama]:

Jama Connect Settings:

  • url: The base URL of the Jama Connect instance.

  • username: The username or client ID for OAuth authentication.

  • password: The password or client secret for OAuth authentication.

  • project_id (integer): The Jama Connect project ID.

  • project_key (string): The key of the Jama Connect project to which items will be added. Alternative to project_id

  • oauth: Set to true to use OAuth for authentication; otherwise, use basic authentication (default: false).

Path Settings:

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

Round-Trip & Relationship Settings:

  • track_global_id: When set to true, ubConnect uses the global_id field of a need from Sphinx-Needs when creating items in Jama Connect. This allows tracking the original Jama item for round-trip synchronization (default: false).

  • relationship_type_id: The default Jama Connect relationship type ID used for creating links between items. This is optional.

  • item_type_id: The default Jama Connect item type ID to use when creating new items. This is optional.

  • parent_item_id: The Jama Connect item ID under which new items will be created. This is optional.

Important

  • Check your Jama Connect platform to ensure you are using the appropriate Jama Connect item IDs if you want to specify parent_item_id.

  • Check your Jama Connect platform to ensure you are using the appropriate Jama Connect item type ID if you want to specify item_type_id as the default type for created items.

  • Check your Jama Connect platform to ensure you are using the appropriate Jama Connect relationship type ID if you want to specify relationship_type_id for creating links between items.

Test Settings:

  • skip_relationships: When set to true, ubConnect will skip creating relationships between items. This is useful for testing purposes (default: false).

  • dry_run: When set to true, ubConnect will simulate the export process without making any changes in Jama Connect. This is useful for testing and verification (default: false).

Note

If both project_id and project_key are provided, project_id takes precedence.

Mapping Configuration

When using the command jama to-jama, ubConnect converts Sphinx-Needs fields to Jama Connect field names directly by default. However, you may want some fields to be directly translated to existing Jama Connect fields for several reasons.

ALM Tool Templates

Jama Connect may require specific field names to represent their internal fields. For example, the title field in Sphinx-Needs may need to be mapped to a specific field name in Jama Connect.

Solution: Custom Mapping Configuration

Therefore, the mapping section defines how Sphinx-Needs fields are mapped to Jama Connect fields. Each mapping must be 1:1 (one Sphinx-Needs field maps to one Jama Connect field). For convenience, some commonly used fields have been pre-defined by ubConnect. The 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 Jama Connect fields:

[ubconnect.to_jama.mapping]
title = "name"
content = "description"
status = "status"

Pre-defined Mappings

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

Default Field Mappings

Source Field

Target Field

id

id

title

title

content

content

status

status

Create Missing Item Types

When mapping Sphinx-Needs types to Jama Connect item typeKeys, you may encounter a situation where the specified item typeKey in the mapping does not exist in your Jama Connect instance.

To address this, ubConnect provides the configuration option create_missing_types.

When create_missing_types is set to true, ubConnect will automatically create any missing item types in your Jama Connect instance based on the typeKeys specified in your type mapping configuration. This ensures that all Sphinx-Needs types can be successfully mapped to corresponding Jama Connect item types, even if those item types do not currently exist in your Jama Connect instance.

Type Mapping Configuration

When using the command jama to-jama, ubConnect converts Sphinx-Needs types to Jama Connect type names directly by default. However, you may want some types to be directly translated to existing Jama Connect item types for several reasons.

ALM Tool Templates

Jama Connect may require specific item typeKeys to represent different types of items. For example, you may want Sphinx-Needs type req to be mapped to Jama Connect item typeKey CMP.

Solution: Custom Type Mapping Configuration

Therefore, the type_mapping section defines how Sphinx-Needs types are mapped to Jama Connect item types. Each mapping must be 1:1 (one Sphinx-Needs type maps to one Jama Connect item type).

Configuration Structure

The following example shows how to customise type mapping between Sphinx-Needs types and Jama Connect item types:

[ubconnect.to_jama.type_mapping]
req = "CMP"
spec = "STY"
test = "TC"
impl = "IMPL"

Important

  • Check your Jama Connect platform to ensure you are using the appropriate Jama Connect item typeKeys.

  • Check your Sphinx-Needs project to ensure you are using the appropriate Sphinx-Needs types for mapping.

  • You can also run ubconnect jama list-types to get all available item types from your Jama instance. See List available item types for details.

  • The item typeKeys specified in the type mapping must exist in your Jama Connect instance unless you have create_missing_types set to true, in which case ubConnect will create any missing item types based on the typeKeys specified in the mapping.

  • The type mapping is essential for ensuring that items created in Jama Connect have the correct item types corresponding to their Sphinx-Needs types, which is important for maintaining consistency and traceability between the two systems.

  • Explicitly list all required type mappings to prevent items from being ignored due to missing type mapping. If an item type in Sphinx-Needs does not have a corresponding mapping to a Jama Connect item type, ubConnect will ignore items of that type during export.

Jama Connect to Sphinx-Needs

Configuration Overview

The ubConnect jama from-jama command uses a flexible configuration system to enable Jama Connect to Sphinx-Needs integration.

The configuration consists of the following components:

  1. Jama Connect Settings: Connection details to the Jama Connect instance

  2. Path Settings: Where to store needs.json file

  3. Round-Trip & Relationship Settings: Options for round-trip sync and relationships

  4. Field Mappings: How Jama Connect fields map to Sphinx-Needs fields

  5. Type Mappings: How Jama Connect item typeKeys map to Sphinx-Needs types

Configurations can be provided in two ways:

  • TOML Configuration File: Define settings in a TOML file under the section [ubconnect.from_jama]. 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.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)

# 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

Fields under [ubconnect.from_jama]:

Jama Connect Settings:

  • url: The base URL of the Jama Connect instance.

  • username: The username or client ID for OAuth authentication.

  • password: The password or client secret for OAuth authentication.

  • project_id (integer): The Jama Connect project ID.

  • project_key (string): The key of the Jama Connect project to which items will be added. Alternative to project_id

  • oauth: Set to true to use OAuth for authentication; otherwise, use basic authentication (default: false).

Path Settings:

  • outdir: Path to the output directory where the needs.json file will be stored.

Round-Trip & Relationship Settings:

  • id_prefix: Prefix to be added to need IDs created from Jama Connect items.

  • include_relationships: When set to true, ubConnect will include relationships between Jama Connect items as links in the created needs.

  • item_type_filter: A list of Jama Connect item typeKeys to filter which items to import. Only items with these typeKeys will be imported. If not provided, all item types will be imported.

  • track_global_id: When set to true, ubConnect will store the Jama Connect globalId of each item as the global_id extra option in the created needs. This allows tracking the original Jama item for round-trip synchronization (default: false).

Note

If both project_id and project_key are provided, project_id takes precedence.

Mapping Configuration

When using the command jama from-jama, ubConnect converts Jama Connect field names to Sphinx-Needs fields directly by default. However, you may want some fields to be directly translated to existing Sphinx-Needs fields for several reasons.

Sphinx-Needs Templates

Jama Connect may use specific field names that do not align with Sphinx-Needs field names. For example, the documentKey field in Jama Connect may need to be mapped to the id field in Sphinx-Needs.

Solution: Custom Mapping Configuration

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

Configuration Structure

The following example shows how to customise mapping between Jama Connect fields and Sphinx-Needs fields:

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

Note

The documentKey parameter refers to the unique identifier for a Jama item. In the Jama Connect UI, this is displayed as “ID” (e.g., “PROJ-123”). When using the Jama REST API, this same field is called documentKey.

Example: If you see “ID: PROJ-456” in the Jama UI, the Jama REST API sets it as the documentKey.

Pre-defined Mappings

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

Default Field Mappings

Source Field

Target Field

id

documentKey

title

name

content

description

status

status

Type Mapping Configuration

When using the command jama from-jama, ubConnect converts Jama Connect types to Sphinx-Needs type names directly by default. However, you may want some types to be directly translated to existing Sphinx-Needs types for several reasons.

ALM Tool Templates

Jama Connect may use specific item typeKeys that do not align with Sphinx-Needs types. For example, you may want Jama Connect item typeKey REQ to be mapped to Sphinx-Needs type req.

Solution: Custom Type Mapping Configuration

Therefore, the type_mapping section defines how Jama Connect item types are mapped to Sphinx-Needs types. Each mapping must be 1:1 (one Jama Connect item type maps to one Sphinx-Needs type).

Configuration Structure

The following example shows how to customise type mapping between Jama Connect item types and Sphinx-Needs types:

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

Note

  • Check your Jama Connect platform to ensure you are using the appropriate Jama Connect item type.

  • You can also run ubconnect jama list-types to get all available item types from your Jama instance. See List available item types for details.

  • Check your Sphinx-Needs project to ensure you are using the appropriate Sphinx-Needs types for mapping.

Static Fields

ubConnect provides pre-defined static fields to add to all needs. If no type mapping is found, we fall back to the static fields type.

Default Static Fields

Type

Name

type

req

Utility Commands

In addition to import/export, ubConnect provides a couple of utility subcommands under ubconnect jama. These commands are helpful for validating credentials and discovering instance-wide metadata.

List available item types

Command: ubconnect jama list-types

Lists all item types available in the Jama instance. This is useful for finding valid Jama typeKey values for:

  • [ubconnect.from_jama] item_type_include, item_type_exclude, and item_type_filter

  • [ubconnect.to_jama.type_mapping] values

Note

Item types are instance-wide, not project-specific.

Authentication & Configuration

You can provide connection settings via:

  • CLI options --url, --username, --password (each also supports environment variables JAMA_URL, JAMA_USERNAME, JAMA_PASSWORD)

  • a TOML config file via --config

Note

  • When --config is used, the command reads credentials from [ubconnect.from_jama]. Any CLI options (or env vars) override values read from the config.

  • If your Jama instance requires OAuth, pass --oauth (or set oauth = true in the config).

Output formats

By default, the command prints a rich table. You can change the output format via the --format / -f option:

  • table (default): human-readable table

  • json: raw JSON array as returned by the Jama API

  • csv: columns id,typeKey,display,category

Examples

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

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

Check connection

Command: ubconnect jama check

Verifies that the provided credentials can authenticate successfully against the Jama instance. The command performs a lightweight API call (listing accessible projects) and reports the number of projects visible to the user.

Authentication & Configuration

Connection settings are provided the same way as for List available item types:

  • CLI options --url, --username, --password (also via env vars JAMA_URL, JAMA_USERNAME, JAMA_PASSWORD)

  • or --config (reads from [ubconnect.from_jama])

If your Jama instance requires OAuth, pass --oauth (or set oauth = true in the config).

Examples

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

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