Customize the workflow for a process

Last Update: 4/5/2017

Team Services (Inheritance)


This topic applies to team project and process customization for the Inheritance process model. For the Hosted XML process model, you customize your team project by importing a custom process template; and for the On-premises XML process model, you customize by importing modified XML definition files.

For an overview of process models, see Customize your work tracking experience.

Each work item type is associated with a workflow that supports tracking the status of work as it moves from creation to completion. To support your business and team processes, you can add custom states to most work item types (WITs). For example, you may want to insert a Triaged state for bugs, or a Design state for features or user stories.

Here, the Bug WIT has been customized to support a Triaged state.

Bug work item form, header area

What you can customize

You customize the workflow for a WIT by adding a custom state. Each WIT consists of two or more inherited states. Inherited states differ based on the core system process —Agile, Scrum, or CMMI—you chose from which to create your custom process.

Workflow elements Customization options
Inherited states Inherited states View assignments | Hide a state
Custom states Add a state | Edit a state | Remove a state

To perform any of these actions, you must be a member of the Project Collection Administrators group or be granted explicit permissions to edit a specific process.

What you can't customize

  • You can't modify an inherited state (you can't change its name, color, or category)
  • You can't hide an inherited state if it's the only one in its state category
  • You can't change the name of a custom state
  • You can't add a custom state to the Completed category
  • You can't change the order of states (states are listed in the order you add them within the States page, and they're listed alphabetically within the drop down list of a work item form)
  • You can't apply a field rule to a state (for example, make a field required).

Workflow elements and state categories

All workflows consist of states, transitions, and reasons. A transition supports forward and backward movement among two states. When you add a custom state, the system automatically adds transitions from the custom state to all other inherited states (except for Removed).

Each state belongs to a state category (previously referred to as a metastate). State categories support the Agile tool backlog and board views.

Workflow states

Workflow states define how a work item progresses from first activation or creation to closed or complete. For example, the four main states defined for the Agile process User Story define a progression of four states, from New, Active, Resolved, to Closed. A fifth state, Removed, also exists to support removing a work item from appearing on the backlog.

The natural progressions and regressions of the user story, product backlog item, and requirement WITs are as shown.

User Story (Agile)

User Story workflow states, Agile process

Product backlog item (Scrum)

Product backlog item workflow states, Scrum process template

Requirement (CMMI)

Requirement workflow states, CMMI process

State categories

State categories, on the other hand, determine how the Agile planning tools treat each workflow state. The state categories used by the backlogs and boards are Proposed, In Progress, and Complete.

Here's how the default, inherited states map to the metastate categories for all three system processes plus test case management WITs. The workflow states for Test Case, Test Design, and Test Suite are the same across all three system processes.

Categories Agile Scrum CMMI Test WITs
Proposed: Assign to states associated with newly added work items that should appear on the backlog. The first column on the Kanban or task board maps to a Proposed state. New New
To Do (Task)
Design (Test Case)
In Progress: Assign to states that represent active work. Work items assigned to states mapped to this category will appear in the backlog (unless you choose to hide them) and make up the middle columns on the Kanban boards. Active
Resolved (Epic, Feature, User Story)
Open (Impediment)
Resolved (Epic, Feature, Requirement, Task)
Active (Test Plan)
In Planning (Test Suite)
In Progress (Test Suite)
Ready (Test Case)
Resolved: Assign to states that represent a solution has been implemented, but are not yet verified. Generally these states apply to bug WITs. Work items in a Resolved state appear on the backlog by default. Resolved (Bug) n/a Resolved (Bug, Issue, Review, Risk) n/a
Completed: Assigned to states that represent work has finished. Work items whose state is in this category don't appear on the backlog and do appear in the last column of the Kanban board. Note that you can't modify states in this category nor can you add states to this category. Closed
Closed (Test Case)
Completed (Test Suite)
Inactive (Test Plan)
Removed: Assigned to the Removed state. Work items in a state mapped to the Removed category are hidden from the backlog and board experiences. Removed Removed n/a n/a

When to add a State versus a Kanban column

Both States and Kanban columns are used to track the status of work. Workflow states are shared across a team project while Kanban columns are shared within a team. Only project collection admins can add custom states, while team admins can add Kanban columns.

