June 10th, 2020

How to hide or edit the reason field in Azure DevOps

Dan Hellem
Product Manager for Azure Boards

Simply put, the reason field is weird. It’s the only field that requires a state to determine what values are allowed. Yet, you are not able to edit the field in the Azure DevOps service. Since the inception of the inherited process model, we received a lot of customer feedback about the reason field. Customers are passionate it. Some love it and want to see full feature parity with Hosted XML. Others question why it even exists and want it removed.

In this blog post, we will share two different work arounds. One, for hiding the reason field from the form. Another, allowing you to create your own reason field with customized values.

Lets get started…

Remove the Reason field

Make sure you are working with an inherited process. Editing a system process is not allowed.

Removing the reason field from the form is simple and can be accomplished by a single REST API endpoint.

First, you need to get the process id of the inherited process.

GET https://dev.azure.com/{{organization}}/_apis/work/processes?$expand=All&api-version=6.0-preview.2
content-type: application/json
Authorization: {{authorizationToken}}

Next, using the processId from the results of the previous call, use the system controls REST endpoint.

@witRefName = ProcessName.Bug

PATCH https://dev.azure.com/{{organization}}/_apis/work/processes/{{processId}}/workItemTypes/{{witRefName}}/layout/systemcontrols/System.Reason?api-version=6.0-preview.1
content-type: application/json
Authorization: {{authorizationToken}}

{
  "visible": false
}

Simple right? Now go and open a work item and see the reason field has been removed.

Image bug no reason

Note: You need to make the API call for each work item type.

Use your own Reason field

Using your own custom reason field requires the following steps:

  1. Hide the system reason field from the form (see above).
  2. Create a custom reason field, add values, and add it to the form layout. Do this for each work item type.
  3. Install the Cascading Picklist extension and configure the JSON

Create custom reason field

Editing of the reason field is not allowed, but you can create a new one. From the work item type, add a new picklist field with values. We then recommend adding the field to the top of the form.

Image custom field

Setup and configure cascading picklist

Now that you have a new custom reason field, you need to control when the values are displayed. This requires the Cascading Picklist extension.

Install the extension into your organization and go to your project settings. In the left navigation, find the Cascading Lists item under the Extensions section. This is where you configure the JSON to control what values are displayed depending on the work item state.

{
  "version": "1",
  "cascades": {
    "System.State": {
      "New": {
        "Custom.MyReasonField" : [
          "New Bug",
          "Not Fixed"
        ]
      },
      "Active": {
        "Custom.MyReasonField" : [
          "Approved",
          "Investigate",
          "Reactivated"
        ]
      },
      "Resolved": {
        "Custom.MyReasonField": [
          "Fixed",
          "As Designed",
          "Cannot Reproduce",
          "Not Going to Fix",
          "Resolved in Error"
        ]
      },
      "Closed": {
        "Custom.MyReasonField": [
          "Verified"
        ]
      }
    }
  }
}

Save the configuration and open up a work item in the project. Now you have your very own custom reason field!

Image work item custom reason field

Summary

We know this is not the perfect solution. But we think it solves a gap in the product for those customers who want to hide the reason field or customize it. Let us know what you think.

Category
AgileDevOps

Author

Dan Hellem
Product Manager for Azure Boards

Dan is a Product Manager with Microsoft's Azure DevOps

2 comments

Discussion is closed. Login to edit/delete existing comments.

  • Neha Vijapur

    Hi People,

    To hide or edit the reason field in Azure DevOps i have done everything same as show above.

    https://dev.azure.com/sandbox/_apis/work/processes/6b724908-ef14-45cf-84f8-768b5384da45/workItemTypes/Microsoft.VSTS.WorkItemTypes.Task/layout/systemcontrols/System.Reason?api-version=6.0-preview.1

    i am getting the following error ,
    {
    "$id": "1",
    "innerException": null,
    "message": "VS403115:You cannot modify form layout information for work item types Microsoft.VSTS.WorkItemTypes.Task in process 6b724908-ef14-45cf-84f8-768b5384da45 as these work item types are locked.",
    "typeName": "Microsoft.TeamFoundation.WorkItemTracking.Server.FormLayout.FormLayoutInfoNotAvailableException, Microsoft.TeamFoundation.WorkItemTracking.Server",
    ...

    Read more
    • Dan HellemMicrosoft employee Author

      You can’t modify as system work item type like Task or Bug. You need to create an inherited process and then modify that. It will be something like [ProcessName].Task