SmartWord4TFS Step-by-Step Guide

Size: px

Start display at page:

Download "SmartWord4TFS Step-by-Step Guide"

Benedict Sherman
6 years ago
Views:

1 Guide

2 CONTENTS Overview... 3 Key Takeaways... 3 Working Modes... 4 User Interface... 4 Ribbon Bar... 4 Ribbon Bar options in Template Designing Mode... 4 Ribbon Bar options in Template Designing Mode... 6 Smart Panel... 8 Key Concepts... 9 What is a control?... 9 What is a Smart Part? Smart Parts in Template Designing Mode Smart Parts in Document Authoring Mode Connecting to TFS Creating a template using Wizard Creating a template manually Adding Controls By Double-click By Right-click Creating Smart Parts All rights reserved Page 1 of 65

3 Auto Create Smart Parts Selection based Smart Parts Saving Template Running Queries on Work Items Getting Work Items from Team Project Publishing Work Items on Team Project Publish all work items Publish selected work items Refresh Work Items Refresh All Work Items Refresh selected Work Items Auto Tag Auto Tagging for forms style Auto Tagging for tables style All rights reserved Page 2 of 65

OVERVIEW SmartWord4TFS is a Microsoft Word add-in that integrates Microsoft's Team Foundation Server in a Word Document. It allows users to create and manage Work Items in their favorite application.

4 OVERVIEW SmartWord4TFS is a Microsoft Word add-in that integrates Microsoft's Team Foundation Server in a Word Document. It allows users to create and manage Work Items in their favorite application. In this way users can get the functionality of TFS while staying in the familiar and user friendly environment of Microsoft Word. The documents created using the add-in can be reused by other stakeholders including Business Analysts, Project Managers, top-level management etc. KEY TAKEAWAYS Individuals will learn the following from this tutorial: Working Modes User Interface (Ribbon Bar options & the Smart Panel) Key concepts Creating a template using Wizard Running Queries Getting Work Items Smart Part Creation Publish Work Items Refresh Work Items Auto Tag existing documents to get Smart Documents All rights reserved Page 3 of 65

5 WORKING MODES The SmartWord4TFS works mainly in the following two modes: 1. Template Designing Mode In this mode a user designs the overall structure of a Word template deciding which Work Items would be available in the template and how they would be shown in the template. 2. Document Authoring Mode In this mode a user actually adds the data (i.e. Work Items) in the Word document/template that is managed in a Team Project on TFS. The options for each mode are grouped separately in the Ribbon Bar as described in the next topic. USER INTERFACE RIBBON BAR After installing the SmartWord4TFS, a new tab named SmartWord4TFS is added in the Ribbon Bar. Although most of the Ribbon Bar options in the tab are same for both Working Modes; a few options differ between these modes. RIBBON BAR OPTIONS IN TEMPLATE DESIGNING MODE Choose Process Template: Used to connect the document/template to a TFS Library, Team Project or a Local project. Wizard: Invokes a step-by-step wizard to create a template easily. Show Process Template: Used to show the Process Template in the Smart Panel. The Smart Panel enables users to create the Smart Parts in the template. Get Work Item: Used to fetch new Work Items from TFS that have not been added in the template yet. Publish: Publish the new Work Items (created in the template) to TFS Queries: Runs a query on Work Items to bring the desired ones into the template/document. Refresh: Refreshes the template to include any changes applied to Work Items on TFS. Remove Team Project: Breaks the link between document/template and the connected team project. All rights reserved Page 4 of 65

