Home
Welcome to the JiraToTfs wiki
JiraToTFS is a windows based utility for migrating tickets from Altassian Jira to Microsoft Team Foundation Server.
It is published under the GNU Public License.
- Supports Agile, CMMI, Scrum and customised templates.
- Supports impersonation ('Make request on behalf of Others')
- Will maintain as much Jira information as possible:
- Stories, Bugs etc. mapped accordingly to their TFS equivalent.
- Jira links between tickets / sub tickets maintained.
- Attachments and comments brought across.
- Ticket states maintained (closed tickets in Jira comes across as closed in TFS).
- History of who and when ticket was created added as comments to TFS entry.
- Hyperlink to original Jira ticket created on TFS entry.
- Can be run more than once. Tickets previously imported will not be imported again.
Latest Build
- v1.1.0 can be found on GitHub here.
Run-time Requirements
JiraToTFS requires
- Team Foundation Server Object Model
- Installed by Visual Studio 2012 otherwise can be found here.
- .NET 4..
###Before you Begin
- Ensure you have set up your TFS Project.
- You can use a pre-existing project. Existing (TFS) tickets will be left untouched.
- Ensure matching Jira users (See Impersonation below) are correctly assigned to your TFS project.
###Step 1 - Supply your Jira Credentials and Project Key
Jira Server: This is your Jira 'base url'. Jira's Demo project's base url is https://jira.atlassian.com.
User name: User name / email for logging into Jira.
Password: Your Password for logging into Jira. Blank if not required.
Project Key: Your Jira 'Project Key'. Jira Demo's project key is 'Demo'.
###Step 2 - Locate your TFS Project
Navigate your way to the desired TFS project by using the Select button. You will need your login credentials for TFS.
Note you may be asked to login twice. This is a known issue and will be addressed in a later release.
####TFS Teams If you've configured TFS to use Teams, by selecting one here, all tickets will be assigned to that team.
If you don't use Teams, just ignore this option.
####Impersonation
JiraToTfs will attempt to use Impersonation to recreate tickets in TFS under the name of the original Jira ticket author.
To do this:
- You will need matching jira users set up under TFS. JiraToTfs will attempt to match first by email address, then by name.
- You will need Impersonation enabled on your TFS server.
If Impersonation is not turned on, JiraToTFS will warn you.
Note It's possible to import tickets with Impersonation turned off. If this is the case all tickets will be created under the credentials of the person running this utility.
###Step 3 (If required) - Advanced Settings For the most part, supplying your Jira and TFS credentials / TFS Project is enough to get importing.
If you want to change the mappings between Jira and TFS ticket 'types' or provide default values for customised fields you will need to access "Advanced Settings".
Note Advanced Settings is only enabled if you have provided your Jira credentials and selected a TFS project.
####Work Item Type Tab Here you can re-arrange ticket type mappings between Jira and TFS. For example: a task in Jira can be mapped to a Product Backlog Item in TFS.
To restore defaults, click "Restore defaults".
####Default Field Values Tab If you have custom fields that require a default value for all tickets imported, set it here.
####Default User This is only useful if you have Impersonation enabled.
JiraToTfs will attempt to map original jira ticket author with a matching TFS user. If this fails, you can designate an alternative default ticket creator / assignee.
Other than this, all tickets not matched with a TFS user will be created /assigned to the person who is running this utility.
####New Work Item Jira tickets marked as 'To-do' can be set to their next 'state' when imported into TFS.
This can be useful where the assumption is that everything logged in Jira has been approved by a Product Owner and are regarded as no longer 'new' in TFS.
See Microsoft Work-Flow.
####Bug Priorities Some organisations define their own unique prioritisation listing for bugs.
Instead of using Microsoft's standard Priority Field, you can choose a custom field to hold prioritisation.
To restore defaults click Restore Defaults.
###Step 4 - Click 'Import Now' Nothing left to do but click 'Import Now' and go for a coffee break. This could take some time depending on the volume of tickets to import.
###Post-Import Following a successful import, clicking on View Report will give you a detailed breakdown of tickets imported and any warnings raised.
If import is not successful there is an additional 'exceptions' log generated in the application folder (normally C:\Program Files (x86)\JiraToTfs) called JiraToTfs.txt.
Please include this log when raising a bug / query against this utility.
####Undoing Imported Tickets Following a successful import, JiraToTfs generates a batch file called UndoImport.bat (located in application folder), that, when run will remove tickets just imported. UndoImport.bat uses a custom console based application to remove created tickets. Source for this tool can be found alongside sources for JiraToTfs.
####JIRA returned status: Unauthorized Unable to connect to Jira. Check your Jira credentials (user name and / password / Project Key) and try again.
####Jira returned status: Forbidden Either you don't have rights to import via the REST API or REST API has not been enabled for this project. Contact your Jira Administrator for help.
####TF400324: Team Foundation Services not available from server Communication has been lost with TFS server. Check internet / network settings and reselect via the "select" button.
####Cannot load issue You may receive this error if communication is lost with your Jira server. Check internet / network settings and try again.
##Common Warnings
####No users assigned to selected TFS Project Aside from the administrator, there are no users assigned to selected TFS project. If you are not logged into TFS as the administrator you will not be able to import tickets into this project. If logged in as administrator, you can continue, otherwise assign some matching users.
####Impersonation not enabled You have users assigned to selected TFS project but impersonation is not enabled on the server. Contact your local TFS administrator to correct. You can import with impersonation turned off but all tickets will be created under your name (the person logged into TFS).
####Failed to impersonate 'User'. (This person does not have rights to create work items in TFS.) A matching Jira user was found in TFS but does not have rights to create a ticket against selected TFS Project. As such, default ticket creator or person running this utility created the ticket instead.
####Failed to attach item.. Exceeds supported file upload size TFS Server attachment size is 4MB by default. Tickets with attachment size bigger than this will still be imported but their associated attachment will not. Attachment size can be increasedby your TFS Administrator.
- JiraToTfs is written in C# using Visual Studio 2012
- Will also build and run under Visual Studio 2015.
- Source can be found here.
- Talks to Jira via a customised version of techTalk.JiraRestClient.
- Talks to TFS via Microsoft.TeamFoundation.Client v2.0.50727.
- Tested against TFS Server 2012 and 2013 (should work against 2010).
This utility would not be possible with out the help / consumption of
Please raise any issues you find here. When logging, please include
- Clear description of problem at hand.
- Clear steps to reproduce problem.
- Attach exceptions log (which can be found under application folder, called JiraToTfs.txt).
I'm a principal software engineer working for a company called Sage. I have over 15 years+ desktop application development experience and have an interest in contributing to the Open Source community.
I can be reached via LinkedIn.