Define link controls to restrict link relationships

TFS 2017 | TFS 2015 | TFS 2013

Important

This article applies to customization for the On-premises XML process model and the old web form. For the new web form, see LinksControlOptions XML elements. (Customizing the link controls isn't a supported feature For the Inheritance process model.)

For an overview of process models, see Customize your work tracking experience.

You can control which work items link to each other by customizing the work form. Specifically, you can control the types of links and work items that users can view and add in a links control. For example, you may want to add a tab to your form that helps you manage dependent features. On that tab, you can add the links control and restrict the link relationships that team members can view and make from that control to include only links to other features.

You use the Control element LinksControl``Type attribute to enable users to create link relationships between work items and other objects in the Team Foundation database. You can then use the LinksControlOptions child elements to define the options for controlling what links team members can add to a work item and to what work item types or objects they can link. Also, you can define the default columns that you want to appear for the list of links in that control.

For a summary of the link restrictions that are defined within the process templates, see:

• For TFS 2017 and later versions, see LinksControlOptions XML elements (Web form)
• For TFS 2015 and earlier versions, see LinksControlOptions XML elements (Client and web, TFS 2015).

Specify the LinksControl

You use the LinksControl option to enable users to add, view, and manage link relationships in a work item form. By using this control, you can open, edit, add, and remove links.

You can customize a form so that one tab displays only parent and child links and another tab displays all other link types. In the following example, a tab that is labeled "All Links" is created that team members can use to add all link types. Also, the default columns that appear for the links display are ID, Work Item Type, Title, Assigned To, State, and the Link Comment field.

Links control

<Tab Label="All Links">  
      <Control Type="LinksControl" Name="All" >  
      <LinksControlOptions>  
         <LinkColumns>  
               <LinkColumn RefName="System.ID" />  
               <LinkColumn RefName="System.WorkItemType" />  
               <LinkColumn RefName="System.Title" />  
               <LinkColumn RefName="System.AssignedTo" />  
               <LinkColumn RefName="System.State" />  
               <LinkColumn LinkAttribute="System.Links.Comment" />  
         </LinkColumns>  
      </LinksControlOptions>  
      </Control>  
</Tab>  

Control link relationships

When you add a link control to a work item form, you can specify filters that restrict the types of links and work items that team members can add when they use the control. The following table describes the optional child elements that control link relationships.

Element	Description
WorkItemLinkFilters	Restricts the types of links that can be used to link to work items.
ExternalLinkFilters	Restricts the types of links that can be used to link to an object that is not a work item type, such as a changeset, hyperlink, or version control item.
WorkItemTypeFilters	Restricts the types of work items to which a user can link, and the projects in which those work items are defined.
Filter	Specifies the link types or work item types that you want to include or exclude.

Restricting Link Relationships to Work Items

You use the WorkItemLinkFilters and the Filter child elements to define which link types the links control should include or exclude. You use this element to restrict the types of links that can be selected by the links control to form relationships to work items that are defined in the same project. The syntax for these elements is as follows.

<WorkItemLinkFilters FilterType="include | exclude | includeAll | excludeAll">  
      <Filter LinkType="linkTypeRefName" FilterOn="reversename | forwardname" />  
</WorkItemLinkFilters>  

Attribute	Description
FilterType	Required WorkItemLinkFilters attribute. Defines the method that is used to filter the set of link types that is provided in the set of Filter elements. You can use the following valid values: - exclude: Use to prevent the creation of links from those link types that are listed in the Filter elements. - excludeAll: Use to disallow all link types. - include: Use to allow only those link types that are listed in the Filter elements. - includeAll: Use to allow the creation of links from all link types.
LinkType	Required Filter attribute. Specifies the reference name for a type of link. For more information, see LinksControlOptions.
FilterOn	Optional Filter attribute. Specifies the type of filter to apply to the link type. You can use the following valid values: - forwardname: Use to filter on the forward name that is defined for a type of link. - reversename: Use to filter on the reverse name that is defined for a type of link. If unspecified, both the forward and reverse names are used to filter the link type. If the link type topology is Network, the forward and reverse names are the same. For more information, see LinksControlOptions.

Example: Excluding Two Work Item Link Types

You can define a links control that allows link relationships for all link types except a custom requirement link type and the system hierarchy link type by using the following code example.

<Control Type="LinksControl" Name="UniqueName">  
      <LinksControlOptions>  
      <WorkItemLinkFilters FilterType="exclude">  
         <Filter LinkType="MyLinks.LinkTypes.Requirement" />   
         <Filter LinkType="System.LinkTypes.Hierarchy" />   
      </WorkItemLinkFilters>  
      <ExternalLinkFilters FilterType="excludeAll" />   
      </LinksControlOptions>  
. . .  
</Control>  

Restrict link relationships to external objects (not work items)

You use the ExternalLinkFilters and the Filter child elements to define which link types to items that are external to the project the links control should include or exclude. These objects correspond to changesets, hyperlinks, commits, and other objects. The syntax for these elements is as follows.

<ExternalLinkFilters FilterType="include | exclude | includeAll | excludeAll">  
      <Filter LinkType="externalLinkName" />  
</ExternalLinkFilters>  

Attribute	Description
FilterType	Optional ExternalLinkFilters attribute. Defines the method that is used to filter the set of link types that are provided in the set of Filter elements. You can use the following valid values: - exclude: Use to disallow the creation of links from those link types that are listed in the Filter elements. - excludeAll: Use to disallow all link types. - include: Use to allow only those link types that are listed in the Filter elements. - includeAll: Use to allow the creation of links from all link types. If unspecified, all links to external work items are excluded.
LinkType	Required Filter attribute. Specifies the reference name for a type of link to exclude or include. You can specify the following link types: - Fixed in Changeset - Result Attachment - Source Code File - Test Result - Workitem Hyperlink

Example: Exclude All Non-Work Item Links

The following example defines a links control that includes all link types to work items, such as related and parent/child, but excludes link types to non-work items, such as changesets, hyperlinks, and test results.

<Control Type="LinksControl" Name="UniqueName">  
      <LinksControlOptions>  
      <WorkItemLinkFilters FilterType="includeAll" />   
      <ExternalLinkFilters FilterType="excludeAll" />   
      </LinksControlOptions>  
</Control>  

The following example defines a link control that allows users to specify only the changeset link type and link only to changesets.

<Control Type="LinksControl" Name="UniqueName">  
      <LinksControlOptions>  
      <WorkItemLinkFilters FilterType="excludeAll"/>  
      <ExternalLinkFilters FilterType="include" />   
         <Filter LinkType="Fixed in Changeset" />  
      </ExternalLinkFilters>   
 </LinksControlOptions>  
. . .  
</Control>  
  

Restricting Link Relationships to Types of Work Items

You use the WorkItemTypeFilters and Filter child elements to restrict the types of work items to which a links control can link. You can restrict link relationships to the project or by work item type. The syntax for these elements is as follows.

<WorkItemTypeFilters Scope=" project | all" FilterType=" include | exclude | includeAll" >  
      <Filter WorkItemType="workItemTypeReferenceName" />  
</WorkItemTypeFilters>  

Attribute	Description
Scope	Optional WorkItemTypeFilters attribute. Defines the scope of the filter that is applied to the set of work item types that is provided in the set of Filter elements. You can use the following valid values: - all: Use to allow the creation of links to all work item types that are specified in the Filter elements. - project: Use to allow the creation of links only to those work item types that are defined for the current project. If unspecified, links to all work item types are allowed.
FilterType	Required WorkItemTypeFilters attribute. Defines the method that is used to filter the set of link types that is provided in the set of Filter elements. You can use the following valid values: - exclude: Use to disallow the work item types that are listed in the Filter elements. - excludeAll: Use to disallow all work item types. - include: Use to allow the work item types that are listed in the Filter elements. - includeAll: Use to allow all work item types.
WorkItemType	Required Filter attribute. Specifies the reference name for a work item type.

Example: Limiting Link Relations to Task Work Items

The following example defines a links control that allows only hierarchical relationships to be formed to tasks that are defined in the project.

<Control Type="LinksControl" Name="UniqueName">  
      <LinksControlOptions>  
      <WorkItemLinkFilters FilterType="include">  
         <Filter LinkType="System.LinkTypes.Hierarchy" />  
      </WorkItemLinkFilters>  
      <ExternalLinkFilters FilterType="excludeAll"/>  
      <WorkItemTypeFilters Scope ="project" FilterType="include" />  
         <Filter WorkItemType="Task" />  
      </WorkItemTypeFilters>   
      </LinksControlOptions>  
. . .  
</Control>  
  

Specifying the Default Columns to Display

You use the LinkColumns and LinkColumn child elements to specify the default columns to display in the links control. You can specify either the reference name for a work item field or a link attribute. The syntax for these elements is as follows.

<LinkColumns>  
      <LinkColumn RefName="reference name" | LinkAttribute=" link attribute name" />  
</LinkColumns>  

The order in which the elements are listed defines the order in which the column fields are displayed in the work item form. For a list of reference names and link attributes, see Work item field index. The following syntax defines the display of four columns: ID, State, Title, and the link attribute Comment.

<Control Type="LinksControl">  
. . .  
      <LinksControlOptions>  
      <LinkColumns>  
         <LinkColumn RefName="System.ID" />  
         <LinkColumn RefName="System.State" />  
         <LinkColumn RefName="System.Title" />  
         <LinkColumn LinkAttribute="System.Links.Comment" />  
      </LinkColumns>  
      </LinksControlOptions>  
</Control>  
  

Related articles

• Link controls, restrictions, and fields
• LinksControlOptions XML element reference