Fetcher Background information

Fetcher Background information#

Work items are fetched from Azure Devops via the Work Item Tracking API. It can be configured by a configuration file that contains a Wiql (WorkItems Query Language) query and other filtering criteria.

Environment variables#

ADO_API_ORG#: It defines the Azure Devops organization name to fetch data from.

ADO_API_PROJECT#: It defines the Azure Devops Project name within the given organization to fetch data from.

ADO_API_PERSONAL_ACCESS_TOKEN#: To be able to fetch work items from the DevOps organization, you require a personal access token with sufficient permissions. To generate a new personal access token, click on the “User settings” icon in the top right corner of Azure Devops, select “Personal access tokens”, then select “New Token”. Give the token Read, write & manage access to work items of the project.

ADO_APPLY_PROXY_SETTINGS#: (Optional) Should be set to true if you are the fetcher behind a proxy.

ADO_WORK_ITEMS_JSON_NAME#: (Optional) It defines the name of the file where the fetcher response will be stored in. The location of this file is set according to the evidence_path environment variable. If you don’t provide this variable, the file will be called workItems.json by default. This variable is also being used by the ado work items evaluator.

ADO_CONFIG_FILE_PATH#: It is the path to the fetcher’s and evaluator’s config file. More details about the config file can be found right below.

The fetcher’s config file#

The definition of which work items are to be fetched, is given by a yaml file. The location of this file is then referenced by the ADO_CONFIG_FILE_PATH environment variable.

Note

This config files is used to configure the Azure work items fetcher and evaluator. For having a better understanding of the config, check out: Evaluator Background Information.

This config file should have the following structure:

workItems:
  query: 'wiql query' # A WiQL query
  neededFields: # List of work item fields to fetch. Default fields are: State and Title
    - 'field1'
    - 'field2'

  relations: # OPTIONAL - Configuration to fetch relations of fetched work items
    get: true # Fetch the relations work items
    type: 'Related' # Type of the relation work items. Can have one of the following values: Related, Child, Parent
    relations: # OPTIONAL - relations of relations work items
      get: true # Fetch the relations work items
      type: 'Child' # Type of the relation work items. Can have one of the following values: Related, Child, Parent

  hierarchyDepth: 2 # OPTIONAL - If relations work items should have the same checks as origin work items, this can be used to define the relations depth. And no checks are needed to be defined under relations

The value of the “query” field is what the fetcher will send inside the request in order to filter the data. To learn more about WIQL syntax, please see the official docs.

Note

As stated in the official docs, it’s not taken into account which fields are requested by using the SELECT statement. No matter which fields are included, the API returns only work item IDs. Therefore, we have to send new requests for getting the full information, which is then filtered based on the neededFields property.

Each element of the “neededFields” list has to be specified by it’s reference name or by it’s friendly name.

Example: “friendly name”: TargetDate, “reference name”: Microsoft.VSTS.Scheduling.TargetDate

By default, the result will contain the Id, Url, State and Title.

Example Output#

The ado work items fetcher creates a file in the evidence path called workItems.json (if you didn’t specify a different name in the ADO_WORK_ITEMS_JSON_NAME). It has the following structure and contains all of the fetched work items:

{
  "workItems": [
    {
      "id": 1,
      "url": "https://dev.azure.com/<org>/<id>/_workitems/edit/8",
      "state": "To Do",
      "title": "Implement new auto-pilot for Azure DevOps",
      "targetDate": "2022-04-06T00:00:00Z",
      "assignedTo": "Name",
      "relations": [
        {
          "id": 2,
          "url": "https://dev.azure.com/ORG/PROJECT/_workitems/edit/2",
          "relationType": "Related",
          "state": "Child",
          "title": "Implement tests new auto-pilot for Azure DevOps",
          "relations": [
            {
              "id": 3,
              "url": "https://dev.azure.com/ORG/PROJECT/_workitems/edit/3",
              "relationType": "Child",
              "state": "In Focus",
              "title": "Implement unit tests for new auto-pilot for Azure DevOps",
              "relations": []
            }
          ]
        },
        {
          "id": 4,
          "url": "https://dev.azure.com/ORG/PROJECT/_workitems/edit//_workitems/edit/4",
          "relationType": "Child",
          "state": "In Focus",
          "title": "Test the new auto-pilot for Azure DevOps",
          "relations": []
        }
      ]
    }
  ]
}

Example config#

You can find a complete example configuration in Getting started with Azure DevOps autopilot.