Share via


Process Configuration XML Element Reference

Process configuration files determine the layout and functionality of the following features: product backlog and team velocity, iteration backlog, team capacity, task board, and burndown charts, stakeholder feedback, and My Work. You can export these configuration files, AgileConfiguration and CommonConfiguration, from your team project or access them from the process template that you download from Visual Studio Team Foundation Server 2012. You customize the layout of the backlog pages by modifying the definitions specified in AgileConfiguration, and you customize areas common to several features by modifying the definitions specified in CommonConfiguration.

For an overview of the features that you can customize, see Customize the Backlog and Board Pages Using Process Configuration.

Note

For information about how a team uses the backlog and task board pages, see Collaborate.

In this topic

  • AgileConfiguration: syntax structure and elements

  • CommonConfiguration: syntax structure and elements

AgileConfiguration: syntax structure and elements

You customize the backlog page by modifying the elements contained within the AgileProjectConfiguration element. To customize the product backlog page, modify the elements within the ProductBacklog element, and to customize the iteration backlog pages, modify the elements contained within the IterationBacklog elements.

The following XML example shows the code structure that defines the agile process configuration contained within the AgileConfiguration.xml file. This example corresponds to the default syntax defined for the MSF for Agile Software Development v6.0.

<?xml version="1.0" encoding="utf-8"?>
<AgileProjectConfiguration>
  <ProductBacklog>
    <Columns>
      <Column refname="System.Title" width="400" />
      <Column refname="System.State" width="100" />
      <Column refname="Microsoft.VSTS.Scheduling.StoryPoints" width="50" />
      <Column refname="System.IterationPath" width="200" />
    </Columns>
    <AddPanel>
      <Fields>
        <Field refname="System.Title" />
      </Fields>
    </AddPanel>
  </ProductBacklog>
  <IterationBacklog>
    <Columns>
      <Column refname="Microsoft.VSTS.Scheduling.StoryPoints" width="50" />
      <Column refname="System.Title" width="400" />
      <Column refname="System.State" width="100" />
      <Column refname="System.AssignedTo" width="100" />
      <Column refname="Microsoft.VSTS.Scheduling.RemainingWork" width="50" />
    </Columns>
  </IterationBacklog>
</AgileProjectConfiguration>

Back to top

XML elements for the backlog pages

The following table describes the child elements of the AgileProjectConfiguration root element. You can use these elements to specify the columns and the fields that should appear on the backlog page.

Element

Description and Syntax

Notes

AddPanel

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

<AddPanel>
    <Fields>
       <Field . . . />
       . . .
   </Fields>
</AddPanel>

Required. One instance only.

You must specify at least one Fields element.

The “quick add” experience only appears on the Product Backlog page in Team Web Access.

Column

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

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

Required.

For each column that you want to appear on the pages that display a backlog list, you must specify the reference name for a field that is defined for the type of work item associated with backlog items. You must specify a positive integer for the field width.

Columns

Specifies a collection of Column elements.

<Columns>
   <Column . . . />
   . . .
</Columns>

Required. One instance only for each IterationBacklog and ProductBacklog parent elements.

You must specify the columns that you want to appear on the pages that display the product backlog or an iteration backlog.

Field

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

<Field refname=”FieldReferenceName” />

Required. One or more elements contained within the Fields parent element.

When you define a work item to add to the backlog, you can specify a value for the fields that you list within the AddPanel section of the configuration process.

The default configuration specifies the Title field as the only field to display, as the following code sample shows:

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

Fields

Specifies a collection of Field elements.

<Fields>
<Field . . . />
   . . .
</Fields>

Required. One instance only defined for the AddPanel parent element.

You specify the fields that you want to specify quickly when adding items to the product backlog.

IterationBacklog

Container element used to customize the layout of pages that display work items assigned to a specific iteration.

<IterationBacklog workItemCountLimit="MaximumLimit"  >
   <Columns> . . . </Columns>
   . . . 
</IterationBacklog > 

Required. One instance only.

You specify the number of columns, column widths, and the fields that populate each column for those pages that display the list of backlog items assigned to an iteration.

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.

ProductBacklog

Container element used to customize the layout of the page that displays the product backlog and that contains a panel for adding work items to the backlog.

<ProductBacklog>
   <Columns> . . . </Columns>
   <AddPanel> . . . </ AddPanel>
