TFS Integration Tools (Platform) … The world of TFS Project Template (MSF Agile v4 to v5) migrations – Part 2

Article
08/17/2010

Continued from post TFS Integration Tools (Platform) … The world of TFS Project Template migrations - Part 1 … today we will investigate the MSF Agile v4 to v5.xml configuration template.

WARNING: As mentioned in the previous post, the configuration templates we are covering in this series are “templates”, they need further attention and lots of hugs. Please use them as reference, enhance them and share your findings and revisions with us. The plan is to package all the templates and make them available as an optional download from the https://tfsintegration.codeplex.com/ Codeplex site.

… l oaned from our book “Software Engineers on their way to Pluto”.

MSF Agile v4 to v5.xml

    1: <SettingXml>
    2:   <WITSessionCustomSetting xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema">
    3:     <Settings />
    4:     <WorkItemTypes>
    5:       <WorkItemType LeftWorkItemTypeName="Task" RightWorkItemTypeName="Task" fieldMap="TaskToTask" />
    6:       <WorkItemType LeftWorkItemTypeName="Bug" RightWorkItemTypeName="Bug" fieldMap="BugToBug" />
    7:     </WorkItemTypes>
    8:     <FieldMaps>
    9:       <FieldMap name="TaskToTask">
   10:         <MappedFields>
   11:           <MappedField LeftName="*" RightName="*" MapFromSide="Left" valueMap="" />
   12:           <MappedField LeftName="Microsoft.VSTS.Common.Issue" RightName="" MapFromSide="Left" />
   13:           <MappedField LeftName="Microsoft.VSTS.Common.Rank" RightName="" MapFromSide="Left" />
   14:           <MappedField LeftName="Microsoft.VSTS.Common.Discipline" RightName="" MapFromSide="Left" />
   15:           <MappedField LeftName="Microsoft.VSTS.Scheduling.TaskHierarchy" RightName="" MapFromSide="Left" />
   16:           <MappedField LeftName="Microsoft.VSTS.Common.ExitCriteria" RightName="" MapFromSide="Left" />
   17:           <MappedField LeftName="Microsoft.VSTS.Scheduling.BaselineWork" RightName="Microsoft.VSTS.Scheduling.OriginalEstimate" MapFromSide="Left" />
   18:         </MappedFields>
   19:         <AggregatedFields />
   20:         <UserIdentityFields>
   21:           <LeftUserIdentityFields />
   22:           <RightUserIdentityFields />
   23:         </UserIdentityFields>
   24:       </FieldMap>
   25:       <FieldMap name="BugToBug">
   26:         <MappedFields>
   27:           <MappedField LeftName="*" RightName="*" MapFromSide="Left" valueMap="" />
   28:           <MappedField LeftName="Microsoft.VSTS.Common.Issue" RightName="" MapFromSide="Left" />
   29:           <MappedField LeftName="Microsoft.VSTS.Common.Rank" RightName="" MapFromSide="Left" />
   30:           <MappedField LeftName="Microsoft.VSTS.Common.Discipline" RightName="" MapFromSide="Left" />
   31:           <MappedField LeftName="Microsoft.VSTS.Scheduling.TaskHierarchy" RightName="" MapFromSide="Left" />
   32:           <MappedField LeftName="Microsoft.VSTS.Common.ExitCriteria" RightName="" MapFromSide="Left" />
   33:           <MappedField LeftName="Microsoft.VSTS.Scheduling.BaselineWork" RightName="Microsoft.VSTS.Scheduling.OriginalEstimate" MapFromSide="Left" />
   34:           <MappedField LeftName="Microsoft.VSTS.Common.Triage" RightName="" MapFromSide="Left" />
   35:           <MappedField LeftName="Microsoft.VSTS.Test.TestName" RightName="" MapFromSide="Left" />
   36:           <MappedField LeftName="Microsoft.VSTS.Test.TestId" RightName="" MapFromSide="Left" />
   37:           <MappedField LeftName="Microsoft.VSTS.Test.TestPath" RightName="" MapFromSide="Left" />
   38:           <MappedField LeftName="System.Description" RightName="Microsoft.VSTS.TCM.ReproSteps" MapFromSide="Left" />
   39:         </MappedFields>
   40:         <AggregatedFields />
   41:         <UserIdentityFields>
   42:           <LeftUserIdentityFields />
   43:           <RightUserIdentityFields />
   44:         </UserIdentityFields>
   45:       </FieldMap>
   46:     </FieldMaps>
   47:     <ValueMaps />
   48:   </WITSessionCustomSetting>
   49: </SettingXml>
   50: <SettingXmlSchema />

