New work item form in TFS 2017
January 13, 2017
About a year ago we released the new work item form to Visual Studio Team Services. This was the beginning of our vision for managing work items in a more social and visual way. Over the past year, we focused on realizing this vision through continual improvements and listening to customer feedback.
We added many useful features along the way, such as:
- A discussion control with @mention support to better collaborate on a work item.
- Ability to follow a work item to be notified when it changes.
- A work item extensibility model which lets you extend the form with custom controls, groups and pages.
- A responsive links control to better visualize related work.
- Integrated development control to both track existing code assets and to create new ones.
- An attachment control that supports drag/drop, uploading multiple files and image preview.
- A more visual history control to better review changes.
With all these changes, we now have a modern and extensible work item form. And, we’re very excited that you’ll be able to access it with the TFS 2017 release.
Enabling the new form in TFS 2017
After installing TFS 2017, all newly created collections will have the new form enabled by default. However, since we know the new form is a big change we built an opt in experience for existing collections. This lets administrators enable the new work item form in stages and make changes to the layout before deploying it broadly.
Start by enabling the new form in the collection administration page:
Once enabled you can configure who can see the new form:
We recommend that you start with enabling for Administrators so that you can review and apply changes until you are happy with the layout. When you are ready to share with the rest of your team, enable as opt-in for all users.
When enabled as opt-in, each user will see a link that lets them toggle to the new form and try it out. This gives the opportunity to test out the layout changes and give feedback.
Once you have made any necessary updates to the layout to address feedback, you can migrate everyone to the new form for a consistent management experience.
Anatomy of the new work item form
The new form consists of a System Header and Pages.
System header
The system header contains vital parts of the work item – this includes Title, Assigned To, Discussion indicator, Tags, Follow, as well as the History, Links and Attachment pages.
We have become more restrictive with the system header so that we can bring consistency and utility across all work item experiences. Currently, the only customization you can make to the system header is changing the labels. You can still customize the underlying fields through the rules. We are looking for your feedback on these changes, and any additional customization you may need on the system header.
Pages
All the other content of the work item is organized into Pages, represented as tabs on the form.
Each page consists of Sections – the picture below shows a page with 3 sections. The first section is allocated 60% of the page width, the other two sections are allocated 20% each.
Groups
Sections are made up of groups. For example, the second section (colored in blue) has 2 groups – Planning and Classification. You can collapse and expand groups. Also, you can maximize certain groups, such as those containing an HTML or rich-text field control.
Controls
Groups are containers of field or custom controls. For example, the Story Point field control is shown below.
By arranging the contents in sections the new form provides an adaptive experience based on the width of your screen. For wide screens, we give each section its own vertical column. However, for small screens we wrap sections to preserve space and readability.
Customizing the new work item form in TFS 2017
The new work item form has a simplified XML layout which is very easy to modify. The page, section, group and control elements map directly to what you see on the form.
When the new form is enabled you can export your work item type to see the new layout automatically added in the WebLayout node. This new layout is auto-generated by transforming your existing form layout. Below is an example of a simple form xml containing a couple groups and links controls:
Given that this is auto-generated, not everything may be perfect and to your liking but you can make changes and apply them using the familiar import command (witadmin importwitd).
Extensibility with the new work item form
The new form brings with it a vastly improved extensibility model. You can add your own pages, groups and controls to the form or choose from the marketplace to get ready-made extensions like an updated Multi Value Control. After installing to your collection, you can enable them in your work item type and add them to your form.
The easiest way to do this is to export your work item type after the extension is installed. We inject a comment into the exported layout describing all extensions available targeting the work item form:
You can use this information to turn on extensions for your work item type and position them. In the example below, we add an Extension node that enables the Multi Value Control extension for the type and then add a ControlContribution node to add the custom control to the planning group. The <Extensions> node must be the first element after the <WebLayout> node.
After importing the work item type the custom control extension will show on the form.
We are planning a future blog post dedicated to work item form extensibility where we’ll go into greater depth about how to build them.
Conclusion
The new form landing in TFS 2017 culminates a lot of work and we are looking forward to receiving your feedback and exploring your ideas for improvements.
Links
- Rolling out the new form
- Customizing the new form layout
- Importing/Exporting a work item type
- Add or modify a custom control for a process and WIT
- Creating Form Extension
- Using Form Extensions
- Reporting Bugs/Issue/Feedback
- Submitting new ideas and enhancements
Thanks,
Hello – in regards to “An attachment control that supports drag/drop, uploading multiple files and image preview.”
There seems to be a significant use case missing: dragging and dropping emails from Outlook. That is our most common attachment.
I can do this through Visual Studio but not the web. Please address this. Thanks! And thanks for all of the other improvements!
Thanks for the comment. I would love that feature too however I believe the browser security model will let this work. I tested this on sites like outlook.com and gmail.com and neither are able to accept this. The workaround I use is I save the email to the desktop and then drag and drop that file into the attachments on the workitem.
Great look, much improved!
Does this style of customization create a potential challenge with upgrades? And for that matter, what about migrating to VSTS if you’ve done this?
Not quite related to the first question, would it be possible to include the Board Column and a Done indicator, maybe even in lieu of state? For those that are leveraging TFS for Kanban or Scrumban, this would be a huge help, and it really shouldn’t require customization to be able to see it. I believe the board column is the same as State if you haven’t modified your Board Columns.
Thanks for the feedback. I am not sure if you have a specific potential issue in mind that may cause an upgrade problem but this should all work fine for both upgrade and moving to VSTS.
As for customization, you can add board column as a field on the work item form already but you can’t customize the header section (like replace state with board column). We have heard this feedback before and are looking to hear more customer use cases to decide what the right level of customizability should be.
Is it possible to use this from when viewing work items in Visual Studio 2015?
The new form is only for the Web. In VS 2017 by default it will open the Web Form so you should see the new form from there.
hello,
I added this extension in TFS 2017.2 (on-premise). however, when attempting to upload a WIT xml with the extensions element, Bug WIT, for example, I get an error saying the “The Element “WebLayout” has invalid child element “Extensions”. List of possible elements expected: “Page, PageContribution”. Is this a bug?
You need to make sure Extension is the first element under . Did you put it after ?
GOOD
BAD
i put it how you have it above in the images. after putting the extension after the first element, it works. Thanks
When using the new form, the Discussions HTML menu (allowing you to format the text and add links, etc.) is only available when you maximize Discussions.
Can this menu be made visible even when the section is not full screen?
Hi Mary Ann,
Thanks for the feedback! After the summer, we will making updates to our discussion experience to improve usability, functionality, and enable Markdown support for comments. We will make sure we take care of the scenario you describe!
Best,
Jose Rady Allende
Hi
Thanks for the great introduction. I’ve been trying to move the “Discussion” control from the details page towards another page, but I can’t find it anywhere in the Template. Do you have any idea if it’s possible?