HowTo use Word4TFS Plug-in

Background

Word4TFS is an add-in to Microsoft Word to be able to extract information from TFS Work Item sto a Word document. The tool is created by Rob Jarret an ALM Ranger. You can get information about the add-in and installation files at https://vsarword4tfs.codeplex.com/

If you want to create a document you can do in one out of two ways. Either you start with a document where you want to insert TFS information or you start with a blank Word document, imports the TFS information and then writes the rest of the text.

How to use the tool

Open the document where you would like you TFS data. Place the cursor where the data should be inserted. Choose the menu Team and click Import.

Three dialog boxes will be shown – see below (I have removed some blank spaces to reduce the image size).

Choose which Team Project to connect to. This is the same dialog you use in Visual Studio so you should be familiar with it.

In this dialog you choose what Query to use to fetch work item data from TFS. The sorting will be taken from this query. In this case I have chosen the query called New Query 1.

Finally you choose which layout of the work items you want. In the right pane you see a preview of how it will look, with just fake data.

When you press Finish the document will be populated with the data from TFS. If it is a log of work items it could take a while. You can make several inserts in the same document, for example you might want a list in the beginning of the document and then details later in the document. That can be reached by inserting the same data with two different layouts.

About layouts

The layouts are stored as regular Word data in a .dotx file called Word4TFSSystemTemplate.dotx in the folder C:\Users\<user>\AppData\Roaming\Microsoft\Templates. The path can vary a bit if it is not an English version of Word. If the buttons Import and Show Layout Designer is disabled the reason could be that the template file is not found by the Word Add-in. The solution is to find the file and copy it to the path mentioned above. You can find more information in the tool web page.

If you want to edit and create new layouts you have to know some basics. You get to the layouts by using the Team ribbon menu and then clicking the button “Show Layout Designer” which will then show as a docking window in Word. The designer clearly states that it consists of two parts, Layouts and TFS Work Item Fields (Edit Layout). To get the list of TFS fields you have to connect to the Team Project you want to create the layout for by using the link in the second part.

Each layout consists of a number of “building blocks”. A building block is a layout for a certain work item type and that building block will be used for that particular work item type. Each building block starts with a headline that has the exact name of the work item type and that has a Style (font size, color, etc) that is called “TFS Work Item Definition”. In the image below the Style is marked red in the upper right and then all the sections are also marked red.

In the image above we see four building blocks. First it is the Default building block that is required and cannot be empty. This is applied to all work item types that does not have its own building block. In this example a Bug would use the Default building block. Then there are two specific block for the work item type “Product Backlog Item” and “Task”. In these building blocks there are static text and fields that are inserted from the field list at the right and this is where the TFS data will be inserted. In the example there are three fields for Product Backlog Item and these are marked with green: Title, Description and Effort. All formatting in the layout will reflect in the document created using the layout.
The Preview block is not used to insert work item data; it is used to show the user a preview in the third dialog box shown above. All text in the layout from Preview and below till not appear in the generated document. In the sample above I have used a special notation and that is Product Backlog Item_0 that is <workitemtype>_n. This is used to make it possible to have different layouts in different levels in a hierarchy. You can have one layout for the Product Backlog Item at the root level (level 0) and another for the next level.

All the text that is above the Default building block and from the Preview building block and below will not appear in the generated document. However if you just insert data from TFS in a blank document the tool will insert a text before and after the inserted data that makes it a bit easier to start writing your own text at the right places. These texts starts with “Start of import…” and “End of import…”.

I find this tool really useful, especially to have data in one place – TFS – and be able to generate documents that are more reader-friendly to for example a stakeholder or a customer.

Advertisement

TFSBranchTool command-line released

Now the ALM Rangers project I am participating in has released the first part – the Command-Line utility to create a branch plan. http://blogs.msdn.com/b/visualstudioalm/archive/2012/10/26/quick-response-sample-command-line-utility-to-create-tfs-branch-scenarios.aspx

We are right now working on a Visual Studio Extension to be able to do the same things from within Visual Studio – it will be really nice!

The code is available, and I think it is really interesting since it uses the Managed Extensibility Framework – MEF that is a part of the latest .NET Framework 4.5 – Take a look at it!

First beta-release of Rangers project

This week we released the first beta version of the work with ALM Rangers. This is a Branching Tool that makes it easier to adopt the branching guidance. For more information, see Willys blog

