Migrate a TFS project to another process template.

Back in 2011, 4 years ago I wrote a blog post called “Manual upgrade a TFS project to a new Process template”. Since then I have got some questions and feedback and now it’s time for an updated version based on the latest process templates in TFS 2015, this time from Agile to Scrum.

  1. Start with downloading the process template you want to upgrade to, to disk with the process template manager, for example to D:\MyDownloadedTemplate

2. Backup your old work item types in the TFS project you want to upgrade in case you need to do a rollback. Use the process template editor in Team Foundation Power Tools or from a Visual Studio command prompt with Witadmin.exe.

MD “C:\Temp\MyWorkItemBackup”

CD C:\Temp\MyWorkItemBackup

witadmin.exe exportwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /n:Bug /f:”Bug.xml”

witadmin.exe exportwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /n:Task /f:”Task.xml”

witadmin.exe exportwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /n:”User Story” /f:”UserStory.xml”

witadmin.exe exportwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /n:Issue /f:”Issue.xml”

witadmin.exe exportwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /n:”Test Case” /f:”TestCase.xml”

3. If you have custom fields, add them to the downloaded process template with the process template editor.

4. Some work item types have different names in Scrum and Agile; because of this you first have change the name in the new template to the name of the work item type in the old template, Impediment to Issue and Product Backlog Item to User Story.

5. Upload the Work Item types from the new template to your project with Witadmin.exe from the Visual Studio command prompt.

CD C:\MyDownloadedTemplate\Scrum\WorkItem Tracking\TypeDefinitions

Witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”ProductBacklogItem.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”Task.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”Bug.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”TestCase.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”CodeReviewRequest.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”CodeReviewResponse.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”FeedbackRequest.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”FeedBackResponse.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”SharedStep.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”Feature.xml”

witadmin.exe importwitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”Impediment.xml”

6. Rename Issue and User Story to Impediment and Product Backlog Item

witadmin.exe renamewitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /n:”Issue” /new:”Impediment”

witadmin.exe renamewitd /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /n:”User Story” /new:”Product Backlog Item”

7. Upload the categories.xml

CD C:\MyDownloadedTemplate\Scrum\WorkItem Tracking

witadmin.exe importcategories /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”Categories.xml”

8. Upload the ProcessConfiguration.xm

CD C:\MyDownloadedTemplate\Scrum\WorkItem Tracking\Process

witadmin.exe importprocessconfig /collection:http://MyTFS:8080/tfs/MyCollection /p:”Demo-Agile” /f:”ProcessConfiguration.xml”

9. If you want the queries associated with a Scrum project copy them from an existing project.

10. Remove your old reports from your project from the project report page and use tfpt.exe from Team Foundation Power Tools to create new reports.

tfpt addprojectreports /collection:http://MyTFS:8080/tfs/MyCollection /teamproject:”Demo-Agile” /processtemplate:”Scrum” /force

