Customizing Team Foundation Server 2013

Visual Studio Team Foundation Server (TFS) manages workflow of software development projects. It is designed for the typical development. If it doesn't support all your team development activities, you can extend it by various means, including the creation custom controls or new work items.

Work Items and Custom Controls

Why Customization?

Team Foundation Server (TFS) manages the entire application lifecycle using underlying process templates. TFS provides, off the shelf, three built-in process templates for managing the general execution of a project. There are also several community-developed templates available that can be integrated to TFS. If you need more than this, you can develop templates to handle specific aspects of the workflow that supports your application development process.

TFS process templates can be customized to meet your particular requirements. This customization can be done at various levels such as:

  • Creating a new process template
  • Adding new work item types
  • Customizing existing work items
  • Customizing existing process template
  • Adding custom controls to work items

In this article, we’ll take a look at how to create a new process template, and demonstrate some of these customizations with the aim of getting you started with your own customizations.

Develop New Process Template

We can define our own process and work items using a new process template. When this process template is defined, it can be based on an existing template and then modified using the process editor. The Process Editor is part of TFS Power tools, which can be downloaded from Visual Studio gallery.

To develop a new process template, we need to perform these steps:

  1. Open Visual Studio and connect to TFS server.
  2. Navigate to Team Explorer â Settings.
  3. Select ‘Process Template Manager‘ from the ‘Team Project Collection section to launch the ‘Process Template Manager’ window.
  4. Select one of the pre-defined process templates, based on which our new template will be developed.
  5. Click ‘Download to download the process template to local system.
  6. Open the downloaded process template in Visual Studio using the Process editor for editing.
  7. Select Tools â Process Editor â Process Templates â Open Process Template.
  8. Select the process template xml file name from the download location.
  9. Work Item Tracking: Work items related to the process and their associated properties.
  10. Areas and Iterations: Iterations defines release management and areas will be based on whether they are functional, non-functional or feature-wise.
  11. Groups and Permissions: Defines the default TFS groups such as Contributors or Readers.
  12. Lab: Defines the lab system details associated with lab management.
  13. Build: Defines the default build templates and permissions related to build for each TFS group.
  14. Source Control: Different policies related to version control management.
  15. Portal: Defines the SharePoint integration components.
  16. Reports: Defines the sub folders under the root reporting URL.
  17. To create a new process template, rename the process template and modify the different sections according to our requirement.
  18. Save the modified template to the local system.
  19. Open the Process Template Manager again and click ‘Upload to upload our new template, for example, XYZ Team Template. This template will be available for any new project creation. Create our new project using the new template to follow user defined process for the project execution.

2128-1-1a5e51fa-87cf-4da7-8b1a-26f9bb30b

Work Item Customization

Customization Work Item Types (WIT) using WITadmin Command

Visual Studio provides a command line tool called WITadmin to perform work item customization. This tool is available in the folder [drive:]\Program Files\Microsoft Visual Studio 12.0\Common7\IDE. This tool can be used for importing a work item, editing it and exporting it back.

Download work item definition to local system using WITadmin:

Parameters:

  • exportwitd : specify whether to export or import the WIT definition
  • /collection:URL: Specify the URL of the project collection
  • /p:name: provide the project name
  • /n:type: provide the work item type
  • /f:path: specify the path where the WIT definition needs to be downloaded

This command downloads the specified WIT definition, in above case the bug template to the specified path. We can edit the XML file using any XML editor or Visual Studio.

Wit definition consists of three sections:

  • Fields – Defines the underlying database field. Specify the name of the database field, reference name, type and whether the field is reportable or not.
  • Layout – Defines the layout of the work item. Fields will be represented in the layout using specific controls.
  • Workflow – Defines the state transitions. Every work item will have its own lifecycle, which will be defined as workflow.

Depending on the customization requirements, fields, layout and workflows can be altered. Here, a new field called Message will be added to our Bug template.

Define the Message field under Fields section as:

Now, place the control to represent this field in the layout after the Reason field as:

Save the Work Item Type (WIT) definition file and run the import command under witadmin tool as:

Open the Bug template and observe our new field appeared after the reason field:

2128-e94c7e0e-73d4-4b7b-8b31-4e1f3ee39ac

Process Editor

The Process Editor has various options for working with a work item definition file. We can open the WIT directly from the server and edit it. Opening WIT from the server will reflect the changes directly on the server. If you are planning many changes or planning to work offline, use the ‘Export WIT’ option to download the WIT file to local system. Modify the local copy using ‘Open WIT from File’ and upload it back to server using ‘Import WIT.

2128-e1d25bb3-fd05-4753-8cfe-7e3398228ed

Custom Work Item

  1. Open the most appropriate template WIT file for the type that is most suited for the new work item that you want to create
  2. Here, we open the task work item and create a new custom work item called Work.
  3. Change the work item name as Work and modify the description.
  4. This creates a new work item type called Work with same template as ‘Task’. New Work Item creation will display the new work item type, displayed as follows:

Custom Fields

The process editor can be used to modify our new work item ‘Work. The Existing task template will appear as follows:

2128-1-e54615f1-2b57-4d0f-8c35-de6abad07

Remove the ‘Reason and ‘Blocked fields and add a new field called ‘Days.

Adding new field:

  1. Click ‘New in the ‘Fields‘ section.
  2. Provide the Name, type, reference name, help text and reportable attributes for the new field under the Field definition tab and click ‘OK.
  3. Navigate to the ‘Layout section, where the new field will replace the ‘Reason‘ and ‘Blocked‘ fields.
  4. Delete the controls by right-clicking the control and select ‘Delete from the context menu.
  5. Right-click the column and select ‘new control’. Bind the new control with our custom field.
  6. Save the work item definition and try to create a new work item to observe the new field.
  7. The field can appear as a text field, into which the user can enter the required value, a drop-down list from which only pre-selected values can be picked, or a combo-box where you can either enter a value from the keyboard or select from the list.
  8. Navigate to the ‘Field‘ section and double-click the ‘custom‘ field to open the Field Definition window.
  9. Navigate to the ‘Rules‘ tab and select either the AllowedValues or the SuggestedValues rule.
  10. Either enter the list of values or else bind to a Global list which will be already defined in the project collection level to handle the list details.
  11. Save the WIT definition and open the new work item of type ‘Work‘ and observe the drop-down displayed for the ‘Days‘ field.

Custom Workflow

You may need to alter the workflow corresponding to an existing work item. We’ll take as an example the existing ‘bug type’ work item. The lifecycle of the bug is
 New â Approved/committed/Done/Removed â Approved/committed/Done.
We want to introduce a new stage after ‘New’ called ‘Triage Approved. Now, the lifecycle of the work item changes to
New â Triage Approved â Approved/committed/Done/Removed â Approved/committed/Done.

  1. Open the ‘Bug‘ work item using Process Editor and navigate to the ‘Workflow‘ tab.
  2. In the flow diagram, drag one state control from the tool box to the work flow and then rename it to ‘Triage Approved.
  3. Connect the new state with ‘New‘ and other states using ‘Transition‘ control from the toolbox. Transition control will appear as an expandable box with two connection as shown below
  4. Double-click the transition to open the Transition properties.
  5. Change the starting state from ‘New’ to ‘Triage Approved’ to point it to the new state.
  6. Now, we have only one transition from New, which is to ‘Triage Approved’. All other transitions will be from ‘Triage Approved’ and back to the same.
  7. New bugs will have the changed lifecycle. After the bug is created, it will be in ‘New‘ state. From ‘New’, there will be only one state change called ‘Triage Approved’.

Custom Work Item Control Development

TFS supports a limited set of controls that can be used in work item customizations. The most important three controls that are supported for field display are:

  • FieldControl – Defines one liner text field. This is the default control used for integer, string or double data type.
  • DateTimeControl – Defines a date field and displays a ‘date-picker’ for quick date selection.
  • HtmlFieldControl – Defines an html field with rich text support.

Your project requirements may require a more complex control than these to support your particular requirements. In this section, we will look into how we can create such a custom control.

Any new control that can be used for work item customization will need to have two versions : a Control to support web access which will be built using jQuery and HTML, and a Visual Studio edition of the control which will be developed using .NET code

Web Access Control

The Web access version of a control is created using HTML tags and jQuery widgets. It can also be based on one of the core TFS controls. TFS offers many core controls, which are not exposed as work item controls. In our first example, we will first create a control using HTML tags and then a control based on a core TFS control.

HTML Control

TFS has a built-in type called PlainText, which supports more than 255 Unicode characters. We can use either the FieldControl or HtmlFieldControl to represent the Plaintext field. PlainText field is to ccapture more than 255 character information, displaying such a long text in a single line will not be appropriate always. FieldControl will display a single line text box only. HtmlFieldControl has a pre-defined minimum height and will display with a 15 line height. We will create a new custom control based on TextArea, which can be used for the PlainText field.

Create JavaScript file

Web access controls are based on jQuery and JavaScript. Start defining the new control as a new module in TFS

Parameters

  • Name of the new module: TFS.WorkItemTracking.Controls.TextAreaControl
  • Dependent module list: Dependent modules like work item tracking controls, tfs core and ui common controls.
  • Module definition: We can define the control logic as a separate method or as an anonymous method shown in the above sample code.

Now, define a constructor for the new module, which in turn calls the base constructor.

Next, implement the new control logic by inheriting from WorkItemControl. Now, define various methods required to handle the new control logic inside the inherit block.

Define an init method to handle the initialization of the control. The following code snippet creates a control that is based on the Html TextArea control.

Define bind and unbind events to handle the change in the control value. A Bind event defines the event handler for the change event – _onChange. The Bind event will bind the data from the underline field to the control. Unbind will remove the event handler binding. this._getField() refers to the bind field or the database field.

Define the change event handler to capture the new control value and assign it to the corresponding field. this._control[0] refers to the TextArea defined in the init section. this._getField() refers to the bind field or the database field.

Now, define the invalidate method, which will be triggered when there is any change in the underline field due to the other control logic or state change. Get the updated value of the field and bind to the control.

Now, register the module as a work item custom control using the TFS.WorkItemTracking.Controls.registerWorkItemControl() method.

The complete code snippet of our new TextAreaControl is as follows:

Create manifest file

With the Control logic implementation using Javascript now complete, we still need to define a manifest file, which defines the module, namespace, vendor and the Web site for more information. The manifest file will be an XML file with following schema:

Create JavaScript minified file

Every Web access control has one debug version of the JavaScript that can be used for future enhancements, and one ‘minified’ (reduced in size by removing anything not essential for execution) version of the JavaScript that will be used by TFS Web access at runtime. We can create the minified version of JavaScript using various tools. Here, the Web essence Minifier extension for Visual Studio has been used to generate the minified version of the JavaScript.

Create Package

We have the following three files associated with the new custom control:

  • JavaScript file
  • Minified version of the same JavaScript
  • Manifest file

Compress all these files into a single .zip file to create a new custom control package, which can be distributed and installed in TFS Web access.

Deployment
  • Open the Team Web access.
  • Navigate to the root admin section of the site
  • Select the Gear symbol (2128-1-9c7a0043-2648-44bc-9f46-2b1479081) in the top-right corner of the site to navigate to admin section or use the link http://tfsserver:8080/tfs/_admin
  • Click the ‘Extensions ‘tab and click ‘Install‘.

2128-1-284b930e-917b-4424-bfc6-f0f3b2813

  • Select the zip file in the install new Extension pop-up window.

2128-1-6d338aa6-d329-4fa8-827c-28fb49f8a

  • Click ‘OK’ to complete the installation process.
  • Click the ‘Enable link to enable the new control for usage.

2128-1-db7dc031-db01-4a56-ba56-3964ea106

Work Item Customization with TextAreaControl

Download the WIT template and the ‘Bug‘ template using the witadmin command and open the XML file in the XML editor to customize the WIT definition. Add a new field to the Bug template as:

Now, define the control using our new custom control, TextAreaControl:

Save the WIT definition file and import to TFS server. Now, create a new bug for the updated project and observe the new control.

2128-1-d89d6ec9-f7d8-42b8-a5cd-78d420aaf

Create New Web Access Control – Based on TFS Core Control

TFS has several core components that are defined in the TFS.UI.Controls.Common script file, which are not exposed to the work item level. When we create new custom controls, we can base them on these core controls, which have defined methods and proper styles. We will create, as an example, a new CheckboxListControl based on the TFS Core control CheckboxList.

We can specify the Module declaration and the construction definition as before. We can define our new control module as CheckboxListControl with dependent modules TFS.WorkItemtracking.Controls, TFS.core and TFS.UI.Controls.Common.

Now, we have to provide the init method to define the control based on the existing Core control TFS.UI.Controls.Common.CheckboxList. We will, however, then change the character used for delimiting the selected items and the handler for the change event. We will use a comma as the delimiting character.

To do this, we define the change event handler to get the checked values from the CheckboxList and join to a single string using comma, which will be assigned to the underline field.

We next define the invalidate method to bind the values to the CheckboxList. getAllowedValues() returns the values bind to the field using AllowedValues or SuggestedValues option. We use the SuggestedValues option to bind the values, which will allow us to select more than one options from the list. Moreover, retrieve the value from the underline field and mark the checked items in the list.

Define the getControlValue method to return the checked values joining using comma:

Now, register the control to the work Item tracking control collection.

Here is the complete code snippet for the new CheckboxListControl

Package & Deploy the CheckboxListControl

The next stage is to create the minified version of JavaScript using the minifier discussed earlier. Also, define the manifest file for the CheckboxListControl. Package the files into a zip file and deploy to the web access using the TFS web access extension.

Work Item Customization with CheckboxListControl

Download the WIT template for ‘Bug’ using the witadmin command and open the XML file in XML editor to customize the WIT definition. Add a new field called Days to the Bug template along with suggested values.

Now, define the control using our new custom control, CheckboxListControl.

<Control FieldName=”My.Days” Type=”CheckboxListControl” Label=”Days” LabelPosition=”Left” />

Save the WIT definition file and import to TFS server. Now, create a new Bug for the updated project and observe the new control.

2128-1-fcaad651-c49f-44d1-858c-178f252aa

Fallback mechanism

TFS supports different clients such as Team Web Access, Visual Studio and Microsoft Test Manager. We have created the custom controls for the Team Web access, where the fields will be displayed using the new control. This new control will not be available for the Visual Studio and it displays an error message shown as follows:

2128-1-ee415a15-04a0-4250-8783-97dad4bff

Either we need to develop a new custom control with the same name for the Visual Studio or else use an existing control as a fallback option. This fallback option requires you to specify a second control type for the control tag, which will be used if the first control isn’t available.

We use the new custom control to display the message field in Web access and use the fallback option to specify FieldControl for Visual Studio.

PreferredType is the option to specify the fallback control. If the TextAreaControl is not available in Web access or in Visual Studio, it will use the FieldControl to display the field. Now, the field is displayed using FieldControl in Visual Studio.

2128-1-5f960502-b7ec-4857-a0bf-a0b2cd246

Visual studio Control

Develop the work item custom control to support the work item management using Visual Studio. Unlike the TFS Web access control which will be deployed in TFS server, Visual Studio controls need to be installed in each individual user system. If most of the users are using Web access, then things are easier because we can limit the control development to Web access control with a fallback mechanism to a default control for Visual Studio. If we have more users who work on Visual Studio, then we must develop the control to support Visual Studio and distribute this control to every user on each deployment of the custom control for them to install in their user system.

Create Custom Control

Create a class library project using Visual Studio and add one UserControl. Add the reference to Microsoft.TeamFoundation.WorkItemTracking.Controls and Microsoft.TeamFoundation.WorkItemTracking.Client from the path [drive]:\Program Files\Microsoft Visual Studio 12.0\Common7\IDE\ReferenceAssemblies to the class library project.

