Custom Fields for TFS Work Items

In Team Foundation Server (TFS), teams often desire custom fields to help better organize their collaboration. For example, we can add a Jira Issue Id because check-ins on TFS are related to a work item - whereas Jira may be on a separate server.

To run the Work Item Tracking Administration (witadmin) command-line tool, open a Visual Studio Command Prompt. The witadmin command-line tool installs with any version of Visual Studio. You will need the version, or higher, of Visual Studio than Team Foundation Server (TFS).

Note: witadmin is not supported on Azure DevOps Services.

To export or list work item types, you must be a member of the Project Administrators group or have your View project-level information permission set to Allow. To destroy, import, or rename work item types, you must be a member of the Team Foundation Administrators security group or the Project Administrators security group.

Note: Using Process Template Manager (in Visual Studio) to replace the active template will delete all work items in the TFS collection.

Importing a single item type using witadmin will not delete any data so long as you are adding fields.

First, grab the xml for the Task type.


witadmin exportwitd /collection:http://<server>:<port>/tfs/<collection> /p:<project> /n:Task /f:Task.xml

If successful, you should get the following message.


Operation complete.

Great! Now we can add a Jira Issue Id field. Start by defining the field in the Task.xml file.


...
<FIELDS>
	<FIELD name="Jira Issue Id" refname="Jira.IssueId" type="String">
		<HELPTEXT>Example PROJECT-3</HELPTEXT>
	</FIELD>
	...

Then define how the field is laid out in the form,


...
<FORM>
	<Layout>
		<Group>
			<Column PercentWidth="20">
				<Control FieldName="Jira.IssueId" Type="FieldControl" Label="Jira Issue &amp;Id:" LabelPosition="Left" />
			</Column>
			<Column PercentWidth="60">
				<Control Type="FieldControl" FieldName="System.Title" Label="&amp;Title:" LabelPosition="Left" />
			</Column>
			...

With the work item modified, we can re-import it.


witadmin importwitd /collection:http://<server>:<port>/tfs/<collection> /p:<project> /f:Task.xml

If successful, you should get the following message.


The work item type import has completed.

Now open the web portal of TFS (http://<server>:<port>/tfs/<collection>/<project>) and create a new task.