How to hide or edit the reason field in Azure DevOps

Dan Hellem

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.

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.

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!

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.

Dan Hellem Program Manager, Azure DevOps

Follow