De-mystifying allowed values for a field in Azure DevOps based on values of another field or Rules?

Question

When you create a work item such as Bug in Azure devops, the values that you would see in the drop down of say Reason field would depend on the value you select for State field. For e.g. see these screenshots (Template Agile, no customizations)

Then if you change the state, the allowed values change as shown

To make matters more confusing, these are just few of the values that are returned by the documented REST API

The given API returns

 "defaultValue": null,
        "allowedValues": [
          "Verified",
          "Not fixed",
          "Test Failed",
          "As Designed",
          "Cannot Reproduce",
          "Copied to Backlog",
          "Deferred",
          "Duplicate",
          "Fixed and verified",
          "Obsolete",
          "Fixed",
          "Investigation Complete",
          "Approved",
          "Investigate",
          "Resolved in error",
          "Reactivated",
          "Regression",
          "Build Failure",
          "New"
        ],
        "helpText": "The reason why the bug is in the current state",
        "alwaysRequired": false,
        "dependentFields": [
          {
            "referenceName": "System.State",
            "name": "State",
            "url": "https://dev.azure.com/nikhil/_apis/wit/fields/System.State"
          },
          {
            "referenceName": "Microsoft.VSTS.Common.ResolvedReason",
            "name": "Resolved Reason",
            "url": "https://dev.azure.com/nikhil/_apis/wit/fields/Microsoft.VSTS.Common.ResolvedReason"
          }
        ],
        "referenceName": "System.Reason",
        "name": "Reason",
        "url": "https://dev.azure.com/{project}/{templateid}/_apis/wit/fields/System.Reason"
      },

I am trying to figure out the right API or set of APIs that help demystify when to show what in the combo boxes, when to mark them read-only and when to let the user edit them.

The Resolved Reason Field is further interesting. For most parts it seems to simply copy the value from the Reason field, however the Rules API (see below) does not indicate this behaviour. It looks like what the Rules API returns does not match the behaviour that this field exhibits.

There is a concept of Rules mentioned in the REST API here - https://learn.microsoft.com/en-us/rest/api/azure/devops/processes/rules/get?view=azure-devops-rest-5.1#processrule

However this does not seem to give rules which specifically control "allowedValues" for fields based on value of another field as I explained above.

Question:

1. Is there an API that can give a comprehensive set of rules for fields on a work item types including their allowedValues? For e.g. the Reason or Resolved Reason field depending on the choice of State field as shown above?

Answer 1

Is there an API that can give a comprehensive set of rules for fields on a work item types including their allowedValues? For e.g. the Reason or Resolved Reason field depending on the choice of State field as shown above?

First of all, I need to say, no, there is no such REST API to get the Reason value which depending on the State filed chosen. Since these are all not be documented, the best way for us to verify it is using the Fiddler trace(Fiddler can record all internet data between web application and internet).

---

[As example, here I will use Bug work item to show that.]

First, clear all the records in Fiddler => open the Bug work item in Azure Devops => press F12 in Fiddler to start record the data.

Change the work item state in Azure Devops(Note: just change, do not save it. "Save" belong to another operation). Then go Fiddler to see its internet records:

You will see that there only 2 event API, and these API are only used to post the action sign but not operate it. See the request body of first POST Event API:

You can see that it just used to post a sign about the State field has changed. That's why I say that there's no API to get the Reason value which depending on the State filed chosen, because our develop team did not use the script with API to achieve that.

---

Now, you should be very confusing that who is this action message to be sent to? Since the Reason field value listed is not controlled by the api, then who is in control?

The answer is XML process template.

In Azure Devops, the WIT are all controlled by XML template. You can find all rules such as the Reason field value listed depend on the State field changed, copy the value from the Reason field and etc.

I have uploaded the Bug.xml of process template into my github, you can refer to that code to analysis it: Agile-process/Bug.xml .

For the Reason field value listed depend on the State field changed.

  <FIELD name="Resolved Reason" refname="Microsoft.VSTS.Common.ResolvedReason" type="String" reportable="dimension">
    <ALLOWEDVALUES>
      <LISTITEM value="As Designed" />
      <LISTITEM value="Cannot Reproduce" />
      <LISTITEM value="Deferred" />
      <LISTITEM value="Duplicate" />
      <LISTITEM value="Fixed" />
      <LISTITEM value="Fixed and verified" />
      <LISTITEM value="Obsolete" />
      <LISTITEM value="Copied to Backlog" />
    </ALLOWEDVALUES>
    <HELPTEXT>The reason why the bug was resolved</HELPTEXT>
  </FIELD>