http://blogs.msdn.com/b/willy-peter_schaub/archive/2012/09/28/extend-the-project-creation-process-to-promote-ranger-branching-guidance-sprint-3-feedback.aspx

Participation in exciting new Rangers project

I have started to take active part in the ALM Rangers that is a community that tries to help people use the Visual Studio products in a better way. The Rangers provide guidance like the popular Visual Studio TFS Branching Guidance, but also code samples and simple tools. The 197 Rangers also contribute to the community with their personal small projects.

Recently I was pinged by the Rangers because they wondered where I had gone. I had gone “dark” since I started my new job, but now I have started to work with the Rangers again. Started a new project at September 1st that is supposed to run for a couple of months. This is my first project as a contributor so it is really exciting. The team is located all over the world: Moscow, New York, Florida, Vancouver, Borlänge and Östersund. It is a challenge to get things working, but using Lync to communicate and have weekly meetings makes it possible. We also use the new TFS Service that Microsoft is providing which is a must-have for this kind of distributed team.

As soon as I can I will reveal what we are doing, but for now it is secret – that is just to not build up any expectations that cannot be held. It is also interesting to reflect over the challenges with working this distributed.

Upgrading TFS 2008 Work Items to 2010 version

Today I have been working with applying new features from TFS2010 to old TFS2008 work items. The approach I have chosen is to take the Microsoft CMMI version 5 as a base, and adding fields we added in the 2008 version of the process template. Then I tried to import the new definition using the witadmin command. The first issue was due to the fact that Microsoft changed some field names adding white space. You can solve this in two ways. Either you change the name of the fields in your definition file as described in this blog post http://www.chrismay.org/CategoryView,category,Programming,TFS.aspx or you use the Witadmin changefield command to change the name of the existing fields.

Another thing that caused some confusion was when trying to import Test Case. It worked fine, but when trying to create a workitem of this type I got an error that said “Work item type is not valid. You must specify a valid work item type.”

Really strange since when importing the workitemtype the workitem type was valid! So I started to search the web and found a hint about the new concept about Categories. So I first imported the categories and tried to create a test case again. But no – it did not work. I had to import the Test case Wit again before it worked. So I found some kind of “catch 22” syndrome here, that since you cannot import categories before the workitem type exists, and the workitem does not work until the categories have been imported. So this is what you need to do (omitted some parameters – collection and project)

1 – witadmin witimport testcase.xml
2 – witadmin importcategories categories.xml
3 – witadmin witimport testcase.xml

Remember that you need to refresh the project if you have Team Explorer opened. If you encounter strange errors it can be the cache that is corrupted. Delete the cache folder in c:\documents and settings\<your username>\Local Settings\Application Data\TeamFoundation\3.0

Good luck!

Customizing the TFS Agile Workbooks

I have been working with customizing a process template for our company. This is a real challenge since there are so many aspects to this, and many are not known until later when the template is in use. It can then be hard to change it if you have been using it in a lot of TFS projects. I have been making different customizations since 2005 and I strongly advise you to put a lot of thinking effort into this work to make sure you do not end up with something that brings you more work…

In my work with a new corporate template for TFS2010 I have been using the Agile template as a base, but want to have more states since we think Active and Closed are just not enough. Also we want to make a template that could work both for Agile (Scrum) teams, for more traditional waterfall based approach and for maintenance projects. You could discuss a lot whether this is a good approach or not – but one additional thing that comes into place is how our TFS projects are structured. We have been creating TFS Projects for almost all of our software projects that mostly lead to a new system. This system always interacts with several other systems, both on the Windows platform and other platforms. In new projects several systems are involved which means you get a TFS project that “sends out” Change Requests to other TFS projects. This means that in the end it is really useful to be able to put together reports and queries that spans several projects. This also means that we use a terminology that is a bit Agile but does not use the “heaviest” Scrum terms. So for example we want to use “Effort” instead of “Story Points” to be more flexible.

We have also been influenced by the MS Scrum template and got rid of query structure of Iteration 1, Iteration 2, and Iteration 3 and replaced it with Current Iteration instead. A renaming and minor change in the queries was also made. One of the most useful new things I have come across so far in the 2010 release is the Agile Workbooks, with Iteration Backlog as the most valuable and Product Planning as the next. So we really want to have people use these since it brings more productivity into their work. So I ended up with a need to customize the Product Planning workbook in several ways.

