Skip to main content
System StatusContact Support
VersionOne Community

TeamSync for JIRA

Overview

TeamSync for JIRA is a connector used by VersionOne TeamSync to provide portfolio and program managers with visibility into the work that their teams are managing within Atlassian JIRA. With this integration, VersionOne is the system of record for programs, initiatives, and features, with JIRA being the system of record for workitems (stories and defects) and worklogs (effort).

TeamSync for JIRA does not support full bi-directional synchronization of all assets and fields, nor does it support customizing the fields that it synchronizes. It is designed to synchronize only the data that portfolio and program managers need to understand and track progress of the feature work that their teams are doing.

TeamSync for JIRA Requirements

In addition to VersionOne TeamSync requirements, TeamSync for JIRA requires the following:

  • HTTP access to one or more JIRA instances
  • JIRA versions 5, 6, or 7
  • JIRA user account with a Developers or higher project role
  • The following fields must be unlocked in JIRA (see "How to Unlock a Locked Field")
    • Epic Link
    • Epic Name
    • Epic Status
  • Story Points for Scrum project type in JIRA are not enabled by default; these must be enabled manually for TeamSync to work properly.
  • User names cannot be changed/updated in Jira once created. Once a user is created, it must remain with the same user name in order for TeamSync to work properly. This is because Jira does not properly update the properties for the user after an update via the API. Refer to JIRA issue No. 36642

Known Constraints

  • Issues created in JIRA belonging to a Portfolio Item that is closed in VersionOne are not synched.
  • Portfolio Items created in VersionOne must contain BLANK reference field in order for the JIRA connector to work properly
  • Closed issues in JIRA that are updated after they are closed will NOT sync. JIRA issues must be in open state in order for sync to take place properly.
  • Updated for JIRA issues that correspond to closed stories/defects in VersionOne will not update.
  • Default access levels for user accounts in JIRA must remain unchanged for the user account used to run the integration.
  • Only Scrum, Kanban, and Default JIRA project types contain issue type EPIC, therefore, these are the only two project types supported with TeamSync.
  • Custom issue types in JIRA are not supported. Only the default issue types are supported (story, bug, epic)

Installing TeamSync for JIRA

The TeamSync for JIRA connector is automatically installed with VersionOne TeamSync.

Configuring TeamSync for JIRA

In addition to the general VersionOne TeamSync configurations, TeamSync for JIRA requires a few additional configurations such as the JIRA server URLs and credentials, and the VersionOne-to-JIRA project mappings. 

TeamSync for JIRA supports the following general configurations:

  • JIRA Settings: These settings are used to set the target one or more JIRA instances and how the service authenticates to them.
  • Project Settings: These settings are used to set the VersionOne-to-JIRA project mappings and other settings related to how projects are synchronized.

TeamSync for JIRA configuration settings are located in the same VersionOne.TeamSync.Service.exe.config file that contains the general TeamSync configurations. 

Server Settings

TeamSync for JIRA supports synchronizing data from multiple JIRA servers into a single VersionOne instance, and the settings for the target JIRA instances includes the JIRA instance URL, the authentication credentials used by the service to communicate with JIRA REST API, and the proxy settings.

Here's an example of the JIRA server settings as they appear in the TeamSync configuration file:

<!-- JIRA settings -->
<jiraSettings>
   <servers>
      <server enabled="true" name="jira6" url="http://jira6server:8080" username="username" password="password" >
         <proxy enabled="false" url="http://proxyurl" domain="proxydomain" username="proxyuser" password="proxypwd" />
         ...
      </server>
      <server enabled="false" name="jira5" url="http://jira5server:8080" username="username" password="password">
         <proxy enabled="false" url="http://proxyurl" domain="proxydomain" username="proxyuser" password="proxypwd" />
         ...
      </server>
   </servers>
</jiraSettings>

Notice that there are two JIRA servers listed in the example above, but only one of them has its enabled attribute set to "true". This means that only that server will be synchronized by TeamSync, servers with enabled set to "false" are ignored. This allows you to turn on/off server synchronization as needed.

To add more servers to the synchronization process, simply create a new server element within the servers element and set its attributes as required.

Project Settings

Nested within each server element is a projectMappings element that is used to set which VersionOne project maps to which JIRA project. 

Here's an example of the project mappings as they appear in the TeamSync configuration file:

<server enabled="true" name="jira6" url="http://jira6server:8080" username="username" password="password" >
   <proxy enabled="false" url="http://proxyurl" domain="proxydomain" username="proxyuser" password="proxypwd" />
   <projectMappings>
      <project enabled="true" v1Project="Scope:1003" jiraProject="ATT" epicSyncType="EpicCategory:208"></project>
      <project enabled="false" v1Project="Scope:1049" jiraProject="AST" epicSyncType="EpicCategory:208"></project>         
   </projectMappings>
</server>

Notice that there are two project mappings listed in the example above, but only one of them has its enabled attribute set to "true". This means that only that project will be synchronized by TeamSync, project mappings with enabled set to "false" are ignored. This allows you to turn on/off project synchronization as needed.

Also notice the epicSyncType attribute which is used to indicate which type of VersionOne Portfolio Item will be synchronized. By default, Portfolio Items of type "Feature" (EpicCategory:208) will be synchronized.

Finally, the statusMappings element --nested within each project-- will allow you to synchronize the statuses between VersionOne and JIRA for epics, stories, and bugs. The system of record for epics will be VersionOne, while for stories and bugs it will be JIRA. If a certain status in the system of record is NOT mapped, it will not be synced.

The following table describes each attribute of the project element:

Name Description
runFromThisDateOn The date from which TeamSync will sync items. Only items that have been created or changed since the specified date will be synced. Any items that were created or changed before this date will be ignored.
enabled Set to "true" to enable the project for synchronization; "false" to ignore.
v1Project The internal ID of the VersionOne project to synchronize. The following Data API query can be used in a browser to determine the internal project IDs of all the projects in your VersionOne instance:
http://localhost/versionone/rest-1.v1/Data/Scope?sel=Name
jiraProject The JIRA project ID that you set when creating the project in JIRA. You set the JIRA project ID when you first create the project in JIRA. This value is typically a three letter acronym.
epicSyncType The default type of VersionOne Portfolio Item to synchronize to JIRA. By default this property is set to "EpicCategory:208" which is the "Feature" type. The following Data API query can be used in a browser to determine the internal IDs of all the Portfolio Item types in your VersionOne instance:
http://localhost/versionone/rest-1.v1/Data/EpicCategory?sel=Name

To add more projects to the synchronization process, simply create a new project element within the projectMappings element and set its attributes as required.

Project mappings are one-to-one only, you cannot map one VersionOne project to multiple JIRA projects, nor can you map one JIRA project to multiple VersionOne projects. Trying to map one-to-many project relationships can result in inconsistent data.

Priority Settings

Nested within each server element is a priorityMappings element that is used to set which VersionOne priority maps to which JIRA priority.

Here's an example of the priority mappings as they appear in the TeamSync Configuration file:

<server enabled="true" name="jira6" url="http://jira6server:8080" username="username" password="password" >
   <proxy enabled="false" url="http://proxyurl" domain="proxydomain" username="proxyuser" password="proxypwd" />
   ...
    <priorityMappings defaultJiraPriority="Medium">
       <priority enabled="true" v1Priority="Low" jiraPriority="Lowest"></priority>
       <priority enabled="true" v1Priority="Low" jiraPriority="Low"></priority>
       <priority enabled="true" v1Priority="Medium" jiraPriority="Medium"></priority>
       <priority enabled="true" v1Priority="High" jiraPriority="High"></priority>
       <priority enabled="true" v1Priority="High" jiraPriority="Highest"></priority>
    </priorityMappings>
