CreateNewWorkItem Task

By default, Team Foundation Build creates a work item if it detects a compilation error or static analysis failure. The CreateNewWorkItem task creates a 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

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

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

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 definition in the TfsBuild.proj file.

The <root>:\Program Files\MSBuild\Microsoft\VisualStudio\v9.0\TeamBuild folder on the Team Foundation Build computer contains the Microsoft.TeamFoundation.Build.targets file.

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 Project Tracking Data, Forms, Workflow, and Other Objects.

You must define a valid work item type for the CreateNewWorkItem task for build integration and you 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

You use the WorkItemFieldValues 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. The task fails if you specify an invalid value for a required field. For example, if you 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. It is set by the 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
         BuildNumber="$(BuildNumber)"
         BuildURi="$(BuildURI)"
         Description="The CreateNewWorkItem task created this bug."
         TeamProject"MyTeamProject"
         TeamFoundationServerUrl="http://MyTFServer.8080"
         Title="Bug in $(BuildNumber)"
         WorkItemFieldValues="$(WorkItemFieldValues)"
         WorkItemType="$(WorkItemType)" />
   </Target>
</Project>

The following example shows the default instance of the CreateNewWorkItem task as defined in the Microsoft.TeamFoundation.Build.targets file.

<CreateNewWorkItem
    TeamFoundationServerUrl="$(TeamFoundationServerUrl)"
    BuildUri="$(BuildURI)"
    BuildNumber="$(BuildNumber)"
    Description="$(WorkItemDescription)"
    TeamProject="$(TeamProject)"
    Title="$(WorkItemTitle)"
    WorkItemFieldValues="$(WorkItemFieldValues)"
    WorkItemType="$(WorkItemType)"
    ContinueOnError="true" />

See Also

Tasks

Customize Build Numbers

Concepts

Understanding Team Foundation Build Configuration Files

Other Resources

Team Foundation Build Targets, Tasks, and Properties

Index to XML Element Definitions for Types of Work Items