Introduction To Work Item Customisation

QLD VSTS Users Group – February Meeting

Presented by William Bartholomew

William Bartholomew

Is the Developer Productivity Specialist at TechnologyOne. Improves developer productivity through education,

processes and tools and implementing Visual Studio Team System is a key aspect of this.

Has been developing software solutions for 9 years primarily using Visual Studio, the .NET Framework and SQL Server.

Was a technical reviewer for the 2nd Edition of Steve McConnell's Code Complete as well as Volume 2 of Brad and Tamara Abram's .NET Standard Library Annotated Reference.

Is a member of: ACM (Association for Computing Machinery) IEEE (Institute of Electrical and Electronics Engineers, Inc.) IEEE Computer Society and IEEE Standards Association (IEEE-SA) Microsoft User Interface Framework Advisory Council (ASP .NET,

Windows Forms, WPF, etc.)

Agenda

Introduction Adding a Field

Exporting a Work Item Type Adding a System Field Defining a New Field Modifying the Form Verifying and Importing a Work Item Type

Customising Workflow Defining Business Rules Defining New Work Item Types Customising Work Item Web Page Real-World Examples Conclusion

Introduction

Process templates ship with a number of work item types: Agile – Bug, Quality of Service Requirement,

Risk, Scenario, Task CMMI – Bug, Change Request, Issue,

Requirement, Review, Risk, Task You can customise existing work item

types. Or, you can create your own work item

types.

Introduction

Work item types are defined using XML. Defines the fields, workflow and form

layout for a work item type. Schema documented in the Team

Foundation Administrator’s Guide: http://msdn2.microsoft.com/en-us/library/

aa337661(VS.80).aspx

Adding a Field

Export the work item type you want to add the field to.

Define the field. Verify the work item type. Import the work item type. Refresh the work item type cache. Test.

Exporting a Work Item Type

witexport.exe /f <Filename> /t <TeamFoundationServerName> /p <TeamProjectName> /n <WorkItemTypeName> Optionally: /exportgloballists

Adding a System Field

System fields always exist for all work item types. Used for cross work item type queries.

List system fields: TFS Administrator’s Guide

http://msdn2.microsoft.com/en-us/library/ms194971(VS.80).aspx

witfields.exe view System fields can be explicitly referenced in work

item types. The definition must match the field’s existing definition. Allows defining different business rules in different work

item types.

Using an Existing Field

Allows you to use fields from other process templates (e.g. use a CMMI field in an Agile project) or from other work-item types.

Same process for using a system field.

Defining a New Field – Name

What’s in a name? Field Name

User visible Free form text Can be changed by the Team Foundation Server administrator

Reference Name Used internally and for integration (APIs etc.) Free form text Best practice is to use namespace format (e.g.

T1.Adf.ReleaseNotes) Can’t be changed

You can specify help text using the HELPTEXT element.

Defining a New Field – Type

Choose a type String (single line up to 255 characters) Integer Double DateTime PlainText (multi-line string) HTML (multi-line string with formatting) History (discussion thread and change log) TreePath (used for iteration and area only)

Can’t be changed once the field is added

Defining a New Field – Reporting

Reporting for duty Sir! Specified using “reportable” attribute: Not Specified – Won’t be included in the warehouse Dimension – Included in the warehouse as a

categorization Detail – Included in the warehouse but not the cube Measure – Included in the warehouse as an aggregate

(sum) Can’t be changed once set. Setting the value only affects new work items,

existing work items won’t be updated in the warehouse unless modified.

Defining a New Field – Changing

If you need to change one of the attributes that is not changeable then you must remove and re-add the field definition. This requires removing it from ALL work

item types referencing it. Any data stored in the field will be lost.

Try to get the field definition correct from the beginning.

Defining a New Field – Example

<FIELD name="Category" refname="MyCompany.MyProcess.MyField" type="String" reportable="Dimension“ />

Modifying the Form – Layout

Group Must contain at least one column. Has a border. Has an optional label. Multiple groups are “stacked”.

Column Allows you to arrange controls side by side. Supports a splitter to allow resizable columns.

TabGroup and Tab Creates a typical tab control.

Modifying the Form – Main Controls

FieldControl Single line. Best for String, Integer, Double and

DateTime data types. Rendered as either a text box or a combo

box. HtmlFieldControl

Multi-line. Best for PlainText and HTML data types. Supports formatting (if the field does).

Modifying the Form – Other Controls

TFStructureControl Only used for Area and Iteration (i.e. TreePath fields). Rendered as a tree combo.

WorkItemLogControl Only used for History. Rendered as a date/time stamped list. Also contains change log.

LinksControl Used to link work items to other artefacts and/or

hyperlinks. Doesn’t have a “backing” field.

AttachmentsControl Used to link work items to arbitrary files. Doesn’t have a “backing” field.

