Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining

Process configuration XML element reference

Process configuration defines the default configuration and functional capabilities that your teams can access using the Agile planning tools. These tools, which you view from the web portal, include the product backlog, sprint backlogs, Kanban board, and task board. These tools become available to you when you create a team project either in Visual Studio Online or on an on-premises Team Foundation Server (TFS).

Configuration elements specify the work item types (WITs), default columns, fields used by the tools, and other elements. The main configurations made determine which items will display for the portfolio, product, and sprint backlogs by defining the PortfolioBacklog, RequirementBacklog, and TaskBacklog sections of the process configuration XML definition file. In addition, process configuration defines the workflow state-to-metastate mappings for all WITs that require mapping.

Process configuration XML elements

Configure and customize Agile planning tools for a team project summarizes what you can configure through the user interface and what requires configuration by defining the ProcessConfiguration file.

Areas that you customize through ProcessConfiguration:

To update the process configuration, you export the XML definition file, edit it, and then import the file. You use the witadmin command line tool to import and export the file.

Process for customizing a WIT object
Note Note

The syntax samples shown in this topic correspond to the default assignments defined in the Scrum process template. To access the latest version of the process templates, install the latest version of TFS and download the templates using the Process Template Manager.

You can customize the following elements for the product backlog, sprint backlogs, and portfolio backlogs:

  • Metastate mappings: Map workflow states to metastates. These mappings support the display of all Agile planning tools, including the Kanban and task boards.

  • Quick add panel: Specify the WITs and work item fields that appear for quickly adding items to the backlog.

    To change the types of work items that are considered backlog items or tasks, you add them to the corresponding category. For an example, see Add bugs to the task board or backlog.

  • Column fields: Define the default fields and column sequence.

You configure backlogs within the XML sections that appear in the following sample:

   <PortfolioBacklog category="Microsoft.EpicCategory" pluralName="Epics" singularName="Epic" workItemCountLimit="1000">
. . . 

     <PortfolioBacklog category="Microsoft.FeatureCategory" pluralName="Features" singularName="Feature" parent="Microsoft.EpicCategory" workItemCountLimit="1000">
. . . 
<RequirementBacklog category="Microsoft.RequirementCategory" pluralName="Stories" singularName="User Story" workItemCountLimit="1000">
. . . 
<TaskBacklog category="Microsoft.TaskCategory" pluralName="Tasks" singularName="Task" workItemCountLimit="1000">
. . . 




Optional. Container element for portfolio backlogs.


Optional. Up to five instances.

Container element that defines the metastate mappings, default columns, and quick add panel for a portfolio backlog.

<PortfolioBacklog category="PortfolioCategory" parent="ParentCategory" pluralName="PluralName" singularName="SingleName" workItemCountLimit="MaximumLimit>
   <States> . . . </States>
   <Columns> . . . </Columns>
   <AddPanel> . . . </ AddPanel>
</PortfolioBacklog >

Assign values to the attributes as described:

  • category: Specify the name of a category that you have defined in the categories definition file for the team project that contains the WITs to be associated with this backlog type.

  • parent: Specify the name of the category that represents the parent portfolio backlog within the hierarchy.

  • pluralName: Specify the plural label to use when referring to the WITs associated with this backlog type. For example, Stories, Goals, Initiatives, or Epics.

  • singularName: Specify the singular label to use when referring to the WITs associated with this backlog type. For example, Story, Goal, Initiative, or Epic.

  • workItemCountLimit: Specify an integer. Default is 1000. Backlogs and boards will limit the count of items displayed based on this limit.


Required. One instance only.

Container element that defines the metastate mappings, default columns, and quick add panel for the product backlog. The product backlog displays all active items in the team’s backlog.

<RequirementBacklog category="RequirementCategory" pluralName="PluralName" singularName="SingleName" workItemCountLimit="MaximumLimit" >
   <States> . . . </States>
   <Columns> . . . </Columns>
   <AddPanel> . . . </ AddPanel>
</RequirementBacklog >


Required. One instance only.

Container element used to customize the layout of sprint backlogs.

