LinksControlOptions elements

TFS 2017 | TFS 2015 | TFS 2013

You use the LinksControlOptions element to define the options for controlling what links can be added to a work item and the default columns that you want to appear for the list of links in a work item. When you add a links control to a work item form, you can specify filters that restrict the types of links that users can be view and create and the types of work items to which users can create links. Specifically, you use the following elements as indicated:

• WorkItemLinkFilters: Use to restrict the types of links between work items in the current project.

• ExternalLinkFilters: Use to restrict the types of links that can be created between work items and other objects, such as changesets, hyperlinks, or version controlled files.

• WorkItemTypeFilters: Use to restrict the link relationships that users can create based on work item type and whether the work item is defined in the current project.

In each of these elements, you can specify Filter elements to specify the link types or work item types that you want to include or exclude. For more information about how to use these elements, see Define link controls to restrict link relationships.

The LinksControlOptions element is a child element of the CONTROL element.

Syntax

<LinksControlOptions>  
   <WorkItemLinkFilters FilterType="include | exclude | includeAll | excludeAll">  
       <Filter LinkType="linkTypeRefName" FilterOn="reversename | forwardname" />  
   </WorkItemLinkFilters>  
   <ExternalLinkFilters FilterType ="include | exclude | includeAll | excludeAll">  
       <Filter LinkType="externalLinkName"/>  
   </ExternalLinkFilters>  
   <WorkItemTypeFilters Scope=" project | all" FilterType=" include | exclude | includeAll" />  
       <Filter WorkItemType="workItemTypeReferenceName"/>  
   </WorkItemTypeFilters>  
   <LinkColumns>  
      <LinkColumn RefName="reference name" | LinkAttribute="link attribute name"/>  
   </LinkColumns>  
</LinksControlOptions>  

Attributes and elements

The following sections describe attributes, child elements, and parent elements.

Child elements and attributes

Parent Elements

Remarks

LinksControlOptions is an optional child element of Control element where ControlType="LinksControl". You can use the LinksControlOptions element to support the following actions:

• Specify the restrictions that govern the creation of relationships to other work items based on the link type and, optionally, the forward and reverse names of the link types.
• Specify the restrictions that govern the creation of relationships to objects other than work items, such as changeset, hyperlink, and so on, based on external link types.
• Specify the restrictions that govern the creation of relationships to other work items based on work item type and, optionally, the project where those work items are defined.
• Specify the default column fields that you want to display information for the link list.

Example

The following example specifies how to enable the creation of links whose type is Microsoft.VSTS.Common.TestedBy and show the Forward Name for this link type. The filter options disallow creation of links to all external link types. In addition, displayed default column fields for the listed links correspond to the following friendly names: ID, Work Item Type, Title, Assigned To, State, and the Comment field defined for the link. For more examples, see Define link controls to restrict link relationships.

<Control Type="LinksControl" Name="TestedBy" Label="&Work items testing this bug:" LabelPosition="Top">  
   <LinksControlOptions>  
      <WorkItemLinkFilters FilterType="include">  
         <Filter LinkType="Microsoft.VSTS.Common.TestedBy" FilterOn="forwardname" />  
      </WorkItemLinkFilters>  
      <WorkItemTypeFilters FilterType="include">  
          <Filter WorkItemType="Test Case" />  
      </WorkItemTypeFilters>  
          <ExternalLinkFilters FilterType="excludeAll"/>  
      <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>  

LinksControl toolbar buttons

Each Control element of Type=LinksControl provides a toolbar, which contains the buttons shown in the next illustration:

These buttons become available only after you perform a specific action:

• The button to create a work item that is linked to the open work item () becomes available only after you save the open work item.
• The buttons to open the list of work items in a query () and in a Microsoft Office client () become available only when at least one work item is listed in the links control tab.
• The buttons to open a work item (), edit a link (), and delete a link () become available only after you click one or more work items listed in the links control tab.

The links control that is displayed is the same for both the web portal and Team Explorer, except when it is configured to only render Storyboard links. In that case, the toolbar only contains those controls to add a new link, open the linked item, and delete the link. Also, the web portal version displays the Start Storyboarding link within the control menu.

Related articles

• LinkTypes elements reference, Define a custom link type
• Define link controls to restrict link relationships
• Specify work item form controls