Jira Software Integration

This section provides an overview of how to configure the integration between Jira Software and LeanIX

Install the App

In Jira Software, go to Marketplace Apps and search for "LeanIX Jira Integration" or access this link directly.

❗️

Important

The LeanIX plugin is supported for Jira Software for Cloud only.

📘

Jira administrator access required

Installing Atlassian Apps can only be done by Jira admins. If you want to install the LeanIX Jira Integration please get in touch with your admin.

The current version of LeanIX-Jira Integration is only available for the Atlassian Jira Cloud.

Setup the integration

After installing the integration you will need to configure the connection to the LeanIX workspace. The following picture shows the button that will take you to the integration configuration

2090

The integration needs to be connected to a LeanIX workspace. In order to configure the integration, you need to provide the below information:

  • Host: Check the browser URL (e.g. app.leanix.net)
  • Workspace name: LeanIX workspace name
  • API token: Can be created using Technical User (Recommended to use Admin role)
974

📘

API Token and Permission

We recommend creating a technical user with an Admin role for the Integration.
All the changes done in LeanIX workspace will be reflected as being done by the user linked to the API Token provided (Technical user in case a token provided by Technical user is used)

📘

Only 1-1 mapping of LeanIX Workspace to Jira Account

Only one LeanIX workspace can be connected to one Jira account. One Jira account can entail more than one project.

Link Jira Issue to LeanIX Fact Sheets

With this integration, you are able to link any Fact Sheet to Jira issues. To do so:

  1. Open an existing Jira issue in one of your Jira Projects
  2. Click on the LeanIX Fact Sheet symbol on the right-hand side in the Glance view
  3. Click the button "Link a Fact Sheet"
  4. Type the name of the Fact Sheet you would like to link the issue to
  5. Click on the Fact Sheet you would like to link the issue to
  6. After the linking process is finished, you will see the Fact Sheet under "Linked Fact Sheets" in Jira

After you linked a Fact Sheet you will be able to track the synchronized Jira issue name, status, and assignee in the "Resources" tab of the respective Fact Sheet in LeanIX.

You can unlink a Fact Sheet from an issue in the Glance view by clicking on the “unlink" icon, which removes the Jira resource from the Fact Sheet.

See the Jira Issue in a LeanIX Fact Sheet

After linking a Jira issue to a LeanIX Fact Sheet, you can see the linked Jira issue's details under the "Resources" tab in LeanIX.

Create Synchronization Mappings

Synchronization Mappings allow the synchronization between the meta-models of Jira and LeanIX. Each Fact Sheet type can be synced to a Jira Issue type. Once a Fact Sheet is paired with a Jira Issue type, it cannot be synced with another Jira issue type. A Jira issue type on the other hand can be synced with multiple Fact Sheet types.
Currently only the text fields of Fact Sheets can be synchronized (e.g., name, description, alias, etc. )

To create a project Synchronization Mappings:

  1. Go to the Synchronization Mappings UI in the top navigation bar “Apps > LeanIX Synchronization Mappings”
  2. Click on the "Add project" button
  3. Type in the name of the project to be synchronized and select it
  4. Click on the + "Add" button to create a new Fact Sheet Type and issue type synchronization
  5. Workspace

In the Add-Type synchronization dialog:

  1. Select the Fact Sheet type (e.g., Project)
  2. Select the issue type (e.g., Epic)
  3. Click “Add Field Mapping”
  4. Select the LeanIX field (e.g., Name)
  5. Select the direction (e.g., Bidirectional)
  6. Select the Jira Issue Type (e.g., Summary)

Repeat this procedure for all the fields that you want to be synchronized and finally click the “Add” button. The synchronized Fact Sheet type will appear in the Synchronization Mappings list. The details of the Synchronization Mappings can be displayed by clicking on the extend arrow.

The Synchronization Mappings can also be deleted by clicking on the "delete" button. This operation will remove all the existing synchronized Fact Sheet from the issues. It can’t be undone, so you must confirm the delete operation with the following dialog.

📘

Only Admins can create Synchronization Mappings.

Synchronize Jira Issues and LeanIX Fact Sheets

Once you created the Synchronization Mappings for a certain project, you are able to sync the Fact Sheet type defined in the Synchronization Mappings to a corresponding Jira issue type. To do so:

  1. Open the Glance view
  2. Click on the "Sync a Fact Sheet" button
  3. Type the name of the Fact Sheet you would like to sync to the issue
  4. Select the Fact Sheet you would like to sync to the issue
  5. After the sync process is finished, you will see the synced Fact Sheet under "Synced Fact Sheet"

When you sync a Fact Sheet, you will be able to track the Jira issue name, status, and assignee in the "Resources" tab of the respective Fact Sheet in LeanIX.

You can un-sync a Fact Sheet from an issue in the Glance view by hovering over the item in the list and clicking on the “unlink icon” that appears or by removing the Jira Issue listed in the "Resource" tab of the respective Fact Sheet.

Create a Fact Sheet from Jira

During the linking or syncing operations, you can create new LeanIX Fact Sheets on the fly in Jira. As a result of the creation operation, the Fact Sheet will be synced or linked to the issue accordingly.

  1. Type the name of the new Fact Sheet in the selection and click on "+ Create new My Fact Sheet name"
  2. The text typed into the search will be filled in as the field Fact Sheet name automatically and the selected type selected as the Fact Sheet type, in case there are constraints (i.e., there is a SyncMap defined for this Issue Type)
  3. Click on "Save"

As a result, the newly created Fact Sheet will appear in the list of synced or linked Fact Sheet.

Search for Fact Sheets in Jira Advanced Search using JQL

The integration adds some properties to the Jira issues that allow filtering on them using JQL. The properties you can use with the integration are:

  • factSheetCount
  • linkedFactSheetCount
  • syncedFactSheetCount
  • syncFactSheetId
  • syncFactSheetType

You can use these properties in JQL queries to extract specific information, as shown in following examples.

Query PurposeJQL Statement
Find out which issues are synchronized with Fact Sheets of the type 'Epic' in the project 'Rocket'project = "Rocket" AND syncFactSheetType = Epic
Identify issues that have at least one Fact Sheet linked in the project 'Rocket'project = "Rocket" AND linkedFactSheetCount > 0