How to create a TFS custom field to store the Jira issue key (TFS4JIRA)

Owned by Paweł Mazur
Dec 18, 2020
3 min read

The purpose of this tutorial is to help you create a custom field in TFS. We're going to use this custom field to store the Jira issue key when synchronizing Jira and TFS.


  1. Access your TFS instance and go to the "Projects" page.
  2. From there click on the 'cog' icon in the middle of the screen, right next to the "My pull requests" option, and select Process:
  3. This is where all your process templates are located. Since TFS does not allow you to change existing templates, we'll need to create our own (custom) template. I'm going to use Agile (default) in this tutorial. Right-click the template you want to modify and select Export:
  4. Find your template and unzip it. If you exported the Agile template the file is called "Agile.zip". Once you unzip the file, rename it (e.g. CustomTemplate):
  5. Edit the <Template_Directory>\ProcessTemplate.xml file and change the "name" and "version type" attributes. This is very important because you're going to import this back to TFS. Your template cannot have the same "name" and "version type" (hash) that the existing Agile one.
  6. After that open up the <Template_Directory>\WorkItem Tracking\TypeDefinitions directory and edit the XML files from the Work Item types you want to modify and add the custom field. I'll change the Bug.xml template in this tutorial.

  7. Open up the XML file and add the following line somewhere between the existing field definitions under the <FIELDS> tag:

    <FIELD name="Jira Issue Key" refname="Custom.JiraIssueKey" type="String" reportable="dimension" />

    This is your field definition. I've added mine right after the existing "Completed Work" field:

  8. Don't close the file yet! You've created the field definition. Now you need to place it somewhere in the Work Item screen. You'll need to add the following <CONTROL> value:

    <Control Label="Jira Issue Key" Type="FieldControl" FieldName="Custom.JiraIssueKey" />

    Scroll down and find the <CONTROL> fields. You'll need to chose where you want to place the field. I've added the field inside the "Planning" group:

  9. Once you're done, save the file and go back to where your <Template_Directory> is located. Compress the <Template_Directory>. In this case since my folder was named "CustomTemplate", now I have the "CustomTemplate.zip" file:
  10. Go back to the TFS process page and click the "+ Upload process template" button. Choose your compressed file (e.g. CustomTemplate.zip):
  11. Wait for TFS to finish uploading the file. Once it's done, you'll see your custom template in the list of processes:
  12. Create a new project and make sure you choose your custom template as the Work item process:
  13. Voilà! Here you can see the "Jira Issue Key" custom field, under the Planning section, when creating a new Bug inside the project using your custom template:


That's it! Next time you set up the TFS4JIRA Synchronizer to test the synchronization between Jira and TFS you can use your custom field to store the Jira issue key instead of using TFS History.