Share via

CreateNewWorkItem Task

  • Article

By default, Team Foundation Build creates a new work item if it detects a compilation error or static analysis failure. The CreateNewWorkItem task creates a new work item of the specified type and with the specified title and description. The Microsoft.VSTS.Build.FoundIn field is set to the value of BuildId property, and any custom field values specified in the WorkItemFieldValues property are set as specified.

Parameters

Property Description

BuildId

Specifies the Team Foundation Build build number. 

Description

Specifies the work item description. The default value of this property is specified in the TfsBuild.proj file of the build type as follows:

<!-- Description for the work item created on build failure -->
    <DescriptionText>This work item was created by Team Build on a build failure.</DescriptionText>

TeamProject

Specifies the team project name.

TeamFoundationServerUrl

Specifies the Team Foundation Server URL. For example, https://MyServer:8080.

WorkItemFieldValues

Specifies a list of field names and values for the created work item.

Specify these values as a semicolon separated list of name, value pairs. For example if you want to set priority=1, severity=2, and rank=0, define the MSBuild property as follows in the XML shown here:

<PropertyGroup>
<WorkItemFieldValues>
priority =1; severity=2; rank =0
</WorkItemFieldValues>
</PropertyGroup>

Title

 
Specifies the work item title.

WorkItemType

Specifies the work item type. For example, "bug."

This must be a valid work item type. If this property is not defined, the default work item type is bug.

Remarks

The CreateNewWorkItem task is defined in the Microsoft.TeamFoundation.Build.Tasks.VersionControl.dll. The Microsoft.TeamFoundation.Build.targets file contains an instance of the CreateNewWorkItem task that Team Foundation Build uses as a default implementation for the CreateWorkItem target. You can also customize the build process by defining a different instance of the CreateNewWorkItem task for a build type in the TfsBuild.proj file.

Microsoft.TeamFoundation.Build.targets file is stored in the <root>:\Program Files\MSBuild\Microsoft\VisualStudio\v8.0\TeamBuild folder on the Team Foundation Build computer.

Valid Work Item Types

Each team project is created with a particular methodology. In Team Foundation, the MSF for Agile Software Development methodology defines Bug, Quality of Service, Risk, Scenario, and Task work item types. The CMMI for Process Improvement methodology defines Bug, Change Request, Issue, Requirement, Review, Risk, Scenario, and Task work item types. You can also define your own work item type by customizing an existing work item type definition. For more information, see Customizing Work Item Types.

A work item type that is defined for the CreateNewWorkItem task must be valid for build integration and must define a FoundIn field. For more information, see Adding Integration Fields in Work Item Types.

Default Behavior

If you leave the WorkItemType property undefined, the CreateNewWorkItem task uses the Bug work item type.

Notes on WorkItemFieldValues Property

The WorkItemFieldValues is used to specify the field values of the work item as a semicolon separated list of name, value pairs. If you specify a field name that does not exist, the corresponding <name, value> pair is ignored. For example if you want to set the severity field to 1, but severity is not defined in the work item type, the input is ignored.

If the work item that you define has required fields without default values, you must provide values in the WorkItemFieldValues property. For example, the Defect work item type has a required field that is named Priority. The values of Priority are 0, 1, 2, or 3 and no default setting is specified. If you specify an invalid value for a required field, for example, set the Priority to 5, the CreateNewWorkItem task fails.

You cannot specify the CreatedBy and State fields of the work item. The CreatedBy field is read-only and is set by work item tracking object model (OM). The State field cannot be specified because the work item tracking OM cannot have multiple start states.

Example

The following example sets the WorkItemFieldValues in the TfsBuild.proj file for the work item created on build failure.

<WorkItemFieldValues>Area Path=$(AreaPath);Iteration Path=$(IterationPath);Severity=1;Priority=0;Symptom=build break;Steps To Reproduce=Start the build using Team Build;Source=Development;How Found=Build Break;Assigned To=Jim Wilson</WorkItemFieldValues>

The following example uses the CreateNewWorkItem task in the TfsBuild.proj file, to create a custom work item on build failure.

<!-- Add the UsingTask to the top of the TFsBuild.proj file after the schema definition-->
<UsingTask TaskName="Microsoft.TeamFounadtion.Build.Tasks.CreateNewWorkItem"
   AssemblyFile="$(TeamBuildRefPath)\Microsoft.TeamFoundation.Build.Tasks.VersionControl.dll" />
<!-- Add the following XML after the closing </ItemGroup>-->
<!-- and before the closing </Project>-->
</ItemGroup>
   <PropertyGroup>
      <BuildNumber>BuildType_Date.1</BuildNumber>
      <WorkItemFieldValues>Priority=1:Severity=2</WorkItemFieldValues>
      <WorkItemType>Bug</WorkItemType>
   </PropertyGroup>
   <TargetName="CreateWorkItem">
      <CreateNewWorkItem
         BuildId="$(BuildNumber)"
         Description="The CreateNewWorkItem task created this bug."
         TeamProject"MyTeamProject"
         TeamFoundationServerUrl="https://MyTFServer.8080"
         Title="Bug in $(BuildNumber)"
         WorkItemFieldValues="$(WorkItemFieldValues)"
         WorkItemType="(WorkItemType)" />
   </Target>
</Project>

See Also

Tasks

How to: Customize Build Numbers

Concepts

Team Foundation Build Tasks

Other Resources

Customizing Team Foundation Build
Team Foundation Build Targets, Tasks, and Properties
Work Item Type Schema Reference