Microsoft Azure DevOps
IT Service Management- Overview
- Setup
- Data & mappings
- Operations & API
- Changelog
The Azure DevOps connector integrates with Azure DevOps Services and Team Foundation Server using the Work Item Tracking (WIT) REST API (API version 7.0). It discovers the work-item types defined in the configured project, builds a dynamic schema from each type's field definitions, and synchronizes work items as connector objects. The connector also supports creating, updating, and deleting work items.
Because work-item fields are project-defined, the model and its attributes are dynamic: one connector object class is produced per work-item type (for example Bug, Task, Epic), and the attributes of each object class mirror the fields configured for that type in the project.
Data retrieved from Microsoft Azure DevOps
| Connector Object | Required | Maps to Data Model |
|---|---|---|
| Work Item | Yes | Resolved per object class |
For detailed steps on how to view the data retrieved from Microsoft Azure DevOps in the Brinqa Platform, see How to view your data.
Connection settings
When setting up a data integration, select Microsoft Azure DevOps from the Connector dropdown and provide the following:
| Setting | Required | Default | Description |
|---|---|---|---|
| Service URL | Yes | — | The Azure DevOps Services organization or TFS server. They are structured as follows<br/>\ |
| Access Token | No | — | Personal access token (PAT) with auth scope to read, write and manage work items. |
| Project | Yes | — | Work item project. |
| SSL / TLS | No | false | Skip certificate verification. |
Authentication
Method
HTTP Basic authentication using a Personal Access Token (PAT). The PAT is sent as the password with an empty username.
Usage
Every request carries an Authorization header built from a Base64 encoding of :{personalAccessToken} (empty username, PAT as password):
Authorization: Basic <base64(":" + personalAccessToken)>
Obtaining a Personal Access Token
- Sign in to your organization (
https://dev.azure.com/{organization}). - From your home page, open User settings and select Personal access tokens.
- Select + New Token.
- Name the token, choose the organization, and set an expiration.
- Select the scopes required for work-item read/write.
- Select Create.
All requests are scoped to the configured project: resource paths are prefixed with /{project} and the api-version=7.0 query parameter is added automatically.
Sync Behavior
The connector supports both full and incremental (delta) syncs. Work items are selected with a WIQL query, and the sync mode determines how that query is scoped:
- Incremental (delta) sync — When a sync-since timestamp is present, the clause
AND [System.ChangedDate] >= '{since}'is appended to the WIQL query, so only work items changed since the last run are returned. - Full sync — When no sync-since timestamp is set, the WIQL query returns all work items of the synced type in the configured project.
This behavior applies to every dynamically generated work-item object class. Per-model incremental details are documented under the model's Sync Duration Parameter below.
How to obtain Microsoft Azure DevOps credentials
Generate a Azure DevOps access token
For the Microsoft Azure DevOps connector to retrieve your work items from the Azure DevOps REST API, you must provide a personal access token. To do so, follow these steps:
-
Log in to your organization's Azure DevOps portal as an administrator.
-
Navigate to User settings > Personal access tokens.
-
Click New Token.
Complete the following fields:
-
Name: Provide a name for the token.
-
Organization: Click the dropdown and select the organization where you want to use the token.
-
Expiration Set an expiry date for the token.
-
Scopes: Allow full access or limit the access of the token. To limit access, select Custom defined and select Read, write, & manage access for Work Items.
-
-
Click Create.
Your new access token displays. You can't view the token again after this. Copy and save it to a secure location.
Note: If you do not have the permissions to create an access token, contact your Azure DevOps administrator. For additional information, see Microsoft Azure DevOps documentation.
Attribute mappings
Expand the sections below to view the mappings between the source and the Brinqa data model attributes:
Work Item
| Source Field Name | SDM Attribute |
|---|---|
| :--- | :--- |
| Converted to epoch milliseconds | datetime type |
| Mapped as-is using the field's resolved type | All other fields |
| Mapped to the value's uniqueName, falling back to displayName | Identity field |
| Mapping behavior | Field characteristic |
| Split on ; into a list of tag values | System.Tags |
WorkItem.fields[referenceName] | {field.referenceName} |
WorkItem.id | UID |
Operations & API
Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).
Work Item
Operation options
| Option | Type | Default | Description |
|---|---|---|---|
query | String | Sync/Search | WIQL query to select work items. Defaults to selecting items of the synced type in the configured project |
top | Integer | Sync/Search | Maximum number of work items to return ($top) |
fields | String | Sync/Search | Comma-separated field reference names to retrieve; * or all expands all fields. Falls back to attributesToGet when not set |
validateOnly | Boolean | Create/Update | Validate the change without saving |
bypassRules | Boolean | Create/Update | Do not enforce work-item type rules |
suppressNotifications | Boolean | Create/Update | Do not fire notifications for the change |
Delta sync
Not supported. The connector performs a full sync of Work Item on every run and applies no incremental date filter.
API
- Type: REST — Azure DevOps Work Item Tracking (WIT) API,
api-version=7.0. All resource paths are prefixed with the configured/{project}.
Changelog
The Microsoft Azure DevOps connector has undergone the following changes:
| Version | Description | Migration Steps |
|---|---|---|
| 3.5.9 | No changes in this release. | N/A |
| 3.5.8 | No changes in this release. | N/A |
| 3.5.7 | No changes in this release. | N/A |
| 3.5.6 | No changes in this release. | N/A |
| 3.5.5 | No changes in this release. | N/A |
| 3.5.4 | No changes in this release. | N/A |
| 3.5.3 | No changes in this release. | N/A |
| 3.5.2 | No changes in this release. | N/A |
| 3.5.1 | No changes in this release. | N/A |
| 3.5.0 | No changes in this release. | N/A |
| 3.4.32 | No changes in this release. | N/A |
| 3.4.31 | No changes in this release. | N/A |
| 3.4.30 | No changes in this release. | N/A |
| 3.4.29 | No changes in this release. | N/A |
| 3.4.28 | No changes in this release. | N/A |
| 3.4.27 | No changes in this release. | N/A |
| 3.4.26 | No changes in this release. | N/A |
| 3.4.25 | No changes in this release. | N/A |
| 3.4.24 | No changes in this release. | N/A |
| 3.4.23 | No changes in this release. | N/A |
| 3.4.22 | No changes in this release. | N/A |
| 3.4.21 | No changes in this release. | N/A |
| 3.4.20 | No changes in this release. | N/A |
| 3.4.19 | No changes in this release. | N/A |
| 3.4.18 | No changes in this release. | N/A |
| 3.4.17 | No changes in this release. | N/A |
| 3.4.16 | No changes in this release. | N/A |
| 3.4.15 | Dependency Upgrades - Updated the underlying Brinqa connector platform libraries. No functional changes to data synchronization. | N/A |
| 3.4.14 | Dependency Upgrades - Updated the underlying Brinqa connector platform libraries. No functional changes to data synchronization. | N/A |
| 3.4.13 | No changes in this release. | N/A |
| 3.4.12 | No changes in this release. | N/A |
| 3.4.11 | No changes in this release. | N/A |
| 3.4.10 | No changes in this release. | N/A |
| 3.4.9 | No changes in this release. | N/A |
| 3.4.8 | No changes in this release. | N/A |
| 3.4.7 | No changes in this release. | N/A |
| 3.4.6 | No changes in this release. | N/A |
| 3.4.5 | No changes in this release. | N/A |
| 3.4.4 | No changes in this release. | N/A |
| 3.4.3 | No changes in this release. | N/A |
| 3.4.2 | No changes in this release. | N/A |
| 3.4.1 | Dependency Upgrades - Updated the underlying Brinqa connector platform libraries. No functional changes to data synchronization. | N/A |
| 3.4.0 | No changes in this release. | N/A |
| 3.3.10 | No changes in this release. | N/A |
| 3.3.9 | No changes in this release. | N/A |
| 3.3.8 | No changes in this release. | N/A |
| 3.3.7 | Dependency Upgrades - Upgraded bundled Azure SDK and supporting libraries. No functional changes to data synchronization. | N/A |
| 3.3.6 | No changes in this release. | N/A |
| 3.3.5 | No changes in this release. | N/A |
| 3.3.4 | No changes in this release. | N/A |
| 3.3.3 | No changes in this release. | N/A |
| 3.3.2 | No changes in this release. | N/A |
| 3.3.1 | Dependency Upgrades - Updated the underlying Brinqa connector platform libraries. No functional changes to data synchronization. | N/A |
| 3.3.0 | Overview The Azure DevOps connector integrates with Azure DevOps Services and Team Foundation Server to synchronize work items across each of your project's configured work item types. Category: IT Service Management Models | N/A |