LinksControlOptions XML elements (Web form)
Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 - TFS 2017
By linking work items to other objects, you can track related work, dependencies, and changes made over time. With the updated Control element, you can specify a scoped links control within the work item form for the web portal by setting type="LinksControl".
This article applies to project customization for On-premises XML (TFS 2017 and later versions) process models. For TFS 2015, see LinksControlOptions elements (Client and web, TFS 2015).
Customizing the links control is not a supported feature For the Inheritance process model. For an overview of process models, see Customize your work tracking experience.
The LinksControlOptions element is a child element of the Control element. With a scoped links control, you can specify filters that restrict the types of links that users can add and the types of work items to which users can create links. Specifically, you use the following child elements to scope the control:
- LinkFilters: Use to specify the types of links that appear in the control:
- Add a WorkItemLinkFilter to select links that may be created to other work items
- Add an ExternalLinkFilter to select links to other objects, such as changesets, hyperlinks, or version controlled files
- WorkItemTypeFilters: Use to restrict the types of work items you can link to from the links control
- Column: Use to specify the work item fields and link type attributes listed within the links control
Note: The standard Links page provides a non-customizable control that displays all link types. From this control, you may view all links associated with the work item, and link the work item to other work items or external objects.
Summary of what's changed
The updated LinksControlOptions element introduces several new elements and deprecates several elements that are still in use with the client LinksControlOptions element version. Overall, it's a much simpler syntax structure than its predecessor.
|New elements||Maintained elements||Deprecated elements|
Differences between web and client links controls
The following table summarizes the differences between the LinksControlOptions elements used within the WebLayout section and those that are used within the Layout section. The WebLayout section supports display of work item forms through the web portal, while the Layout section supports display of work item forms from the web portal for TFS 2015 and clients such as Visual Studio.
|Control option||Web portal elements (WebLayout)||Client elements (Layout)|
|Restrict link relationships to other objects (non work items)||Specify to include an external link type using the ExternalLinkFilter element within the LinkFilters container element
|Specify to include or exclude external link types using ExternalLinkFilters|
|Restrict link relationships to other work items||Specify to include a work link type using the WorkItemLinkFilter element within the LinkFilters container element, specifying a link type reference name
|Specify to include or exclude work link types using WorkItemLinkFilters, specify a link type reference category|
|Restrict links allowed based on work item type||Specify to include a work item type using the Filter element within the WorkItemTypeFilters container element||Specify to include or exclude work item types using WorkItemTypeFilters|
|Link order and grouping||When
||All links grouped by type and listed alphabetically or ordered by column field|
|Composite display of link information||For each listed item, the links control displays the Work Item Type, ID, Title, and Assigned To as a composite field called Link as shown:
When the links control width is less than 460 pixels, the field also displays the item's State and the time of its Latest Update (the creation or latest modification of the item). See Responsive design and dynamic resizing for details.
|Field and attribute display||Specify the fields to display within the link control's grid using a Column element within the Columns container element||Specify the default fields to display using LinkColumn elements, users can change the column options through the client form|
Add links through a scoped links control
From the scoped links control, you can perform the same actions provided from the standard Links page—you simply do them from a menu rather than a tool bar.
- To open an associated item or object, click the linked item
- To delete a link, highlight it and click the delete icon
- To link to an existing item, or create and link a new work item, select one of the menu options.
Responsive design and dynamic resizing
By default, the scoped links control displays dynamically (
ViewMode=Dynamic) based on the form's width and the space allocated to the links control. The links control width expands and shrinks proportionally based on the overall form width.
- When the links control width is less than 460 pixels, the control displays as a List. Only the composite field called Link (consisting of Work Item Type, ID, Title, and Changed By fields)
- When the links control width equals or exceeds 460 pixels, the control displays information within a Grid according to the fields specified within the Column elements. The number of columns that appear is space-dependent, starting at a minimum of 4, and increasing by one column for every 100 pixels until the width is sufficient to display all defined columns.
You can specify whether the links display as a list, grid, or dynamically by setting the
ViewMode in the LinksControlOptions.
Sample code for default scoped link controls
Core system processes—Agile, Scrum, CMMI—have been updated to include the Development and Related Work scoped links control.
These controls appear on all default work item types, except the following:
- Code Review Request/Code Review Response
- Feedback Request/Feedback Response
- Shared Steps/Shared Parameter (these items have specific controls that list Test Case items).
Development links control
The Development links control displays all of your development links, whether based on a git or Team Foundation version control (TFVC) repository. It displays links in a set order, and provides calls-to-action that support users to drive development from a work item.
The following code sample specifies the syntax used to code the Development link control. This control supports adding external links of the specified types— pull requests, builds, branches, commits, and other development-related links— and grouping them according to the Development experience.
<Control Type="LinksControl" Label="Development"> <LinksControlOptions ViewMode="Dynamic" ZeroDataExperience="Development" ShowCallToAction="true"> <ListViewOptions GroupLinks="false"> </ListViewOptions> <LinkFilters> <ExternalLinkFilter Type="Build" /> <ExternalLinkFilter Type="Integrated in build" /> <ExternalLinkFilter Type="Pull Request" /> <ExternalLinkFilter Type="Branch" /> <ExternalLinkFilter Type="Fixed in Commit" /> <ExternalLinkFilter Type="Fixed in Changeset" /> <ExternalLinkFilter Type="Source Code File" /> <ExternalLinkFilter Type="Found in build" /> </LinkFilters> </LinksControlOptions> </Control>
Related Work links control
The Related Work links control displays links to other work items in a set order on the front page of the form. It supports these link types: Duplicate/Duplicate of, Parent/Child, Predecessor/Successor, Related, and Tests/Tested by.
The following code sample specifies the syntax used to support the Related Work links control.
<Control Type="LinksControl" Name="Related Work"> <LinksControlOptions> <LinkFilters> <WorkItemLinkFilter Type="System.LinkTypes.Duplicate-Forward" /> <WorkItemLinkFilter Type="System.LinkTypes.Duplicate-Reverse" /> <WorkItemLinkFilter Type="System.LinkTypes.Hierarchy-Forward" /> <WorkItemLinkFilter Type="System.LinkTypes.Hierarchy-Reverse" /> <WorkItemLinkFilter Type="System.LinkTypes.Dependency" /> <WorkItemLinkFilter Type="System.LinkTypes.Related" /> <WorkItemLinkFilter Type="Microsoft.VSTS.Common.TestedBy-Forward" /> <WorkItemLinkFilter Type="Microsoft.VSTS.Common.TestedBy-Reverse" /> </LinkFilters> <Columns> <Column Name="System.State" /> <Column Name="System.ChangedDate" /> <Column Name="System.Links.Comment" /> </Columns> </LinksControlOptions> </Control>
For Test Case items, this control also displays Shared Steps and Shared Parameter links.
Sample code to showcase test-related work
You can include work and external links together in a single control, while also filtering specific work item types to display. This powerful range of scoping allows you to create link controls that satisfy any number of scenarios.
For example, the syntax below would create a control specifically designed to display test results and testing work items.
<Control Name="Test" Type=""LinksControl""> <LinksControlOptions> <ListViewOptions GroupLinks="true"> </ListViewOptions> <LinkFilters> <ExternalLinkFilter Type="Result attachment"/> <ExternalLinkFilter Type="Test Result "/> <WorkItemLinkFilter Type="Microsoft.VSTS.Common.TestedBy-Forward" /> <WorkItemLinkFilter Type="Microsoft.VSTS.Common.TestedBy-Reverse" /> <WorkItemLinkFilter Type="Microsoft.VSTS.TestCase.SharedStepReferencedBy" /> </LinkFilters> <WorkItemTypeFilters> <Filter WorkItemType="Test Case" /> <Filter WorkItemType="Test Suite" /> <Filter WorkItemType="Test Plan" /> <Filter WorkItemType="Shared Steps" /> </WorkItemTypeFilters> </LinksControlOptions> </Control>
Create a scoped links control
To add or modify a scoped links control, use the information provided in this topic to modify the XML definition file for a specific work item type. Each links control must be added as a Control of type="LinksControl" within the WebLayout section, specifying the appropriate LinksControlOptions.
To import and export your changes, see Customize the work item tracking web form.
LinksControlOptions element syntax
The following table describes the LinksControlOptions element and its child elements. The syntax for the LinksControlOptions element is:
<LinksControlOptions ViewMode="Static | Dynamic" ZeroDataExperience="Development" ShowCallToAction="true | false" WorkItemTypeFiltersScope="project | all" > <ListViewOptions GroupLinks="true | false" /> <LinkFilters> <ExternalLinkFilter Type="ExternalLinkName" /> <WorkItemLinkFilter Type="WorkItemLinkName" /> </LinkFilters> <WorkItemTypeFilters> <Filter WorkItemType="WorkItemTypeName" /> </WorkItemTypeFilters> <Columns> <Column RefName="FieldReferenceName"/> </Columns> </LinksControlOptions>
Required Columns element used to specify the work item and link-related fields to display within the links control.
The order in which the Column elements are listed defines the order in which the column fields display in the control's grid.
To determine the reference name for a field, see Work item field index.
Link-related fields include:
Optional child element of the LinksControlOptions element.
Container element for one or more Column elements you use to specify the fields that display in the control's grid.
Optional LinkFilters element used to specify an external link type. With an external link type, users can create a link relationship to objects that are not work items, such as changesets, hyperlinks, and files under version control.
Examples of external link types you can specify include:
Important: For import purposes, use the name
Note: When you specify
Required child element of the WorkItemTypeFilters container element. Specifies the name of a work item type to include as an allowed type that users can link to from the links control.
You can specify any work item type defined within the project or project collection, including custom work item types. Typically, the work item types you specify depend on the process used to create your project. See Choose a process for details.
The following lists the default work item types available based on the default system processes:
Required container child element of Control element when type="LinksControl" and when used within the WebLayout element.
Use to scope the link types and work item types that users can add to a work item and the columns to appear for the list of link relationships in the work item form.
All attributes are optional. Supported attributes include:
Optional LinksControlOptions child element.
Use this container element to specify which link types are used to scope the control. List one or more ExternalLinkFilter or WorkItemLinkFilter elements to specify the link types to use to filter the links control.
Optional LinksControlOptions child element.
Specifies whether or not to group links according to their type. If
Optional LinkFilters child element.
Specifies a work-specific link type which is included within the links control. Users can create relationships to other work items only for those link types included in the links control.
Examples of work item link types you can specify include:
For a complete list, see Link type reference. In addition, you can specify the reference name for a custom link type.
When you specify
Optional container child element of the LinkFilters element. Use this element to specify the set of work item types to include in the links control. This element restricts the work item types that users can create links to and those that will appear in the linked list. Specification of this element depends on specifying at least one WorkItemLinkFilter element.
You use scoped links controls to support your team and business needs. You link work items to support traceability and manage dependencies. To learn more about customizing the web form, see these topics: