Azure DevOps processes and work item types
How your Azure DevOps setup affects a BoardwalkDesk desk, and what to choose.
Every Azure DevOps project uses a process (Microsoft also calls it a template). The process decides which work item types exist (Bug, Issue, User Story and so on), which states they move through, and which fields their forms show. BoardwalkDesk works with all of them: the four built-in processes (Basic, Agile, Scrum, CMMI) and customised copies of them. You never have to change your process for BoardwalkDesk.
When you create a desk you pick one work item type. Every ticket on that desk becomes a work item of that type in your project. You can pick a different type later on the desk's Settings page.
What BoardwalkDesk fills in
On every new ticket BoardwalkDesk sets only these fields:
- Title: the customer's title.
- Description: the customer's text. At the top it adds a Product: line (when the desk has products), a Severity: line (when the customer chose one) and a line for each desk question the customer answered (see below). At the bottom it adds who raised the ticket and that it came through BoardwalkDesk.
- Area Path: the chosen product's area, or the desk's own area.
- Tags:
BoardwalkDeskandBoardwalkDesk:your-desk, plusBoardwalkDesk:Privatewhen the customer keeps the ticket private (and on every emailed ticket when other customers or anyone can see the desk's tickets),BoardwalkDesk:Unverifiedon an emailed ticket whose sender could not be verified, and an answer tag such asVersion:2.4.1for each desk question you set up as a tag. - Priority (and Severity when your work item type has it): from the customer's severity, when the desk setting "Use the customer's severity as the starting Priority" is on (it is unless you turned it off).
- The fields you map to desk questions, such as Found In or a field you added yourself.
- The fields you set on every new ticket (Set on every new ticket on the desk's Settings page), such as Source = Portal, and the chosen product's name in the field you pick under Write the product to a field (see below).
- Attachments and comments.
Every other field gets whatever your process gives a new work item: its first state and the default value of any field you added yourself. BoardwalkDesk does not set any other field: Found In, Found In Environment and your own fields only when you map a desk question to them or set them on every new ticket, and Priority and Severity only from the customer's severity, once, when the ticket is created (unless you set Priority or Severity on every new ticket). It never changes any of them afterwards, so your team can re-triage freely. BoardwalkDesk reads the fields you choose to show your customers (see below) but never writes them.
Your process changes only when a desk admin asks for it. When a desk admin clicks Add it for me for a desk question's field and confirms, BoardwalkDesk adds that field to the desk's work item type in your inherited process (creating the field first when it is new, and putting it on the form in a group called Customer details). That changes every project that uses that process. It is done with the admin's own Azure DevOps sign-in, not the desk's connection, so the admin's Azure DevOps permissions decide. BoardwalkDesk never does this for a built-in process, never removes a field, never moves a project to another process, and never changes your process at any other time (see below).
Your internal work stays internal. The portal shows only the desk's tickets: work items a customer raised
through the desk, and work items you deliberately link to a customer (see below). Tasks, internal
issues and every other work item your team creates in the project never appear there, even when Azure DevOps reports a
change to them. Comments that start with [internal] are never shown or emailed to a customer.
Link an existing work item
A work item your team created directly in Azure DevOps (for example after a phone call) is not on the desk, so no customer
can see it. To hand it to a customer, open the desk's Settings page, enter the work item number and the customer's email
under Link a work item to a customer, and click Check. BoardwalkDesk shows the ticket exactly as the
customer will see it: the title, the status, the description and every comment that does not start with
[internal]. Nothing changes until you click Link.
- The work item must be in the desk's project and of the desk's work item type (the desk's service hooks watch only that type, so change its type in Azure DevOps first if needed). It can belong to one desk only.
- Linking adds the tags
BoardwalkDeskandBoardwalkDesk:your-desk (plusBoardwalkDesk:Privatefor a private ticket) and keeps every other tag. No other field changes. - The customer is added to the desk's customers if they are new, which counts toward your plan's customer limit. You can email them a link to the ticket. After that they get the usual emails when the status label changes or your team comments; the comments the work item already had are not emailed.
- Files attached in Azure DevOps stay team-only until you share them on the ticket's page in the team area.
- Unlink from customer on that page takes the ticket away again: the customer no longer sees it, nobody is emailed, and the desk's tags are removed from the work item.
Which work item type to choose
Customers' text goes into Description, so pick a type whose form shows the Description field. In the built-in processes that is every type in the table below except Bug. The Create a desk page picks one for you: Issue in Basic and CMMI, User Story in Agile, Product Backlog Item in Scrum.
| Process | Good choices | States (in order) | Notes |
|---|---|---|---|
| Basic | Issue | To Do, Doing, Done | Basic has only Issue, Task and Epic; it has no Bug type. Issue is meant for this. |
| Agile | User Story, Issue | User Story: New, Active, Resolved, Closed, Removed Issue: Active, Closed |
Agile's Issue has no "new" state: tickets start as Active (shown as "In progress") and customers cannot reopen a closed ticket. User Story avoids both. |
| Scrum | Product Backlog Item | New, Approved, Committed, Done, Removed | Scrum's Impediment starts as Open (in progress) and also has no "new" state. |
| CMMI | Issue, Requirement | Proposed, Active, Resolved, Closed | |
| Agile, Scrum, CMMI | Bug: avoid for now | Agile and CMMI: New/Proposed, Active, Resolved, Closed Scrum: New, Approved, Committed, Done, Removed |
The Bug form shows Repro Steps and System Info instead of Description. BoardwalkDesk writes the customer's text to Description, so on these Bug forms your team would not see it. |
Types for tests, code reviews and feedback, and types your process hides, are never offered.
Desk questions: version, environment and more
On the desk's Settings page, under Desk questions, you can add up to 6 extra questions to the ticket form. One click adds a ready-made one (Version, Request type, Environment, Reference number) or a question of your own; each can be a short text, a pick list, a date, a number, Yes/No or a long text (several lines), optional or required, offer "I don't know", and be asked for every ticket or only for some of the desk's products. Your customers see the label, the hint and the choices; they never see field names or tags.
Each answer goes to up to three places in the new work item:
- Always a line at the top of the description, such as Version: 2.4.1 ("not known" for "I don't know").
- A real field, when you pick one for the question. A real field is what you want for sorting, queries, charts and reports. Only fields of the desk's work item type that BoardwalkDesk may write are offered: not read-only fields, people fields, or the fields Azure DevOps and BoardwalkDesk fill themselves (Title, State, Area Path and so on). A short text needs a text field, a pick list a text or pick-list field (or a number field with a fixed list), a date a date field, a number an Integer or Decimal field (a whole number for an Integer field), Yes/No a Boolean field, and a long text a multi-line text field. When the field has its own list of values, the ticket form offers exactly that list. A field that is not on the work item type yet can be added as described below.
- A tag prefix
:answer, such asEnvironment:Production, when you tick "Also add a tag". Tags suit pick lists. For free text every different answer becomes a new tag, so use it only when answers repeat, such as versions (a leading "v" is dropped, so v2.4 and 2.4 are one tag). Dates and long texts never become tags.
Only the ticket form asks the questions. A ticket that arrives by email has no answers, and a required question never stops it. If Azure DevOps refuses a new answer tag (the desk's account may not create tags), BoardwalkDesk creates the work item again without the answer tags but still with the answers' fields. If it refuses a question's field or value (for example the field was removed from your process), it creates the work item again without the answers' fields and tags. Either way the answers stay in the description, and your team gets a note saying what could not be set and what Azure DevOps said.
Getting a real field on any process
A question's field list shows the fields already on the desk's work item type. To use another field of your organization (for example Severity or Found In on a User Story) or a completely new one, choose Use a field not on your work item type at the end of the question's field list on the desk's Settings page. Pick an existing field (search by name) or type a name and a type for a new one. Then choose, each time:
- Add it for me, only when your project uses an inherited process. BoardwalkDesk first shows the process, the projects that use it, and that every work item of that type in those projects gets the field. The list shows only the projects your Azure DevOps account can see; the change applies to every project on the process. You tick I understand this changes every project on the process and click Add. With your own Azure DevOps sign-in it then creates the field when it is new (for a new pick-list field it first creates a pick list with the question's choices), makes the process's own inherited copy of the work item type when the type was never customized in it (Azure DevOps requires that before a field can be added; the type's states, fields and form stay as they are), adds the field to the work item type (not required) and puts it on the form in a group called Customer details; the question is still saved with Save questions. Your Azure DevOps account needs permission to edit the process (Project Collection Administrators have it); without it BoardwalkDesk says so and shows the steps instead. The field can be removed only in Azure DevOps.
- Show me how: the steps below, filled in with your organization, process, work item type and field, ending with Check again, which reads the fields again and picks the field for the question.
The built-in processes (Basic, Agile, Scrum, CMMI) cannot be changed. For them only Show me how is offered: it includes creating an inherited process and moving your project to it, which you always do yourself. A Hosted XML process changes only when it is imported again. To add a field yourself:
- You need permission to create and edit processes in your organization (Project Collection Administrators have it; Microsoft: process permissions).
- Open Organization settings > Boards > Process
(
https://dev.azure.com/your-organization/_settings/process). - If your project uses a built-in process (for example Basic): select ... next to it, choose Create inherited process, give it a name and select Create process (Microsoft: Create an inherited process). If your project already uses an inherited process, skip this.
- Open the inherited process, then the desk's work item type (for example Issue).
- Select New field. Create a field (Text (single line) for a short text or a version, Picklist (string) for a fixed list, Date/Time for a date, Integer or Decimal for a number, Boolean for Yes/No, Text (multiple lines) for a long text), or choose Use an existing field to reuse one such as Found In or Found In Environment.
- On the Layout tab choose the Details page and a group (for example a new group called Customer details), then select Add field. You can give it any label on the form; BoardwalkDesk lists it by its field name.
- If you created a new inherited process: back on the process list, open the process your project uses now, then its Projects, and choose Change process on your project to move it to the inherited process (Microsoft: Change a project's process). Your work items, states and settings stay.
- In the desk's Settings page, under Desk questions, pick the new field for the question (or select Check again in Use a field not on your work item type) and click Save questions. The Azure DevOps check on the same page then shows the question going to that field, and whether it is sortable.
Without a field the question still works: the answer goes to the description and, if you choose, a tag.
Severity and Priority
The ticket form lets the customer pick a severity (Critical, High, Medium, Low). It is always written as a Severity: line at the top of the description. With the desk setting "Use the customer's severity as the starting Priority" on (the default), it also sets the new work item's Priority: Critical 1, High 2, Medium 3, Low 4. When the work item type also has a Severity field (Bug in Agile, Scrum and CMMI), it is set to the matching value, such as "1 - Critical"; if your process changed those values so they no longer start with 1 to 4, the field is left alone. This happens only when the ticket is created: your team can change Priority and Severity afterwards and BoardwalkDesk never sets them again. Turn the setting off and Priority keeps your process's default. A desk question mapped to Priority or Severity takes precedence.
Product and who raised it
Each product on the desk's Settings page can have its own Area Path (Project Settings > Boards > Project configuration > Areas), so each product's tickets show on the right team's board, and its name is written as a Product: line. Azure DevOps has no built-in field for an outside customer: the customer's name and email are written at the bottom of the description. "Created By" shows the team member who connected the desk, because BoardwalkDesk works with that connection.
Fields set on every new ticket
Under Set on every new ticket on the desk's Settings page you can give up to 10 fields of the desk's work item type a fixed value, for example Source = Portal, so your own queries, dashboards and automations can tell desk tickets apart. BoardwalkDesk writes them on every new ticket, from the ticket form and by email; a work item you link to a customer is not changed. Only fields BoardwalkDesk may write are offered (the same rule as for desk questions), and the value must suit the field: one of its values for a pick list, a whole number, a number, Yes/No or a date. A field a desk question goes to cannot be set here: the question's answer wins. A value set here wins over the customer's severity for Priority or Severity.
Under Write the product to a field you can pick one text or pick-list field (for example Product) that gets the name of the product the customer chose, from the ticket form or by email. For a pick-list field whose values do not include a product's name, that ticket leaves the field empty and your team gets a note on the work item.
If Azure DevOps refuses one of these fields (for example it was removed from your process), BoardwalkDesk creates the work item again without them, as it does for desk question fields, and your team gets a note saying which fields were left out and what Azure DevOps said. The Azure DevOps check on the Settings page lists these fields, and warns about a field that is gone, a value the field no longer takes and products a pick-list field does not hold.
What your customers see of a work item
By default the portal shows a ticket's title, its status label, the description (without the team-only footer), the
comments that do not start with [internal] and the files you shared. Two settings on the desk's Settings page
show more; BoardwalkDesk only reads these fields, with the desk's connection:
- Show to customers: up to 6 fields of the desk's work item type, each with your own label, shown under the ticket's title when they have a value, for example Fixed in from a Fixed In Release field your release pipeline fills in. Rich text is cleaned like the description, dates show as yyyy-MM-dd and Yes/No fields as Yes or No. People fields (such as Assigned To) and Azure DevOps' own System fields are never offered. A customer sees them only on a ticket they may open.
- Release notes: a page in the portal (
/d/your-desk/releases, and one per product) that lists the desk's tickets whose release field has a value, grouped by release, newest first: each ticket's number, title, product (from the field under Write the product to a field) and an optional note field. Every customer signed in to the desk can see it, including other customers' tickets, so turn it on only if that suits you (anyone can, without signing in, when the desk shows its tickets to anyone with the link). Private tickets and tickets held for review are never listed. It reads the newest 2,000 tickets and follows Azure DevOps within 10 minutes. While it is on, the ticket form offers "Keep this ticket private" on every desk. - Who can see tickets (Settings, 3 Customers): when the desk shows its tickets to every
signed-in customer or to anyone with the link, they read each ticket that is not private: title, status, the description
(with the answers to the form's questions), the comments without
[internal]ones and without replies the customer sent by email, and the files your team made public. BoardwalkDesk takes the customer's name and email address out of what they read, including the "Raised by" line at the bottom of the description. Your team's "Make private" and "Let others see it again" buttons work at once; "Let others see it again" also removes theBoardwalkDesk:Privatetag from the work item. ABoardwalkDesk:Privatetag your team adds directly in Azure DevOps hides the ticket page within a minute but can take up to 5 minutes to hide it from the All tickets list (up to 10 from the release notes). Switching a desk away from "Only the customer who raised it" makes its existing tickets private.
Tags and the permission to create them
Applying a tag that already exists in the project needs no special permission, but a new one (for example
BoardwalkDesk:your-desk on the desk's first ticket, or the first Version:3.0) needs the
project-level Create tag definition permission for the account the desk is connected with. Contributors
have it by default. In a private project a Stakeholder can only apply existing tags, so connect the desk with an account
that has at least Basic access. To grant the permission: Project settings > Permissions > that account or its group
> Create tag definition = Allow. The Azure DevOps check on the Create a desk and Settings pages tells you whether
it is allowed (it reads the permission, not the access level). Without it, a ticket that needs a new desk tag fails; when
only an answer tag is new, the ticket is created without the answer tags (see above).
States and what customers see
BoardwalkDesk reads the states of your work item type from Azure DevOps and never adds, renames or deletes them. Customers see a label for each state instead of its name, which you set on the desk's Settings page. By default a state in the "Proposed" category shows as Received, "In Progress" as In progress, "Resolved" as Resolved, and "Completed" or "Removed" as Closed. When a customer reopens a closed ticket it moves back to the type's first Proposed state; a type without one (Agile's Issue, Scrum's Impediment) cannot be reopened by customers.
Customised processes
A customised (inherited) process works the same way. Three things to check:
- Required fields need a default value. BoardwalkDesk fills in only the fields listed above. If you made another field required and gave it no default, Azure DevOps refuses every new ticket. The Azure DevOps check on the desk's Settings page lists such fields. A required desk question that always answers it (no "I don't know", asked for every product) fills it for tickets from the ticket form, but tickets that arrive by email have no answers, so give the field a default anyway.
- Your own fields keep their defaults. BoardwalkDesk fills them only when you map a desk question to them, so a default like "Low" will appear on every other customer ticket until your team changes it.
- Pick a type whose form shows Description, as above. If you built your own Bug type with a Description field on its form, it is fine to use.
Changing your process later
You can move a project to another process at any time (Organization settings > Boards > Process). If the desk's work item type no longer exists afterwards (for example you leave a customised process that had a Bug type and go back to Basic), new tickets fail until you pick another type on the desk's Settings page; the page warns you when this happens. Tickets already filed keep their old type and stay visible to your customers, but the desk's service hooks then watch only the new type, so customers are no longer emailed when your team changes one of those older tickets.