Jira Cloud Plugin Documentation (depr)

1. Getting Started: Using the Adapter

1.1 Operations Overview

This section is intended to guide end users on how to operate the Jira Cloud Digital Thread Plugin once it has been properly installed and configured. If you haven’t completed these steps yet, please refer to those sections before proceeding.

The Jira Cloud DT Plugin is used to:

• Create links between Jira issues and items/objects present in external systems, which may include systems other than Jira.

• These links are then published to the SBE platform using the Jira Adapter, enabling centralized traceability and visibility across tools.

1.2 Accessing the Adapter

• The primary function of the plugin is to add a panel to Jira Issues that displays related models from the SBE instance and enables linking to these models.

• It also enables linking to the Models in SBE.

• After the installation, the plugin can be accessed from the Issue view page.

1.3 Attaching & Connecting

• Adding the Digital Thread panel on an Issue to show related Models on the Digital Thread.

• Enabling Linking to the Models in SBE.

Channel properties

The following valid combinations can be used:

Note: projectArea must always be provided. release and component can be optionally included in any combination.

1.4 Publishing Items

• All items within the Channel scope, including their plugin links, are published.

• Links to items outside the Channel scope are not published.

• The ASOT links stored inside Jira are published as Reflected links

1.5 Refreshing Items

• Refreshing the channel with links: Digital Thread links, other relations and properties remain intact and unchanged.

1.6 Verify

NA

1.7 Advanced Operations

• Add: Create new links from the SBE interface.

• Refresh: Update the link view by refreshing the panel in the web interface.

• Delete: Remove links that were previously saved in the Jira Server.

Project Settings → Apps → SBE Digital Thread,or you can directly acess it through sidebar as shown in fig [1.7.2 SBE Digital Thread (Delete Links)].

1.8 ASOT Link Creation

ASOT links are created when a relation points to an item that resides outside the current Jira channel or originates from a non-Jira authoritative system. Instead of generating a native Jira issue link, the adapter classifies such relations using the target item’s ownership metadata and records them as ASOT links to accurately represent cross-system dependencies. During processing, the adapter prevents duplicate ASOT links by validating against existing stored entries, which is essential because external systems often do not provide consistent correlation identifiers. Newly detected ASOT links are collected throughout the refresh cycle and persisted in a single batch to ensure consistency, reliability, and proper synchronization of external references across integrated systems.

• Jira to Jira ASOT Link creation

• This plugin supports Jira to Jira ASOT linking .ASOT Link created through one channel of Jira to another channel .

• ASOT link created through one channel of Jira to another channel.

• For creating ASOT link make sure the contex is available for the target item.

• Jira to non-jira(cameo,creo,windchill etc) ASOT Link creation

• Our plugin supports Jira to non Jira(cameo,creo,windchill,aras,etc) ASOT linking .ASOT Link created through one channel of Jira(source channel) to another non Jira channel(cameo,creo,windchill,aras,etc) which is target channel .

• ASOT link created through one channel of Jira to another channel.

• For creating the ASOT link make sure the context is available for the target item.If context is missing, then you are not able to see the link in the plugin if link is created through SBE, vice versa for the server.

This feature is available starting from version 8.x.

1.9 Troubleshooting for End Users

Links Not Visible in Kibana (on the Issue)

• This may occur if the apiUrl and apiToken are not configured properly.

• Please ensure both are set.

• Please verify link mappings.

Links Visible in Kibana, But Not in Authoring (Post-Process)

• In such cases, the reflected links may not have been transformed correctly.

• This typically indicates an issue during the link transformation phase.

Tracking Pipeline Does Not Finish

• One common reason is the presence of stale links.

What are stale links?

• Stale links are those created on a different SBE instance or stack.

• If the stack is reset or re-deployed, such links become invalid.

• It's important to clear old links from the plugin when resetting stacks.

Solution:
You can remove stale links from the Project Settings.

• Click on Clear all links, it will remove all stale links.

2. Document Overview

2.1 Document Overview

This states that the documentation provided is for the Jira plugin only. For general operation and configuration of the adapter, you should refer to the Jira Adapter documentation

2.2 Document Orientation

This document is designed to inform users with various roles:

• End Users should begin with Section 1 to understand how to access and operate the adapter, and Section 5 for issues pertaining to the setup, configuration, and use of the digital tool itself.

• Digital Thread Specialists should focus on Section 1, and also consult Sections 3, 4, and 5 for deployment and semantic mapping. Section 11 contains details related to mapping items from this tool into a semantic ontology.

• Administrators should refer to Section 6 and beyond for setup, security, support, and version management.

3. Adapter Use Cases

3.1 Adapter Overview

