Using Spira with Jira Cloud¶

Overview¶

Teams can work seamlessly using both Spira and Jira Cloud, using Inflectra's Jira Cloud data sync engine to keep key information in sync between both applications.

Real world example

The QA team uses Spira for requirements and test management.
When the QA team finds bugs during testing incidents are created in Spira, and then sync to Jira
The Dev team manages the bug in Jira, with changes reflected back in Spira

This data syncs can sync the follow information (what exactly syncs and is user configurable and discussed more below)

Jira artifact	Spira artifact
Project	Product
Users	Users
Versions	Releases
Issues	Incidents and Requirements
Sub-tasks	Tasks
Comments	Comments
Attachments	Documents

The table below shows a summary of how data is synced from/to Spira and Jira Cloud. The Jira datasync gives you three different syncing modes, depending on your workflows and needs.

Artifact	Type of Change	Default	Bidirectional	NoRequirements	NoIncidents
releases	new	Jira Spira	Jira Spira	Jira Spira	Jira Spira
requirements	new	Jira Spira	Jira Spira	(no syncing)	Jira Spira
	updates	Jira Spira	Jira Spira	(no syncing)	Jira Spira
incidents	new	Jira Spira	Jira Spira	Jira Spira	(no syncing)
	updates	Jira Spira	Jira Spira	Jira Spira	(no syncing)
tasks	new	Jira Spira	Jira Spira	Jira Spira	Jira Spira
	updates	Jira Spira	Jira Spira	Jira Spira	Jira Spira

Notes about syncing:

The default sync mode is the best for when the dev team uses Jira, and the QA team uses Spira. Devs in Jira create and manage requirements/user stories, so these sync one-way to Spira. Spira users can see incidents created in Jira, but bugs reported by QA can be see in Jira. After bug creation, Jira users are in charge of updates, which sync back to Spira.
The bidirectional sync mode is similar to default, except that incident fully sync both ways - for new incidents/issues, and their updates.
The NoRequirements sync mode is for when Spira is used to create new incidents and tasks, but Jira is used as the system where incidents and tasks are updated.
The NoIncidents sync mode is for when you want to mainly sync requirements (or tasks) between Spira and Jira, but not incidents. In the other modes, incidents are the default artifact that syncs, but this mode sets requirements to be the default artifact. This means all the Jira Issue types will sync against Requirements or Tasks (if Task Types are configured).
Users are not synced - instead Jira users are mapped to existing Spira users, wherever possible.
Comments are always synced from Spira and to Spira.
Spira artifact tags sync as Jira labels and vice-versa, in the way supported by the sync mode
Attachments are created in the other system when new artifacts/issues are created. Attachments are not created or changed during updates. Optionally, you can turn off the sync of attachments between the systems adding an extra parameter to the field Sync Mode.
If you are syncing requirements, the hierarchy is not synced due to the fundamental differences in how this functions in Jira and Spira
If you have two separated Jira instances to sync from/to, please follow these instructions to set up a second DataSync plugin without data duplication

Checklist¶

For the data sync to work correctly make sure you meet all of the steps below:

Use Spira v6.3.0.1+
Use Jira Cloud (we have a separate data sync for Jira Server / DataCenter)
Setup a datasync service - either in Inflectra's cloud or on your own servers
Download the Jira configuration helper application
Configure the plugin in Spira
Configure system wide user mapping

Then, for each product you want to sync:

Activate the datasync
Configure release mappings
Configure standard field data mappings
Configure custom field data mappings

Configure the Plugin¶

Make sure you have setup a datasync service before going further

Login to Spira as a system administrator
Go to System Administration > Integrations > Data Synchronization

Find the plugin called JiraDataSync and click the "Edit" button to open the settings page

What do if the plugin is not there

If you don't see the plug-in in the list, click the ""Add" button at the top of the page. This opens the generic Data Sync plug-in details page. This is not yet customized to help you more easily set up the data sync. We recommend, adding just enough information now to create the plug-in. Then edit the plug-in after its made to complete the process.

