Use templates to add and update work items

Azure Boards | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015 | TFS 2013 | Visual Studio 2015

With work item templates you can quickly create work items which have pre-populated values for your team's commonly used fields. For example, you can create a task template that will set the area path, iteration path, and discipline or activity whenever you use it to create a task.

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.

For example usage of work item templates, see Sample work item templates

Prerequisites

  • To add, capture, edit, or delete work item templates through the web portal, you must be a member of the team under which you add them.
  • To apply a work item 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, 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.

Capture a work item as a template

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

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

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

    Capture work item field definitions as a template, vsts

    Name the template, select the team for which you want to save it under, and optionally define or clear fields. Save the template when finished.

    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.

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

    Within the web portal, work item templates are associated with a team. Only those templates defined for a team are accessible when working in a team context, either through a work item form or bulk update context menu.

  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.

If you connect to an on-premises TFS and primarily create work items working in the web portal, you can create a hyperlink that captures the default values you specify for a template. Choose the hyperlink, and it opens the template in the web portal.

  1. From the web portal Queries page, open a new work item.

    Open a new work item from the web portal Work page

  2. Fill in the default values you want the template to specify. You can leave required fields empty, or place some text in them

    Here, we fill in several values, including tags, but leave the Title blank. When you're done, copy the URL for the template.

    Define fields and choose Copy the URL

  3. The URL defines each predefined field, for example (line breaks added for clarity):

    http://fabrikamprime:8080/tfs/DefaultCollection/Fabrikam%20Fiber/_workItems/create/Task?%5B
    System.AssignedTo%5D=Jamal+Hartnett&%5B
    System.Description%5D=%3Cp%3EAlways+include+Remaining+Work+and+links+to+any+related+bugs+or+user+stories.%3C%2Fp%3E&%5B
    System.Tags%5D=Web%3B+Phone%3B+Service&%5B
    Microsoft.VSTS.Common.Activity%5D=Development&%5B
    System.IterationPath%5D=Fabrikam+Fiber%5CIteration+1
    

    Tip

    The URL won't contain defaults defined for the work item type. To specify a default field value, see Add or modify a field. Also, there's a 2000 character limit recognized by browsers. There's no work around to that limit.

  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.

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. You can then share these links through email, a network share, team portal, or a team dashboard or Welcome page.

  1. Open settings for a team.

    Choose Project Settings.

    Open project settings

    Expand Boards and choose Team configuration. Then, choose Templates.

  2. Copy the link to a shared network or send to your team via email. Also, consider adding a link the team dashboard.

  3. 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 web page as a hyperlink.

  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 actions icon for the template you want to copy and select Copy link.

    Copy link of a template
  3. Copy the link to a shared network or send to your team via email. Also, consider adding a link the team dashboard.

  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 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.

Note

Multiple team dashboards and the Markdown widget are available for Azure Boards and TFS 2015.2 and later versions.

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.

Apply a template to existing work item(s)

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

Apply a template within a work item form

  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 pre-defined template.

    Apply a template to an existing work item within the form

    Only those templates defined for teams that you belong to appear.

    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 within a work item form

  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 pre-defined template.
<img src="_img/wi-templates-apply-user-story-template-vsts.png" alt="Apply a template to an existing work item within the form" style="border: 1px solid #CCCCCC;" /> 

> [!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. 
  1. 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 (bulk update)

  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.

Apply a template to several work items (bulk update)

  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.

The feature to apply a template to existing work items from the web browser isn't supported for TFS 2015 and earlier versions.

Manage work item templates

You can view the list of templates defined for each work item type, and also add, edit, copy, delete, 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 Project Settings.

    Open project settings

    Expand Boards and choose Team configuration. If you need to switch to a different team, use the team selector.

  2. Choose Templates.

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

You can view the list of templates defined for each work item type, and also add, edit, copy, delete, 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 team admin context
  2. Choose Work>Templates.

    Open Work - Templates page for team

    From here, you can click 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

Define a template from scratch

  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, click Copy link to capture the URL for the template that you can use to add work items using the template.

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

Copy or duplicate 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.

Managing work item templates from the web portal is only supported from TFS 2017 and later versions. For TFS 2013 and TFS 2015, you can manage work item templates in Visual Studio 2013 or Visual Studio 2015 by downloading TFS Power Tools. With the Work Item Templates power tool add-in, you can:

  • Create and edit work item templates
  • Create and update work items using a template
  • Create a template from an existing work item
  • Bulk-edit work items by applying a template
  • Use templates created in Visual Studio to create work items through the Visual Studio client.

Note

Visual Studio 2015 is the last version in which you can install TFS power tools. You can use the Work Item Templates tool whenever you connect to TFS 2015 version or an earlier version. Templates you define through the power tool are separate from those defined through the web portal for TFS.

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 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://dev.azure.com/{OrganizationName}/{ProjectName}/_workItems/create/{WorkItemType}?
[FieldReferenceName 1]={FieldValue 1}&
[FieldReferenceName 2]={FieldValue 2}&
[FieldReferenceName 3]={FieldValue 3}&
. . .
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, and specifies values for the Assigned To, Description, Tags, Activity, and Iteration Path fields.

http://dev.azure.com/{OrganizationName}/{ProjectName}/_workItems/create/Task?
[System.Title]=TaskTitle&
[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
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 recognized by browsers.

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

Q & A

Q: How do I set a default template for a team?

A: The feature to set a default template for a team isn't a supported at this time.

From the Work Item Templates tool, you can set a default for each work item type. However, that default is set only for you and available only when working through Team Explorer. Open the template context menu and select Set as default.

Q: Can I copy a work item template to another team or project?

A: No. This feature isn't supported at this time.

Q: How do I delete a work item template?

A: From the work item type page, choose  the actions icon for an existing template and select the Delete option.

Delete template

A: You can't create templates that contain default links to work items. However, you can use the Marketplace extension, Work item form one click actions, to create rules that support adding linked work items with a single click.

Or, you can use a Kanban board to add child tasks, backlog items, or features. To learn more, see:

Otherwise, you can quickly copy tasks, bugs, and other items using Excel to apply parent-child links in a tree list.

You can't create templates that contain default links to work items. However, you can quickly copy tasks, bugs, and other items using Excel to apply parent-child links in a tree list.

Or, you can use a Kanban board to add child tasks, backlog items, or features. To learn more, see: