{"id":39442,"date":"2020-05-31T09:22:03","date_gmt":"2020-05-31T16:22:03","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/premier-developer\/?p=39442"},"modified":"2020-05-11T09:41:39","modified_gmt":"2020-05-11T16:41:39","slug":"upgrading-to-the-new-work-item-form-in-azure-devops","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/premier-developer\/upgrading-to-the-new-work-item-form-in-azure-devops\/","title":{"rendered":"Upgrading to the New Work Item Form in Azure DevOps"},"content":{"rendered":"

 <\/p>\n

Premier Field Engineer Greg Schunemann<\/a> discusses his experience with managing work item form customizations after an upgrade to Azure DevOps Server 2019.<\/p>\n

\n

More and more organizations are upgrading their on-premises Team Foundation Server instances, many having the end goal of migrating to Azure DevOps Services in the cloud. If you are upgrading from a pre-2017<\/em> version of Team Foundation Server, you’ll notice that work items have been given a major facelift.<\/a> If your pre-2017 Team Foundation Server collection or project has a fair number of customizations to the work item forms, there is a good possibility that your work items will look very different after upgrading to Azure DevOps Server. This is due to some changes in the XML which defines how the work items are rendered in the browser.<\/p>\n

This blog post will highlight a case from the field to shed some light on what changes are made to the work item form, also known as the ‘Best-effort transformation’<\/a>. We’ll walkthrough a case from the field where the custom work item was very different after upgrade.<\/p>\n

Problem Statement<\/h2>\n

The work item type \u2018Change Request\u2019 form does not display properly in the web UI as a result of upgrading Team Foundation Server 2012 Update 4 to Azure DevOps Server 2019 Update 1. Prior to upgrade, the Change Request work item (WI) form displayed in the web UI as follows:<\/p>\n

\"Image<\/p>\n

Note that many of the fields shown are custom, and they are placed in what we’ll call the ‘header’ of the form (more on that later). Also, note the grouping of fields under a section titled BETA<\/strong>; from left to right, the fields \u2018Change Required\u2019, \u2018Properties\u2019, \u2018Status\u2019 and \u2018Change Date\u2019 are shown. This same structure repeats with the subsequent sections titled Dev<\/strong>, QC<\/strong>, QA<\/strong>, and PROD<\/strong> (not shown). This structure led to a long work item form, which the user needed to scroll downwards to enter\/view all fields.<\/p>\n

After upgrade to Azure DevOps Server 2019 Update 1, the CMDB Change Request work item form is displayed in the web UI as follows:<\/p>\n

\"Image<\/p>\n

Note that the Beta<\/strong> section is now pushed to the right of the form, and the fields of \u2018Properties\u2019, \u2018Status\u2019 and \u2018Change Date\u2019 are not shown. The ‘Properties’ field is not shown until the value of ‘Yes’ is entered for the ‘Change Required’ filed. Once ‘Yes’ is entered, ‘Properties’ appears on the left of the form, under \u2018Risk\u2019. Removing the \u2018Yes\u2019 value causes the \u2018Properties\u2019 field to disappear. These same undesired behaviors and field locations are repeated for each of the Dev<\/strong>, QC<\/strong>, QA<\/strong>, and PROD<\/strong> field groups defined on the old form.<\/p>\n

Causes for incorrect display<\/h2>\n

Prior to TFS 2017 Update 2, the .xml tag <Layout><\/code> was used to render the WI form. <Layout><\/code> has been deprecated in favor of the new <WebLayout><\/code> .xml tag (although <Layout><\/code> is still a required element of the work item form). During the upgrade process from versions of TFS earlier than TFS 2017.2, TFS attempts a ‘Best Effort Transformation of Layout to WebLayout’<\/a>. Depending on the complexity of the old <Layout><\/code> tag, there may be unexpected results.<\/p>\n

In the upgrade of the Change Request work item form, there were a combination of factors that led to the incorrect rendering of the WI form; these contributing factors are detailed in the following sections.<\/p>\n

Limits on customization to the SystemControls<\/code> section<\/h3>\n

In <WebLayout><\/code>, we have a section defined as <SystemControls><\/code>. This section acts as a WI form header and is highlighted in the screenshot below.<\/p>\n

\"Image<\/p>\n

The ability to customize the <SystemControls><\/code> section is limited in the new <WebLayout><\/code>. In the old version of the WI Layout, there was much more flexibility around customizations that could be made to this area of the work item; the Change Request form has much of its customization done there, as shown in the areas highlighted below:<\/p>\n

\"Image<\/p>\n

As part of the upgrade, Azure DevOps moved these fields out of the <SystemControls><\/code> section.<\/strong><\/p>\n

\n

NOTE: There are 3 types of fields that are defined here as part of this form: HtmlFieldControl<\/code>, FieldControl<\/code>, and DateTimeControl<\/code>. An HtmlFieldControl<\/code> is the larger text box which has greater control over text and format; a FieldControl<\/code> is shown as a simple text box and a DateTimeControl<\/code> limits the user to data entry in DateTime format.<\/p>\n<\/blockquote>\n

During the upgrade process, Azure DevOps does a \u2018best effort\u2019 guess at where the fields should appear, while conforming to new work item layout structure.<\/p>\n

In the out-of-the-box WI templates, the larger HtmlFieldControls<\/code> are displayed on the left side of the form, while FieldControls<\/code> and DateTimeControls<\/code> are displayed on the right side. Based on this standard, the upgrade process places all HtmlFieldControls<\/code> on the left side of the form; all FieldControls<\/code> were placed on the right side of the WI form, each in their own section or group.<\/strong><\/p>\n

\"Image<\/p>\n

Changes to fields defined as READONLY<\/code><\/h3>\n

In <WebLayout><\/code>, fields defined as read-only which have no set value are not displayed on the WI form by default.<\/strong>\nIt was discovered the example work item had a fair amount of custom logic built into the form. Much of this logic involved setting certain fields as read-only based on certain conditions and is valid. However, many of the custom fields were set as read-only when this work item is in the \u2018New\u2019 state and therefore have no value. Due to this, the fields were not visible on the form after the upgrade.<\/strong><\/p>\n

Steps Taken to Address Work Item Field Issues<\/h2>\n

The following sections describe the actions to return the work item form to a usable state.<\/p>\n

Add the ShowEmptyReadOnlyFields<\/code> attribute to <WebLayout><\/code><\/h3>\n

To allow for empty, read-only fields to be visible on the work item form the ShowEmptyReadOnlyFields<\/code> attribute must be set to true for the <WebLayout><\/code>. To set this, locate the opening <WebLayout><\/code> tag in the work item xml, and add the following text: ShowEmptyReadOnlyFields=\u201dtrue\u201d<\/code><\/p>\n

When done, the <WebLayout><\/code> opening tag should look similar to below:\n\"Image<\/p>\n

….<\/p>\n

Create tabbed pages for each environment<\/h3>\n

Recall that in the original work item form, there was a section defined for each environment (BETA<\/strong>, DEV<\/strong>, QA<\/strong>, QC<\/strong>, PROD<\/strong>), and each environment had four fields associated (Properties<\/code>, ChangeRequired<\/code>, Status<\/code>, ChangeDate<\/code>). After upgrade, these sections were rearranged and the relationships between the fields became unclear. The next steps will bring the related fields back together and place them in their own tab on the work item form.<\/p>\n

In <WebLayout><\/code>, different areas of the work item form are defined as follows (from top level down): Page<\/code>, Section<\/code>, Group<\/code>, Control<\/code>. The following image highlights these areas:<\/p>\n

\"Image<\/p>\n

Notice there is one Page<\/strong>, titled \u2018Description\u2019, which consists of 3 different Sections<\/strong>. Each section has its own Groups<\/strong> defined, which may contain one or more Controls<\/strong>. The goal for this work item is to gather related fields (Properties<\/code>, ChangeRequired<\/code>, Status<\/code>, ChangeDate<\/code>) and place them in their own environment page (BETA<\/strong>, DEV<\/strong>, QA<\/strong>, QC<\/strong>, PROD<\/strong>).<\/p>\n

Examine the .xml snippet from the incorrect work item form below. Notice that the related fields for the DEV<\/strong> and QA<\/strong> environments have been split across separate sections. Similarly, the related fields for BETA<\/strong>, QC<\/strong>, PROD<\/strong> have also been split across separate sections. These fields (Controls) will need to be gathered and placed in their own page using the subsequent steps. We’ll examine the steps taken for the BETA<\/strong> environment fields.<\/p>\n

\"Image<\/p>\n

Define the new page(s) on the work item form<\/h4>\n

Locate the closing tag for the \u2018Description\u2019 page, located near the end of the WebLayout<\/code> section. Insert a new <Page><\/code> section and set the label to match the environment which will be referenced. Set LayoutMode<\/code> to “EqualColumns”. Using this LayoutMode<\/code> will render a page where each column is one-third of the page.<\/p>\n

\"Image<\/p>\n

Working methodically, build out the work item form. Start with the \u201cChangeRequired\u201d field. Cut the existing \u201cChangeRequired\u201d control and paste it in the new page. Wrap this control with a Group<\/code> tag (providing a title to match the environment), and finally wrap this group with a Section<\/code> tag. When complete, the Page should look as follows:\"Image<\/p>\n

Next, create the center section. Add a new Section<\/code> tag after the previous but inside the Page<\/code> closing tag. Locate the existing “Properties” control on the Description page \u2013 cut the control and it\u2019s Group<\/code> wrapper and paste to the new section. When complete, the page should look as follows:<\/p>\n

\"Image<\/p>\n

The right-side section of the form will consist of 2 controls in a group. Add a new Section<\/code> tag subsequent to the previous. Add a Group<\/code> tag and provide the appropriate label. Cut and paste the fields for “Status” and “ChangeDate” to the new Group. The completed page should look as follows:<\/p>\n

\"Image<\/p>\n

\n

NOTE:<\/strong> Be sure to clean up empty Group<\/code> tags as their contents are moved to the new page. Any empty Group<\/code> tags may create errors upon import.<\/p>\n<\/blockquote>\n

Repeat the steps for defining new pages for each the remaining environments fields (DEV<\/strong>, QA<\/strong>, QC<\/strong>, PROD<\/strong>). Push the new .xml definition back to the server using one of the following: TFS Team Project Manager<\/a>, Process Template Editor extension for Visual Studio<\/a>, or witadmin<\/a>. Navigate to the project and create a new work item of type Change Request. The form should now look as follows, with each environment in its own tab:<\/p>\n

\"Image<\/p>\n

Notice that environment fields are grouped into tabs, and the layout of each tab should look as seen below:<\/p>\n

\"Image<\/p>\n

Conclusion<\/h2>\n

While most organizations will be able to upgrade to Azure DevOps and the new work item form without much pain, we’ve seen that some of the more-heavily customized work item forms may take some effort to get back to a functional state. Hopefully this blog helped to shed some light on what happens during the upgrade process and will help you on your way to fixing up those forms.<\/p>\n

Links<\/h2>\n

WebLayout and Control elements reference<\/a><\/p>\n

Handling a TFS 2018 Upgrade from Old form to New form<\/a><\/p>\n

Customize the work tracking web form<\/a><\/p>\n

New work item tracking experience<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"

This blog post will highlight a case from the field to shed some light on what changes are made to the work item form, also known as the ‘Best-effort transformation’. We’ll walkthrough a case from the field where the custom work item was very different after upgrade.<\/p>\n","protected":false},"author":582,"featured_media":39458,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[22],"tags":[2571,21,10243],"class_list":["post-39442","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","tag-azure-devops","tag-devops","tag-work-items"],"acf":[],"blog_post_summary":"

This blog post will highlight a case from the field to shed some light on what changes are made to the work item form, also known as the ‘Best-effort transformation’. We’ll walkthrough a case from the field where the custom work item was very different after upgrade.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/39442","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/users\/582"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/comments?post=39442"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/39442\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media\/39458"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media?parent=39442"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/categories?post=39442"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/tags?post=39442"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}