The purpose of this adapter is to allow the data contained within instances of Jira to connect with the SBE Digital Thread platform. The provided sources include an overview of the Jira plugin. It adds a Digital Thread panel on a Jira Issue and enables linking to SBE Models. This adapter was built using the SBE Java Pro-SDK product.

3.2 Typical Use Cases

• Why this adapter exists

• What problem it solves in the system development lifecycle

• reqs ↔ architecture with diff/merge in between

• Example: “Sync requirements from Tool A to Tool B”

• Step-by-step walkthroughs or diagrams

4. Supported Versions

4.1 Supported Adapter Products

• This document covers all the version of adapter that support SBE 7.x (Woburn)

4.2 External Tool Versions Supported

• Jira Cloud

4.3 Differences Across Tool Versions

NA

4.4 Supported Plug-Ins and Add-Ons

NA

5. Digital Tool Best Practices

5.1 Tool Configuration Considerations

• Generate the Jira Cloud Token, required for authentication

  • (Refer to Section 8.1 for detailed instructions).

• Set API URL and API Token for publishing links.

  • (Refer to Section 11.3 for detailed instructions).

• Configure additional settings such as link types and DT table fields.

  • (Refer to Section 6.2 for detailed instructions)

5.2 Usage Tips & Gotchas

Configuring Link Types

• Link types can be configured using a comma-separated list in the appropriate configuration field.

• Digital thread table columns can be configured using a comma-separated list which will be shown on the Digital Thread Plugin Panel.

• The configured types will appear as a dropdown menu on the Jira issue UI for selection.

How Links Are Created and Stored

1. User Action

   • The user creates a link using the SBE UI.

2. Automatic Subscription

   • SBE automatically creates a subscription for the selected channel.

3. Payload Transmission

   • The payload for the selected models is sent back to the Jira plugin.

4. Link Storage

   • The Jira plugin stores:

     • The issue key

     • The selected relation type

     • The model metadata

     • And any additional data returned from the SBE backend.

5. Publishing

   • When the user triggers Publish, the stored links are published.

5.3 Tool Limitations and Workarounds

• Known tool-side issues

• SBE-recommended solutions

6. Installation

6.1 Installation Instructions

• Create token for authentication (Refer to Section 8.1)

• Set up plugin configuration from admin page (Refer to Section 6.2)

• Generate token for internal and external APIs (Refer to Section 11.1)

6.2 Configuration

To use the Digital Thread plugin on Jira Cloud, it must be configured to connect to the appropriate SBE server. Follow these steps:

1. Navigate to Settings →Billing →Site settings →Connected Apps →SBE Digital Thread

2. In the three dots menu, Click on Configure.

