Customize the work tracking web form

TFS 2018

This article applies to customizations you can make when you use the Hosted XML process model or the On-premises Xml process model for an on-premises Azure DevOps Server. For the Inheritance process model, see Customize a process. For an overview of process models, see Customize your work tracking experience.

Import/export XML definition files

Use this sequence when you use the On-premises XML process model and manage your work tracking customization through import of individual XML definition files.

Import/export process zip files

Use this sequence when you use the Hosted XML process model and manage your work tracking customization by importing a process or process template.

FORM section

The main difference is that there are now two main layout sections within the FORM node. The first section, contained within the Layout element, defines the form layout when viewed through a client such as Visual Studio. The second section, contained within the WebLayout element, defines the form layout when viewed through a web browser.

<FORM>
   <Layout HideReadOnlyEmptyFields="true" HideControlBorders="true">
       . . .  
   </Layout>
   <WebLayout>
       . . .  
   </WebLayout>
</FORM>

See the following topics to make the indicated customizations:

• To customize the form for the web portal (WebLayout node), see WebLayout and Control XML elements
• To add a scoped links control to the form for the web portal (LinksControlOptions), see LinksControlOptions XML elements
• To customize the client form (Layout node), see Layout XML elements.

Import and export definition files (On-premises XML process)

1. If you don't have administration permissions for your project, get them.

2. Open a Command Prompt window according to the instructions provided in witAdmin: Customize and manage objects for tracking work.

   For example:

   %programfiles(x86)%\Microsoft Visual Studio\2017\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer 
   

3. Export the WIT definition file where you want to modify or add a field. Specify the name of the WIT and a name for the file.

   witadmin exportwitd /collection:CollectionURL /p:ProjectName /n:TypeName /f:"DirectoryPath/FileName.xml"  
   

   An example of a CollectionURL for an organization is https://dev.azure.com/OrganizationName.

4. Edit the file. For details, see WebLayout XML elements.

5. Import the WIT definition file.

   witadmin importwitd /collection:CollectionURL /p:ProjectName /f:"DirectoryPath/FileName.xml"  
   

6. Open either the web portal to view the changes. If the client is already open, refresh the page.

   The latest updates are downloaded from the server, including the changes that you just imported. Wait several seconds until the refresh completes.

   For more information about using witadmin, see Import, export, and manage work item types.

Tip

With witadmin, you can import and export definition files. Other tools you can use include the Process Editor (requires that you have installed a version of Visual Studio). Install the TFS Process Template editor from the Visual Studio Marketplace. You can use this version of the Process Editor to modify the old-style work item forms. You can't use it to edit forms associated with the new web forms.

Or, you can use the TFS Team Project Manager, an open-source client available from GitHub.

Layout and resizing

The web form resizes depending on the width available and the number of sections defined. At maximum width, in most web browsers, each section within a page will display within its own column. As the display width decreases, each section resizes proportionally as follows:

• For four sections: 40%, 20%, 20%, and 20%
• For three sections: 50%, 25%, and 25%
• For two Sections: 66% and 33%
• For one Section: 100%.

When the display width won't accommodate the columnar display of each section, sections appear stacked within a column.

Global lists

Global lists are managed differently in Hosted XML than they are on Azure DevOps Server. The witadmin command and a separate global list file aren't supported. In Hosted XML, you attach global lists to an existing work item type as illustrated in the following code snippet.

<?xml version="1.0" encoding="utf-8"?>
<witd:WITD xmlns:witd="http://schemas.microsoft.com/VisualStudio/2008/workitemtracking/typedef" application="Work item type editor" version="1.0">
  <WORKITEMTYPE name="Shared Steps" refname="Custom.SharedSteps">
    <DESCRIPTION>Server-side data for reusable set of test steps. Version: B.02</DESCRIPTION>
    <GLOBALLISTS>
      <GLOBALLIST name="Foo">
        <LISTITEM value="No" />
        <LISTITEM value="Yes" />
        <LISTITEM value="Maybe" />
        <LISTITEM value="Not Sure" />
      </GLOBALLIST>
      <GLOBALLIST name="Bar">
        <LISTITEM value="Open" />
        <LISTITEM value="Closed" />
      </GLOBALLIST>
     </GLOBALLISTS>  
     ...

By default the global lists will be attached to the Shared Steps work item type.

Import warnings and errors

You'll receive a warning when you import a modified WIT definition if you add a Control element for a required field in only the WebLayout or Layout node, but not the other.

You'll receive an error if you enable the new form, and then modify a WIT definition in which you delete the WebLayout node.

Related articles

• Add and modify a WIT