To start, fill in the following fields:

Name: enter "JiraDataSync" exactly
Connection Info: enter the the full URL to the Jira instance (see "Jira URL" below)
Login: enter your Atlassian cloud login

Now click "Add" to save the plug-in and return you to the list of plug-ins. Now follow the instructions below.

You need to fill in the following fields for the plugin to operate correctly:

Name: (leave this as JiraDataSync)
Caption: this is the plugin's display name. Put something like "Jira" or leave it blank. If you have multiple Jira instances, you will need a separate plugin for each one. Each plugin needs the same name so use the caption field to make it clear each one is different
Description: this is an optional field you can use to help describe to your future self the setup and use of the plugin
Jira URL: enter the full URL of the Jira instance to connect with (make sure to include any custom port numbers). Entering this URL into a web browser should bring up the Jira login page and is typically of the form: https://mycompany.atlassian.net
Jira Login: enter a valid login to the Jira instance that has permissions to create and view Jira issues and versions. Typically this is your Atlassian email address.
Jira API Key: enter the API Key (not password) for the Atlassian login you are using

Time Offset: normally this should be set to zero, but if you find that issues being changed in Jira are not being updated in Spira (especially if comments are not syncing), try increasing the value as this will tell the data-synchronization plug-in to add on the time offset (in hours) when comparing date-time stamps. Also Jira is on a server set to a different time-zone, you should add in the number of hours difference between the servers time-zones here.
Auto-Map Users: This changes the way that the plugin maps users between Spira and Jira. Set to yes to auto-map users, or no to manually map users. See [below]

In normal use, keep the fields below blank

For most users, we recommend leaving these fields blank: "Jira Custom Fields"; "Task Types"; and "Sync Mode". Leave "Requirement Types" blank if you do not want sync user stories/requirements (not valid for the NoIncidents mode).

Jira Custom Fields: This is used to specify the value(s) for Spira Incident Severity and/or Requirement Estimate Points based on Jira custom properties . Please enter the Jira custom property IDs separated by a comma. Both fields are optional, but if you want to skip one, please enter it as 0. This can be left empty for now and will be discussed below in Configuring the Data Mapping.
Task Types: This should be set to a comma-separated list of IDs of any Jira issue types that you want to be synchronized with Spira tasks instead of incidents. If you leave this blank, tasks in Spira will not be synched with Jira at all.
Sync Mode: This determines how the synchronization works. How each mode works is explained above:
- Default (leave blank): recommended for most users.
- Bidirectional: enter the word "Bidirectional" to use this mode. Recommended for advanced users only. Only use this mode if you have a well-defined set of workflows that make sense in both systems, and that do not conflict. If using this mode make the polling interval as short as possible (to avoid conflicting changes in the two systems) as the integration works at the record-level, not the field level.
- NoRequirements: enter the word "NoRequirements" to use this mode
- NoIncidents: enter the word "NoIncidents" to use this mode
Optionally, you can avoid the sync of attachments between the systems by adding the extra sync option NoAttachments to the sync mode field. Example: NoRequirements,NoAttachments or simply NoAttachments if you use the default mode
Requirement Types: This should be set to a comma-separated list of IDs of any Jira issue types that you want to be synchronized with Spira requirements instead of incidents. If you leave this blank, all Jira issue types will be synchronized with incidents (user stories/epics will not be synced at all). This field is ignored when using the sync mode "noIncidents", as Requirements are the main artifact of this mode.
Link Type: This field should either be set to the name of a Jira issue link type or be left blank. If you want the datasync to create links between Jira issues, based off of existing associations between Spira incidents and/or requirements, then enter in an issue link type name. If you do not want Jira to create these links between issues based off data in Spira, then leave this field blank. The artifact associations from Spira will sync to Jira as links of that type. All the link types from Jira will sync to Spira as 'Related-to'. You can get the list of issue link types from the following screen in Jira:

User Mapping¶

The datasync does not create users itself. Instead, it maps existing users in Spira to existing users in Jira, where it can. These mappings mean that the datasync will correctly show who is, for example, assigned to an incident, if that field was updated from Jira during the datasync.

User mapping has two different modes: auto-mapping users; and manual user mapping.

Set the "auto-map" field describe above to yes to use auto-mapping. In this mode, all users in Spira need to have the same username as users in Jira. This is a big time-saver but only works if you can guarantee that all usernames are the same in both systems.

If you are not auto mapping users (the field is set to no in the plugin configuration) follow these steps:

Login as a system admin
Go to Administration > Users > View Edit Users to show the list of users
For each user you want to manually map to a Jira user:
- Click the "Edit" on that user's row:
- Click the "Data Mapping" tab at the bottom to list see the list of datasync plugins you can set for this user.
- Enter a valid Jira identifier for that user In the text box called "Jira ID" (see below)
- Click "Save"

User Profile in Spira

User Data Mapping Tab in Spira

Valid Jira user identifiers

Email Address: use the email address of the user as it is used in Jira. This will only work if the user's profile is set to public and that the profile's email address visibility set to Anyone in Jira:

Atlassian AccountID: you can always use this value - it does not matter if the user's profile is public or private.

User Data Mapping Tab in Spira using Account ID

Product Configuration¶

Now that the datasync and user mapping has been setup system wide, you are ready to configure the datasync at the product level. This is an important and necessary part of the process. It tells the datasync what products to sync with, what to sync it with in Jira, and how to sync up all the different fields.

How to copy datasync configuration to another product

Once you have successfully configured the product for the datasync, you can clone the datasync configuration. When creating a new product, make sure to choose the option to "Create product from Existing product" rather than "Use Default Template" so that all the product mappings get copied across to the new product.

Jira Configuration Helper¶

It is difficult to find the unique IDs for various fields and items in Jira from the web application. To make the product configuration and all the required data mapping easier, please use our helper application. This is a Windows application that connects to your Jira instance (cloud or on premise) and helps you find the IDs for all various fields in Jira.

Download the helper here.
Unzip the contents
Run the JiraConfigurationHelper.exe. You will see the screen below:

Enter in the URL of your Jira instance, along with a login and API Key (as describe above)
Click "Connect"

Choose the project in Jira you want to get IDs for

You will then see tabs for the following information: issue types, issue statuses, issue priorities, components, versions, and custom fields.

Keep the helper application open so you can refer to it as you go through the remaining configuration steps below

Activate the datasync¶

Login to Spira as a system administrator
Go to System Administration > Integrations > Data Synchronization
Open the "Data Mapping" dropdown for the plugin and select the product you want to sync with
Click the arrow to the right of the product name
This will open the Jira data-mapping home page for the selected product:

If the project name does not match the name of the project you want to configure the data-mapping for, click on the "(Change Project)" hyperlink to change the current product.

To activate this product for the datasync, update the following fields:

External Key: enter the short acronym name of the project in Jira
Active: set to 'Yes' to activate the datasync for this product. Remember to set this back to "No" to turn off the datasync when the product or need for sync has finished
Click "Save"

Note: One Spira product can only be mapped to one Jira project, in other words it is a one-to-one mapping.

Release Mapping¶

The datasync uses a special mapping field to identify what a Spira artifact should sync with in Jira. It uses this field to map a Spira releases to a Jira version so that users can create releases/versions in one application and see them in either application. The summary of how it works is:

valid mapping on a Spira release for a Jira version: no action
no valid mapping:
- datasync sees a Jira version for the first time: creates a new release in Spira (mapped to the Jira version)
- datasync sees a Spira release for the first time: creates a new version in Jira (with the Jira version then mapped to the Spira release)

When you have a blank Spira product, the datasync will create all needed releases in Spira, mapped to the corresponding Jira version.