</ProductBacklog >

Required. One instance only.

You specify the number of columns, column widths, and the fields that populate each column for those pages that display the list of backlog items assigned to the product backlog. The product backlog displays all active items in the backlog, including those that have been assigned to an iteration.

Back to top

CommonConfiguration: syntax structure and elements

You customize the task board page by using the CommonProjectConfiguration element, which supports several child elements. The TypeFields specify the field that is used in types of work items to capture specific information. Several of the other child elements, for example, RequirementWorkItems, TaskWorkItems, and BugWorkItems specify the category group to associate with these types that are referenced by specific process configuration feature areas.

The following XML example shows the code structure that defines the common process configuration contained within the CommonConfiguration.xml file. This example corresponds to the default syntax defined for the MSF for Agile Software Development v6.0.

<?xml version="1.0" encoding="utf-8"?>
<CommonProjectConfiguration>
  <TypeFields>
    <TypeField refname="System.AreaPath" type="Team" />
    <TypeField refname="Microsoft.VSTS.Scheduling.RemainingWork" type="RemainingWork" format="format h" />
    <TypeField refname="Microsoft.VSTS.Common.StackRank" type="Order" />
    <TypeField refname="Microsoft.VSTS.Scheduling.StoryPoints" 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>
  <RequirementWorkItems category="Microsoft.RequirementCategory" plural="Stories">
    <States>
      <State value="New" type="Proposed" />
      <State value="Active" type="InProgress" />
      <State value="Resolved" type="InProgress" />
      <State value="Closed" type="Complete" />
    </States>
  </RequirementWorkItems>
  <TaskWorkItems category="Microsoft.TaskCategory">
    <States>
      <State value="New" type="Proposed" />
      <State value="Active" type="InProgress" />
      <State value="Closed" type="Complete" />
    </States>
  </TaskWorkItems>
  <BugWorkItems category="Microsoft.BugCategory">
   <States>
        <State value="Active" type="InProgress" />
        <State value="Resolved" type="Resolved" />
        <State value="Closed" type="Complete" />
      </States> 
  </BugWorkItems>
  <FeedbackRequestWorkItems category="Microsoft.FeedbackRequestCategory" plural="Feedback Requests">
    <States>
      <State value="Active" type="InProgress" />
      <State value="Closed" type="Complete" />
    </States>
  </FeedbackRequestWorkItems>
  <FeedbackResponseWorkItems category="Microsoft.FeedbackResponseCategory" plural="Feedback Responses">
    <States>
      <State value="Active" type="InProgress" />
      <State value="Closed" type="Complete" />
    </States>
  </FeedbackResponseWorkItems>
  <Weekends>
    <DayOfWeek>Saturday</DayOfWeek>
    <DayOfWeek>Sunday</DayOfWeek>
  </Weekends>
</CommonProjectConfiguration>

Back to top

XML elements for common areas

The following table describes the child elements of the CommonProjectConfiguration element. These elements configure areas that support pages that display both in Team Web Access, Team Explorer and the feedback request form.

Important

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 the latest release of Visual Studio ALM, five new categories have been defined. For more information, see Categories, process configuration, and disabling creation of specific types of work items.

Element

Description and syntax

BugWorkItems

Required. Specifies the category that corresponds to bug work items and associates the workflow states of backlog items with metastates. The CategoryName must correspond to a category defined for the team project.

<BugWorkItems category=”CategoryName”>
    <States>
       <State . . . />
       . . .
   </States>
</BugWorkItems

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.

FeedbackResponseWorkItems

Required. Do not customize.

Specifies the category that corresponds to work item types that are used to capture feedback response and associates the workflow states of these items with metastates. The CategoryName must correspond to a category group defined for the team project.

<FeedbackResponseWorkItems category="Microsoft.FeedbackResponseCategory" plural="Feedback Responses">
   <States>
      <State value="Active" type="InProgress" />
      <State value="Closed" type="Complete" />
   </States>
</FeedbackResponseWorkItems>

FeedbackRequestWorkItems

Required. Do not customize.

Specifies the category that corresponds to work item types that are used to capture feedback requests and associates the workflow states of these items with metastates. The CategoryName must correspond to a category group defined for the team project. Specify category groups using the Categories.xml file.