3. Enter the SBE root URL (e.g., https://sbe.acme.com).

4. Configure Link Types using comma-separated values. These types will appear as a dropdown when linking issues to models.

5. To enable link publishing from Jira, configure the DT Internal API and its related token:

   • These values must be added to the SBE Datasource fields: apiUrl and apiToken

6.3 Data Source Type Definition

• Data source definition contains the following properties

7. Channels and Mappings

7.1 Channel Definition

7.2 Approaches to Mapping

• All shapes published from Jira are considered issues. The METACLASS used for these is always Issue.

• The exact Jira issue type (like Story, Epic, Task, Bug) is captured using a STEREOTYPE shape on top of the MetaClass.

  For example, to map an Epic:

  • Use Issue as the METACLASS .

  • Use Epic as the STEREOTYPE in the inherited ontology class.

• Map custom links to respective relations on the METACLASS.

The issue type is determined by this combination:

• shapeId = Issue, type = METACLASS

• shapeId = Story/Epic/etc., type = STEREOTYPE

Mapper Considerations

• Mappers must ensure that the required properties (summary, issueType, key, etc.) are correctly mapped for data to flow between systems.

• When customizing the mapping or modifying ontology classes, maintain the integrity of MetaClass and Stereotype structures to avoid type mismatches.

• Incorrect or missing stereotype mappings can cause subscription and sync failures.

8. Security and Access

8.1 Authentication Methods

Jira Cloud Authentication

Set Up cloud token

To publish from Jira Cloud, the user needs to use an API token as the password and their email ID as the username.

To generate an API token:

• Click on the Manage Account button from the top right user profile. This will take you to your profile page.

• Go to the Security page, and under the API token section, click on Create and manage API tokens.

• Click on the Create API token button to generate a new token. Make sure to save the token in a safe place, as it cannot be retrieved again once generated.

8.2 Authorization and Roles

• REST API access is enabled by default for all users on Jira.
  This means any authenticated user can perform standard API operations like GET and POST based on their Jira permissions.

• DELETE API calls are permission-restricted and depend on the user's role and project-level permissions.
  For example, an admin user typically has the required permissions to perform delete operations, while regular users may not.

Always ensure the user has appropriate Jira permissions before invoking operations that modify or delete data.

8.3 Secure Communication

• TLS configuration

• Firewall or VPN guidelines

8.4 Identity Integration

• LDAP, SSO, or identity federation

9. Troubleshooting

9.1 Known Issues

• Compatibility limitations

• Common operational issues

• Maximum item-size limitations

• Performance Issues

9.2 Logs and Diagnostics

• Where logs are located

• Enabling debug output

9.3 Common Misconfigurations

• Setup pitfalls

• Misuse scenarios

9.4 Escalation and Support

• How and when to contact SBE support

• Required logs or artifacts

10. Release Notes

10.1 Version History

Release Notes

7.0

• Save Issue Id on links

3.14.0

• Updated the Overview section in the documentation

3.13.0

• Bug fixes on link retrieval

3.12.0

• Save Issue Id on links

3.11.0

• SBE icon in issue panel

• Improve Web API performance

3.10.0

• Show more properties in Digital Thread Panel

• Woburn Upgrade Support

3.9.0

• Resolved embedded channels display issue

3.8.0

• Fix issue with link deletion

3.5.0

• Get Issue ID for web API

• Auto move storage

3.4.0

• Add new Web Trigger to get links saved in Jira

• Fix issue on Project admin screen

2.1.0

• Improve linking with Auto Subscriptions

• Support Migration of links

• Plugin version 3.2.0

2.0.0

• Store links in Jira

• Add Web trigger to get the saved links

• Admin option to create link types

1.2.0

• Fix login issue

• Use centralized config for all projects

1.1.0

• Fix styling on Plugin

• Updates to Admin page to show current settings

1.0.0

• First version of the plugin

• Support SBE Model linking

11. Technical Reference

11.1 Adapter API Endpoints

Internal API

INTERNAL ONLY:
This API is used exclusively by the Jira Adapter to retrieve stored DT links from Jira Cloud for further publishing to SBE.
It is not intended for public or external consumption.

Purpose

• The API fetches only existing links that are stored within Jira Cloud.

• The Jira Adapter consumes this response to publish those links to the SBE system.

Authentication Header Configuration

dt-api-key: <your-generated-token> 

To generate this token:

• Go to Settings → Manage Apps →Take me there →SBE Digital Thread →Configure

• Click "Generate Api Token" under the DT Internal API Access section.

Request Body

{
  "projectId": "PROJ-1"
}

projectId must be a valid Jira project key (e.g., "U4").

Sample API Response

Returns an array of Digital Thread link objects associated with the given project:

[
        "id": "97b9c870-4b79-48b3-ba52-2824b151c529",
        "targetName": "U4-352",
        "asotUri": "",
        "linkType": "Block",
        "targetFqn": "68762779309cc7467958e809.68762785309cc7467958e80b.68be811e0b950f2bba06f7da",
        "projectKey": "DEMO",
        "issueId": "10106",
        "issueKey": "DEMO-11",
        "channel": "79",
        "dataSourceType": "JIRA",
        "dataSource": "JIRA_SOURCE_1",
        "externalLocator": "{\"__sbe_type\":\"item\",\"__sbe_item_type\":\"Issue\",\"id\":\"35959\"}"
]

• Use the appropriate Jira Cloud Token depending on your environment.

  • (Refer to Section 8.1 for detailed instructions)

11.2 Identity

• Description of external locator or mechanism of identity

11.3 Configuration File Format Reference

Set up API Token and API URL

1. Generate API token for DT Internal API .

2. After setting up the plugin, you can create a data source using the DT Internal API for apiToken and url properties and create links directly from the issue.

11.4 Schema Support

• Link Schema

{
        "id": "97b9c870-4b79-48b3-ba52-2824b151c529",
        "targetName": "U4-352",
        "asotUri": "",
        "linkType": "Block",
        "targetFqn": "68762779309cc7467958e809.68762785309cc7467958e80b.68be811e0b950f2bba06f7da",
        "projectKey": "DEMO",
        "issueId": "10106",
        "issueKey": "DEMO-11",
        "channel": "79",
        "dataSourceType": "JIRA",
        "dataSource": "JIRA_SOURCE_1",
        "externalLocator": "{\"__sbe_type\":\"item\",\"__sbe_item_type\":\"Issue\",\"id\":\"35959\"}"
}

11.5 Glossary of Terms

• Common technical terms across tools/adapters

11.6 Compliance and Certification

• ITAR, DoD, or cybersecurity compliance info (if applicable)

• Adapter Maturity Model ratings

11.7 Migrate from SBE 7.x to SBE 8.x

This section will cover the guide to upgrade from your SBE 7.x to SBE 8.x

Back to top