These are the xml code which control the Resolved Reason listed. I believe that you have got its logic. The message of event API we got from fiddler are get by the relevant WIT *.xml. Then the corresponding operation will be trigger and acted.

For copy the value from the Reason field.

    <TRANSITION from="New" to="Resolved">
      <ACTIONS>
        <ACTION value="Microsoft.VSTS.Actions.Checkin" />
      </ACTIONS>
      <REASONS>
        <DEFAULTREASON value="Fixed">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <COPY from="value" value="Fixed" />
              <ALLOWEDVALUES>
                <LISTITEM value="Fixed" />
              </ALLOWEDVALUES>
            </FIELD>
          </FIELDS>
        </DEFAULTREASON>
        <REASON value="Deferred">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <COPY from="value" value="Deferred" />
              <ALLOWEDVALUES>
                <LISTITEM value="Deferred" />
              </ALLOWEDVALUES>
            </FIELD>
          </FIELDS>
        </REASON>
        <REASON value="Duplicate">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <COPY from="value" value="Duplicate" />
              <ALLOWEDVALUES>
                <LISTITEM value="Duplicate" />
              </ALLOWEDVALUES>
            </FIELD>
          </FIELDS>
        </REASON>
        <REASON value="As Designed">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <COPY from="value" value="As Designed" />
              <ALLOWEDVALUES>
                <LISTITEM value="As Designed" />
              </ALLOWEDVALUES>
            </FIELD>
          </FIELDS>
        </REASON>
        <REASON value="Cannot Reproduce">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <COPY from="value" value="Cannot Reproduce" />
              <ALLOWEDVALUES>
                <LISTITEM value="Cannot Reproduce" />
              </ALLOWEDVALUES>
            </FIELD>
          </FIELDS>
        </REASON>
        <REASON value="Obsolete">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <COPY from="value" value="Obsolete" />
              <ALLOWEDVALUES>
                <LISTITEM value="Obsolete" />
              </ALLOWEDVALUES>
            </FIELD>
          </FIELDS>
        </REASON>
        <REASON value="Copied to Backlog">
          <FIELDS>
            <FIELD refname="Microsoft.VSTS.Common.ResolvedReason">
              <COPY from="value" value="Copied to Backlog" />
              <ALLOWEDVALUES>
                <LISTITEM value="Copied to Backlog" />
              </ALLOWEDVALUES>
            </FIELD>
          </FIELDS>
        </REASON>
      </REASONS>
      <FIELDS>
        <FIELD refname="System.AssignedTo">
          <COPY from="field" field="System.CreatedBy" />
        </FIELD>
        <FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
          <SERVERDEFAULT from="clock" />
        </FIELD>
        <FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
          <COPY from="currentuser" />
          <VALIDUSER />
          <REQUIRED />
        </FIELD>
        <FIELD refname="Microsoft.VSTS.Common.ResolvedBy">
          <COPY from="currentuser" />
          <VALIDUSER />
          <REQUIRED />
        </FIELD>
        <FIELD refname="Microsoft.VSTS.Common.ResolvedDate">
          <SERVERDEFAULT from="clock" />
        </FIELD>
      </FIELDS>
    </TRANSITION>

This just a short section which about the copy value from the Reason field from the xml file of Bug work item.

In fact, you can find all process rules from these XML file which could not get with API(Note: I just mean the default process rule). If you want, I can share the completed XML files of process in my github.

Hope this could help you more clearly:-)

Answer 2

Is there an API that can give a comprehensive set of rules for fields on a work item types including the allowedValues of say Reason field depending on the choice of State field?

For this issue , you can use Rules - List api to get it .

GET https://dev.azure.com/{organization}/_apis/work/processes/{processId}/workItemTypes/{witRefName}/rules?api-version=5.1-preview.2

I test with postman , the figure below is the result returned by my test.

By searching for keywords, we can get the rules of allowed values for Reason field depending on the choice of State field.

The processId parameter required in the api can be obtained through this rest api.

Hope this helps.