Edit a WIT definition to add web content to a work item form
TFS 2017 (Hosted XML) | TFS 2015
This topic applies to team project customization for the On-premises XML process model. For the Hosted XML process model, see WebLayout and Control elements. For the Inheritance process model, see Customize a process.
For an overview of process models, see Customize your work tracking experience.
You can add web content or HTML content to a work item form by exporting the type definition XML file and adding a
WebpageControl in the
FORM section. After you modify and import the XML file, you can verify the display of the Web content in the updated work item type.
The Web content that you display can be specified in one of the following ways:
URL of a Web page
A URL path that is dynamically determined at run time based on one or more field values defined for the work item
Update the XML definition for a WIT
If you are new to WIT customization, note the following:
- To customize any aspect of a WIT requires updating the XML definition for the WIT. The WIT XML definition is described in All WITD XML elements reference
- If you are customizing the web form that uses the new work item experience, you'll want to reference the WebLayout and Control elements
- If you are customizing a client form for use with Visual Studio, you'll want to reference the Layout XML element reference
- Follow the sequence of steps outlined in Customize the work item tracking web form.
Export and open the WIT definition file
Perform one of the following steps based on the scope of the customization that you want to perform:
If you are modifying a work item type for a single project:
Run witadmin exportwitd to export the XML file for the work item type that you want to modify. For more information, see Import, export, and manage work item types.
In Visual Studio, choose File, Open, File.
Under Look in, move to the location where you exported the file.
If you are modifying a work item type to customize a process template:
Find the location where you downloaded the process template.
Select the work item type XML file that you want to update, and then choose Open. When you are prompted about line endings, click No.
Add Web content to the FORM section of the definition file
<TabGroup>section of the XML file. Notice that there are
<Tab>elements for items such as Links and File Attachments in which each
<Tab>element contains a
<Control>element that renders the respective control.
<Tab Label="Links"> <Control Type="LinksControl" /> </Tab> <Tab Label="File Attachments"> <Control Type="AttachmentsControl" /> </Tab>
Add a new
<Tab>element that will contain the Web or HTML content that you want to display in the work item form. Copy the following code into the
<TabGroup>section of the file based on how you are defining the Web content.
To specify the URL of a Web page:
<Tab Label="Tab Label"> <Group> <Column PercentWidth="100"> <Control Type="WebpageControl" Name="Webpage" Label=" Name of Web Page" LabelPosition="Top" > <WebpageControlOptions AllowScript="false"> <Link UrlRoot="URL of Web Page" /> </WebpageControlOptions> </Control> </Column> </Group> </Tab>
Replace Tab Label and URL of Web Page with the information that you want to appear on the work item form.
To specify a dynamic URL to be determined at run time:
<Tab Label="Tab Label"> <Group> <Column PercentWidth="100"> <Control Type="WebpageControl" Name="Webpage" Label=" Name of Web Page" LabelPosition="Top" > <WebpageControlOptions AllowScript="false"> <Link UrlRoot="URL of Web Page" URLPath="URL path with parameters > <Param Index="0" Value="Param Value 0"/> <Param Index="1" Value="Param Value 1"/> <Param Index="2" Value="Param Value 2"/> </Link> </WebpageControlOptions> </Control> </Column> </Group> </Tab>
Replace Tab Label, URL of Web Page, URL path with parameters, and Param Value 1, 2, and 3 with the information that you want to appear on the work item form.
To specify HTML content:
<Tab Label="Tab Label"> <Group> <Column PercentWidth="100"> <Control Type="WebpageControl"> <Content> <![CDATA[HTML Content]]> </Content> </Control> </Column> </Group> </Tab>
Replace Tab Label and HTML Content with the information that you want to appear on the work item form.
For best results, every control or group should display in a column even if the column spans the full width of the form. In turn, every column should display in a group even if the group has no visible label or boundary.
Save your changes to the XML file.
witadmin importwitdto import the new work item type to a single project. To add the work item type to your process template, see Add type definitions for work items.
Verify the Web page or HTML content appears in the form
In Team Explorer, open Work Items for the team project that contains the WIT definition that you modified, and choose Refresh.
The latest updates are downloaded from the server, including the changes that you just imported. Wait several seconds until the Work Items node is refreshed. Nodes that are still loading display the word working.
Create a work item using the WIT that you modified.
Verify that the Web page or HTML content appears on the form as expected.
Choose Close to close the new work item.