</server>

Notice that there are five priority mappings listed in the example above and all of them have their enabled attribute set to "true". This means that by default, all priority statuses will sync. Additionally, note that the defaults use JIRA 6 statuses. If you are using JIRA 5 be sure to update the fields to use JIRA 5 defaults. 

Also notice the epicSyncType attribute which is used to indicate which type of VersionOne Portfolio Item will be synchronized. By default, Portfolio Items of type "Feature" (EpicCategory:208) will be synchronized.

The following table describes each attribute of the priority element:

Name Description
enabled Set to "true" to enable priority for synchronization; "false" to ignore.
v1Priority The common VersionOne priority for Portfolio Items and Workitems (story/defect)
jiraPriority The common JIRA priority for all issue types (epic/task/bug)

Status Settings

Nested within each project element is a statusMappings element that is used to set which VersionOne status maps to which JIRA status.

Here's an example of the priority mappings as they appear in the TeamSync Configuration file:

<server enabled="true" name="jira6" url="http://jira6server:8080" username="username" password="password" >
   <proxy enabled="false" url="http://proxyurl" domain="proxydomain" username="proxyuser" password="proxypwd" />
   ...
    
     <statusMappings>
        <status enabled="true" v1Status="Future" jiraStatus="To Do" />
        <status enabled="true" v1Status="In Progress" jiraStatus="In Progress" />
        <status enabled="true" v1Status="Done" jiraStatus="Done" />
     </statusMappings>

</server>

Notice that there are only three status mappings listed in the example above and all of them have their enabled attribute set to "true". This means that by default, all the listed statuses will sync. Any status NOT listed here will be ignored by TeamSync.

The following table describes each attribute of the status element:

Name Description
enabled Set to "true" to enable status for synchronization; "false" to ignore.
v1Status The common VersionOne status for Portfolio Items
jiraStatus The common JIRA status for stories and bugs

 

Using TeamSync for JIRA

Using TeamSync for JIRA involves starting the TeamSync service then creating assets in one system so that the service will then create them in the other system. The following sections describe the major workflows that TeamSync for JIRA supports.

Feature Workflow

Using the feature workflow of TeamSync involves creating a Portfolio Item of the configured type in VersionOne, then when a synchronization occurs, a matching Epic Issue will be created in JIRA.

The following are the steps involved in using the feature workflow:

  1. In VersionOne, select a project that has been mapped to a JIRA project in the TeamSync config file.
  2. In the Portfolio Planning menu, select Portfolio Tree.
  3. Click the Add Portfolio Item button.
  4. In the Portfolio Item dialog, enter a title, description, and type, then click OK. Note that they type that you select should match the type that you specified in the epicSyncType attribute in the TeamSync config file.
  5. Once a synchronization occurs, a new Epic will be created in the mapped JIRA project.

Worktem Workflow

Using the workitem workflow of TeamSync involves creating a Story or Bug Issue in JIRA, then when a synchronization occurs, a matching workitem will be created in VersionOne.

The following are the steps involved in using the feature workflow:

  1. In JIRA, select the Create button to create a new issue.
  2. In the Create Issue dialog, select Story or Bug for the issue type, enter a summary, description, optionally an epic link to a synced epic, optionally story points, and then click OK.
  3. Once a synchronization occurs, a new backlog item will be created in VersionOne. It will be a defect if the JIRA issue is a bug, or a story if the JIRA issue is a story.

All synchronized JIRA issues will be placed in the VersionOne backlog for the mapped project. If the JIRA issue is associated with a VersionOne Portfolio Item that has been synced, that relationship will also be reflected in VersionOne and the backlog item will appear in the Portfolio Item tree.

Effort Workflow

Using the effort workflow of TeamSync involves creating a Worklog against a synced backlog item in JIRA, then when a synchronization occurs, a matching effort entry will be created in VersionOne.

The following are the steps involved in using the worklog workflow:

  1. In JIRA, open a synced backlog item.
  2. Select More, then Log Work.
  3. Enter the Time Spent and Date Started for the worklog, then click Log.
  4. Once a synchronization occurs, a new effort entry will be created in VersionOne for the effort and date that is associated with the synced backlog item.

Your VersionOne instance must be configured to track effort with the Story or Defect levels, or both the Story and Defect and Task/Test levels. JIRA worklogs cannot be synchronized at only the Task/Test level.

Accumulated effort for a synced backlog item will appear in the backlog item’s Done field in VersionOne. In addition, you can see a list of all effort entries in the VersionOne Effort Quicklist report.

TeamSync for JIRA Data Mappings

TeamSync for JIRA synchronizes the minimal set of data that is need to effectively track and understand work that is being managed in JIRA.

TeamSync does not support adding additional data mappings for either standard or custom fields.

Portfolio Item (Epic) Data Mappings

For the feature workflow, the following fields are mapped between VersionOne Portfolio Items and JIRA Epics:

VersionOne Portfolio Item Fields

JIRA Epic Fields

Title

Summary

ID

Name

Description

Description

Link

Comment

Priority

Priority

Status

Status

Workitem (Story/Defect) Data Mappings

For the workitem workflow, the following fields are mapped between JIRA issues (Story and Bug) and VersionOne workitems (Story and Defect):

VersionOne Workitem Fields

JIRA Issue Fields

Title

Summary

ID

Label

Description

Description

Portfolio Item

Epic Link

Estimate

Story Points

Link

Issue Links

Priority

Priority

Status

Status

Worklog (Effort) Data Mappings

For the effort workflow, the following fields are mapped between JIRA worklogs and VersionOne effort entries:

VersionOne Effort Fields

JIRA Worklog Fields

Date

Date Started

Value

Time Spent

Member

User

Synchronized effort entries in VersionOne are assigned to the VersionOne account that TeamSync is configured to run as. In addition, worklogs that are deleted in JIRA are zeroed out in VersionOne.

Viewing JIRA Worklogs in VersionOne (Effort)

Because the TeamSync service syncs worklogs from JIRA to VersionOne as "effort", users are able to use the "Effort Quicklist" report in VersionOne to view detailed effort (Done) transaction listing by team member and task in VersionOne. For more information see Quicklist Reports.

Troubleshooting TeamSync for JIRA

The TeamSync service is unable to connect to JIRA.

This can happen as a result of an invalid URL, incorrect credentials, or an issue getting HTTP access to your JIRA instance. Try opening JIRA directly using a browser on the machine that TeamSync is running on.

VersionOne Portfolio Items are not being synchronized as JIRA Epics.

Check that the value that you have configure for the epicSyncType setting exists in VersionOne, and that you have set that value as the Portfolio Item Type for all the epics that you want to have synchronized.

JIRA issues are not being synchronized as VersionOne workitems.

Check the log file for a WARN log message that the “JIRA story points field is not enabled”. If this is found, you will need to enable the Story Points field in the JIRA Issue Screen that you are using for your mapped project.

JIRA worklogs are not being synchronized as VersionOne effort entries.

Check the log file for a WARN log message indicating that the “reference” field is missing in VersionOne. If this is found, you are running an older version of VersionOne that is not supported by TeamSync. Upgrade your VersionOne instance to version 14.1 or higher.

Getting Help with TeamSync for JIRA

While we strive to make TeamSync for JIRA as easy to use as possible, however you may still occasionally need some help, and there are a few different ways you can get it:

  • StackOverflow: For asking question of the VersionOne Developer Community.
  • VersionOne Support: Our support team is well versed in TeamSync and can advise and help troubleshoot.
  • VersionOne Technical Services: A paid support offering, this team provides API training, development pairing, and complete custom development services.
  • Was this article helpful?