Chatter

The sample configuration file maps work item types Task and Bug from MSF Agile v4 to MSF Agile v5. For both work item types the template currently uses only the MappedFields feature to either map fields from source (v4) to target (v5) or drop fields.

Let’s cover some of the relevant configuration features, but pulling content from the TFS Integration Tools Documentation content.

- Any missing field in the configured map will be dropped if a field map is defined.
- If no field map is defined the platform implicitly maps every field as is.
- See lines 7 and 11 … which connects the work item type with the relevant field map.
- In the past an absence of WIT mapping meant that we map from source A to target A. This implicit mapping is now obsolete!
- To simulate the old map everything from source to target implicitly, we can define:
- Note that both “*” and “@@ALL@@” are wildcard characters.
- Only explicitly mapped fields will now be migrated if a map is defined.

FieldMap

The FieldMap defines the field mappings from source to target.

    1: <CustomSettings>
    2:  
    3:  <SettingXml>
    4:    <WITSessionCustomSetting>
    5:      <WorkItemTypes>
    6:         <WorkItemType LeftWorkItemTypeName="Defect" RightWorkItemTypeName="Bug" 
    7:                       fieldMap="DefectBugFieldMap" /> 
    8:      </WorkItemTypes>
    9:      <FieldMaps>
   10:        <FieldMap name="DefectBugFieldMap">
   11:           <MappedFields>
   12:               <MappedField LeftName="State" RightName="System.State" 
   13:                            MapFromSide="Left" valueMap="StateMap" /> 
   14:               <MappedField LeftName="Priority" RightName="Microsoft.VSTS.Common.Priority" 
   15:                            MapFromSide="Left" valueMap="PriorityMap" /> 
   16:           </MappedFields>
   17:        </FieldMap>
   18:      </FieldMaps>
   19:      <ValueMaps>
   20:        <ValueMap name="PriorityMap"> …
   21:        <ValueMap name="StateMap"> …
   22:      </ValueMaps>
   23:    </WITSessionCustomSetting>
   24:  </SettingXml>
   25: </CustomSettings>

CAUTION: It is not allowed to map the same source field to multiple target fields, by creating multiple MappedField elements. Only the first MappedField will be processed in this case. Consider using AggregatedFields, if you need this feature. While you can only define one MappedField per source field, you can define multiple aggregated fields for the same source field.

All Fields (@@ALL@@)

At the Work Item type mapping level we now have to be explicit.

<WorkItemType LeftWorkItemTypeName="*" RightWorkItemTypeName="*" fieldMap=" @@ALL@@ " />

ExcludedFields (Obsolete Feature)

In the “past” …

We could optionally exclude fields as part of the migration. In the configuration extract below, we have a work item type Defect originating from the left (source), which maps to Defect 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 below we have a list of exclusion fields if we process a Defect work item type.