6 Open in Web Access: Opens the selected Work Item info (as it appears in TFS)/ or team project info in a browser window. Edit Work item: Opens a new window to edit the selected Work Item of the template. Show All Links: Shows a list (in the Smart Panel) of all the Work Items linked with the Work Item currently selected in the template/document. Auto Create Smart Part: Used to create Smart Parts automatically by detecting the controls added in the template Create Smart Parts: Used to create Smart Parts based on controls selected by the User Clear Smart Parts: Used to delete all of the Smart Parts created in the template Insert Smart Part*: Used to add the desired Smart Part in the template MakeSub: Creates a parent child relationship with the upper level Work Item. Visually, adds indentation for the relevant control UnSub: Removes the parent child relationship. Visually removes the indentation for the relevant control. Add Row: Adds a new row in the Smart Part (originally created in tabular format) Add Bullet: Formats a Content Control as a bullet in the Smart Part Control Properties: Displays the properties of the selected control in the Smart Panel. Document Data: Displays the association and properties of Work Items in the Smart panel, as authored in the document Convert To Text: Converts the bulleted data in a Rich Text Content Control into plain text Auto Tag: Converts a Word Document (in a pre-defined format) into a Smart Document with potential Work Items that can then be published to TFS. Feedback: Used to provide feedback from users. The details of the feedback are stored in a Feedback Work Item created in TFS. Discussion Board: Used to view/enter comments for a selected Work Item Project Information: Shows the connected Team project properties in a popup window. Help: Opens the.chm Help file Get Started: Invokes the relevant tutorial video page on the Modern Requirements' website Support: Invokes the support FAQs page on the Modern Requirements' website Send a Smile: Send positive feedback to the SmartWord4TFS Team Send a Frown: Send negative feedback to the SmartWord4TFS Team SmartWord4TFS: Shows the About splash screen for the SmartWord4TFS. * This option appears in the Ribbon Bar only after a Smart Part has been created in the template. Note: Get Work Item, Publish, Refresh, Document Data, Validate and Open in Web Access options are enabled in Template Designing mode only when document is connected to a Team Project. For TFS Library & Local connections these options remain disabled. All rights reserved Page 5 of 65

7 RIBBON BAR OPTIONS IN TEMPLATE DESIGNING MODE Choose Process Template: Used to connect the document/template to a TFS Library, Team Project or a Local project. Show Process Template: Used to show the Process Template in the Smart Panel. The Smart Panel enables users to create the Smart Parts in the template. Get Work Item: Used to fetch new Work Items from TFS that have not been added in the template yet. Publish: Publishes the new Work Items (created in the SmartWord template) to TFS Queries: Runs a query on Work Items to bring the desired ones in the template/document. Refresh: Refreshes the template to include any changes applied to Work Items in TFS. Remove Team Project: Breaks the link between document/template and the connected team project. Open in Web Access: Opens the selected Work Item info (as it appears in TFS)/ or team project info in a browser window. Edit Work item: Opens a new window to edit the selected Work Item of the template. Show All Links: Shows a list (in the Smart Panel) of all the Work Items linked with the Work Item currently selected in the template/document. Insert Smart Part: Used to add desired Smart Part in the document/template that was created in Template Designing Mode. MakeSub: Creates a parent child relationship with the upper level Work Item. Visually, adds indentation for the relevant control UnSub: Removes the parent child relationship. Visually removes the indentation for the relevant control. Add Row: Adds a new row in the Smart Part (originally created in tabular format) Add Bullet: Formats a Content Control as a bullet in the Smart Part Control Properties: Displays the properties of the selected control in the Smart Panel. Document Data: Displays the association and properties of Work Items in the Smart panel, as authored in the document Convert To Text: Converts the bulleted data in a Rich Text Content Control into plain Text Auto Tag: Converts a Word Document (in a pre-defined format) into a Smart Document with potential Work Items that can then be published to TFS. Feedback: Used to provide feedback from users. The details of the feedback are stored in a Feedback Work Item created in TFS. Discussion Board: Used to view/enter comments for a selected Work Item Project Information: Shows the Team project properties in a popup window. All rights reserved Page 6 of 65

8 Help: Opens the.chm Help file Get Started: Invokes the relevant tutorial video page on the Modern Requirements' website Support: Invokes the support FAQs page on the Modern Requirements' website Send a Smile: Send positive feedback to the SmartWord4TFS Team Send a Frown: Send negative feedback to the SmartWord4TFS Team SmartWord4TFS: Shows the About splash screen for the SmartWord4TFS. For more details about the modes of SmartWord4TFS please refer to.chm Help available in the SmartWord4TFS Tab. All rights reserved Page 7 of 65

