Brain dump on CreateNewWorkItem task for Team Build

Lately there have been a lot of questions about CreateNewWorkItem task. Today I will be sharing some details of this task.

Team Build opens a new work item on detecting a compilation error or static analysis failure (build break). MSbuild task is expected to update the work item “FoundIn” field with the current build number and will have the pointer to the detailed log file in description/history field. The task is defined as:-

<CreateNewWorkItem

          BuildId="$(BuildNumber)"

          Description="$(DescriptionText)$(BuildlogText)$(ErrorWarningLogText)"

          TeamProject="$(TeamProject)"

          TeamFoundationServerUrl="$(TeamFoundationServerUrl)"

          Title="$(WorkItemTitle)"

          WorkItemFieldValues="$(WorkItemFieldValues)"

          WorkItemType="$(WorkItemType)"

          ContinueOnError="true" />

Semantics of the input arguments

WorkItemType

A team project is created with a particular methodology (process template) and each methodology defines different type of work items. For example MSF Agile methodology is shipped with the Bug, Quality of Service, Risk, Scenario and Task type of work items while CMMI methodology defined the work items of the type Bug, Change Request, Issue, Requirement, Review, Risk and Task. Do note that you can also define your own type by customizing/modifying the existing WorkItemType definition. Using this property you can pass the type of work item you want to create on build break. 

How will you know what type of work item to create?

 

We expect the work item to be of the valid type. A valid work item will always define “FoundIn” field. If you do not know what type of work item to create, then you can leave this property empty. We will try selecting the best one for you. The logic in the code is

• Check for the user specified type for the given team project. It the type is valid then create the work item otherwise fail.
• Is user has not specified the work item and the $(WorkItemType) property is empty, search for the “bug” type (default). Do note that “bug” string is localized so if you have a setup where server (AT) and build machine (BM) are of same locale then (i.e JPN) things will work file.
• If the AT and BM are of different locale and we can not find the default type of work item, we will try to iterate through all the work item types defined for the team project and will select the first valid work item type. The disadvantage of this approach is that it is possible that team build will create different type of work items (on build breaks) for different team projects. Fortunately the possibility of this happening is very remote.

WorkItemFieldValues

Using this property, user can specify the field values of the bug. This is a semicolon separated list of name, value pair. For example if you want to set priority =1, severity=2 and rank =0, you need to define the msbuild property:-

<PropertyGroup>

<WorkItemFieldValues>

priority =1; severity=2; rank =0

</WorkItemFieldValues>

</PropertyGroup>

 

Do note the following important points

• • If user specified the field name that does not exist, we will ignore the corresponding <name, value> pair. For example if you want to set severity field to 1 but severity is not defined in the work item type, we will ignore the input.
  • User is expected to pass the required values that do not have default values. For example, I want to create a bug of the type “Defect” on build break. In the definition of Defect (defect.xml), Priority is the required field that can have the value from the range {0, 1, 2, 3}. The Defect (work item definition) does not specify any default value for priority. We expect you to pass the proper value using this field.
  • If the user has passed invalid value of field (i.e he wants to set the priority to 5 in the example mentioned above), task will fail.
  • Task makes sure that user specified values will take precedence over value set by team build or default values defined in work item type. For example if user wants to overwrite title of the work item, he can pass the value using the given property.

<PropertyGroup>

<WorkItemFieldValues>

priority =1; severity=2; title =”Custom title”

</WorkItemFieldValues>

</PropertyGroup>

Please note that the title of the newly created bug will be “Custom title” instead of the value of $(WorkItemTitle).

• • Please note that it is not possible to set all the properties for the work item using task. I will demonstrate this for different scenarios by giving different examples -
    • User can not set the “CreatedBy” field of the work item because it is read only and is set by Currituck OM (object model).
    • User can not set the “State” field because Currituck OM can not have multiple start states. The schema of the workItem has work flow defined which clearly defines this value. We can not set it even through UI. I had a hard time figuring it out. I wanted to create bug type of work item (with "Active" state) for a team project with CMMI type methodology. Bug type definition had “Proposed” as the default start state. I tried passing the state value using MSbuild property WorkItemFieldValues but it failed. I verified that the “Active” was the valid value for state and is defined in the schema. Later Neeraj told me that Workflow of the bug allowed only one state for the bug (while creating). I will write about these transition rules in different blog entry.

I will not be enumerating about the other input arguments because they are pretty much self explanatory and there is nothing special about them.