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 through Team Web Access (TWA), display a filtered set of work items based on the configuration made to the PortfolioBacklog, RequirementBacklog, and TaskBacklog sections of the process configuration XML definition file. In addition, process configuration defines the workflow states-to-metastate mappings for all work item types (WITs) that require mapping.

To learn more, see Configure and customize Agile planning tools for a team project.

Areas that you can customize:

• Configure a backlog page

  • Map metastates for a category of work item types

  • Customize the default columns and column sequence

  • Customize the quick add panel

  • Change the number of work items that can appear on the task board

• Map metastates for tool-specific work item types

• Assign fields used in agile planning tools and charts

• Specify weekend days

• Change the color for a work item type

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.

Note

The syntax samples shown in this topic correspond to the default assignments defined in the Visual Studio Scrum 2013 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.

Configure a backlog page

There are three types of backlog pages: product backlog, iteration or sprint backlog, and portfolio backlog. You can customize each backlog page in the following ways:

• Metastate mappings: Map workflow states to metastates. These mappings support the display of all agile planning pages, including the Kanban board and task board.

• 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 the backlog pages within the XML sections that appear in the following sample:

<PortfolioBacklogs>
   <PortfolioBacklog category="Microsoft.FeatureCategory" pluralName="Features" singularName="Feature">
. . . 
   </PortfolioBacklog>
</PortfolioBacklogs>
<RequirementBacklog category="Microsoft.RequirementCategory" pluralName=" Backlog items" singularName=" Backlog item">
. . . 
</RequirementBacklog>
<TaskBacklog category="Microsoft.TaskCategory" pluralName="Tasks" singularName="Task">
. . . 
</TaskBacklog>

Element	Description
PortfolioBacklogs	Optional. Container element for portfolio backlog pages.
PortfolioBacklog	Optional. Up to five instances. Container element that defines the metastate mappings, default columns, and quick add panel for a portfolio backlog page. <PortfolioBacklog category="PortfolioCategory" parent="ParentCategory" pluralName="PluralName" singularName="SingleName">    <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.
RequirementBacklog	Required. One instance only. Container element that defines the metastate mappings, default columns, and quick add panel for the product backlog page. The product backlog displays all active items in the team’s backlog. <RequirementBacklog category="RequirementCategory" pluralName="PluralName" singularName="SingleName">    <States> . . . </States>    <Columns> . . . </Columns>    <AddPanel> . . . </ AddPanel> </RequirementBacklog >
TaskBacklog	Required. One instance only. Container element used to customize the layout of pages that display work items assigned to a specific iteration. <TaskBacklog category="Microsoft.TaskCategory" pluralName="Tasks" singularName="Task workItemCountLimit="MaximumLimit"> . . .  </TaskBacklog > By default, the task board is restricted to a total of 500 work items. You can change this limit by specifying a value for the workItemCountLimit attribute.

Implementation notes

• 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. For more information, see Categories XML element reference.

• You use portfolio backlogs to view the rollup of backlog items at lower levels and to view progress across several teams. New and upgraded team projects contain one level labeled Features. You can add up to four additional levels.

  Note

  Use of the portfolio pages may require you to be granted Advanced access. For details, see Change access levels.

  For information about using portfolio backlog pages, see Work with portfolio backlogs.

• The product backlog represents a list of requirements for the product that you are developing. Backlog items correspond to a specific type of work item based on the process template used to create your team project, such as product backlog item, user story, or requirement. If you use different types of work items or capture your requirements using two or more types of work items, then you can customize the product backlog page to support your usage.

  For information about using the product backlog pages, see Create your backlog.

• The sprint or iteration backlog pages display both the set of requirements that you and your team have committed to in a specific iteration cycle and the tasks that you have linked to those requirements. Tasks must be linked to requirements using the child link type. Because the types of work items that appear on these pages correspond to the same types that appear on the product backlog page, much of the customization work that you do for the product backlog page will define the functionality of the task backlog pages.

  For information about using the sprint backlog pages, see Work in sprints.

Map workflow states to metastates

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 pages

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

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

Element	Description
State	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 items page. However, it will continue to be listed on the Kanban board. Work items in a workflow state that are not mapped to one of the supported metastates do not appear on the backlog or board pages. 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. Note 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.
States	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

Customize the default columns and column sequence

You can add or remove columns, change the sequence of the columns, or change the column width for the pages that display a backlog page. Changes you make to the page through the Column Options dialog persist until you change them again. The following section of code simply defines the default column set and sequence.

<Columns>
   <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" />
</Columns>

Element	Description
Columns	Specifies a collection of Column elements. Required element for the backlog page elements: PortfolioBacklog, RequirementBacklog, and TaskBacklog.
Column	Specifies a field to appear as a column on a backlog page. <Column refname="FieldReferenceName" width="FieldWidth" />

Task board column headings

The column headings that appear on the task board page 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.

Customize the quick add panel

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

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.

<AddPanel>
   <Fields>
      <Field refname="System.Title" />
   </Fields>
</AddPanel>

