TFS Integration Platform – Mapping Work Item Fields and Values: Questions & Answers 12

Article
12/14/2009

How do I migrate work item type XYZ_A to work item type XYZ_B, during a migration or synchronisation process when using the TFS Integration Platform? Here are extracts from a configuration file in a pilot environment where we move Clear Quest (CQ) items to Team Foundation Server (TFS) WIT items to highlight some of the features at our disposal.

The basic configuration

VSTS Rangers Project - TFS Migration Tools: Configuration Demystified gives a basic breakdown of the configuration file, so in this post we will limit this specific section to the bare essentials to give this post and the configuration used some context.

As shown, we a Clear Quest to TFS sync configuration, with one session group that contains two migration sources. The CQ Demo Source points back at the Clear Quest Provider and the TFS WIT Demo Target Source points to the TFS 2008 WIT Migration Provider.

Work Item Tracking Session is the TFS based session, which in this scenario we are migrating to as part of the OneDirectionalMigration.
CQ Demo Source is the Clear Quest based session, which is the source from which we are migrating from.
For more details on filter pairs, see the previous post TFS Integration Platform – Configuration: Question & Answer 9 for an example.

Excluding Fields

2010-06 ALERT: This is an obsolete feature and you should refer to the configuration document that accompanies the TFS Integration Platform for documentation on the new features that allow you to exclude fields.

So, how do we exclude fields as part of the migration?

Before we jump to the exclusion answer, we need to highlight that in the configuration extract below, we have a work item type Request originating from the left (source), which maps to Change Request work item type on the right (target).

To exclude (ignore) fields during the processing create an ExcludedFields section within the FieldMap of the relevant work item type. In the scenario above, we have a list of exclusion fields if we process a request work item type, for example, dbid.

Mapping Fields

This is the eye of this post, because the question has been “how do I map a work item type X on the left to a work item type Y on the right and vice versa.

The answer is the MappedFields section, which allows us to map from fields on the left, to fields on the right. For example, in the above extract we map the field headline of work item request from Clear Quest, to field System.Title of work item Change Request on TFS.

But what if the values differ ... read on.

Mapping Values

The ValueMaps allow us to map values from the left to different values on the right, something we included in the TFS Integration Platform – Getting Started Walkthrough (advanced scenario) which you can find on www.codeplex.com/tfsintegration. The example above defines that a value of High from the source is mapped to 1 on the target. The last value defines that if we have no value on the left, we default to 3 on the right. Nifty!

To conclude …