<TaskBacklog category="Microsoft.TaskCategory" pluralName="Tasks" singularName="Task workItemCountLimit="MaximumLimit">
. . . 
</TaskBacklog > 

  • By default, each backlog is restricted to a total of 1000 work items. You can change this limit by specifying a value for the workItemCountLimit attribute.

  • The values assigned to CategoryName must correspond to a category group defined for the team project. You specify category groups in the definition file for Categories.

  • You use portfolio backlogs to organize your backlog, view the rollup of backlog items at lower levels, and to view progress across several teams. New and upgraded team projects contain two portfolio backlog levels: Features and Epics. You can add up to three additional levels. Only the top level portfolio backlog doesn’t specify a parent category.


    You may need to have Advanced access to exercise some of portfolio backlog features.

  • Your product backlog corresponds to your project plan, the roadmap for what your team plans to deliver. It lists work items whose WITs belong to the Requirements Category. In order to manage different WITs than those provided by your default team project, you can add WITs to the Requirements Category and map the workflow states to metastates.

  • Your sprint or iteration backlogs display both the set of requirements that you and your team have committed to in a specific sprint cycle and the tasks that you have linked to those requirements. You link tasks to requirements using the parent-child link type. Because the WITs that appear on these backlogs correspond to the same types that appear on the product backlog, much of the customization work that you do for the product backlog will define the functionality of the sprint backlog.

Most WITs require their workflow states to be mapped to a metastate. Workflow states define how a work item progresses from first activation or creation to closed or complete. For example, the states defined for the Scrum product backlog item define a progression of four states, from New, Approved, Committed, to Done, and also includes a fifth state, Removed, to account for a state removed from the backlog without being implemented.

Metastates, on the other hand, determine how the Agile planning tools treat each workflow state. The primary metastates used by the backlog and task board are Proposed, InProgress, and Complete.

By associating each workflow state to a metastate, the background operations performed to display the backlog and task boards know how to correctly interpret the status of each work item. For example, the following mappings are defined for the Scrum product backlog.

<RequirementBacklog category="Microsoft.RequirementCategory" pluralName="Backlog items" singularName="Backlog item">
      <State value="New" type="Proposed" />
      <State value="Approved" type="Proposed" />
      <State value="Committed" type="InProgress" />
      <State value="Done" type="Complete" />
 . . .
</RequirementBacklog >

There are three categories of metastates: Agile, Bug, and Feedback. The following table describes the mapping attributes and values.




Required. Assigns a workflow state to a metastate.

<State type="TypeName" value="ValueName"/>

Valid values for TypeName correspond to a value assigned to a STATE within the WORKFLOW section of those WITs assigned to the category group.

Valid values for ValueName correspond to one of the following enumerated values:

  • Agile: Use for all work item types.

    • Proposed: Indicates work items that are new, not yet committed, or not yet being worked on.

    • InProgress: Indicates work items that have been committed or are actively being worked on.

    • Complete: Indicates work items that have been implemented. For the Kanban board to be valid, at least one workflow state must be mapped to the Complete metastate.

      Once a workflow state transitions to a state that is associated with the Complete metastate, the associated work item will fall off the product backlog. However, it will continue to be listed on the Kanban board.

    Work items in a workflow state that aren’t mapped to one of the supported metastates don’t appear on the backlog or board.

  • Bug: Use only for work item types grouped within the Bug Category. In addition to the Agile metastates, includes the Resolved metastate which indicates bugs that have been resolved.


    You can only assign the Resolved metastate to a workflow state specified under the BugWorkItems element.

  • Feedback: Use only for work item types grouped within the Feedback Request or Feedback Response categories. Requested, Received, Reviewed, and Declined.


Specifies a collection of State elements that associate WIT workflow states with metastates.

Required element for the following parent elements:

  • BugWorkItems

  • PortfolioBacklog

  • RequirementBacklog

  • TaskBacklog

  • TestPlanWorkItems

  • TestSuiteWorkItems

  • FeedbackRequestWorkItems

  • FeedbackResponseWorkItems

Specify which fields you want displayed on each backlog within the Columns section. Changes you make through the Column Options dialog persist until you change them again.

Default columns and sequence for backlog page

Here’s the default configuration defined by the Scrum process template for the product backlog.

   <Column refname="Microsoft.VSTS.Common.Priority" width="400" />
   <Column refname="System.Title" width="400" />
   <Column refname="System.State" width="100" />
   <Column refname="Microsoft.VSTS.Scheduling.Effort" width="50" />
   <Column refname="System.IterationPath" width="200" />