9 SMART PANEL The Smart Panel appears at the right hand side of MS-Word after a connection to a team project has been established. This panel is primarily used to add Work Item related controls to a template/document. However the same panel is also used to show different kinds of information (e.g. Linked Work Items, Control Properties etc.). All rights reserved Page 8 of 65

10 KEY CONCEPTS WHAT IS A CONTROL? A control is a property of a Work Item that is added at the desired position in a document/template. Available controls for a Work Item depend upon the Process Template associated with the document/template. The available controls (ready to be added) are shown in the Smart Panel and the added controls are shown in the document/template user area. Unlike the XML Schema in a document, the controls in the Smart Panel do not have a hierarchy. Feature Title control (in the template): After the control has been added in the template, it appears like this (when selected). Feature Title control (in Smart Panel): Like other controls of the process template, this control can be added in the document/template wherever desired by the user. All rights reserved Page 9 of 65

11 WHAT IS A SMART PART? A Smart Part is a collection of controls that belong to the same Work Item. In Template Designing Mode initially users add relevant controls from Smart Panel and then create a Smart Part. After the Smart Parts have been created, users can directly add them from Ribbon Bar using Insert Smart Part option. In Document Authoring Mode, the Smart Parts created in the design mode become available as a Ribbon Bar option. Users can then insert the desired Smart Part at the selected location in the document. SMART PARTS IN TEMPLATE DESIGNING MODE The following image shows 2 Smart Parts i.e. Issue & Risk All rights reserved Page 10 of 65

SMART PARTS IN DOCUMENT AUTHORING MODE After the template (showing the Smart Parts in the above image) has been saved and opened in the Document Authoring Mode, the two original Smart

12 SMART PARTS IN DOCUMENT AUTHORING MODE After the template (showing the Smart Parts in the above image) has been saved and opened in the Document Authoring Mode, the two original Smart Parts are still in the template (2), while new instances of these Smart Parts can be added (1) in the template using Ribbon Bar option Insert Smart Parts. All rights reserved Page 11 of 65

13 CONNECTING TO TFS Template Designing Mode offers multiple options to connect to TFS; details of which are available in the SmartWord4TFS Help. However for simplicity, we are only discussing the process to connect to a Team Project in this guide. This process is mainly used in Document Authoring Mode. Connecting to TFS is the first logical step after a document/template is created, because most of the options in the Ribbon Bar remain disabled until a connection with TFS is established. 1. Click the Choose Team Project option in the Ribbon Bar. All rights reserved Page 12 of 65

Contact your Network Administrator or relevant person about the required information.

15 Upon successful connection, other options in the SmartWord4TFS Tab become enabled, while the Choose Team Project option becomes disabled. * During this step you may be asked to enter some validation information. Contact your Network Administrator or relevant person about the required information. Note: For Template Designing Mode or for general Word Document use, the user needs to select Team Project option after Step 1. The rest of the process is same. All rights reserved Page 14 of 65

CREATING A TEMPLATE USING WIZARD Designing SmartWord templates using the Wizard is the most user-friendly way of creating a template using SmartWord4TFS.

16 CREATING A TEMPLATE USING WIZARD Designing SmartWord templates using the Wizard is the most user-friendly way of creating a template using SmartWord4TFS. While other methods are more suited for a particular type of user, this method suits both novice and experienced users alike. 1. Create a new template and save it with a suitable name. 2. Connect the template to a Team Project. 3. Click the Wizard Button in the Ribbon Bar. All rights reserved Page 15 of 65

19 7. Select the desired Section Type, to determine how the Work Item would be displayed in the SmartWord template/document. 8. Select the desired field from the available list and include it in the Smart Part using the arrow button. Users can select multiple fields by holding down the Ctrl key and clicking all of the desired fields from the list. All rights reserved Page 18 of 65

The Selected Fields list displays all the fields included in the Smart Panel. 9.

