Azure DevOps
Azure DevOps is CardBoard’s deepest tracker integration. A card linked to a work item shares six fields with it, edited from either side: title, description, acceptance criteria, status, assignee, and story points.
At a glance
Section titled “At a glance”| Topic | Details |
|---|---|
| Connects | A board to one Azure DevOps project |
| Workspace connection | The workspace holds the Azure DevOps organization and its service hooks. Admins see boards, connected members, and webhook health in Settings → Integrations. |
| Member sign-in | Each member who edits linked cards signs in with their own Microsoft account, so every change is attributed to them. |
| Fields that sync | Title, description, acceptance criteria, status, assignee, story points. Parent links go from CardBoard to Azure DevOps. |
| Updates from Azure DevOps | Service hooks on each connected project, within seconds. Checked daily and re-registered if deleted. |
| Plan | Pro, Team, or Enterprise |
| Marketplace listing | Not listed yet. Connect from CardBoard. |
What syncs
Section titled “What syncs”| Card field | Direction | Notes |
|---|---|---|
| Title | Both ways | |
| Description | Both ways | CardBoard stores Markdown. Azure DevOps rich text is converted each way, so unusual formatting can simplify. |
| Acceptance criteria | Both ways | Maps to the standard Acceptance Criteria field. See Acceptance criteria. |
| Status | Both ways | Uses the work item’s own states (New, Active, Resolved, Closed, or your process’s states). |
| Assignee | Both ways | Matched by email address. |
| Story points | Both ways | Uses whichever estimate field the work item type has: Story Points (Agile), Effort (Scrum, Basic, and every Epic and Feature), or Size (CMMI). A type with none, like Task, is sent without a size. Clearing the size clears the points. |
| Parent | CardBoard to Azure DevOps, and on import | Setting a card’s parent in CardBoard sets the parent link on the work item. |
| Work item type | Set when created | Cards you send to Azure DevOps become the type you choose (Epic, Feature, User Story, Task, Bug). |
| Comments, tags, attachments | Not synced | |
| Position, slice, connections between cards, color, shape, reactions | Never | Position belongs to the map. Rearrange freely. |
Statuses. The card’s status menu lists the states your project uses, so you pick the names your team already knows. There’s nothing to map by hand.
Coupled fields, decoupled position
Section titled “Coupled fields, decoupled position”Rewrite the acceptance criteria in Azure DevOps and the card shows the new text within seconds. Pull the same card out of the release slice to see what ships without it, and the work item doesn’t change. Fields sync. Position stays on the map. Why position never syncs.
How the connection maps
Section titled “How the connection maps”- Your CardBoard workspace holds the connection to each Azure DevOps organization it syncs with. It can hold more than one.
- Each board connects to exactly one project in one organization. Boards connected to the same project share its service hooks.
- Each card links to exactly one work item in that project.
The workspace owns the connection and the service hooks, not the member who set them up. CardBoard checks the hooks every day and re-registers any an Azure DevOps admin deleted. See Service hooks.
Connect a board
Section titled “Connect a board”- Open the board, then open the tracker drawer and choose Azure DevOps.
- If you haven’t connected your Microsoft account yet, choose Sign in and approve CardBoard. You do this once, not per board.
- Pick the organization and project for this board, then choose what the drawer lists: All work items in the project, or one of the project’s saved queries. Only a query’s results appear, so a query is the easiest way to leave out closed work or another team’s area path. CardBoard registers service hooks on the project so changes in Azure DevOps reach the board. Registering hooks needs permission to manage service hooks in that project.
- Link your first card. Import work items from the drawer, or send cards you’ve planned to create work items from them.
Connecting a board requires a paid plan and permission to manage the board.
Import work items
Section titled “Import work items”Most teams already have a backlog when they start mapping. Import it, and CardBoard lays the work items out on the map using your Epic, Feature, and User Story tree. From then on the layout is yours to change.
Open the tracker drawer. Work items that aren’t on the board yet are listed under Not on Board.
- One item: drag it from the drawer onto the map, where you want it.
- Several items: select them and import them together.
Work items already on the board are skipped, so importing twice doesn’t make duplicates.
How the first layout is built
Section titled “How the first layout is built”On a story map, a batch import reads each work item’s parent link and builds the layout from the tree. Parents are created before their children and children land under their parents, so an epic’s features and stories arrive grouped the way they are in Azure Boards. Each card takes its type from the work item.
That layout is a starting point. After import, nothing in Azure DevOps moves a card. Reorder the backbone, move a story into a later release slice, or split a feature across two activities, and the work items don’t change. Fields keep syncing both ways.
What each work item gets
Section titled “What each work item gets”Every work item you bring onto the board gets a hyperlink titled CardBoard Card that opens its card on the map. The link is the plain card URL and grants no access. Someone without access to the board is asked to sign in or request an invite.
Send cards to Azure DevOps
Section titled “Send cards to Azure DevOps”Map first, then commit. When a release slice is agreed, send its cards to Azure DevOps and each one becomes a work item, linked back to its card.
- Open the tracker drawer on a board connected to an Azure DevOps project.
- Cards that aren’t linked yet are listed under Ready to Sync. Cards without a title are left out, since Azure DevOps won’t create a work item without one.
- Pick a work item type for each card: Epic, Feature, User Story, Task, Bug, or another type your project uses.
- Sync. CardBoard creates the work items and links each card to its new item.
Sending needs a workspace member with their own Microsoft account connected. The work items are created with that member’s account, so Azure DevOps shows who created them.
What a new work item gets
Section titled “What a new work item gets”| Work item field | From the card |
|---|---|
| Title | The card title |
| Description | The card description, converted from Markdown to Azure DevOps rich text |
| Acceptance Criteria | The card’s acceptance criteria, when the type is User Story |
| Assigned To | The card’s assignee, matched by email |
| Size | The card’s size |
| Hyperlink | A CardBoard Card link back to the card |
After that, the linked fields sync both ways.
Where new work items land
Section titled “Where new work items land”If the board is connected through a saved query, new work items take the area path, iteration path, and tags that query filters on, so they show up in the query and stay in the drawer. With All work items, they use the project defaults.
Parent links
Section titled “Parent links”Give a card a parent in CardBoard and, once both cards are linked, the child work item gets that parent in Azure DevOps. A parent card that isn’t linked to a work item has nothing to point at, so the child’s parent in Azure DevOps is left alone.
What doesn’t go across
Section titled “What doesn’t go across”The card’s place on the map, its release slice, color, connections, and reactions stay in CardBoard. Moving a card to another slice after sending it changes nothing in Azure DevOps.
Acceptance criteria
Section titled “Acceptance criteria”A card’s acceptance criteria and the work item’s Acceptance Criteria field
(Microsoft.VSTS.Common.AcceptanceCriteria) are the same text, edited from either side. Tighten
the criteria during a mapping session and the developer sees the new version in Azure Boards.
Change them in Azure Boards during a sprint and the card shows the change within seconds.
Azure DevOps is the only tracker CardBoard syncs acceptance criteria with, because it’s the only one with a standard field for them.
How it syncs
Section titled “How it syncs”| Change | Result |
|---|---|
| Edit acceptance criteria on the card | The work item’s Acceptance Criteria field updates. |
| Edit the Acceptance Criteria field in Azure DevOps | The card updates, carried in by service hooks. |
| Send a card to Azure DevOps as a User Story | The new work item is created with the card’s acceptance criteria. |
| Import a work item | The card gets the work item’s acceptance criteria. |
| Clear the acceptance criteria on the card | The Azure DevOps field is left as it was. |
Edits go out with the editing member’s own Microsoft account, so the work item history shows who changed the criteria.
Formatting
Section titled “Formatting”CardBoard stores acceptance criteria as Markdown. Azure DevOps stores the field as rich text. Lists, bold, italics, and line breaks convert both ways. Tables, colors, and other formatting Markdown can’t express come back simplified. Images are sent as absolute links so Azure DevOps can show them.
Which work item types
Section titled “Which work item types”New work items get acceptance criteria when they’re created as User Stories. For other types, link the card to a work item that already has an Acceptance Criteria field, and edits sync from then on. Which types have the field depends on your process (Agile, Scrum, CMMI, or custom).
Where to write them
Section titled “Where to write them”Acceptance criteria are a separate field on the card, next to the description. They’re prose, not a checklist, so write them the way your team writes them in Azure DevOps today. See Card properties.
Who can edit linked cards
Section titled “Who can edit linked cards”The workspace connection carries updates in. Writes go out as a person: every change is made with the editing member’s own Microsoft account, so the work item history shows who changed what. To edit a linked card you need to be a workspace member with your own Azure DevOps account connected. Until you connect it, the synced fields on linked cards are locked for you and CardBoard offers the sign-in. Guests can view, comment on, and react to linked cards.
Service hooks
Section titled “Service hooks”Changes made in Azure DevOps reach CardBoard through service hooks. CardBoard sets them up when a board connects and keeps them working without anyone watching them.
What CardBoard registers
Section titled “What CardBoard registers”Two subscriptions on each connected project: work item created and work item updated. Updates carry field changes onto linked cards within seconds.
Every board connected to the same project shares one set of hooks. Connecting a second board doesn’t add more.
Permission needed
Section titled “Permission needed”The member who connects the first board to a project needs permission to manage service hooks in that project. In Azure DevOps that’s usually a Project Administrator. Later boards on the same project reuse the existing hooks, so they don’t need it.
The daily health check
Section titled “The daily health check”The workspace owns the hooks, not the person who created them. Once a day, CardBoard checks every project its boards are connected to:
- A hook is missing (an admin deleted it, say): CardBoard registers it again.
- No board uses the project any more: CardBoard removes its hooks.
- Nobody connected can manage hooks (their access to the organization has ended, or their sign-in has expired): the check can’t repair the hooks until a connected member signs in again.
Repairs are made with the account of a member connected to a board on that project.
Where to see hook health
Section titled “Where to see hook health”Workspace admins see each Azure DevOps organization in Settings → Integrations: the boards connected to it, the members who’ve signed in, and the state of its service hooks.
If changes stop arriving
Section titled “If changes stop arriving”- Check Settings → Integrations for a hook or sign-in problem.
- Make sure at least one member connected to the board still belongs to the Azure DevOps organization. Azure DevOps rejects everyone else, whatever permissions CardBoard asked for.
- Ask that member to sign in again from their personal Integrations settings. The next daily check re-registers anything missing.
Disconnect
Section titled “Disconnect”- A board: a board manager disconnects it from the tracker drawer. Cards keep their current content but lose their work item links. When it’s the last board on a project, CardBoard deletes that project’s service hooks. Your work items stay exactly as they are.
- Your account: disconnect Azure DevOps from your personal Integrations settings. You’ll need to reconnect before you can edit linked cards again.
If a work item is deleted in Azure DevOps, its card stays on the map and shows the item as deleted. CardBoard never deletes work items.
Related
Section titled “Related”- Story mapping with Azure DevOps: why position stays on the map, and how CardBoard compares with hierarchy-synced story map tools.
- Working with your tracker: what to link, reorganizations, and migrating off. These work the same way for every tracker.