VSTS - Workitem Architecture, Design Considerations and Customization: Part 1
In VSTS terminology, workitem is the data representation of any abstract entity which needs to be tracked over a period of time. Workitems store the data in the form of records in Team Foundation Server. Each workitem once created store the status of various data elements like identification, state, creation date, change history, links, attachments, quantification of work done etc. Collectively they provide the status of the entire project. Each workitem is based upon the workitem type which is architected to store the data and the workflow related to the abstract entity which it is representing. Examples of workitem types include task, bug, risk, requirement, scenario etc. Everyone will agree that all of these need to be tracked over a period of time and sometimes over the entire length of the project.
This article is the first in the 3 part series:
Part 1: Workitem types: Architecture and Structure
Part 2: Design considerations for creation of new workitem types
Part 3: Customization of existing workitems: process and code changes
Workitem types: Architecture and Structure
Workitem types are defined in the Process Template. Each Process Template defines which workitem types will be supported in the Team Project created based upon that Process Template. Process Template also defines which workitems will be created in the Tam Project initially. These workitem types and workitems support the methodology encapsulated in the Process Template. Once the workitem types are created during the Team Project creation, it is possible to add new workitem types or to modify existing workitem types using tools WitExport and WitImport. Any modification done in the workitem type definition in the Process Template itself is effective in the new Team Projects created using that Process Template.
Definition of workitem type: Structure and data of the workitem type are stored in the database of the Team Foundation Server. We can get a representation of that in a XML file to view and modify for customization. To get the file representation of a workitem type in XML, from an existing Team Project, we can use WitExport command.
Workitem type is defined in three sections of xml file. The first section defines the data which is to be stored in the workitem and it is defined with the fields which will be available in the workitems. Second section defines the workflow that the workitem can go through. The third section defines the form which will be used to display the workitem of the type.
Fields Section: Fields define the data to be stored in the workitem which means that each field will have a name and a datatype. Those are provided as the attributes to the field definition element. Name has to be unique identifier for the field for the workitem type and the scope of the uniqueness has to be over the entire TFS. Length of field name can be upto 128 characters. Datatypes supported are the primitive datatypes like string, integer and double as well as some complex types as DateTime, PlainText, HTML, History and TreePath (to denote where in the area or iteration that workitem fits in. Additionally, the fields will have a RefName which the name by which the field will be known. The refname attribute has a value which provides a qualified name by which the field can be referred internal in the definition of the workitem. A refname has to be in the form of Qualifier Name.Common Name, for example SEED.StartTime. Qualifier names System and Microsoft are reserved. A general practice is to give name of the company. System qualifier is used for fields which store the data which are required to be present in every workitem type. Examples of System qualifier can be System.Name and System.AssignedTo. Microsoft qualifier is used to qualify fields which are more specific but are in the workitem types which are provided by default by Microsoft in the process templates which are packaged with VSTS.
We can also set the field to be reported by providing ‘reportable’ attribute. If the field is to be reported then we need to provide whether the field will be put in the OLAP cube as ‘dimension’, ‘measure’ or ‘detail’.
Fields can be made to adhere to certain pre-defined rules. These rules are: REQUIRED, READONLY, FROZEN (as soon as a field has a value after a commit the value can no longer be modified.), EMPTY, CANNOTLOSEVALUE, NOTSAMEAS (with a refname of other field), VALIDUSER (with or without specific group name), ALLOWEXISTINGVALUE, ALLOWEDVALUES, SUGGESTEDVALUES, PROHIBITEDVALUES, DEFAULT, COPY, SERVERDEFAULT, MATCH (with a pattern). These rules are given as sub-elements of the Field element.
Many of the rules can take attributes ‘for’ and ‘not’ with the names of the group or user for whom the rule is applicable and not applicable. This can help us in setting up a workflow for a scenario.
These rules can also be applied conditionally by using WHEN, WHENNOT, WHENCHANGED, and WHENNOTCHANGED elements. These rules define which elements are run when the defined clause is True. An example can be <WHEN field="refname" value="yyy">,which means that the rule encapsulated will be applicable as long as the field with refname has the value ‘yyy’.
Workflow Section: In a workitem, workflow is defined with the states and transitions of states. States have certain values and we can set the ALLOWEDVALUES rule to each of the states. When we mention the transitions from one state to other, we are putting the constraint that transitions other than those which are mentioned are not allowed. We have to provide one transition compulsorily. That transition is from nothing (denoted by “” as initial state) to any other state which we want should be the initial state of the workitem as soon as it is created. Every transition should have a reason for the transition associated with it. All the possible reasons should be defined in the definition of the transition. We may also give a default reason which may be used if the user does not explicitly select a reason while activating the transition. An example of a small workflow as mentioned in the documentation, with little modification can be:
<STATE value="Complete" />
<TRANSITION from="" to="Active">
<TRANSITION from="Active" to="Complete">
<REASON value="No Plans to Fix"/>
Transition is usually triggered by the user by selecting a state as target state. The field named State holds the values allowed for the state to be transitioned to. The allowed values after the rules are applied are filled in the dropdown control which represents the State field.
Transition can also be triggered by an “Action” element which is the subelement of transition element. The only action which is supported is checkin which can trigger the state transition. Example of such action definition is:
<TRANSITION from="Working" to="Ready To Build">
Any other action may have to be defined outside in a custom application.
Form Section: The last section in the workitem definition is the form in which the data can be shown. The definition of the form is somewhat similar to the HTML page where tags like <table> are used for layout. The highest container for all tags is <LAYOUT> tag. Within these there may be some grouping present with <GROUP> tags. It visibly demarks some groups of controls. It is like a frame control on the windows form. It may contain columns with <COLUMN> tags to divide it vertically. Each column has set width in the terms of % width of the total form width.
We can layout controls in the columns with <CONTROL> tags. We should link the data to be displayed or accepted in the controls by providing the FieldName attribute. Types of controls supported are FieldControl (Which displays field value in textbox or dropdown list if there is a <ALLOWEDVALUES> constraint on field.), TFStructureControl (To display iteration and area paths), WorkitemLogControl (to display the history of the workitem), LinsControl (to display the list of links of the workitem) and AttachmentsControl (to display the attachments list). Custom controls will be supported in the next version of TFS.
Optionally, the form may also have tabgroup and tabs. These are usually used to display the controls of history, links, attachment etc.
An example of form as provided in MSDN is as follows:
<Control Type="FieldControl" FieldName="System.Title" Label="Title" LabelPosition="Top" />
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Discipline" Label="Discipline"
<Control Type="TFStructureControl" FieldName="System.AreaPath" Label="Area" LabelPosition="Left" />
<Control Type="TFStructureControl" FieldName="System.IterationPath" Label="Iteration" LabelPosition="Left" />
<Control Type="FieldControl" FieldName="System.AssignedTo" Label="Assigned To" LabelPosition="Left" />
<Control Type="FieldControl" FieldName="System.State" Label="State" LabelPosition="Left" />
<Control Type="FieldControl" FieldName="System.Reason" Label="Reason" LabelPosition="Left" />
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Rank" Label="Rank" LabelPosition="Left" />
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.ShortDescription" Label="Summary"
<Control Type="WorkItemLogControl" FieldName="System.History" Label="Detailed Description and History"
LabelPosition="Top" Dock="Fill" />
<Control Type="LinksControl" />
<Tab Label="File Attachments">
<Control Type="AttachmentsControl" />
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.Issue" Label="Issue" LabelPosition="Left" />
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Common.ExitCriteria" Label="Exit Criteria"
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Build.IntegrationBuild" Label="Integration Build"
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.RemainingWork" Label="Remaining Work (hours)"
<Control Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.CompletedWork" Label="Completed Work (hours)"
This article is first in the series of three in which we will discuss about the workitems and their customization. It has laid the foundation by providing the documentation about what are the contents in any workitem type and options available to us.
In the next article we will discuss about the design considerations while creating the new workitem type. I hope this article was useful and I thank you for viewing it.
This article has been editorially reviewed by Suprotim Agarwal.
C# and .NET have been around for a very long time, but their constant growth means there’s always more to learn.
We at DotNetCurry are very excited to announce The Absolutely Awesome Book on C# and .NET. This is a 500 pages concise technical eBook available in PDF, ePub (iPad), and Mobi (Kindle).
Organized around concepts, this Book aims to provide a concise, yet solid foundation in C# and .NET, covering C# 6.0, C# 7.0 and .NET Core, with chapters on the latest .NET Core 3.0, .NET Standard and C# 8.0 (final release) too. Use these concepts to deepen your existing knowledge of C# and .NET, to have a solid grasp of the latest in C# and .NET OR to crack your next .NET Interview.
Click here to Explore the Table of Contents or Download Sample Chapters!