Azure DevOps Boards (Pro)
On this page
Instance Setup
- Label should be the label that you want to use to identify this integration.
- Location should be set to your Azure URL - for example
https://dev.azure.com/{your organization} - Token should be set to a personal access token from Azure.
Authentication with Azure DevOps requires a personal access token with permissions set to “Read, Write and Manage” for “Work Items” for the Azure Project that you wish to work with.
Issue Tracker Mapping
These details dictate how DefectDojo will map Finding or Finding Group attributes to a given Project in Azure DevOps:
Issue Tracker Mapping Details
The Project ID field corresponds to the name or the ID of the Project in Azure.
The Work Item Type field sets the type DefectDojo creates each work item as, by name: Issue
(the default), Bug, Task, or a custom type your process defines, such as Vulnerability.
DefectDojo sets the type when it creates a work item, and never changes it afterwards, so this
field is the only place to set it. DefectDojo does not check this when a mapping is saved: a
Custom Field Mapping on System.WorkItemType (or its display name, Work Item Type) can be
saved, but every push through that mapping then fails, creates and updates alike, with an error
naming the field, until that custom field mapping is removed. The type must exist in the
project. If it does not, creating a work item through this mapping fails with an error naming
the type and the project; updates and closures of existing work items are not affected. Changing
the type only affects work items created afterwards: existing ones keep the type they were
created with.
Severity Mapping Details
The attributes in the form are supplied as defaults, and are as follows:
- Severity Field Name:
/fields/Microsoft.VSTS.Common.Priority - Info Mapping:
4 - Low Mapping:
4 - Medium Mapping:
3 - High Mapping:
2 - Critical Mapping:
1
Status Mapping Details
The attributes in the form are supplied as defaults and are as follows:
- Status Field Name:
/fields/System.State - Active Mapping:
To Do - Closed Mapping:
Done - False Positive Mapping:
Done - Risk Accepted Mapping:
Done
The status values must be states that exist on the work item type in your project’s process.
For example, a project using the Scrum process template does not have a To Do state on
every type - check the allowed states in Azure DevOps and adjust the mapping to match.
Custom Field Mappings
Custom field mappings set additional Azure DevOps fields on the work items DefectDojo
creates or updates. The Vendor Field must be the Azure DevOps field’s reference name
(for example System.AreaPath, System.Tags, or Custom.MyField - not its display name),
and the field must exist on the work item type in your project’s process.
The work item type itself is set by the mapping’s Work Item Type. A custom field mapping on System.WorkItemType can be saved, but every push through the mapping then fails with an error naming that field.
Two mappings are especially useful for routing work items to a team:
- Area Path: a mapping with Source
Static Value, Vendor FieldSystem.AreaPath, and a value such asMy Project\My Teamroutes the work item to the team that owns that area. - Iteration Path: a mapping with Vendor Field
System.IterationPathplaces the work item in a sprint. The value can be a static iteration path, or the special token@CurrentIteration/@CurrentIteration(My Team), which DefectDojo resolves at push time into the named team’s currently active sprint (the project’s default team when no team is given). If the team has no current sprint selected in Azure DevOps, the push fails with an error saying so.
Note that Azure DevOps boards and backlogs only display work item types that belong to a backlog level. DefectDojo creates work items of the mapping’s Work Item Type (Issue by default); if that type is not part of a backlog level in your project’s process, the pushed items are only visible in the Boards → Work items view regardless of their area or iteration.