21 10. Arrange the selected fields in the desired order (using arrow buttons) and customize them (if desired). 11. Give a heading for the selected fields as you want it to appear in the SmartWord template/document. The Heading could be given using Section Heading (1) or selected from the drop down control (2). All rights reserved Page 20 of 65

23 The template is created as per the settings of the Wizard. Note that the State property is not shown in the template, as it was marked as Hidden. The details of hidden properties can be seen in the SmartWod4TFS Help CREATING A TEMPLATE MANUALLY The previous section discussed the process to create a template using the Wizard. In this section we will discuss how to perform the process manually. While the Wizard automates many of the tasks, if we do them manually we have to do each individually ourselves. The following list contains all of the tasks that are required to create a template manually: 1. Adding Controls 2. Creating Smart Parts 3. Saving the template ADDING CONTROLS 1. Open a new document/template. 2. Connect it to a Team Project. All rights reserved Page 22 of 65

24 Now the available Work Item Controls are shown in Smart Panel. These can be added in the template using two ways. By Double-click By Right-click BY DOUBLE-CLICK This is the easiest way. Using this method Controls are added with default settings. 3. Format the document as desired. This includes adding text that would elaborate the controls, Setting their appearance (Font, Paragraph settings etc.). Now place the cursor at the desired location in the document where the Work Item Control should be appearing. All rights reserved Page 23 of 65

BY RIGHT-CLICK This is the advanced method. Using this method Work Item Controls are added with desired settings chosen by the user. 3. Format the document as desired.

27 BY RIGHT-CLICK This is the advanced method. Using this method Work Item Controls are added with desired settings chosen by the user. 3. Format the document as desired. This includes adding text that would elaborate the Work Item Controls, Setting their appearance (Font, Paragraph settings etc.). Now place the cursor at the desired location in the document where the control should be appearing. All rights reserved Page 26 of 65

4. In the Smart Panel, right-click on the

The Work Item Control is added in the template with the selected settings. 6. Similarly, proceed to add all of the desired Work Item Controls in the document.

30 The Work Item Control is added in the template with the selected settings. 6. Similarly, proceed to add all of the desired Work Item Controls in the document. CREATING SMART PARTS Creating Smart Parts is the most important task after the desired controls have been added in the template. SmartWord4TFS has two slightly different options to create Smart Parts: Auto Create Smart Parts Selection based Smart Parts As the name suggests, Auto Create Smart Parts is used to create the Smart Parts automatically. Users only have to click the relevant option. The template is parsed and the detected Smart Parts are created automatically. All rights reserved Page 29 of 65

For Selection based Smart Parts option, users have to first select all of the Controls belonging to a particular Work Item, and then upon clicking the Selection based Smart Parts option, that Smart

31 For Selection based Smart Parts option, users have to first select all of the Controls belonging to a particular Work Item, and then upon clicking the Selection based Smart Parts option, that Smart Part is created. In this way each Smart Part is created individually. AUTO CREATE SMART PARTS 7. After adding the desired controls in the template, click the Create Smart Parts Button and then the Auto Create Smart Parts option. The following message box is displayed. All rights reserved Page 30 of 65

32 8. Click the desired button on the message box. All the Smart Parts detected in the template are created. SELECTION BASED SMART PARTS 7. Select all of the Work Item controls of a particular Work Item. 8. Click Create Smart Parts à Selection based Smart Parts option in the Ribbon Bar. All rights reserved Page 31 of 65