If you are syncing an existing product with releases in it to Jira, you should manually add the mapping information to Spira releases, to make sure you don't get duplicates being made. For each release/version that exists in both Spira and Jira at the time of starting the datasync for the first time:

Find the ID of the Jira version you want to map to a release in Spira
Go to the product in Spira
Open the Release list page
Go to the overview tab of the release
Look for the field called Jira ID (used to store the identifier of the equivalent version in Jira)
Set the value to the Jira version ID
Click "Save"

How to find the Jira version ID

The Jira ID for a version can be found using the Jira Configuration Helper on the Versions tab.

Standard Field Data Mapping¶

Mapping field values between Spira and Jira is a very important part of the configuration. Without this step, the datasync will not know what values to match things up with. For example, it will not know that an Jira issue with a type of "New Feature" should become an incident in Spira with a type of "Enhancement"

This process starts on data mapping home page for the selected product you were on to activate the datasync. On this page you will see a large list of options like in the screenshot below. This shows different fields across different artifacts.

Not all fields and artifacts need to be mapped

The screenshot above shows all possible artifacts and fields that any of our datasyncs use. Only some of these are need to be filled in for each particular datasync. So, only fill in mappings for fields explained below that meet your needs.

For many of the fields, you can map multiple Spira field values to the same Jira field value (e.g. Bug and Incident in Spira may both map to Bug in Jira). If you map the same Jira ID for different Spira field values, make sure to set "Primary" to Yes on one of the field values. This will be the value used when syncing from Jira to Spira.

Incidents¶

TypeStatusPriorityComponentSeverity

This field mapping is required

Click on the "Type" hyperlink under Incident Standard Fields to bring up the Incident type mapping configuration screen. The table lists each of the incident types available in Spira. Enter the matching Jira issue type ID for each one.

The Jira ID can be found by using the "Issue Types" tab of the Jira configuration helper.

This field mapping is required

Click on the "Status" hyperlink under Incident Standard Fields to bring up the Incident status mapping configuration screen. The table lists each of the incident statuses available in Spira and provides you with the ability to enter the matching Jira issue status ID for each one.

We recommend that you map the New and Open Spira statuses to the Jira ID for "Open" and make the Spira status of Open the primary status. This means that when new incidents in Spira get synced over to Jira, they will get switched to the Open status in Jira which will then be synched back to "Open" in Spira. This helps you easily see which incidents have been synced with Jira and those that haven't.

The Jira ID can be found by using the "Issue Statuses" tab of the Jira configuration helper.

This field mapping is required

Click on the "Priority" hyperlink under Incident Standard Fields to bring up the Incident Priority mapping configuration screen. The table lists each of the incident priorities available in Spira and provides you with the ability to enter the matching Jira priority ID for each one.

The Jira ID can be found by using the "Issue Priorities" tab of the Jira configuration helper.

This field mapping is OPTIONAL

Click on the "Component" hyperlink under Incident Standard Fields to bring up the Incident component mapping configuration screen. The table lists each of the components available in Spira and provides you with the ability to enter the matching Jira component ID for each one.

The Jira ID can be found by using the "Components" tab of the Jira configuration helper.

This field mapping is OPTIONAL

Click on the "Severity" hyperlink under Incident Standard Fields to bring up the Incident severity mapping configuration screen. Unlike the other incident standard fields, Jira doesn't have a built-in severity field. If you want to see Spira incident severities in Jira, create a Jira custom list field to store the different severity values. If you don't want to synchronize severity values with Jira, you can skip the rest of this section.

Once you have created a severity custom list field in Jira, you need to: - populate the field mappings with the name (Not the ID) of the severity custom property values in Jira - go to the Plugin configuration screen - Enter the ID of the custom field you're using to store severities in Jira in the "Jira Custom Fields" field. You can fin the ID on the "Custom Fields" tab of the Jira configuration helper.