Modifying the Form – Custom Controls Standard Windows user control. Implements IWorkItemControl from

Microsoft.TeamFoundation.WorkItemTracking.Controls.dll.

Special XML file called <ControlName>.wicc tells Visual Studio where to load the control from.

DLL must be deployed on all developer workstations. All developer workstations must be running Service

Pack 1. More information:

http://blogs.msdn.com/narend/archive/2006/10/02/How-to-use-Custom-Controls-in-Work-Item-Form.aspx

Verify and Import Work Item Type

witimport.exe /f <Filename> /t <TeamFoundationServerName> /p <TeamProject>

Verify rather than import: /v

Work item type definitions are cached by Visual Studio so you will need to refresh Team Explorer.

Customising Workflow – Introduction

States Rules

Transitions From State To State Reasons Rules

Initial states are those with a transition from the “” (null) state.

Active Resolved

Closed

Customising Workflow – In Practice

The work item editor shows a list of transitions with the work item’s current state as the from state.

When changing state: Must choose from one of the reasons

associated with the transition. A default is used by default if an alternate isn’t

chosen. Must meet any business rules associated

with the transition and destination state.

Customising Workflow – Security

Transitions can be restricted by security group: “for” attribute – Allow a group “not” attribute – Deny a group “not” has a higher precedence than “for”.

Customising Workflow – Integration

When assigning work items to a changeset you can choose which transitions to execute on the assigned work items.

When customising a work item type you can choose which transitions are eligible for this functionality: <ACTIONS>

<ACTION value="Microsoft.VSTS.Actions.Checkin" /></ACTIONS>

Defining Business Rules – Available Rules Required ReadOnly Empty Frozen CannotLoseValue NotSameAs ValidUser AllowExistingValue Match

Defining Business Rules – Defaults

Default Only used if the field is empty. Field Value Clock CurrentUser

Copy Always used. Field Value Clock CurrentUser

ServerDefault Default is always used, field appears read-only on form. Clock CurrentUser

Defining Business Rules – Lists

Lists: AllowedValues SuggestedValues ProhibitedValues

Using AllowedValues results in a DropDownList, otherwise a Combo.

Values can be enumerated in the list definition. Or, can be stored in a global list which can be reused. Global lists can be exported with glexport or using

the /exportgloballists switch on witexport. Global lists can be imported with glexport or as part

of a work item type using witimport.

Defining Business Rules – Where Used Rules can be nested inside:

Field – The rule must always pass. State – The rule must always pass when

the work item is in this state. Transition – The rule must pass when the

work item is moved using this transition. Reason – The rule must pass if the reason

is used.

Defining Business Rules - Conditional

Conditional rules: “for” attribute – Defines the security groups that

the rule applies to “not” attribute – Defines the security groups

exempt from the rule “not” has a higher precedence than “for”.

WHEN element – Apply rules based on the value of a field being equal to a value.

WHENNOT element – Apply rules based on the value of a field not being equal to a value.

WHENCHANGED element – Apply rules only if a field has changed.

Defining New Work Item Types

Simply combine all these concepts into a new XML file.

Beware, work item types cannot be deleted or renamed!

Always test in a sandpit project or even better server.

Store your work item type definitions in Source Control so you can track changes.

Customising Work Item Web Page – Before

Available by going to: http://server:8080/WorkItemTracking/

WorkItem.aspx?artifactMoniker=<WorkItemNumber>

Customising Work Item Web Page

Generated by XSL:%ProgramFiles%\Microsoft Visual Studio 2005 Team Foundation Server\Web Services\WorkItemTracking\v1.0\Transforms\WorkItem.xsl

Backup the original XSL. Backup your new XSL. It may be

overwritten by service packs, upgrades, etc.

Real-World Examples

TechnologyOne Customised the agile work item types to include

fields for storing Release Notes. Customised the task workflow to mimic the bug

workflow. Custom work item types for tracking QA issues.

Conchango Have created a set of custom work item types for

the Scrum methodology. http://scrumforteamsystem.com

Real-World Examples – Microsoft

Real-World Examples – Microsoft

Real-World Examples – Microsoft

Conclusion

Just do it!

Teamprise 2.0

Teamprise is a suite of client applications for accessing Microsoft Visual Studio 2005 Team Foundation Server from outside of the Visual Studio Integrated Development Environment (IDE).

Teamprise enables software development teams to use the source control, work item tracking, documents, and reporting features of Team Foundation Server from within the Eclipse IDE, and from other operating systems, including Linux and Mac OS X.

A big thanks to our friends at Teamprise for their support of our user group. Visit them at http://www.teamprise.com

Contributor Prize free license of Teamprise 2.0 valued at

USD$499

Member Discount QVSTSUG members get a 12% discount

when purchasing on-line from our website (http://www.stpsoft.co.uk/vsts). To use the discount, enter the coupon code QVUG015 on the on-line order form screen.