Here is the complete “DEMO” configuration file used in this post. Use as reference, but do not copy+paste, because there is a lot of missing configuration that was “snipped”.

    1: <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    2: <Configuration UniqueId="191...snip...969" FriendlyName="CQ to TFS Sync" >
    3:   <Providers>
    4:     <Provider     ReferenceName="D96...snip...D16" 
    5:         FriendlyName="ClearQuest  Migration Provider" />
    6:     <Provider     ReferenceName="663...snip...FC1" 
    7:         FriendlyName="TFS 2008 WIT Migration Provider" />
    8:   </Providers>
    9:   <SessionGroup FriendlyName="ClearQuest to TFS Sync Sessions"
   10:         SessionGroupGUID="DE6...snip...9D6"
   11:         WorkFlowType="OneDirectionalMigration">
   12:     <MigrationSources>
   13:       <!-- CQ migration source -->
   14:       <MigrationSource InternalUniqueId="BB2...snip...F0D"
   15:                        FriendlyName="CQ Demo Source"
   16:                        ServerIdentifier="TFS2010B232WT_CQ"
   17:                        ServerUrl="TFS2010B232WT_CQ"
   18:                        SourceIdentifier="CQU4"
   19:                        ProviderReferenceName="D96...snip...D16">
   20:         <CustomSettings>
   21:           <CustomSetting SettingKey="LoginCredentialConfigType"    SettingValue="UseTextUsernamePasswordPairInConfig" />
   22:           <CustomSetting SettingKey="UserName"             SettingValue="CQ_Reader_User" />
   23:           <CustomSetting SettingKey="Password"             SettingValue="…snip…" />
   24:           <CustomSetting SettingKey="AdminUserName"         SettingValue="" />
   25:           <CustomSetting SettingKey="AdminPassword"         SettingValue="" />
   26:         </CustomSettings>
   27:       </MigrationSource>
   28:  
   29:       <!-- TFS WIT migration source -->
   30:       <MigrationSource InternalUniqueId="F47...snip...5C3"
   31:                        FriendlyName="TFS WIT Demo Target"
   32:                        ServerIdentifier="TFS2010B232WT_TFS"
   33:                        ServerUrl="https://TFS2010B232WT_TFS:8080"
   34:                        SourceIdentifier="CMMI...snip...DEMO"
   35:                        ProviderReferenceName="663...snip...FC1">
   36:         <CustomSettings>
   37:           <CustomSetting SettingKey="DisableAreaPathAutoCreation"     SettingValue="" />
   38:           <CustomSetting SettingKey="DisableIterationPathAutoCreation"     SettingValue="" />
   39:         </CustomSettings>
   40:       </MigrationSource>
   41:     </MigrationSources>
   42:  
   43:     <Sessions>  
   44:       <Session SessionUniqueId="882...snip...bd2"
   45:                FriendlyName="Work Item Tracking session"
   46:                LeftMigrationSourceUniqueId="BB2...snip...F0D"
   47:                RightMigrationSourceUniqueId="F47...snip...5C3"
   48:                SessionType="WorkItemTracking">
   49:         <EventSinks/>
   50:         <Filters>
   51:           <FilterPair>
   52:             <FilterItem MigrationSourceUniqueId="BB2...snip...F0D" 
   53:             FilterString="request::id='CQ...snip...9999'" />
   54:             <FilterItem MigrationSourceUniqueId="F47...snip...5C3" 
   55:             FilterString="[System.Id] = 0" />
   56:           </FilterPair>
   57:         </Filters>
   58:         <CustomSettings>
   59:           <SettingXml>
   60:             <WITSessionCustomSetting>
   61:               <WorkItemTypes>
   62:                 <WorkItemType     LeftWorkItemTypeName="Request" 
   63:                  RightWorkItemTypeName="Change Request" 
   64:                 fieldMap="Request_To_ChangeRequest_FieldMap" />
   65:               </WorkItemTypes>
   66:               <FieldMaps>
   67:                 <FieldMap name="Request_To_ChangeRequest_FieldMap">
   68:                   <MappedFields>
   69:                     <MappedField LeftName="Headline"     RightName="System.Title"     
   70:                             MapFromSide="Left" valueMap=""/>
   71:                     <MappedField LeftName="Description" RightName="System.Description"     
   72:                             MapFromSide="Left" valueMap=""/>
   73:                     <MappedField LeftName="History"     RightName="System.History"     
   74:                             MapFromSide="Left" valueMap=""/>
   75:                     <MappedField LeftName="Owner"     RightName="System.AssignedTo"     
   76:                             MapFromSide="Left" valueMap=""/>
   77:                     <MappedField LeftName="Priority"     RightName="Microsoft.VSTS.Common.Priority" 
   78:                             MapFromSide="Left" valueMap="Request_Priority_Map"/>
   79:                   </MappedFields>
   80:                   <ExcludedFields>
   81:                     <ExcludedField field="dbid" ExcludeFromSide="Left"></ExcludedField>
   82:                     <ExcludedField field="is_active" ExcludeFromSide="Left"></ExcludedField>
   83:                     <ExcludedField field="id" ExcludeFromSide="Left"></ExcludedField>
   84:                     <ExcludedField field="State" ExcludeFromSide="Left"></ExcludedField>
   85:                         <!-- ...snip... -->
   86:                     <ExcludedField field="Originator" ExcludeFromSide="Left"></ExcludedField>
   87:                     <ExcludedField field="URL" ExcludeFromSide="Left"></ExcludedField>
   88:                     <ExcludedField field="ExternalRefID" ExcludeFromSide="Left"></ExcludedField>
   89:                   </ExcludedFields>
   90:                 </FieldMap>
   91:                     <!-- ...snip... -->
   92:                 <FieldMap name="Task_To_Task_FieldMap">
   93:                     <!-- ...snip... -->
   94:                 </FieldMap>
   95:               </FieldMaps>
   96:               <ValueMaps>
   97:                 <ValueMap name="UserMap">
   98:                   <Value LeftValue=""            RightValue="TFS Setup" />
   99:                   <Value LeftValue="AdminDemoUser" RightValue="Administrator" />
  100:             </ValueMap>
  101:                 <ValueMap name="Request_Priority_Map">
  102:                   <Value LeftValue="High"        RightValue="1" />
  103:                   <Value LeftValue="Medium"        RightValue="2" />
  104:                   <Value LeftValue="Low"        RightValue="3" />
  105:                   <Value LeftValue=""            RightValue="3" />
  106:                 </ValueMap>
  107:               </ValueMaps>
  108:             </WITSessionCustomSetting>
  109:           </SettingXml>
  110:         </CustomSettings>
  111:       </Session>
  112:     </Sessions>
  113:   </SessionGroup>
  114: </Configuration>

… hope this helps. Refer to the TFS Integration Platform – Architecture Overview documentation on www.codeplex.com/tfsintegration for more information on the configuration file and the TFS Integration Platform.

Acronyms Used

| CQ - Clear Quest | TFS – Team Foundation Server | WIT – Work Item Type |