Azure DevOps Configuration

The most powerful part of Teamhood and Azure DevOps integration is the “Config”. It is a JSON map file. You can map Azure DevOps structure and work item properties to Teamhood structure and item properties. In this post, we will provide common config examples. If you have not yet connected Teamhood to Azure DevOps, we recommend reading our getting started with Azure DevOps integration guide first.

Project scope mapping

Project (required)

First and the most important properties that you need to specify are related to work item location. You must specify the Azure DevOps project name and which iterations to include in the synchronization scope.

Iterations (required)

• [“Iteration 1”, “Iteration 2”, … ] – array of specific iterations
• [“Root/Release 1/Sprint*”] – wild cards for partial matching. This will match multiple iterations starting with Root/Release 1/Sprint
• All – includes all iterations
• Current – if you are using a rolling current iteration, you can choose this option to avoid reconfiguring the scope once you set different iterations to current in Azure DevOps

"Location": {
    "Project": "ADO integration test",
    "Iterations": [
      "ADO integration test/*"
    ]
}

ItemMappings

An array of item types to be mapped. For each type, you specify a corresponding Azure DevOps work item type.

ItemType (required)

Any standard or custom item type that is present in your Azure DevOps project type definition. For example, “Task”, “User Story”, “Feature”, and “Bug”.

Template (optional)

You can specify which template to use when creating items in Teamhood. The value should match any of the existing Workspace item templates.

"ItemMappings": [
    {
      "ItemType": "User Story",
      "Template": "User Story",
    }
]

FilterQuery (optional)

To reduce the scope of items to synchronize, you can figure out smart ways to filter by specific properties. You can use Azure DevOps work item query language (WIQL) for that.

"ItemMappings": [
    {
      "ItemType": "User Story",
      "FilterQuery": "[State] <> 'New' AND [Assigned To] = 'John Smith'"
    }
]

FieldMappings

An array of fields to be mapped between Teamhood and Azure DevOps.

SourceField (required)

Field from Azure DevOps work item

TargetField (required)

Teamhood item field

DefaultValueOnCreate (optional)

You can specify what should be the default value of the item property when it is created. Works both ways – if created from Azure DevOps or in Teamhood.

CreateIfNotExists (optional, boolean)

You can instruct Teamhood to create a corresponding entity if such value exists in Azure DevOps but does not exist in Teamhood. Use case example – mapping Azure DevOps areas to Teamhood board rows. During sync, Teamhood will ensure that there are as many rows in Teamhood as in Azure DevOps areas.

"ItemMappings": [
    {
      "ItemType": "User Story",
      "FieldMappings": [
        {
          "SourceField": "Title",
          "TargetField": "Title"
        },
        {
          "SourceField": "Description",
          "TargetField": "Description"
        },
        {
          "SourceField": "Assigned To",
          "TargetField": "Assignee"
        },
        {
          "SourceField": "Tags",
          "TargetField": "Tags",
          "CreateIfNotExists": true
        },
        {
          "SourceField": "Story Points",
          "TargetField": "Estimation",
          "DefaultValueOnCreate": "5"
        },
        {
          "SourceField": "State",
          "TargetField": "Status"
        }
      ]
    }
]

Options (optional)

If you want to customize further or avoid adjusting both software to match values ideally, you can define custom value maps. Use case example – you do not want to change board status names, or you want to map a single Azure DevOps state to multiple Teamhood statuses.

For each option in the Options array, you must specify SourceValue (Azure DevOps) and TargetValue (Teamhood).

{
  "SourceField": "State",
  "TargetField": "Status",
  "Options": [
    {
      "SourceValue": "New",
      "TargetValue": "Backlog"
    },
    {
      "SourceValue": "Active",
      "TargetValue": "In Progress"
    },
    {
      "SourceValue": "Resolved",
      "TargetValue": "Ready"
    },
    {
      "SourceValue": "Closed",
      "TargetValue": "Done"
    }
  ]
}

ChildMappings

Teamhood offers a flexible hierarchy and visualization, so you can bring Azure DevOps work item relations as child items. You can define more than one item type to be included as a child item. Each child item supports the same ItemMapping structure. See above for more details.

"ChildMappings": [
  {
    "ItemType": "Task",
    "FieldMappings": [
      {
        "SourceField": "Title",
        "TargetField": "Title"
      }
    ]
  }
]

Full config example

{
  "Location": {
    "Project": "ADO integration test",
    "Iterations": [
      "ADO integration test/*"
    ]
  },
  "ItemMappings": [
    {
      "ItemType": "User Story",
      "FilterQuery": "[State] <> 'New' AND [Assigned To] = 'John Smith'",
      "Template": "User Story",
      "FieldMappings": [
        {
          "SourceField": "Title",
          "TargetField": "Title"
        },
        {
          "SourceField": "Description",
          "TargetField": "Description"
        },
        {
          "SourceField": "Assigned To",
          "TargetField": "Assignee"
        },
        {
          "SourceField": "Tags",
          "TargetField": "Tags",
          "CreateIfNotExists": true
        },
        {
          "SourceField": "Iteration Path",
          "TargetField": "BoardRow",
          "CreateIfNotExists": true
        },
        {
          "SourceField": "Story Points",
          "TargetField": "Estimation",
          "DefaultValueOnCreate": "5"
        },
        {
          "SourceField": "State",
          "TargetField": "Status",
          "Options": [
            {
              "SourceValue": "New",
              "TargetValue": "Backlog"
            },
            {
              "SourceValue": "Active",
              "TargetValue": "In Progress"
            },
            {
              "SourceValue": "Resolved",
              "TargetValue": "Ready"
            },
            {
              "SourceValue": "Closed",
              "TargetValue": "Done"
            }
          ]
        }
      ],
      "ChildMappings": [
        {
          "ItemType": "Task",
          "FieldMappings": [
            {
              "SourceField": "Title",
              "TargetField": "Title"
            }
          ]
        }
      ]
    }
  ]
}