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 a range different syncing modes, depending on your workflows and needs.

Sync Mode	Releases	Requirements	Incidents	Tasks
Default	Jira <-> Spira	Jira <- Spira	New: Jira <-> Spira Updates: Jira -> Spira	New: Jira -> Spira Updates: Jira <- Spira
Bidirectional	Jira <-> Spira	Jira <- Spira	Jira <-> Spira	New: Jira -> Spira Updates: Jira <- Spira
Complete	Jira <-> Spira	Jira <-> Spira	Jira <-> Spira	Jira <-> Spira
NoRequirements	Jira <-> Spira	(not synced)	New: Jira -> Spira Updates: Jira <- Spira	New: Jira -> Spira Updates: Jira <- Spira
NoIncidents	Jira <-> Spira	Jira <- Spira	(not synced)	New: Jira -> Spira Updates: 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 Complete sync mode allows fully bidirectional sync upon creation and update of all the supported artifacts (Releases, Requirements, Incidents, and Tasks).
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 synced bidirectionally by default between Spira and Jira Cloud. You can disable comments syncing using the option on the configuration page.
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 or existing ones are updated. 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, you can optionally sync the Epic/Story hierarchy from Jira to Spira Requirements and vice-versa.
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]

Configuration Tip

For most users, we recommend leaving "Jira Custom Fields" blank. If you want to sync Tasks and/or Requirements, do not forget to configure "Task Types" and/or "Requirement Types", and choose the proper "Sync Mode". Leave "Requirement Types" blank if you do not want to sync user stories/requirements (not valid for the NoIncidents mode).

Jira Special 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. Also, use this field to activate Time Tracking fields sync. This can be left empty for now and will be discussed below in Configuring Jira Special Fields.
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 synced 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.
- Complete: enter the word "Complete" to use this mode. Recommended for advanced users only. Like the bidirectional sync mode, only use this mode if you have a well-defined set of workflows that make sense in both systems, for all artifacts, and make the polling interval as short as possible, to avoid conflicting changes in the two systems. This mode syncs all the artifacts bidirectionally, but you can also use the field Types to Skip to ignore the sync of some Jira types.
- 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 a single name of a Jira issue link type or be left blank. If you want the datasync to create links between Jira issues, based on 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 on 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:

Types to Skip: This optional field can be used to ignore some Jira issue types during the sync. To do this, enter a comma-separated list of IDs of any Jira issue types that you want to exclude from synchronization. If you leave this blank, all Jira issue types will be considered for synchronization, sync mode permitting.
Skip Comments: Set this field to Yes if you want the dataSync to ignore comments in both directions. Please note old comments already synced won't be deleted.
Auto-Map Properties: Set this field to Yes if you want the dataSync to try to automatically map the standard and custom properties based on name matching. When enabled, the system will automatically map properties with matching names between Spira and Jira, significantly reducing the need for manual mapping. Even if this option is enabled, you can still manually map properties as explained in this documentation. The system will try to auto-map only the blank mappings. Learn more here.

Configuration Tip

If you are using the Auto-Map Properties option, please remember you still need to activate the sync for your project and provide an External Key as explained below. The auto-mapping will occur when the datasync runs for the first time after activation, but you won't see the values on the mapping pages, so you can still provide different values for manual mapping.

Sync Epic/Story hierarchy: Set this field to Yes if you want to see the Epic/Story hierarchy reflected in Spira Requirements and vice-versa, depending on the sync mode.

Hierarchy Limitations

Spira supports multi-level Requirement hierarchies that are more complex than Jira's default capabilities. The dataSync plugin cannot create hierarchical relationships in Jira that aren't supported by its configuration. When encountering an unsupported hierarchy structure, the dataSync will place the affected work item at the root level instead. To customize your work item hierarchy settings in Jira, please refer to the Jira documentation.

Use Plain Text: Set this field to Yes to remove any formatting from the description fields when using either the bidirectional or the complete sync modes. This allows the description fields to sync bidirectionally (two ways) depending on the sync mode. This option is useful if you don't require complex text formatting.

Rich Text vs Plain Text

If you normally don't add text formatting, embedded images, or files to your descriptions and need updated text to be visible in both systems, use Plain Text. However, if you need embedded images, colors, tables, etc., in your descriptions, use Rich Text. Please note that Jira has limited capabilities for exporting and importing text formatting. Consequently, while the plugin will do its best to sync the text, some differences in formatting may occur. Also, due to these limitations, when using Rich Text sync, changes to description fields are only synchronized one-way - from the source artifact (older) to the target (newer) and never in the reverse direction. The plugin will add a warning message to the affected description fields.

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 described 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 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 have been set up 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.

Standard Field Data Mapping¶

You can use Auto-Map to simplify and potentially skip the manual mapping process described in this section.

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

If not using Auto-Map, 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.

If not using Auto-Map, 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.

If not using Auto-Map, 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. You can save time using Auto-Map.

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.