Welcome to Day 9 of the “100 Days of DevOps with PowerShell”!. For background on our goals in this series, see Announcing the “100 Days of Devops with PowerShell” Series here at SCC.
In my previous post, “PowerShell and Team Foundation Server 2013 – Getting Started”, I showed how you can use the Team Foundation Server Power Tools PowerShell cmdlets to work with Team Foundation Server 2013. As we saw, however, those cmdlets are mostly designed to work with only the version control aspects of TFS. TFS also has a very rich work item tracking system, that integrates with the version control system, which can be used to track all the work related to the project. In this post, I will show how to use PowerShell, in conjunction with another TFS Power Tools tool, to create new work items in TFS.
There is no PowerShell command to directly access the TFS Work Item Tracking (WIT) system. Instead, I will use PowerShell to call TFPT.EXE. TFPT.EXE is a command-line tool that consists of 20 commands that provide the ability to work with TFS version control, work item tracking, and team projects. If I run the command tfpt.exe workitem /?, then I can see the various switches available for this command:
For this scenario, I want to create a new Task work item in TFS. Reviewing the help information shows me that I will want to run a command similar to this:
tfpt.exe /new <WorkItemTypeIWantToCreate> /collection: <TFSCollectionIWantToUse> /fields: <FieldsIWantToPopulateOnTheNewWorkItem>
Armed with this knowledge, I can now create a simple PowerShell script to create my new Task:
#Load TFS PowerShell Snap-in
if ((Get-PSSnapIn -Name Microsoft.TeamFoundation.PowerShell -ErrorAction SilentlyContinue) -eq $null)
#TFS Server Collection
[string] $tfsServerCollection = "http://r2-09-tfs:8080/tfs/DefaultCollection"
#Set Variables For the Task
[string] $workItemType = "TestTeamProject\Task"
[string] $taskTitle = "Sample Task Title"
[string] $description = "Sample Description"
[string] $assignedTo = "Mickey Gousset"
[string] $areaPath = "TestTeamProject"
[string] $iterationPath = "TestTeamProject"
#Combine field variables into key/value pairs
[string] $taskFields = "Title=$($taskTitle);Description=$($description);Area Path=$($areaPath);" $taskFields += "Iteration Path=$($iterationPath);Assigned To=$($assignedTo)"
#Create the task work item
$wiOutput = tfpt workitem /new $workItemType /collection:$tfsServerCollection /fields:$taskfields
#Strip out TFS work item number
$wiSplitOutput = $wiOutput.split()
$wiNumber = $wiSplitOutput
Write-Host "The TFS work item number is: $wiNumber"
The script starts off by loading the TFS PowerShell snap-in, if it is not already loaded. Next I define the TFS server project collection that I want to connect to. Keen observers will note that I am not specifying the team project I want to use, just the collection (which can contain multiple team projects). Don’t worry, you will specify the team project in just a moment.
Next, I define the work item type I want to create. For this example, I want to create a Task work item. When specifying the work item type to create, I need to specify it as <TeamProjectName>\<WITName> (See, I told you we would be specifying the team project in a moment). Then I need to specify the different fields for the work item, such as Title, Description, etc.
Once I have specified the different fields, I need to combine them into a set of key/value pairs, for use with the TFPT command. To do this, I need to know the name of the fields I will be setting in the work item. The easiest way to gather this information is to use the Process Editor that is part of the TFS Power Tools. In Visual Studio 2013, select TOOLS | Process Editor | Work Item Types | Open WIT from Server. In the window below, I select my Project Collection, my Team Project, and then the Task work item type:
Clicking the OK button opens the Task WIT in a tab in Visual Studio:
From this tab I can get the Task WIT field names for use in my key/value pairs, as well as the field type, which will be helpful for ensuring the data I insert into those fields is correct.
Once I’ve configured the key/value pairs, I can now execute the TFPT command. This command returns the phrase “Work item # created”, where # is the work item id from TFS. More than likely, I’m going to want to use this id somewhere else, or store it in another system. Therefor, the last couple of lines of the script extract the work item id into a variable, where I could then use it later in my process.
If I execute my script, I get the following output:
If I go to Visual Studio and execute a work item query to return all tasks, I can see Task 4, which matches the work item I just created:
This post has shown the basics of how to create a new work item in Team Foundation Server, using PowerShell and the TFS Power Tools. You could use this script as part of a larger process. For example, let’s say I am using System Center Service Manager to track incidents in my work environment. I could create a workflow in Service Manager, such that, whenever an incident of a particular type is created (perhaps related to a specific application), the workflow uses the PowerShell script above to create a new work item in TFS, related to this incident, and then stores the TFS work item ID in the incident. I could then create other workflows, perhaps using System Center Orchestrator, to watch for changes to either the Incident or the work item in TFS, and update the other work item as appropriate. Hmmmm, sounds like a good idea for a future PowerShell DevOps post, don’t ya think?
Next up though, I’m going to dive into how to use PowerShell and the Team Foundation Server API to interact with Team Foundation Server 2013.
To see the previous installments in this series, visit “100 Days of DevOps with PowerShell”.