We have created one custom control for web access, CheckboxListControl in our last section. We will create the corresponding visual Studio control now. Implement the IWorkItemControl and IWorkItemToolTip interfaces to the user control.

Before moving to the details of the interfaces, we will look into the basic implementation of the custom control. Our control is a checkboxlist control, so we must define the CheckedListBox control and initialize the properties of the control in a public constructor. Moreover, add the new control to the controls collection.

ToolTip and Label properties are declared in the IWorkItemToolTip interface. Label will be used for displaying the label and can be implemented using the automatic property.

The tooltip defines the tooltip of the control, which normally displays the HelpText associated with the field. Associate the field name to the tooltip of the label.

IWorkItemControl has following method declarations and properties to handle the life time of the control.

  • Clear();
    Clears the current value of the control

  • InvalidateDatasource();
    When there is any change in the field value, this method will get invoked to propagate the field change to the control. Get the field values and before setting the checked items, bind the allowed values or the suggested values to the control.

  • FlushToDatasource();
    Bind the control value back to the field

  • SetSite(IServiceProvider serviceProvider);
    Allows the platform to provide ServiceProvider implementation to the control, which we are not using for our custom control.
  • ReadOnly
    Defines whether the control is read-only or not, which is again not used for our custom control.

  • WorkItemFieldName 
    returns the work item field name corresponding to the control

  • WorkItemDatasource 
    Define the work item data source bound to the control

  • Properties Refers the collection of properties. This can be used for binding the custom control options and other properties.


  • These events will handle the changes done by the control itself and avoid the invalidation notifications.

The core implementation of the control is completed. The completed code snippet corresponding to our CheckboxListControl

Create wicc file

We need to create the metadata file corresponding to the manifest file for our Web control to define the assembly and the control. This file will be saved with an extension of .wicc.

Package and Deploy

Now, we need to package the Visual Studio class library as a Visual Studio extension or an MSI to distribute to the users. For testing, we can copy the dll and the wicc file to the location UserApplicationData\Local\Microsoft\Team Foundation\Work Item Tracking\Custom Controls\12.0.

Verify the new Custom Control

Now, open a new work item of type ‘Bug’ in Visual Studio, which is already bound to the CheckboxListControl as part of our web access custom control development. Observe the Checkbox control inside Visual Studio with values updated from Web access control.

2128-1-a0da4058-e1cb-4f82-929c-efa866262

Access Control

Access Control at Field Level

Sometimes, we need to control the access at field level. This can be implemented using the Rules associated with the field. In the following scenario, we have added the read-only constraint for all valid users and not for the administrators. This rule displays the field in read-only mode for all users except those in the Project Collection Administrators group.

2128-1-5c223baa-7de3-4191-bf5d-97c220403

We have other constraints such as Empty, Frozen or conditional using When and WhenNot, required and so on as part of the pre-defined rule set. We can use these constraints to restrict the field-level access for the user.

Access Control at Workflow level

Sometimes, we may need to allow only one specific group to create a work item and allow others to edit the work item once created. This kind of lifecycle level access privileges can be set at work flow level. Open the transition properties to define the access restrictions.

We can restrict the creation of a particular work item using the Workflow transition rules. The transition rule defined in the next figure shows that this specific work item can be created by only Project Collection Administrators and not by Project Collection Build Administrators.

2128-1-39ee005c-02f2-4ffa-983b-4b8d81213

Similarly, we can specify which groups are able to make updates to any specific work item using the transition-level management of access rights.

Conclusion

It is possible to customize TFS at different levels beyond the standard process templates. TFS provides standard controls but allows the end user to develop new custom controls in order to meet special requirements. We can develop custom work item controls to improve the usability aspects of both TFS Web access and Visual-Studio-based management of work items.

  1. [Process Editor]: Microsoft Visual Studio Team Foundation Server 2013 Power Tools
  2. [Web essence Minifier extension for Visual Studio]: Visual Studio Gallery: The Minifier
  3. [TFS 2013 WIT Custom Controls]: TFS 2013 Work Item custom Controls