See lines 15 – 21 which shows how we “used to” define excluded fields. This feature is now OBSOLETE and should not be used. But … how do we exclude fields then? See next topic :)

    1: <CustomSettings>
    2:   <SettingXml>
    3:     <WITSessionCustomSetting>
    4:       <WorkItemTypes>
    5:       <WorkItemType LeftWorkItemTypeName="Defect" 
    6:                     RightWorkItemTypeName="Defect" fieldMap="Defect2DefectFieldMap" />
    7:     </WorkItemTypes>
    8:       <FieldMaps>
    9:         <FieldMap name="Defect2DefectFieldMap">
   10:           <MappedFields>
   11:             <MappedField LeftName="State" RightName="System.State" MapFromSide="Left" valueMap="" />
   12:             <MappedField LeftName="Headline" RightName="System.Title" MapFromSide="Left" valueMap="" />
   13:             ...
   14:           </MappedFields>
   15:           <ExcludedFields>
   16:             <ExcludedField field="Submitter" ExcludeFromSide="Left" />
   17:             <ExcludedField field="Submit_Date" ExcludeFromSide="Left" />
   18:             ...
   19:             <ExcludedField field="System.Id" ExcludeFromSide="Right" />
   20:             ...
   21:           </ExcludedFields>
   22:         </FieldMap>
   23:       </FieldMaps>
   24:     ...
   25:     </WITSessionCustomSetting>
   26:   </SettingXml>
   27:   <SettingXmlSchema />
   28: </CustomSettings>

How would do I do it “today”?

The equivalent of the example “past” as above, would be just removing the ExcludedFields section because there are mapped fields. Note that if you define any fields in the mapped fields, all the rest will be excluded automatically, which was one of the reasons the ExcludedFields field feature was deprecated.

See lines lines 11 and 12 which implicitly defined two field mappings, making the rest of the fields “excluded”. Also see next topic.

    1: <CustomSettings>
    2:    <SettingXml>
    3:      <WITSessionCustomSetting>
    4:        <WorkItemTypes>
    5:        <WorkItemType LeftWorkItemTypeName="Defect" 
    6:                      RightWorkItemTypeName="Defect" fieldMap="Defect2DefectFieldMap" />
    7:      </WorkItemTypes>
    8:        <FieldMaps>
    9:          <FieldMap name="Defect2DefectFieldMap">
   10:            <MappedFields>
   11:              <MappedField LeftName="State" RightName="System.State" MapFromSide="Left" valueMap="" />
   12:              <MappedField LeftName="Headline" RightName="System.Title" MapFromSide="Left" valueMap="" />
   13:              ...
   14:            </MappedFields>
   15:          </FieldMap>
   16:        </FieldMaps>
   17:      ...
   18:      </WITSessionCustomSetting>
   19:    </SettingXml>
   20:    <SettingXmlSchema />
   21:  </CustomSettings>

By implicitly excluding all other fields it is much easier to create a configuration file than before, as we do not have to worry about excluded fields any more.

Excluded Field Feature

We can either implicitly exclude fields as mentioned above, or use a new feature to explicitly exclude fields in a MappedField of *->*, using the mapping Some.Field->’’.

See line 11 which maps all fields from left to right and lines 12-14 which define implicit excluded fields, a feature that has been used in the MSF Agile v4 to v5 template.

    1: <CustomSettings>
    2:    <SettingXml>
    3:      <WITSessionCustomSetting>
    4:        <WorkItemTypes>
    5:        <WorkItemType LeftWorkItemTypeName="Example" 
    6:                      RightWorkItemTypeName="Example" fieldMap="Example2ExampleFieldMap" />
    7:      </WorkItemTypes>
    8:        <FieldMaps>
    9:          <FieldMap name="Example2ExampleFieldMap">
   10:            <MappedFields>
   11:              <MappedField LeftName="*" RightName="*" MapFromSide="Left" valueMap="" />
   12:              <MappedField LeftName="Submitter" RightName="" MapFromSide="Left" valueMap="" />
   13:              <MappedField LeftName="Submit_Date" RightName="" MapFromSide="Left" valueMap="" />
   14:              <MappedField LeftName="Submit_Id" RightName="" MapFromSide="Left" valueMap="" />
   15:              ...
   16:            </MappedFields>
   17:          </FieldMap>
   18:        </FieldMaps>
   19:      ...
   20:      </WITSessionCustomSetting>
   21:    </SettingXml>
   22:    <SettingXmlSchema />
   23:  </CustomSettings>
   24:

What’s next?

The following templates are next in line:

MSF v4 to Emc Scrum v3.xml
Scrum v2 to Agile v5.xml
scrum v2 to v3.xml

… your candid feedback and contribution to the template will be highly appreciated :)

Share via