Specifies a collection of Column elements. Required element for the backlog elements: PortfolioBacklog, RequirementBacklog, and TaskBacklog.


Specifies a field to appear as a column on a backlog.

<Column refname="FieldReferenceName"  width="FieldWidth" />

Task board column headings

The column headings that appear on the task board correspond to the workflow states assigned to the default WIT assigned to the Task Category. The column sequence corresponds to the natural progression of the workflow transitions, moving from left to right. To modify the column layout, you modify the workflow for the WIT assigned to the Task Category. The workflow states defined for the default task type in the Task Category must be assigned to a valid metastate as described in Map metastates for a category of work item types.

You can add fields for any quick add panel. For example, the following example adds Business Value to the product backlog panel.

Backlog panel with Business Value field added

The panel only displays fields that are included in the FIELDS section of the WIT definition for the WIT selected. For example, if you select the bug WIT, then only Title displays, because Business Value isn’t defined for bugs. To add another WIT to the panel, you add it to the Requirements Category as described here.

The following code corresponds to the default assignments defined in the Visual Studio Scrum and MSF for Agile process templates.

      <Field refname="System.Title" />




Container element used to specify the “quick add” experience, the fields to appear within the panel area where new backlog items are defined.


Specifies a collection of Field elements.


Specifies a work item field to appear within the panel for the product backlog.

<Field refname="FieldReferenceName"/>

The same field should appear on the work item form of each WIT included in the category for the backlog.

For performance reasons, the task board is restricted to display a maximum of 1000 work items. When you open the task board, all work items are loaded into cache. Limiting the number of work items may yield quicker load times. You can change this limit by specifying a value for the workItemCountLimit attribute of the TaskBacklog element.

For example, you can decrease the limit by specifying workItemCountLimit="800":

<TaskBacklog category="Microsoft.TaskCategory" pluralName="Tasks" singularName="Task" workItemCountLimit="800" >
. . .

Metastate mappings are defined for additional WIT categories. For the Scrum process template, this includes mappings for the feedback request and response categories. For the MSF Agile and CMMI process templates, it also includes mappings for the bug category. (Scrum includes bugs in the Requirement Category and therefore defines the metastate mappings within the RequirementBacklog section.)

<FeedbackRequestWorkItems category="Microsoft.FeedbackRequestCategory" pluralName="Feedback Requests" singularName="Feedback Request">
      <State value="Active" type="InProgress" />
      <State value="Closed" type="Complete" />
<FeedbackResponseWorkItems category="Microsoft.FeedbackResponseCategory" pluralName="Feedback Responses" singularName="Feedback Response">
   <State value="Active" type="InProgress" />
   <State value="Closed" type="Complete" />

The following table describes the additional elements used to define the metastate mappings for tool-specific work item types. See Map metastates for a category of work item types for information about assigning the actual state values and types. The CategoryName must correspond to a category defined for the team project.




Optional. Container element that defines the metastate mappings for work item types assigned to the Bug Category. In addition to how these mappings are used in the display of Agile tools, they also control how the My Work feature in Team Explorer updates the bug state as developers move bugs using My Work. To learn more, see Day in the life of an ALM Developer: Write new code for a user story.

<BugWorkItems category="CategoryName" pluralName="PluralName" singularName="SingleName">
. . .


Required. Do not customize.

Container element that defines the metastate mappings for work item types assigned to the feedback request category.

<FeedbackResponseWorkItems category="CategoryName" pluralName="PluralName" singularName="SingleName">
. . .


Required. Do not customize.

Container element that defines the metastate mappings for work item types assigned to the feedback response category.

<FeedbackResponseWorkItems category="CategoryName" pluralName="PluralName" singularName="SingleName">
. . .


Only required when you customize the workflow state for Test Plan and you support connections to the team project from versions of Test Manager installed with Visual Studio 2013.2 or earlier versions.

Container element that defines the metastate mappings for work item types assigned to the Test Plan Category. For example:

<TestPlanWorkItems category="Microsoft.TestPlanCategory" pluralName="Test Plans" singularName="Test Plan">
      <State type="InProgress" value="Design" />
      <State type="InProgress" value="Testing" />
      <State type="Complete" value="Signed Off" />


Only required when you customize the workflow state for Test Suite and you support connections to the team project from versions of Test Manager installed with Visual Studio 2013.2 or earlier versions.

