# Import from Azure DevOps Boards

> Bring Azure DevOps work items into By Dawn through your organization's existing Azure DevOps connection, by project, area path or WIQL query.

This page helps you bring Azure DevOps Boards work items into By Dawn. At the end they're By Dawn tickets, epics and
features are By Dawn epics, and, if you chose to keep syncing, the two stay in step until your end date.
[Import and sync](https://docs.bydawn.com/import-and-sync/) explains the steps every tracker shares, so this page covers only
what's particular to Azure DevOps.

## Before you start

- You need to be a project admin in By Dawn.
- Your By Dawn organization must already be connected to Azure DevOps: an owner does that once under
  **Settings › Azure DevOps**. There's no separate token for Boards. The import acts as the person who made that
  connection, so it sees the projects they can see.
- If you've connected Azure DevOps for pull requests already, nothing else is needed: the same connection covers
  work items, read and write.

## Connect

1. In By Dawn, open **Settings › Import & sync › New import** and pick **Azure DevOps**.

2. Choose **Use it**. By Dawn uses your organization's connection, so there's nothing to paste.

## Pick what to bring

- **Project**: every work item in one project. Choose this if you might create tickets in By Dawn that should
  appear in Azure DevOps, because a new work item needs a project to go into.
- **Area path**: one team's work, such as `Acme\Web\Checkout`, including everything under it.
- **WIQL query**: any flat work-item query, such as
  `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = 'Acme' AND [System.State] <> 'Removed'`.
  By Dawn uses only the `WHERE` part, so `ORDER BY` is ignored, and tree or direct-link queries aren't accepted.

## How Azure DevOps maps

- **Statuses.** By Dawn proposes a column from each state's category: *Proposed* goes to a to-do column, *In
  Progress* to a building column, *Resolved* to a review column, and *Completed* and *Removed* to a completed
  column. Removed items also get a `resolution:` label.
- **Priorities.** Priority 1 → Urgent, 2 → High, 3 → Medium, 4 → Low.
- **Epics and features** both become By Dawn epics by default, and the items under them join the epic. Below that,
  By Dawn nests one more level, so deeper trees are flattened to sub-tickets, with a related link back to the lost
  parent.
- **Iterations** can become By Dawn cycles, `sprint:` labels, or nothing. Only current and future iterations join a
  cycle.
- **Tags** become labels.
- **Descriptions** are converted from HTML to markdown. Tables with merged cells become a quoted block, so
  nothing is dropped.

## When you sync both ways

By Dawn writes back the title, description, state, priority, assignee and tags, plus new comments. Due dates come
from Azure DevOps but aren't written back.

Every update tells Azure DevOps which revision it was based on. If someone changed the work item in the
meantime, Azure DevOps refuses the update, and By Dawn settles it the way it settles any change made on both sides
(see [When both sides change the same field](https://docs.bydawn.com/import-and-sync/#when-both-sides-change-the-same-field)),
so a newer edit is never overwritten blindly.

New tickets you create in By Dawn become the project's default backlog item type, such as a User Story or a Product
Backlog Item, and only on a connection that names a project.

By Dawn asks Azure DevOps to tell it about changes in the projects a sync covers, so they usually reach By Dawn within
seconds. A connection scoped by a query across projects is checked every few minutes instead.

## Where to go next

- [Import and sync](https://docs.bydawn.com/import-and-sync/): conflicts, pausing and ending a sync.

Source: https://docs.bydawn.com/import-azure-devops/