Comments

  1. Bob Niehaus says:

    I used this on an on Premise TFS 2017 install trying to convert a project from Agile to Scrum. Now I am getting three error messages and it says configuration is incorrect. Errors are TF400517, TF400587 and TF401098.
    I’ve tried looking up these errors but have been unsuccessful in correcting this.
    TF400517: The following element contains an error: TypeFields/TypeFieldTYpes=”Order”. The value of this element is set to Microsoft.VSIS.Common.BacklogPriority. You must set the value to a field that exists in all of the work item types

  2. Hi Bob,
    I have not tried this for some time. Have you checked that your project is configured correctly Before you tried the conversion?

    https://docs.microsoft.com/sv-se/vsts/work/customize/configure-features-after-upgrade

  3. Bob Niehaus says:

    This was a new install of TFS 2017 to a new VM server. There was no upgrade. The configure features link never showed up. I saw that page and was wondering about it but did not think it would apply to a new install. I also looked at the “add manually” link but was confused about it

  4. Bob Niehaus says:

    Here is the whole thing from the command window.
    I first got an error in importing the categories.
    I did the backups first to make sure they worked, then REM those statements and ran the script again

    C:\temp>dir
    Volume in drive C has no label.
    Volume Serial Number is 327B-30E3

    Directory of C:\temp

    02/08/2018 12:22 AM .
    02/08/2018 12:22 AM ..
    02/07/2018 11:43 PM MyWorkItemBackup
    02/08/2018 12:22 AM Scrum
    04/05/2017 03:53 PM 941,778,480 SSMS-Setup-ENU.exe
    02/08/2018 01:20 AM 4,198 tfsagilescrum.bat
    2 File(s) 941,782,678 bytes
    4 Dir(s) 462,196,686,848 bytes free

    C:\temp>tfsagilescrum

    C:\temp>REM WORKING FROM C:\Temp on local pc

    C:\temp>REM Running the statements in this batch file in a command window on loc
    al PC.

    C:\temp>REM

    C:\temp>REM 1. Start with downloading the process template you want to upgrade t
    o, to disk with the process template manager, for example to D:\MyDownloadedTemp
    late

    C:\temp>REM -Scrum template downloaded to C:\temp

    C:\temp>REM 2. Backup your old work item types in the TFS project you want to up
    grade in case you need to do a rollback. Use the process template editor in

    C:\temp>REM Team Foundation Power Tools or from a Visual Studio command promp
    t with Witadmin.exe.

    C:\temp>REM -backup stuff by running these statements

    C:\temp>REM MD “C:\Temp\MyWorkItemBackup”

    C:\temp>REM CD C:\Temp\MyWorkItemBackup

    C:\temp>REM witadmin.exe exportwitd /collection:https://vm-tfs-01/GoodwillConnec
    t /p:”GoodwillConnect” /n:Bug /f:”Bug.xml”

    C:\temp>REM witadmin.exe exportwitd /collection:https://vm-tfs-01/GoodwillConnec
    t /p:”GoodwillConnect” /n:Task /f:”Task.xml”

    C:\temp>REM witadmin.exe exportwitd /collection:https://vm-tfs-01/GoodwillConnec
    t /p:”GoodwillConnect” /n:”User Story” /f:”UserStory.xml”

    C:\temp>REM witadmin.exe exportwitd /collection:https://vm-tfs-01/GoodwillConnec
    t /p:”GoodwillConnect” /n:Issue /f:”Issue.xml”

    C:\temp>REM witadmin.exe exportwitd /collection:https://vm-tfs-01/GoodwillConnec
    t /p:”GoodwillConnect” /n:”Test Case” /f:”TestCase.xml”

    C:\temp>REM 3. If you have custom fields, add them to the downloaded process tem
    plate with the process template editor.

    C:\temp>REM ???

    C:\temp>REM 4. Some work item types have different names in Scrum and Agile; bec
    ause of this you first have change the name in the new template

    C:\temp>REM to the name of the work item type in the old template, Impediment
    to Issue and Product Backlog Item to User Story.

    C:\temp>REM -Installed TFS Process Template Editor from Tools->Extensions and
    Updates. Choose ONLINE and search for TFS Process Template Editor.

    C:\temp>REM -C:\Temp\Scrum\ProcessTemplate.xml edited in Visual Studio Tools-
    >Process Editor->Process Templates->Open Process Template

    C:\temp>REM 5. Upload the Work Item types from the new template to your project
    with Witadmin.exe from the Visual Studio command prompt.

    C:\temp>CD C:\Temp\Scrum\WorkItem Tracking\TypeDefinitions

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>Witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”ProductBacklogIte
    m.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Task.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Bug.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”TestCase.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”CodeReviewRequest
    .xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”CodeReviewRespons
    e.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”FeedbackRequest.x
    ml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”FeedBackResponse.
    xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”SharedStep.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Feature.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe importwitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Impediment.xml”
    The work item type import has completed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>REM 6. Rename Issue and User Sto
    ry to Impediment and Product Backlog Item

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe renamewitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /n:”Issue” /new:”Impe
    diment”
    Are you sure you want to rename the work item type Issue to the new name of Impe
    diment? (Yes/No) y
    The work item type was renamed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>witadmin.exe renamewitd /collect
    ion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /n:”User Story” /new:
    “Product Backlog Item”
    Are you sure you want to rename the work item type User Story to the new name of
    Product Backlog Item? (Yes/No) y
    The work item type was renamed.

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>REM 7. Upload the categories.xml

    C:\temp\Scrum\WorkItem Tracking\TypeDefinitions>CD C:\Temp\Scrum\WorkItem Tracki
    ng

    C:\temp\Scrum\WorkItem Tracking>witadmin.exe importcategories /collection:https:
    //vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Categories.xml”
    TF237059: The import of the category definition failed. In the type definition,
    category Requirement Category refers to a work item type that does not exist Use
    r Story.

    C:\temp\Scrum\WorkItem Tracking>REM 8. Upload the ProcessConfiguration.xml

    C:\temp\Scrum\WorkItem Tracking>CD C:\Temp\Scrum\WorkItem Tracking\Process

    C:\temp\Scrum\WorkItem Tracking\Process>witadmin.exe importprocessconfig /collec
    tion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”ProcessConfigura
    tion.xml”
    The following element contains an error: TypeFields/TypeField[type=’Order’]. TF4
    00517: The value of this element is set to: Microsoft.VSTS.Common.BacklogPriorit
    y. You must set the value to a field that exists in all of the work item types t
    hat are defined in Microsoft.EpicCategory. The field does not exist in the follo
    wing work item types: Epic.
    The following element contains an error: PortfolioBacklog(Microsoft.EpicCategory
    )/States. TF400587: This element defines the states for work items that appear o
    n your backlog. Each state must exist in at least one of the work item types bel
    ong to category defined in: ‘PortfolioBacklog(Microsoft.EpicCategory)/States’. T
    he following state does not exist in any of the work item types: In Progress, Do
    ne.
    The following element contains an error: PortfolioBacklog(Microsoft.EpicCategory
    )/States. TF401098: This element defines the states for work items that appear o
    n your backlog. The state configuration is incorrect. Each work item on this bac
    klog must have one state with the type ‘Complete’. The following work item type
    does not have any state with the type ‘Complete’: Epic.

    C:\temp\Scrum\WorkItem Tracking\Process>CD C:\Temp\Scrum\WorkItem Tracking\Proce
    ss

    C:\temp\Scrum\WorkItem Tracking\Process>
    C:\temp\Scrum\WorkItem Tracking\Process>CD C:\Temp\Scrum\WorkItem Tracking\Proce
    ss

    C:\temp\Scrum\WorkItem Tracking\Process>
    C:\temp\Scrum\WorkItem Tracking\Process>witadmin.exe importprocessconfig /collec
    tion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”ProcessConfigura
    tion.xml”
    The following element contains an error: TypeFields/TypeField[type=’Order’]. TF4
    00517: The value of this element is set to: Microsoft.VSTS.Common.BacklogPriorit
    y. You must set the value to a field that exists in all of the work item types t
    hat are defined in Microsoft.EpicCategory. The field does not exist in the follo
    wing work item types: Epic.
    The following element contains an error: PortfolioBacklog(Microsoft.EpicCategory
    )/States. TF400587: This element defines the states for work items that appear o
    n your backlog. Each state must exist in at least one of the work item types bel
    ong to category defined in: ‘PortfolioBacklog(Microsoft.EpicCategory)/States’. T
    he following state does not exist in any of the work item types: In Progress, Do
    ne.
    The following element contains an error: PortfolioBacklog(Microsoft.EpicCategory
    )/States. TF401098: This element defines the states for work items that appear o
    n your backlog. The state configuration is incorrect. Each work item on this bac
    klog must have one state with the type ‘Complete’. The following work item type
    does not have any state with the type ‘Complete’: Epic.

    C:\temp\Scrum\WorkItem Tracking\Process>CD C:\Temp\Scrum\WorkItem Tracking

    C:\temp\Scrum\WorkItem Tracking>witadmin.exe importcategories /collection:https:
    //vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Categories.xml”
    TF237059: The import of the category definition failed. In the type definition,
    category Requirement Category refers to a work item type that does not exist Use
    r Story.

    C:\temp\Scrum\WorkItem Tracking>witadmin.exe rebuildcache /collection:”https://v
    m-tfs-01/GoodwillConnect”
    This command will invalidate cached data about work item types held on all clien
    ts. Each client will refresh its cache the next time that it connects to the Tea
    m Foundation Server. To avoid server performance issues, you should not run this
    command during typical operating hours. Do you want to continue (Yes/No) y
    Operation complete.

    C:\temp\Scrum\WorkItem Tracking>CD C:\Temp\Scrum\WorkItem Tracking

    C:\temp\Scrum\WorkItem Tracking>witadmin.exe importcategories /collection:https:
    //vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Categories.xml”
    TF237059: The import of the category definition failed. In the type definition,
    category Requirement Category refers to a work item type that does not exist Use
    r Story.

    C:\temp\Scrum\WorkItem Tracking>witadmin.exe listwitd /collection:”https://vm-tf
    s-01/GoodwillConnect” /p:”GoodwillConnect”
    Bug
    Code Review Request
    Code Review Response
    Epic
    Feature
    Feedback Request
    Feedback Response
    Shared Steps
    Task
    Test Case
    Test Plan
    Test Suite
    Product Backlog Item
    Impediment
    Shared Parameter

    C:\temp\Scrum\WorkItem Tracking>CD C:\Temp\Scrum\WorkItem Tracking

    C:\temp\Scrum\WorkItem Tracking>witadmin.exe importcategories /collection:https:
    //vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Categories.xml”
    The category import has completed.

    C:\temp\Scrum\WorkItem Tracking>CD C:\Temp\Scrum\WorkItem Tracking\Process

    C:\temp\Scrum\WorkItem Tracking\Process>witadmin.exe importprocessconfig /collec
    tion:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”ProcessConfigura
    tion.xml”
    The following element contains an error: TypeFields/TypeField[type=’Order’]. TF4
    00517: The value of this element is set to: Microsoft.VSTS.Common.BacklogPriorit
    y. You must set the value to a field that exists in all of the work item types t
    hat are defined in Microsoft.EpicCategory. The field does not exist in the follo
    wing work item types: Epic.
    The following element contains an error: PortfolioBacklog(Microsoft.EpicCategory
    )/States. TF400587: This element defines the states for work items that appear o
    n your backlog. Each state must exist in at least one of the work item types bel
    ong to category defined in: ‘PortfolioBacklog(Microsoft.EpicCategory)/States’. T
    he following state does not exist in any of the work item types: In Progress, Do
    ne.
    The following element contains an error: PortfolioBacklog(Microsoft.EpicCategory
    )/States. TF401098: This element defines the states for work items that appear o
    n your backlog. The state configuration is incorrect. Each work item on this bac
    klog must have one state with the type ‘Complete’. The following work item type
    does not have any state with the type ‘Complete’: Epic.

    C:\temp\Scrum\WorkItem Tracking\Process>witadmin.exe listwitd /collection:”https
    ://vm-tfs-01/GoodwillConnect” /p:”GoodwillConnect”
    Bug
    Code Review Request
    Code Review Response
    Epic
    Feature
    Feedback Request
    Feedback Response
    Shared Steps
    Task
    Test Case
    Test Plan
    Test Suite
    Product Backlog Item
    Impediment
    Shared Parameter

    C:\temp\Scrum\WorkItem Tracking\Process>

  5. Lets take the errors one a a time:
    TF237059: The import of the category definition failed. In the type definition,category Requirement Category refers to a work item type that does not exist User Story.
    It seems that your Categories XML refers to User Stories so I thnink you are trying to upload the categoriesxml from Agile, not Scrum. Could that be correct?

  6. Bob Niehaus says:

    That’s what I was thinking too, but it is the categories.xml that was downloaded with the rest of the scrum xml files. I modified the categories.xml to be Product Backlog Item instead of User Stories. The rest of the categories.xml seemed ok. When I reran the import, it worked.
    Here is the line in the xml file I changed. The only change was from name=”User Stories” to name=”Product Backlog Item”

    Here is the whole file:

  7. Bob Niehaus says:

    It seems all of the XML disappeared from the post. Let me know if you need it

  8. Good, the next error is:
    TF400517: The value of this element is set to: Microsoft.VSTS.Common.BacklogPriority. You must set the value to a
    The field does not exist in the following work item types: Epic.

    Open the Epic.XML from the Scrum template and check that the field Microsoft.VSTS.Common.BacklogPriority exits. If not you have the wrong Epic.XML

  9. Bob Niehaus says:

    This is what is in C:\temp\Scrum\WorkItem Tracking\TypeDefinitions\Epic.xml (I took off the opening/closing brackets so the line doesn’t disappear.)

    FIELD name=”Backlog Priority” refname=”Microsoft.VSTS.Common.BacklogPriority” type=”Double” reportable=”detail”

  10. Bob Niehaus says:

    I found the problem. The list of scrum work item type XMLs to import is incomplete. I happened to notice that the import list had fewer items than the scrum work item types listed in the SCRUM download. I ran the imports for these missing work item types and redid the categories and process statements and everything seems to have cleared up.
    The missing statements are:
    witadmin.exe importwitd /collection:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”Epic.xml”
    witadmin.exe importwitd /collection:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”ProductBacklogItem.xml”
    witadmin.exe importwitd /collection:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”SharedParameter.xml”
    witadmin.exe importwitd /collection:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”TestPlan.xml”
    witadmin.exe importwitd /collection:https://vm-tfs-01/GoodwillConnect /p:”GoodwillConnect” /f:”TestSuite.xml”

    Thanks for your help!!!

  11. I am glad it worked!

Speak Your Mind

*