Container element that defines the metastate mappings for work item types assigned to the Test Suite Category. For example:

<TestSuiteWorkItems category="Microsoft.TestSuiteCategory" pluralName="Test Suites" singularName="Test Suite">
      <State type="Proposed" value="Authoring" />
      <State type="InProgress" value="Testing" />
      <State type="Complete" value="Completed" />

To map metastates for TestPlanWorkItems or TestSuiteWorkItems, you must upgrade your application-tier server to TFS 2013.3. Afterwards, you can customize the workflow state of test plans and test suites.

To learn more, see Import and export process configuration.

You can change the work item fields that are used in calculating capacity, burndown charts, forecasting, and velocity. Any change you make to one of the default assignments should correspond to a change made to the WIT used to define and capture information for that value.

For example, if you change the refname assigned to type="Activity" then you should include the same field in the WIT definition assigned to the Task Category which captures the activity information.

    <TypeField refname="System.AreaPath" type="Team" />
    <TypeField refname="Microsoft.VSTS.Scheduling.RemainingWork" type="RemainingWork" format="format h" />
    <TypeField refname=" Microsoft.VSTS.Common.BacklogPriority" type="Order" />
    <TypeField refname="Microsoft.VSTS.Scheduling.Effort" type="Effort" />
    <TypeField refname="Microsoft.VSTS.Common.Activity" type="Activity" />
    <TypeField refname="Microsoft.VSTS.Feedback.ApplicationStartInformation" type="ApplicationStartInformation" />
    <TypeField refname="Microsoft.VSTS.Feedback.ApplicationLaunchInstructions" type="ApplicationLaunchInstructions" />
    <TypeField refname="Microsoft.VSTS.Feedback.ApplicationType" type="ApplicationType">
            <TypeFieldValue value="Web application" type="WebApp" />
            <TypeFieldValue value="Remote machine" type="RemoteMachine" />
            <TypeFieldValue value="Client application" type="ClientApp" />




Required. Specifies a collection of TypeField elements.


Required. Specifies the reference name of a field whose value supports a type of activity for a feature area. The fields you specify should correspond to the fields that you use within the WITs used to capture the feature information.

<TypeField refname=”FieldReferenceName” type=”NameOfType” [format="{0} TimeUnitString"] / >

Specify the format only when type="RemainingWork". You can specify any text string for the TimeUnitString that you want to have appear on the capacity bars on the current sprint backlog and on the task board.

For Agile tools:

  • Activity: Used to support the capacity-by-activity feature. Specify the same field used in the WIT assigned to the Task Category.

    Note: The values displayed by the Capacity tool reflect a union of all values defined for the field in all team projects within the project collection instance. Therefore, to restrict the values that appear for sprint Capacity, you must make the values match in all the team projects for the field assigned to type="Activity".

  • Effort: Used to calculate the team velocity. Specify the same field used in the WIT assigned to the Requirement Category that you use to capture the estimated level of effort, story points, or size for the amount of work that a backlog item requires to implement.

  • Order: Used to define the sort order for items on the backlogs and boards. The system lists work items according to their ascending order as defined by the field for this type.


    You can move items by dragging them up or down the list on a backlog or board. As you move items, a background process updates the field assigned to the type="Order".

  • RemainingWork: Used to calculate remaining work and burndown charts. Specify the same field used in the WIT assigned to the Task Category which you use to capture the hours, days, or other unit of measurement that remain to finish a task.

    The value that you specify for format is used on the sprint backlogs and task boards wherever remaining work is reported. For example, when reporting capacity-by-activity or capacity per team member, or next to the column heading for the task states on the task board.

    For TimeUnitString, specify any text string that you want to use to reflect the time value, such as hours or days.

    For example, the following values are all valid:

    format="{0} h"

    format="{0} hours"

    format="hours {0}"

    format="time {0}"

  • Team: Used to associate the backlogs with a team. The default value is System.AreaPath. To decouple teams from area paths, you can specify a different field, as described in Use team fields instead of area paths to support teams.

For the feedback request form:


You should not have to change the default assignments made for the following TypeField elements. These assignments correspond to the fields used to capture the corresponding information in the WIT assigned to the Feedback Request Category.

  • ApplicationStartInformation: Used to capture the path to execute the application.

  • ApplicationLaunchInstructions: Used to capture launch instructions.

  • ApplicationType: Used to capture the type of application. The types listed correspond to the allowed values specified in the WIT definition for the feedback request. To customize this list, see Customize a pick list.


Required for the TypeFieldValue when type="ApplicationType".

Specifies a collection of TypeFieldValue elements which are used in the feedback request form.


Required. Do not customize.

Specifies the name of an application type to appear on the feedback request form.

<TypeFieldValue value="ApplicationTypeName" type="TypeApp"/>

The default assignments correspond to the allowed values specified in the type definition for the feedback request form.

   <TypeFieldValue value="Web application" type="WebApp" />
   <TypeFieldValue value="Remote machine" type="RemoteMachine" />
   <TypeFieldValue value="Client application" type="ClientApp" />

  • If you change a field within the TypeFields section, you should make the corresponding change in the WIT definition. For example, if you change the fields assigned to capture work Effort, then you should make the same change in the WIT definitions for the product backlog item and bug (for Scrum).

  • You can look up the reference name for a field using this index.

Non-working days are removed from calculations made by the capacity planning tool and burndown charts. Default Visual Studio Online processes and TFS process templates specify Saturday and Sunday as non-working days. After you create a team project, each team can set their specific non-working days.





Required child of the Weekends element.

Specifies a day of the week that corresponds to a non-working day.


Valid names correspond to the English days of the week: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday.


You must specify the day of a week in English, regardless of the installed language of your on-premises TFS.


Optional. Container element used to specify non-working days.

Specify non-working days when you want to account for non-working days in the calculation of capacity and burndown charts.

At a glance, you can differentiate WITs when viewing a query result or backlog based on the color assigned to the WIT.

Color assignments to different work item types

The Scrum process template defines the following color assignments. Similar ones are made for the Agile and CMMI templates.

   <WorkItemColor primary="FF009CCC" secondary="FFD6ECF2" name="ProductBacklogItem" />
   <WorkItemColor primary="FF773B93" secondary="FFEEE2F2" name="Feature" />
   <WorkItemColor primary="FFFF7B00" secondary="FFFFD7B5" name="Epic" />
   <WorkItemColor primary="FFF2CB1D" secondary="FFF6F5D2" name="Task" />
   <WorkItemColor primary="FFCC293D" secondary="FFFAEAE5" name="Bug" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Code Review Request" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Code Review Response" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Feedback Request" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Feedback Response" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Impediment" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Shared Step" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Test Case" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Test Plan" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Test Suite" />
   <WorkItemColor primary="FFFF9D00" secondary="FFFCEECF" name="Shared Parameter" />




Optional. Container element for specifying colors for work item types.


Specifies the colors used to display a WIT within the web portal. The primary color is used in list displays, and the secondary color is used in board displays, such as the task board or Kanban board.

<WorkItemColor primary="HexColorCode" secondary="HexColorCode" name="witName" />

There’s only one property that you can specify at this time. The BugsBehavior property defines the default configuration for how bugs, and other WITs defined in the Bug Category, show up on backlogs and boards. Basically, you can configure whether bugs are treated as requirements, as tasks, or not appear on backlogs and boards. After you create a team project, each team can set the behavior they want.

   <Property name="BugsBehavior" value="AsTasks" />
   <Property name="HiddenBacklogs" value="Microsoft.EpicCategory" />




Optional. Container element for specifying default properties and behaviors.


Specifies the default assignment made to new teams or existing teams when updating a team project with new features. Teams can choose the behavior they want through their team settings. BugsBehavior sets the default for the Show bugs on backlogs or boards. HiddenBacklogs specifies the category of backlog that’s inactive for the team.

Allowed values for BugsBehavior correspond to:

  • AsRequirements – Bugs appear on backlogs and boards similar to requirements

  • AsTasks – Bugs appear on backlogs and boards similar to tasks

  • Off – Bugs don’t appear on backlogs or boards

A: Some customizations can be done through the user interface. Others require editing process configuration or other team project objects. For an overview, see Configure and customize Agile planning tools for a team project.

A: If you’ve added a custom WIT and want to add that to either the backlog or task board, you can. You just can’t have them appear in both places. Learn how by reading Add work item types to backlogs and boards.

© 2015 Microsoft