Changing the Workflow of a Work Item Type

Article
02/04/2013

You can change the workflow of a work item type by exporting the XML file and modifying its content. As soon as you have modified the workflow, you can import the XML file to start to use the updated work item type.

Required Permissions

To perform this procedure, you must be a member of the Team Foundation Administrators group or a member of the Project Administrators group for the project. For more information, see Team Foundation Server Permissions.

To change the workflow

If you are modifying a work item type on a single project, run witadmin exportwitd to export the XML file for the work item type you want to modify. For more information, see Customizing and Managing Work Item Types [witadmin].
In Visual Studio, click File, click Open, and then click File.

This displays the Open File dialog box.
Under Look in, move to the location where you exported the file.

If you are modifying a work item type to customize a process template, move to the location where you downloaded the process template.

Note

If you are running Windows Vista you might not have access rights to certain folders. If you try to export the work item type to a location where you do not have access rights, the registry virtualization technology automatically redirects the exported file and saves it to the virtual store. To avoid this redirection, you can export the file to a location where you have access rights. For more information about registry virtualization, see the following pages on the Microsoft Web site: Registry Virtualization and Common file and registry virtualization issues in Windows Vista.
Select the work item type XML file that you want to update, and then click Open. When you are prompted about line endings, click No.

Find the definition of the work item type’s workflow, in the <WORKFLOW> section of the XML file, as shown in the following XML:

<WORKFLOW>
  <STATES>
    <STATE value="Active">
      <FIELDS>
        <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
          <EMPTY />
        </FIELD>
        <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
...

Add an Unapproved state to the type definition by inserting another <STATE> element. The new state is shown as highlighted in the following example:

<WORKFLOW>
  <STATES>
    <STATE value="Unapproved">
    </STATE>
    <STATE value="Active">
      <FIELDS>
        <FIELD refname="Microsoft.VSTS.Common.ClosedDate">
          <EMPTY />
        </FIELD>
        <FIELD refname="Microsoft.VSTS.Common.ClosedBy">
...

Create a transition between the null state and the Unapproved state. To do this, first find the section of the workflow definition for transitions. Then, insert the following XML, shown as highlighted in the following example.

Note

Because of this change, all new work items of this kind will start in the Unapproved state with the default reason of New.

<TRANSITIONS>
  <TRANSITION from="" to="Unapproved">
    <REASONS>
      <DEFAULTREASON value="New" />
    </REASONS>
  </TRANSITION>
  <TRANSITION from="" to="Active">
    <REASONS>
      <DEFAULTREASON value="New" />
    </REASONS>
    <FIELDS>
      <FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
        <COPY from="currentuser" />
      </FIELD>
      <FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
        <COPY from="clock" />
      </FIELD>
      <FIELD refname="System.AssignedTo">
        <COPY from="currentuser" />
      </FIELD>
    </FIELDS>
  </TRANSITION>

Delete the transition to Active that is shown as highlighted in the following XML.

Do this because there can be only one opening transition.

<TRANSITIONS>
  <TRANSITION from="" to="Unapproved">
    <REASONS>
      <DEFAULTREASON value="New" />
    </REASONS>
  </TRANSITION>
  <TRANSITION from="" to="Active">
    <REASONS>
      <DEFAULTREASON value="New" />
    </REASONS>
    <FIELDS>
      <FIELD refname="Microsoft.VSTS.Common.ActivatedBy">
        <COPY from="currentuser" />
      </FIELD>
      <FIELD refname="Microsoft.VSTS.Common.ActivatedDate">
        <COPY from="clock" />
      </FIELD>
      <FIELD refname="System.AssignedTo">
        <COPY from="currentuser" />
      </FIELD>
    </FIELDS>
  </TRANSITION>

Add a "Ported" reason for the opening transition by inserting the following XML, shown as highlighted in the following example. This lets users know whether the work item is new or was ported from another tracking system.
```
<TRANSITIONS>
  <TRANSITION from="" to="Unapproved">
    <REASONS>
      <DEFAULTREASON value="New" />
     <REASON value="Ported" />
    </REASONS>
  </TRANSITION>
...
```
Insert the following COPY rule, shown as highlighted in the following example. This rule defaults the Assigned To field to the user who created the work item, and it is to be evaluated only during the opening transition.
```
<TRANSITIONS>
  <TRANSITION from="" to="Unapproved">
    <REASONS>
      <DEFAULTREASON value="New" />
     <REASON value="Ported" />
    </REASONS>
    <FIELDS>
       <FIELD refname="System.AssignedTo">
         <COPY from="currentuser" />
       </FIELD>
    </FIELDS>
  </TRANSITION>
...
```
Note

Inserting this rule under other <TRANSITION> or <STATE> elements will scope the rule to other transitions or states. For more information, see How Rules are Evaluated.

Create a transition from the Unapproved state to the Active state by inserting the following XML, shown as highlighted in the following example. Because of this change, when the work item is approved, it can undergo this transition.

<TRANSITIONS>
  <TRANSITION from="" to="Unapproved">
    <REASONS>
      <DEFAULTREASON value="New" />
     <REASON value="Ported" />
    </REASONS>
    <FIELDS>
       <FIELD refname="System.AssignedTo">
         <COPY from="currentuser" />
       </FIELD>
    </FIELDS>
  </TRANSITION>
  <TRANSITION from="Unapproved" to="Active">
    <REASONS>
      <DEFAULTREASON value="Approved" />
    </REASONS>
  </TRANSITION>
  <TRANSITION from="Active" to="Closed">
    <REASONS>
      <DEFAULTREASON value="Completed" />
      <REASON value="Deferred" />
      <REASON value="Obsolete" />
      <REASON value="Cut" />
    </REASONS>
...

On the toolbar, click Save to save the changes to the XML file.
To import the new work item type to a single project, see Customizing and Managing Work Item Types [witadmin]. To add the work item type to your process template, see Add Type Definitions for Work Items to a Process Template.

To verify changes imported to a single project

In Team Explorer, click Refresh to download the latest updates from the server.

These updates include the changes that you just imported. Wait several seconds until the Work Items node is loaded. Nodes that are still loading display the word working.
Create a new work item by using the work item type you modified. To do this, right-click the Work Items node, point to Add Work Item, and then click the work item type.

This work item is created from the work item type that you changed and imported.
Notice that the initial State is now Unapproved and that the Reason is New. Additionally, the Assigned To value is your account name. Click the Reason field to see a list that lists the reasons New and Ported.
In the Title field, type a title, and then click Save to save the work item. Wait until the save operation finishes, as indicated by Item(s) Saved on the status bar.
In the State field, select the Active value to approve the work item and transition it again. Notice that the Reason field is Approved.
On the toolbar, click Save to save this transition.
Click Close to close the work item.

Changing the Workflow of a Work Item Type

To change the workflow

To verify changes imported to a single project

See Also

Concepts

Other Resources

Additional resources