Add custom states when you want all teams to track the status according to the business workflow adopted by the organization. By customizing the process, you automatically customize the team projects and WITs that reference that process.

Also, by adding custom states to support those workflow states that several teams want to track, you avoid the confusion that can arise when team's create a query based on a Kanban column. Because each team can customize the Kanban board columns and swimlanes, the values assigned to work items which appear on different boards may not be the same. The primary work around for this issue is to maintain single ownership of work items by team area path. Another work around is to formalize the columns by adding custom states which can be shared across teams.

Open Process>Work Item Types in the admin context

  1. To open the admin context from the user context, click the gear Settings icon and choose Account settings.


    If you don't see the Account settings option, then you are working from an on-premises TFS. The Process page isn't supported. You must use the features supported for the On-premises XMl process model as described in Customize your work tracking experience.

    Default Collection Overview, Projects reference processes

  2. Click Process.

    Web portal, Account menu, Turn on new navigation selection

  3. Choose the inherited process you want to customize, and then click Work Item Types. If you haven't yet created an inherited process, do that now. See Create an inherited process.

    Here we open Work Item Types for the MyAgile process.

    Process page, WITs


States you add will appear in the pick list for the States field shown in work item forms and the query editor. A transition to and from the State you add is created to every other State, except not to a Removed state. Also, default reasons are defined, such as Moved to state Triaged, Moved out of state Triaged.

Add a state

  1. From the Work Item Types tab, choose the States tab for the process and WIT to which you want to add a custom state, and then choose New State.

    Process page, Bug WIT, States tab, Add state

  2. Enter the name of the State, choose it's category and color, and then click Save. The color you specify will appear throughout the product including on the work item form and when the State field appears on a backlog, boards, query results, and more.

    State dialog box

  3. When you've finished adding states for the WIT, check the layout. Refresh your browser and open a work item of the type you just customized.

    Here we show the state drop down field with Triaged selected.

    Bug form, Triaged state added

  4. Team's that use the Kanban board will need to update their column settings. Work items assigned to a custom state won't appear on the Kanban board until you assign the column mappings.

Edit a state

You can edit the category or the color of a custom state. You can't change the name of the custom state.

  1. Choose Edit from the actions menu for the state you want to modify.

    Bug WIT, Edit custom state

  2. Modify the category or color, and then click Save.

  3. If you change the category, team's that use the Kanban board may need to update their column settings.

Remove a state

  1. Choose Remove from the actions menu for the state you want to remove. You can only remove a custom state.

    Process page, Bug WIT, States tab, Add state

  2. From the Remove State dialog, click Remove.

    Remove state warning dialog box

  3. If you use your Kanban board to update the status, you'll need to update the column settings for each team.

When you remove or hide a state:

  • The state no longer appears in the State pick list for the WIT, nor does it appear in the query editor pick list for the state field.
  • You can't assign new work items to the removed or hidden state.
  • Existing work items maintain their state value, but are in an invalid state. If you want to make a change to the work item, the state values must be updated. If you add the state back to the work item type, the work items revert to a valid state.
  • No changes occur to the work item history.

Hide and unhide a state

You can hide an inherited state that your team doesn't use in its workflow process. However, you must have at least one state defined for each category.

  1. Choose the Hide option for the WIT state you want to hide. Here we Hide the RAesolved state for

    Hide an inherited state

  2. Team's that use the Kanban board will need to update their column settings.

  3. To unhide, choose the Unhide option from the action menu.

    Unhide an inherited state

As you customize a workflow, all team projects that reference the inherited process that you're customizing will automatically update to reflect the customized workflow states. To view your customizations, refresh your web browser.

To customize a single team project, always start by creating an inherited process and migrating the team project to that process. Then, all the customizations that you make to the inherited process automatically appear for the team project you migrated.

Additional topics of interest:

Feedback and support

We welcome your feedback.

Send suggestions on UserVoice, and follow us on Twitter @VSTeam. Or, tell us what you think with Send-a-Smile on the title bar ... Send-a-Smile.

Or, see our comprehensive feedback and support page.

Need additional help?

Email VS Team Services Customization Help and we'll be happy to help you out!