* Replace “Story Points” with “Effort”
* Change the formulas to use more than two states, meaning that there is not such a distinct difference between Active and Closed
* Different names and folder structures in the Queries

I have also checked with Microsoft, and these customizations are supported.

The first two changes I have written about in a blog post called Howto Customize Product Planning Workbook

The third change is described in the blog post Necessary Customizations when changing Query Names in TFS Process Template

Howto Customize Product Planning Workbook

The reasons for me customizing the Product Planning Workbook can be found in the blog post called Customizing the Agile Workbooks

To get the customized workbook to be created and tied to each new TFS Project you need to customize the empty workbook in the process template. To do this you first have to download the template. This can be done in Team Explorer by right-clicking on the root node (collection) and choose Team Project Collection Settings, Process Template Manager. In the dialog shown, choose the template you want to customize and click Download. The template is written to a directory, and under this you can find the Product Planning Workbook in the folder

First of all I needed to replace “Story Points” with “Effort” in the query and the formulas. This showed up to be made in two places. First a change in the actual query file Product Planning.wiql where I simply replaced the field. Then to change this in the Product Planning Workbook. Not so suprisingly the workbook consists of some Macro code. It turns out that this code is based on values that can be found on a hidden tab in Excel. So this is how you easily change this:
1 – Open up the Product Planning.xlsx file. Find and press on the Macro button to the right end of the Ribbon called Show (at least that is a direct translate from the Swedish Visa).
2 – Choose to Edit the Macro. A Visual Basic for Applications window is shown. Make sure to mark the Microsoft Excel-object LocalizableStrings. At the bottom of the properties windows you can find the Visible property. Change this from “xlSheetVeryHidden” to “xlSheetVisible”

3 – Switch back to Excel. You can now see and edit an Excel sheet called LocalizableStrings. Here I have change two values. First I change “Story Points” in cell B5 to “LFEffort” which is the field name for the Effort field I have added in my workitems. Then I change Active to Closed in the cell C2. I will explain why later on.

4 – Get back to the Macro sheet and change back the visible property on the LocalizableStrings worksheet to “xlSheetVeryHidden”. Take caution here because when you change the property to hidden the tool will automatically change to another visible sheet. First I thought I did not change the property and ended up hiding all sheets…
5 – Secondly I needed to adjust how the sheet actually calculates the values in “Planned” and “Delivered” cells in the Iterations sheet. I found out that the formulas for this is created during project creation. And the state value is taken from the cell C2 in the LocalizableStrings sheet mentioned above. Since I have changed my state machine from Active+Closed to Proposed+Active+Resolved+Closed I need to find a way to have these values to be calculated in a correct way. The default behavior means that Planned is the workitems with State=Active and Delivered is State<>Active. The easiest way to customize this is to have Planned be State<>Closed and Delivered to be State=Closed. With the change in the LocalizableStrings sheet I have been able to change Active to Closed, but to switch the operators I have to do a change in the code that puts the formula together. This can be found in the module called ProductBacklog. In the code you can find a Sub called UpdateFormula. At the end of this Sub there are two calls to UpdatePointsColumn where the operator is the last parameter. So I simply switched these to get the desired behavior. Se image below.

6 – Switch back to Excel and bring up the first sheet and position the marker in the call A1. I did not do this at first so when the workbook was initialized during project creation the table for Product Backlog was created in the wrong sheet…

The only thing that now needs to be done is to upload the new process template using the reverse of what I explained at the beginning of this post. If you do process template customizations I really encourage you to use Source Control for all changes and not download and upload the workitem definition, but only use upload. In this way you get a controlled way doing this – and the possibility to roll back changes you do not want since you have the previous version in hand.

I have not yet needed to customize the Iteration Backlog workbook, but I might need to – and then I will write a blog post about that as well. 

Necessary Customizations when changing Query Names in TFS Process Template

The reasons for me customizing the Product Planning Workbook can be found in the blog post called Customizing the Agile Workbooks

What I wanted to do was to change the query folders and query names in our process template. We wanted to have just a few necessary queries and make sure people used them instead of having a lot of queries where it is hard to find the ones that you need. So when I renamed the folder Iteration 1 to Current Iteration and got rid of the folders Iteration 2 and Iteration 3 I thought it was going to be fine. Our query structure now looks like this:

However I ended up with some problems with the Iteration Backlog workbook. When trying to upload the process template and create a new project I got an error. The “Iteration 1/Iteration backlog” query was not found. So this was because I renamed the Query folder to Current Iteration. So where can you change this? Since the workbooks reside in the Documents folder they are actually stored in Sharepoint. So my first place to look was in the Windows Sharepoint Services folder of the process template. The WssTasks.XML file seems to be the configuration file that controls the creation of the portal and then also the “binding” of the Agile workbooks to the newly created project. I have to admit I was a bit scared that the customization of this had to be done in code in some of the Tasks for creating the portal, but I did not have to worry. In the WssTasks.XML file I found the node <files> and under that a row that defines the file Iteration Backlog. And in that definition there is a pointer to the Query. So I just had to change to the correct folder name – and it all worked just fine!

<file
source=“Windows SharePoint Services\Shared Documents\Project Management\Iteration Backlog.xlsm“
documentLibrary=“Shared Documents“
target=“Current Iteration/Iteration Backlog.xlsm“
queryId=“Current Iteration/Iteration Backlog“ />

WebDeployproblem – error message not obvious

We have been using WebDeploy along with Beta 2 of TFS for some while. We have a local IIS installed on the WebServer and the build is taking the settings from this IIS when preparing the deploy package.

Last week we installed the RC of Visual Studio and TFS. Instead of upgrading the Build server we installed a new one. Besides from the problem with Build Defintions that I blogged about we had one peculiar problem. We got an error when building that said:
C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.targets (1650): The “MapUriToIisWebServer” task failed unexpectedly.
When making a search on “MapUriToIisWebServer” I found one (!) reference – how often does that happen! It referenced to the Connect site and a bug report. This told me a workaround would be to uncheck “Apply server settings to all users” on the Web tab of the Project Properties. I made this change and now it worked. Satisfied with solving that I went on with next thing without giving much thought to this…

However, things started to become strange to another user, that settings were not preserved and so on. So we started looking at this a bit more and realized what the checkbox actually did, when uncechking some settings were removed from the project file and ended up in a personal setting instead – not what we wanted.

So we started digging into this. A local build in VS worked. So to track down the error I went to the build server trying to do the same build. And this is when things started to show up. Loading the web project that contained the webdeployment did not work. An error message similar to this appeared:

The components it complained about was the IIS 6 Management Compability and some more stuff related to IIS 6. So I ended up looking at Vishal Joshis blog post about Basic Microsoft Web Deployment Tool Setup For Visual Studio 2010 and ended up installing some role services. First I tried to add the things he highlights but ended up added everything with Security and everything with IIS 6 as well as the Management Service.  

Now I was certain it would work, but I ended up with another error that is pretty new and unfamiliar to a Windows XP user:

I checked, and the account I was running under was an administrator. Then I realized I was not running the process as administrator. So right-click and say “Run as administrator” made the trick. Now it works.

A long way to a pretty simple error, but the first indication of the error was not that obvious…

Solving build problems after upgrading from Beta2 to RC

If you like me did not read the upgrade manual thoroughly before trying to run your existing Beta2-builds in TFS 2010 RC you might have encountered some or all of these problems. (Upgrade manual can be found in this post http://blogs.msdn.com/bkrieger/archive/2010/02/03/tfs-2010-beta2-to-rc-upgrade-guide.aspx)

Build ends with the following error: File not found: C:\Windows\Microsoft.NET\Framework\v4.0.21006\MSBuild.exe
If you look in the Framework folder you notice that the RC of .NET Framework is in a folder called v4.0.30128 – so of course the files cannot be found.
In the upgrade guide, chapter 5 – point 3 you can read that you have to update your Build templates. It also says to create a new project and take the templates from there. One point that is not that clear in the guide is that if you create a new project in a Collection that was created under Beta2 you will get the Beta2 templates. So you will have to create a new Collection and then create a new project in that collection to be able to get a hold on the new Build templates. So the steps in chapter 5, point 2 is what you should do for the build templates as well.
I also made the obvious mistake not the check-in the new templates after adding them, so I did not find the new templates at first. Luckily I have made this error several times, so I knew how to solve it 😉

Since we installed a complete new Build Server with the RC version we ran into the following problem as well.
When using Lab Management you have several Agents. So when configuring your builds you might point to the Build Server as described in this post https://tomasscott.wordpress.com/2010/01/09/default-setting-might-cause-problems-with-tfs2010-builds/
Remember to change that value for the build server as well as the value on the tab Build Defaults.

Enjoy the RC!