Share via


Use templates to add and update work items in Azure Boards and Visual Studio

TFS 2017 | TFS 2015 | TFS 2013

Visual Studio 2019 | Visual Studio 2017 | Visual Studio 2015

With work item templates, you can quickly create work items that have pre-populated values for your team's commonly used fields. For example, create a template that defines the area path, iteration path, and activity to use when creating a task.

You can use work item templates to create work items or bulk update several work items. For examples that show usage of work item templates, see Sample work item templates.

Note

Work item templates are distinct from process templates. For information on process templates, see Choose a process template or these specific topics for the default process templates: Basic, Agile, Scrum, or CMMI.

Supported template tasks

The availability of template task options depends on the client and platform version available to you. Add and manage work item templates from the web portal or from Visual Studio 2015 or earlier versions. Visual Studio 2015 and earlier versions support working with templates by installing the Microsoft Visual Studio Team Foundation Server 2015 Power Tools. These templates only appear in your view of Team Explorer.

As shown in the following table, a ✔️ indicates the task is available from the web portal or from Visual Studio 2015 or earlier versions. (Make sure that you've selected the content version based on your platform version).


Task

Web portal

Visual Studio 2015


✔️

✔️


Manage work item templates
(Define, edit, delete, copy link, create copy, and rename)

✔️

✔️


✔️

✔️


✔️

✔️


✔️

✔️


✔️

✔️


✔️


✔️


Tip

The templates you define through the web portal are distinct from those you define through Visual Studio. Web portal templates can only be managed and applied to work items through the web portal. Similarly, Visual Studio templates can only be managed, viewed, and applied to work items in Visual Studio. However, you can use the URLs of both template types to add work items through the web portal.

Prerequisites

  • To add, capture, edit, or delete work item templates through the web portal, you must be a team administrator.

  • To apply a team template, you must be a Contributor of the project and a member of the team under which the work item template is defined.

  • To add, capture, or edit work item templates through Visual Studio Team Explorer, install the Microsoft Visual Studio Team Foundation Server 2015 Power Tools. These templates only appear in your view of Team Explorer.

Capture a work item as a template

The steps to capture a work item differ based on the platform, version, and client you use.

Templates captured through the web portal are assigned a GUID.

  1. From the web portal, open a work item that you'll use as the basis for a template.

    Within the web portal, work item templates are associated with a team. Only those templates that are defined for a team are accessible when you go to apply a template to work items using the web portal.

  2. Choose the actions icon to open the menu. Choose Templates and then Capture.

    Capture work item field definitions as a template

    Name the template and optionally define or clear fields. Save the template when finished. The template is saved under the team you selected in the first step.

    Capture template dialog

  3. Once you've saved the template, choose Copy link to capture the URL for the template that you can use to add work items using the template.

  4. Use the URL whenever you want to add a work item of the type you've defined with its predefined values.

    You can save the URL as a text file or add the URL to a dashboard or web page as a hyperlink.

Manage work item templates

You can view the list of templates defined for each work item type, and also add, edit, copy, delete, rename, and copy the link of a template. All templates are defined and managed for a team.

You manage templates from team settings. All templates are defined for a team. If you're not a team administrator, get added as one. Only team or project administrators can change work item templates.

  1. From the web portal, open settings for a team.

    Choose the gear icon to open the settings for a team.

    Here we open the admin page for the Web team.

    Open the admin page for the Web team.
  2. Choose Work>Templates.

    Open Work - Templates page for team

    From here, you can select any work item type to view or add templates for that type.

Manage templates for a work item type

  • Choose the work item type to view the templates defined for each type. For example, choose User Story to view templates defined to capture user stories.

    Manage user story templates

Create a work item template

  1. From the work item type page, choose the green plus icon New template to create a template from scratch.

    Add a user story template
  2. Name the template and optionally add and remove fields. Save the template when finished.

    Once you've saved the template, select Copy link to capture the URL for the template that you can use to add work items using the template.

  1. From the work item type page, choose the actions icon for an existing template to access the menu options to Edit, Delete, or Copy link.

    Open template action menu
  2. To rename a template, choose to edit the template, change the name, and then save your changes.

Create a copy of a template

  1. To duplicate an existing template, choose the actions icon for an existing template and select the Create copy option.

    Copy an existing template
  2. Name the template and optionally add and remove fields. Save the template when finished.

Delete a template

  1. From the web portal, open Project Settings>Team configuration>Templates.

  2. Choose the actions icon to open the menu, and choose Delete.

    Screenshot of Delete a template menu option.

  3. Choose Delete from the Delete template confirmation dialog that displays.

    Delete template confirmation dialog.

    As indicated in the confirmation dialog, you can't recover a template once it's deleted.

Add a work item using a template

The main method for adding a work item using a template is to open the template link within a browser window. To get the template link, see the next section Copy the link to a template.

You can share these links through email, a network share, or a team dashboard.

Use the URL whenever you want to add a work item of the type you've defined with its predefined values. Copy the link to a shared network or send to your team via email. Also, consider adding a link to the team dashboard.

  1. Choose the gear icon to open the settings for a team.

    Open team admin context

  2. Choose the Work>Templates tab. Then, choose the actions icon for the template you want to copy and select Copy link.

    Copy link of a template

    You can save the URL as a text file or add the URL to a web page as a hyperlink.

Apply a template to new or existing work item(s)

You can apply a template to a single work item or do a bulk update of several work items.

Apply a template within a work item

  1. Open the work item that you want to update using the fields defined within a template, choose the actions icon to open the menu, select Templates, and then select the name of a predefined template.

    Apply a template to an existing work item within the form

    Tip

    Refresh your browser to discover the latest templates that have been added. If you don't see any templates, it may be that there are none defined for the work item type.

  2. Save the work item for the changes to be applied. The fields changed are noted in the History field.

Apply a template to several work items

  1. To bulk update several work items, first select them from the backlog or a query results list, and then open the actions menu for one of them. All work items you select must be of the same work item type. For example, all user stories or all bugs.

  2. Choose the template to apply.

    Bulk update several work items

  3. Field changes are automatically applied and work items saved. To learn more about bulk updates, see Bulk modify work items.

Add or remove tags from templates

You can add tags to a template and they'll be applied to the work item when you use the template. To add two or more tags, delimit them with a comma (,).

Edit bug template, add or remove tags

If you don't specify tags to remove, then all tags present in a work item will remain defined. They'll remain defined even when you apply a work item template to an existing work item.

You can specify a work item template that specifies several field values using the following syntax. Use the URL whenever you want to add a work item of the type you've defined with its predefined values.

http://{ServerName}:8080/tfs/DefaultCollection/{ProjectName}/_workItems/create/{WorkItemType}?
[FieldReferenceName 1]={FieldValue 1}&
[FieldReferenceName 2]={FieldValue 2}&
[FieldReferenceName 3]={FieldValue 3}&
. . .

For example, the following syntax specifies a work item task with title TaskTitle. It specifies values for the Assigned To, Description, Tags, Activity, and Iteration Path fields.

http://{ServerName}:8080/tfs/DefaultCollection/{ProjectName}/_workItems/create/Task?
[System.AssignedTo]=Jamal+Hartnett&
[System.Description]=<p>Always+include+Remaining+Work+and+links+to+any+related+bugs+or+user+stories.</p>&
[System.Tags]=Web;+Phone;+Service&
[Microsoft.VSTS.Common.Activity]=Development&
[System.IterationPath]=Fabrikam+Fiber%5CIteration+1

Tip

There is a 2000 character limit imposed by some browser clients.

You can save the URL as a text file or add the URL to a dashboard or web page as a hyperlink.

You can add links to a Markdown widget that appear on your team dashboard in the web portal. These links open a work item with the template defined fields predefined.

For example, the following widget contains links to three templates.

Markdown widget with links to templates

To learn more about the Markdown widget see Add Markdown to a dashboard, Markdown widgets.