Element	Description
AddPanel	Container element used to specify the “quick add” experience, the fields to appear within the panel area where new backlog items are defined.
Fields	Specifies a collection of Field elements.
Field	Specifies a work item field to appear within the panel for the product backlog page. <Field refname="FieldReferenceName"/> The same field should appear on the work item form of each WIT included in the category for the backlog.

Change the number of work items that can appear on the task board

For performance reasons, the task board is restricted to display a maximum of 500 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 increase the limit by adding workItemCountLimit="800":

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

Map metastates for tool-specific work item types

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">
   <States>
      <State value="Active" type="InProgress" />
      <State value="Closed" type="Complete" />
   </States>
</FeedbackRequestWorkItems>
<FeedbackResponseWorkItems category="Microsoft.FeedbackResponseCategory" pluralName="Feedback Responses" singularName="Feedback Response">
   <States>
   <State value="Active" type="InProgress" />
   <State value="Closed" type="Complete" />
   </States>
</FeedbackResponseWorkItems>

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.

Element	Description
BugWorkItems	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 TWA agile planning pages, 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">    <States> . . .    </States> </BugWorkItems>
FeedbackRequestWorkItems	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">    <States> . . .    </States> </FeedbackRequestWorkItems>
FeedbackResponseWorkItems	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">    <States> . . .    </States> </FeedbackResponseWorkItems>
TestPlanWorkItems	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">     <States>       <State type="InProgress" value="Design" />       <State type="InProgress" value="Testing" />       <State type="Complete" value="Signed Off" />     </States>   </TestPlanWorkItems>
TestSuiteWorkItems	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">     <States>       <State type="Proposed" value="Authoring" />       <State type="InProgress" value="Testing" />       <State type="Complete" value="Completed" />     </States>   </TestSuiteWorkItems>

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.

Assign fields used in agile planning tools and charts

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.

<TypeFields>
    <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">
        <TypeFieldValues>
            <TypeFieldValue value="Web application" type="WebApp" />
            <TypeFieldValue value="Remote machine" type="RemoteMachine" />
            <TypeFieldValue value="Client application" type="ClientApp" />
        </TypeFieldValues>
    </TypeField>
</TypeFields>

Element	Description
TypeFields	Required. Specifies a collection of TypeField elements.
TypeField	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 iteration backlog page and on the task board. For agile planning pages: 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 in the Agile planning tool Capacity page 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 Capacity on the sprint backlog pages, 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 backlog and board pages. Work items are listed on the page according to the ascending order as defined by the field for this type. Note You can move items by dragging them up or down the list on a backlog page. 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 backlog and task board pages 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 backlog pages with a team. The default value is System.AreaPath. To decouple teams from area paths, you can specify a different field, as described in Set up team fields to support Agile planning tools. For the feedback request form: Note 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.
TypeFieldValues	Required for the TypeFieldValue when type="ApplicationType". Specifies a collection of TypeFieldValue elements which are used in the feedback request form.
TypeFieldValue	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. <TypeFieldValues>    <TypeFieldValue value="Web application" type="WebApp" />    <TypeFieldValue value="Remote machine" type="RemoteMachine" />    <TypeFieldValue value="Client application" type="ClientApp" /> </TypeFieldValues>

Implementation notes

• 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.

Assign non-working days

The capacity planning and burndown charts reference the non-working days. The following non-working days are defined within each TFS process template.

<Weekends>
   <DayOfWeek>Saturday</DayOfWeek>
   <DayOfWeek>Sunday</DayOfWeek>
</Weekends>

Element	Description
DayOfWeek	Required child of the Weekends element. Specifies a day of the week that corresponds to a non-working day. <DayOfWeek>NameOfADay</DayOfWeek> Valid names correspond to the English days of the week: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday. Note You must specify the day of a week in English, regardless of the installed language of Team Foundation Server.
Weekends	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. Some note about how this appears in the burndown chart and cannot be removed.

Change the color for a work item type

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

The following color assignments are defined within the Scrum process template.

<WorkItemColors>
   <WorkItemColor primary="FF009CCC" secondary="FFD6ECF2" name="ProductBacklogItem" />
   <WorkItemColor primary="FF773B93" secondary="FFEEE2F2" name="Feature" />
   <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" />
</WorkItemColors>

Element	Description
WorkItemColors	Optional. Container element for specifying colors for work item types.
WorkItemColor	Specifies the colors used to display a WIT within TWA. 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" /> To get hexadecimal colors, use this HTML color picker tool.

Q & A

Q: How do I customize other functions that appear on the Agile planning tools in TWA?

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.

Q: Do you want to work with two or more portfolio backlogs?

A: The default experience supports one level of portfolio backlog. You can add up to five levels as described in Add a backlog to Agile portfolio management.

Q: Do you want to add or change the WITs that appear on your task board or product backlog?

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 bugs or other work item types to backlogs or boards.

Q: Do you want to see a worked example for importing and exporting process configuration?

A: An example is provided here: Import and export process configuration [witadmin].