<FeedbackRequestWorkItems category="Microsoft.FeedbackRequestCategory" plural="Feedback Requests">
   <States>
      <State value="Active" type="InProgress" />
      <State value="Closed" type="Complete" />
   </States>
</FeedbackRequestWorkItems>

RequirementWorkItems

Required. Specifies the category that corresponds to backlog items, such as user stories, requirements, and product backlog items and associates the workflow states of backlog items with metastates. The CategoryName must correspond to a category group defined for the team project. Specify category groups using the Categories.xml file.

<RequirementWorkItems category="CategoryName" plural="NameOfBacklogItems" >
   <States>
      <State . . . />
      . . .
   </States>
</RequirementWorkItems>

State

Required. Assigns a workflow state to a metastate. Metastates represent a grouping of workflow states that support the management of the workflow states on the task board or other process configuration components.

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

Valid values for TypeName correspond to a value assigned to a STATE within the workflow defined for the types of work items that are present in the category group, respectively.

Valid values for ValueName correspond to one of the following enumerated values: within the workflow defined for the types of work items that are present in the category group, respectively.

  • Agile:

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

  • Bug: In addition to the Agile metastates, includes the Resolved metastate which indicates bugs that have been resolved.

  • Feedback: Requested, Received, Reviewed, and Declined.

For more information, see Workflow states, metastates, and process configuration.

States

Required element for the BugWorkItems, FeedbackResponseWorkItems, FeedbackRequestWorkItems, RequirementWorkItems and TaskWorkItems elements.

Specifies a collection of State elements that associate the workflow states of types of work items with metastates.

<States>
   <State . . . />
   . . .
</States>

State elements are used to assign workflow states to metastates.

TaskWorkItems

Required. Specifies the category that corresponds to task items and associates the workflow states of tasks with metastates. The CategoryName must correspond to a category group defined for the team project. You specify category groups using the Categories.xml file.

<TaskWorkItems category="CategoryName">
   <States>
      <State . . . />
      . . .
   </States>
</TaskWorkItems>

The iteration backlog and board pages list those work items that correspond to the state values specified within the States element.

TypeField

Required. Specifies the reference name of a field whose value is referenced to support a type of activity for a supported feature area. You specify this element within the TypeFields container element. You must specify the fields that correspond to the fields that you use within the types of work items to capture specific information.

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

Specifying the format is only valid 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 the backlog and task board pages:

  • Activity: Used to support the capacity-by-activity feature. Specify a field defined for the task type of work item that you use to specify the type of activity to be performed.

  • Effort: Specifies the field used to calculate the team velocity. Specify a field defined for the backlog type of work item that you use to capture the level of effort or the relative rating for the amount of work that a backlog item will require to implement.

  • Order: Specifies the field used to define the sort order for backlog items on the iteration backlog and task board pages. Specify the field that you use to capture the relative priority assigned to backlog items. Work items are listed on the page according to the ascending order as defined by the field for this type.

  • RemainingWork: Specifies the field used to calculate remaining work and burndown charts. Specify the field that you use to capture the number of hours or days 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: Specifies the field used to associate the backlog and task board 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 Customize a team project to support team fields.

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 feedback request type of work item.

  • ApplicationStartInformation: Specifies the field used to capture the path to execute the application.

  • ApplicationLaunchInstructions: Specifies the field used to capture launch instructions.

  • ApplicationType: Specifies the field used to capture the type of application. The types listed correspond to the allowed values specified in the type definition for the feedback request.

TypeFields

Required. Specifies a collection of TypeField elements. You must specify the types of fields that you want referenced to support features that appear on the backlog, task board, and feedback request form.

<TypeFields>
   <TypeField . . . />
   . . .
</TypeFields>

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>

TypeFieldValues

Required for the TypeFieldValue when type="ApplicationType".

Specifies a collection of TypeFieldValue elements. You must specify the values for the types of fields that you want to appear on the feedback request form.

<TypeFieldValues>
   <TypeFieldValue . . . />
   . . .
</TypeFieldValues>

Weekends

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

<Weekends>
   <DayOfWeek> . . . </DayOfWeek >
   . . . 
</ Weekends >

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

Back to top

See Also

Reference

Manage Process Configuration [witadmin]

Concepts

Customize Work Item Tracking and Your Team Project

Update an Upgraded Team Project to Access New Features

Customize the Backlog and Board Pages Using Process Configuration