SAVING TEMPLATE Saving a template enables the user to author/design it later on. The template should be saved in the default location (as shown in the above image) and with the default extension (.

35 SAVING TEMPLATE Saving a template enables the user to author/design it later on. The template should be saved in the default location (as shown in the above image) and with the default extension (.dotx). Users can also save a template before creating Smart Parts, but the template should be re-saved after creating Smart Parts in order to save the changes. After saving the template, it should be closed, so that it can be opened in Document Authoring Mode. All rights reserved Page 34 of 65

36 RUNNING QUERIES ON WORK ITEMS Running queries on Work Items is useful if the document is to be populated from the existing Work Items saved on TFS. SmartWord4TFS supports 2 types of queries: 1. Custom queries saved on TFS (My Queries) 2. Default queries available on TFS (Shared Queries) The process to run each type of query is similar and is described below: 1. Open the desired document and connect it to a Team Project. 2. Place the cursor where the desired Work Items are to be displayed (in case of successful query). 3. Click the Queries option in the SmartWord4TFS Tab in the Ribbon Bar. All rights reserved Page 35 of 65

37 4. Select desired type of query from the drop down menu. The Query Dialogue Box appears with the following checkboxes: Without smart content: If selected, the query is to be inserted as tables with plain text; the values in the table will not be smart content. Insert at cursor position: If selected, the query is to be inserted at the current cursor location, otherwise it will be inserted at the end of the document. Insert query block only: If selected, an empty query control is added in the document without any Work Items (refer to the image at the bottom of the page). The query control can be refreshed later on, to be filled with the relevant Work Items. 5. Set the desired check boxes and Click the OK Button. All rights reserved Page 36 of 65

39 GETTING WORK ITEMS FROM TEAM PROJECT SmartWord4TFS offers users a two-way information exchange with your TFS Team Project. Users can not only publish Work Items to a Team Project, but they can also get Work Items from a Team Project. The Work Items can be fetched in three modes: Flat List: without any linked Work Items Tree of Work Items: with Work Items that are associated with the selected Work Item Work Items and Direct Links: with Work Items (plus their child Work Items) that are associated with the selected Work Item The desired mode is selected from the Result Type control at the bottom of the Smart Panel. The fetched Work Items can be placed in the document at the cursor position or at the end. The placement of the Work Items depends upon the relevant check box at the bottom of the Smart Panel. All rights reserved Page 38 of 65

40 The data could be fetched without smart content if the objective is to minimize the elapsed publishing time. Note: For a particular template/document, users can only get the types of Work Items in accordance with those that were used while creating the template. e.g. if a template was created for only the Risk Work Item, then other types of Work Items cannot be imported into it. The process to get Work Items is described in the following steps: 1. Create some Work Items in a Team Project. These should be of a type that is supported by your template/document. 2. In Word, place the cursor where you want the imported Work Item to be displayed in the document. 3. Click the Get Work Item option in the SmartWord4TFS Tab in the Ribbon Bar. All rights reserved Page 39 of 65

4. In the Smart Panel provide details for the desired query and

The Work Item is imported into the document as per the

PUBLISHING WORK ITEMS TO A TEAM PROJECT After entering values in the Smart Parts they are ready to be published as Work Items to the connected Team Project.

46 PUBLISHING WORK ITEMS TO A TEAM PROJECT After entering values in the Smart Parts they are ready to be published as Work Items to the connected Team Project. SmartWord4TFS offers two distinct ways to publish work items to TFS: Publish all work items Publish only selected Work Items PUBLISH ALL WORK ITEMS 1. Click the Publish Button (Icon above the text - as shown in the following image) in the SmartWord4TFS Tab in the Ribbon Bar. 2. Enter comments (if desired) and then click the Yes Button to confirm publishing to a Team Project. All rights reserved Page 45 of 65

Given that there are no invalid values in the controls of the Smart Parts, the respective Work Items are published to the Team Project. 3. Click the OK Button to close the message box.

47 Given that there are no invalid values in the controls of the Smart Parts, the respective Work Items are published to the Team Project. 3. Click the OK Button to close the message box. PUBLISH SELECTED WORK ITEMS 1. Select the desired Work Item(s) in the document. The selection means placing a cursor in a control (for a single Work Item), partially selecting a Work Item or completely selecting multiple Work Items. All rights reserved Page 46 of 65

49 2. Click the Publish option (Text below the icon - Step 1 as shown in the following image) and then the Publish Selected option (Step 2) from the drop down menu. The remaining process is same as described for publishing all Work Items. REFRESH WORK ITEMS If a user applies some changes to Work Items in the TFS Team Project, then these updates can be reflected in the SmartWord document using the Refresh option. In other words, the Refresh option is used to bring the document in sync with the updates of the Work Items done in the TFS Team Project. Users can refresh all Work Items at once or only the selected Work Items. REFRESH ALL WORK ITEMS 1. Apply the desired changes to the Work Items in the TFS Team Project using Visual Studio or any other application. 2. Click the Refresh option (Icon above the text - as shown in the following image) in the SmartWord4TFS Tab in the Ribbon Bar. All rights reserved Page 48 of 65

Select the relevant Work Items in MS-Word.

50 The fields are updated in the document as per updates done in the Team Project. REFRESH SELECTED WORK ITEMS 1. Apply the desired changes to the Work Items in the TFS Team Project using Visual Studio or any other application. 2. Select the relevant Work Items in MS-Word. The selection means just placing a cursor in a control (for a single Work Item), partially selecting a Work Item or completely selecting multiple Work Items. All rights reserved Page 49 of 65

52 3. Click the Refresh option (Text below the icon - Step 1 as shown in the following image) and then the Refresh Selected option (Step 2) from the drop down menu. The selected Work Items are updated in the document as per updates done in the TFS Team Project. AUTO TAG Importing existing Word documents into TFS and creating Work Items for each line of content is a major hurdle for enterprises. Previously SmartWord4TFS users have to manually tag each distinct piece of content in order to create the respective Work Items from the document. The new Auto Tag feature automates this process. Now users can create Smart Documents out of their existing Word Documents in just 3-4 clicks. The Auto Tagging feature can work with two types of documents: Where data is arranged in forms style Where data is arranged into tables style AUTO TAGGING FOR FORMS STYLE No particular format is required for the document, however it should be arranged in a manner that the text that is destined to become the name of Work Item, should be formatted as a Heading. Each Heading level can be a distinct type of Work Item (e.g. in our example Level 1 Heading would become a Feature Work Item and Level 2 Heading would become Requirement Work Item. The Rich Text between two consecutive headings can be treated as the description or any other property (depending upon user selection) of the above Work Item. All rights reserved Page 51 of 65

53 To create a Smart Document out of an ordinary Word document, follow these steps: 1. Open the desired Word Document. 2. Connect the document with desired Team Project. 3. Select the desired content area in the document. All rights reserved Page 52 of 65

4. Click the Auto Tag option in the Ribbon Bar. 5.

56 6. Set the desired Work Item for Level 1 Heading. 7. In the next drop down menu select the desired rich text field. This field would map against the relevant property of the Work Item (selected in the previous step). All rights reserved Page 55 of 65

57 8. Repeat the last two steps until all of the heading levels are accounted for as relevant types of Work Items. 9. Click the Apply button. The auto-tagging process is completed. Clicking inside the relevant text shows the corresponding tag as shown in the following image. All rights reserved Page 56 of 65

58 The contents of the Smart Document can now be published to TFS as Work Items using the Publish option. After publishing the Work Items can be accessed in the relevant Team Project All rights reserved Page 57 of 65

AUTO TAGGING FOR TABLES STYLE Previously, users could only tag plain text (formatted into headings), however the Auto Tagging feature is now also available for tables.

59 AUTO TAGGING FOR TABLES STYLE Previously, users could only tag plain text (formatted into headings), however the Auto Tagging feature is now also available for tables. With the help of tables, users can quickly create a large number of work items, within little time. Each table in the document can represent only one type of Work Item. If the user wants to create many types of Work Items from a single document he should create a separate table for each type of Work Item. The process to use Auto Tagging for a table style document is described in the following steps: 1. Open the desired document or create a new one. All rights reserved Page 58 of 65

2. Connect the document to a Team Project. 3.

Map the columns of the table to relevant

8. Repeat the last two steps until all of the tables have been accounted for, and then click

9. Click the Publish option in the Ribbon Bar to publish the values in the tables as

edev Technologies SmartWord4TFS Release Notes

edev Technologies SmartWord4TFS Release Notes edev Technologies 3/14/2017 Table of Contents 1. SYSTEM REQUIREMENTS... 2 2. APPLICATION SETUP... 4 3. NEW FEATURES... 5 4. ENHANCED FEATURES... 5 5. KNOWN