Jira connector¶

Import Jira issues into a Sphinx-Needs needs.json file.

Note

The jira connector requires an active ubConnect license. See License configuration for activation instructions. The connector accepts the license via UBCONNECT_LICENSE_KEY / UBCONNECT_LICENSE_USER environment variables, the ubconnect.toml license file, or the --license-key / --license-user CLI options.

Quick start¶

Add a [ubconnect.from_jira] section to your ubproject.toml:

[ubconnect.from_jira]
url = "https://example.atlassian.net"
username = "alice@example.com"
password = "your-api-token"
project_key = "PROJ"
outdir = "./generated"

Then run:

$ ubconnect jira from-jira --config ubproject.toml

This produces ./generated/needs.json.

Authentication¶

The connector supports two auth modes via auth_type:

"basic" (default): Cloud uses the Atlassian email plus API token; Server / Data Center uses username plus password. username is required.
"bearer": Jira Data Center personal access token (PAT). Set auth_type = "bearer" and put the PAT in password; username is ignored.

Type mapping defaults¶

Standard Jira issue types map by default:

Jira type	Need type
Epic	`us`
Story	`req`
Task	`impl`
Bug	`risk`
Sub-task	`spec`

Anything else falls back to fallback_type (default "req") and emits one WARN per unique unmapped type. Override per project:

[ubconnect.from_jira.type_mapping]
"Test Case" = "spec"     # Xray / Zephyr plugin
"Spike" = "dec"

Field mapping defaults¶

Three Jira fields map by default:

Jira field	Need field
`summary`	`title`
`description`	`content`
`status`	`status`

Add more by extending [ubconnect.from_jira.mapping]:

[ubconnect.from_jira.mapping]
priority = "priority"
assignee = "assignee"
labels = "labels"

Audit extras¶

Every imported need carries:

jira_key (always): the original Jira issue key, e.g. "PROJ-12".
jira_url (always): a deeplink built from url and the issue key.
jira_parent_key (conditional): set when the issue has a parent, always present on Sub-tasks. For Story-to-Epic relationships, present only on modern Jira (Cloud Next-gen, Cloud Company-managed, Data Center / Server 8.x and newer). On older Cloud classic projects, Epic Link lives in a custom field; extend [ubconnect.from_jira.mapping] with the custom field id to capture it.

Link mapping¶

The connector ships no built-in link defaults because Jira link type names vary widely between teams. The short form (key on the left, target on the right) is intended for symmetric Jira link types where inward and outward carry the same label (for example “Relates”). For asymmetric types (Blocks, Cloners, Duplicate), use the long form (table) so both directions resolve correctly. Use the following starter preset:

# Always available on every Jira instance (default Atlassian link types)
[ubconnect.from_jira.link_mapping]
"is blocked by" = "blocks"          # Blocks link, inward direction
"is cloned by"  = "links"           # Cloners link, inward direction
"is duplicated by" = "links"        # Duplicate link, inward direction
"relates to"    = "links"           # Relates link (symmetric)

The block below is common but project-dependent; only enable it if your Jira instance actually defines these link types. Long form is recommended for asymmetric link types so both inward and outward labels resolve correctly:

# [ubconnect.from_jira.link_mapping.blocks]
# inward = "is blocked by"
# outward = "blocks"
# target = "blocks"
#
# [ubconnect.from_jira.link_mapping.cloned]
# inward = "is cloned by"
# outward = "clones"
# target = "links"
#
# [ubconnect.from_jira.link_mapping.duplicate]
# inward = "is duplicated by"
# outward = "duplicates"
# target = "links"

For full control, use the long form:

[ubconnect.from_jira.link_mapping.implements]
inward = "is implemented by"
outward = "implements"
target = "implements"

Markup conversion¶

The connector translates Jira description bodies to RST automatically:

Server / Data Center wiki markup to RST.
Cloud ADF (Atlassian Document Format) to RST.

The converter covers the common surface (paragraphs, headings, lists, code blocks, basic inline marks, links). Advanced ADF nodes (tables, panels, media) emit placeholders. Full-fidelity conversion via Pandoc is tracked separately.

Covered constructs (full conversion):

Paragraphs, headings, hard breaks, horizontal rules.
Bullet and ordered lists, list items.
Code blocks (with language hint).
Blockquotes.
Inline marks: bold, italic, code, links, strikethrough.

Placeholder constructs (rendered as RST notes / minimal directives):

Tables (single-row .. list-table:: placeholder; full conversion tracked separately).
Mentions, emoji, panels, expand / nested expand, media.

Unsupported constructs are aggregated and logged as a single WARN per unique node type at end of run. The original text content survives the conversion in all known cases; advanced layout features may render as plain text.

JQL filtering¶

For complex selection, use jql:

[ubconnect.from_jira]
project_key = "PROJ"
jql = 'fixVersion = "1.4.0" AND status != "Done"'

When constructing JQL programmatically (CI templates, scripted config generation), sanitize external inputs (branch names, ticket IDs) before splicing into the query. The connector does not escape JQL values.

Status normalization¶

Jira status values are free-form workflow states (“To Do”, “In Progress”, “Won’t Fix”, “Done”); the default mapping is direct passthrough. To pin status to a single value across imports use static_fields:

[ubconnect.from_jira.static_fields]
status = "open"

Visualizing imported issues¶

Once ubconnect jira from-jira has produced needs.json, dashboard directives in your Sphinx project can render the imported needs. Starting points:

A traceability table with a clickable deeplink back to Jira (the jira_url extra is added by the connector to every imported need):

.. needtable::
   :filter: "jira_key" in extras
   :columns: id, type, title, jira_key, status
   :style: table

A flow diagram over the imported issues and their links:

.. needflow::
   :filter: "jira_key" in extras
   :show_link_names:
   :alt: Imported Jira issues and their relations

For multi-component layouts (needpie / needbar / needgantt), reusable filter definitions, and color-scheme conventions, see the Creating Dashboards tutorial.

Configuration reference¶

All available fields:

Field	Default	Description
`url`	required	Jira base URL.
`username`	required for basic auth	Email (Cloud) or username (Server / Data Center).
`password`	required	API token, password, or personal access token.
`auth_type`	`"basic"`	One of `"basic"` or `"bearer"`.
`ssl_verify`	`true`	Disable for self-signed certificates.
`timeout_seconds`	unset	HTTP timeout (connect plus read).
`project_key`	XOR with `project_id`	Project key, e.g. `"PROJ"`.
`project_id`	XOR with `project_key`	Numeric project id.
`jql`	unset	Free-form JQL filter.
`issue_types_include`	unset	Whitelist of Jira issue types; XOR with `issue_types_exclude`.
`issue_types_exclude`	unset	Blacklist of Jira issue types; XOR with `issue_types_include`.
`mapping`	3 defaults	Jira field to Need field map.
`type_mapping`	5 defaults	Jira issue type to Need type map.
`fallback_type`	`"req"`	Used for unmapped Jira types.
`link_mapping`	`{}`	See above.
`static_fields`	`{}`	Values applied unconditionally to every emitted need.
`id_prefix`	`""`	Prepended to `Need.id`.
`on_error`	`"skip"`	Per-issue error policy.
`batch_size`	`100`	Capped at the Jira API limit of 100.
`retry_max_attempts`	`3`	Retries on HTTP 429 and 5xx responses.
`proxy`	unset	HTTP proxy URL.