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