Define link controls to restrict link relationships

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 LinksControlType 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 for TFS process templates, see Link controls, restrictions, and field reference. For more information about link types, see Link type element reference.

In this topic

• Specifying the Links Control

• Controlling Link Relationships

• Restricting Link Relationships to Work Items

• Restricting Link Relationships to Changesets, Hyperlinks, and Other Non-Work Items

• Restricting Link Relationships to Types of Work Items

• Specifying the Default Columns to Display

Specifying the Links Control

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>

Back to top

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

Back to top

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>

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>

Back to top

Restricting Link Relationships to Changesets, Hyperlinks, and Other Non-Work Items

You use the ExternalLinkFilters and the Filter child elements to define which link types to items that are external to the team project the links control should include or exclude. The syntax for these elements is as follows.

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

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>

Back to top

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

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

Back to top

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 reference for Visual Studio ALM. 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>

Back to top

See Also

Reference

LinksControlOptions Elements

Concepts

Link controls, restrictions, and field reference

Link type element reference

Specify work item form controls