TFS Integration Tools – Understanding the default templates
The TFS Integration Tools (Platform) ship with default configuration templates, which can include some or all of the following, based on your configuration options:
- File System
- FileSystem_To_TFS2008.xml
- FileSystem_To_TFS2010.xml - IBM Rational
- ClearCase.xml
- ClearQuest.xml - Subversion
- Subversion_To_TFS.xml - Team Foundation Server
- VersionControl.xml
- VersionControlAndWorkItemTracking.xml
- WorkItemTracking.xml
- WorkItemTracking_ExplicitFieldMap.xml
In this post we will have a closer look at the WorkItemTracking_ExplicitFieldMap file, pointing out some possible issues you may encounter or features you may wish to configure.
- Notes
- For a generic overview of the TFS Integration Tools configuration file structure, peruse the configuration documentation that ships with the product first.
- To decide which template is the right one, have a look at Which configuration template should I use.
Here is the complete configuration template file:
1: <?xml version="1.0" encoding="utf-16"?>
2: <Configuration UniqueId="6b819d88-5668-45da-b322-2878f786796e"
3: FriendlyName="TFS to TFS Work Item Tracking with Explicit Field Map">
4: <Providers>
5: <Provider ReferenceName="00000000-0000-0000-0000-000000000000"
6: FriendlyName="Empty Provider" />
7: </Providers>
8: <Addins />
9: <SessionGroup FriendlyName="<New Work Item Tracking Configuration>"
10: SessionGroupGUID="af613bb7-80d1-420d-b017-1a5a98902da1">
11: <MigrationSources>
12: <MigrationSource InternalUniqueId="205c034a-47a3-405d-af6c-09ecd26c5d8f"
13: FriendlyName="Source System"
14: SourceIdentifier="<SourceIdentifier>"
15: ServerIdentifier="Source System"
16: ServerUrl="https://localhost:8080"
17: ProviderReferenceName="00000000-0000-0000-0000-000000000000"
18: EndpointSystemName="TFS">
19: <Settings>
20: <UserIdentityLookup />
21: </Settings>
22: <CustomSettings />
23: <StoredCredential />
24: </MigrationSource>
25: <MigrationSource InternalUniqueId="fae8917a-b373-48c8-863f-d9880aa749f1"
26: FriendlyName="Target System"
27: SourceIdentifier="<SourceIdentifier>"
28: ServerIdentifier="Target System"
29: ServerUrl="https://localhost:8080"
30: ProviderReferenceName="00000000-0000-0000-0000-000000000000"
31: EndpointSystemName="TFS">
32: <Settings>
33: <UserIdentityLookup />
34: </Settings>
35: <CustomSettings />
36: <StoredCredential />
37: </MigrationSource>
38: </MigrationSources>
39: <Sessions>
40: <Session SessionType="WorkItemTracking"
41: SessionUniqueId="be1d07b0-d9d1-4aed-9633-a5b76acdccaf"
42: FriendlyName="Work Item Tracking Session"
43: LeftMigrationSourceUniqueId="205c034a-47a3-405d-af6c-09ecd26c5d8f"
44: RightMigrationSourceUniqueId="fae8917a-b373-48c8-863f-d9880aa749f1">
45: <EventSinks />
46: <CustomSettings>
47: <SettingXml>
48: <WITSessionCustomSetting >
49: <Settings />
50: <WorkItemTypes>
51: <WorkItemType LeftWorkItemTypeName="Bug"
52: RightWorkItemTypeName="Bug"
53: fieldMap="BugToBugFieldMap" />
54: </WorkItemTypes>
55: <FieldMaps>
56: <FieldMap name="BugToBugFieldMap">
57: <MappedFields>
58: <MappedField MapFromSide="Left"
59: LeftName="*"
60: RightName="*" />
61: <MappedField MapFromSide="Left"
62: LeftName="Microsoft.VSTS.Common.Priority"
63: RightName="Microsoft.VSTS.Common.Priority"
64: valueMap="PriorityValueMap" />
65: </MappedFields>
66: </FieldMap>
67: </FieldMaps>
68: <ValueMaps>
69: <ValueMap name="PriorityValueMap">
70: <Value LeftValue="2"
71: RightValue="1" />
72: </ValueMap>
73: </ValueMaps>
74: </WITSessionCustomSetting>
75: </SettingXml>
76: <SettingXmlSchema />
77: </CustomSettings>
78: <Filters>
79: <FilterPair Neglect="false">
80: <FilterItem MigrationSourceUniqueId="205c034a-47a3-405d-af6c-09ecd26c5d8f"
81: FilterString="[System.AreaPath] UNDER '<SourceIdentifier>'" />
82: <FilterItem MigrationSourceUniqueId="fae8917a-b373-48c8-863f-d9880aa749f1"
83: FilterString="[System.Id] = 0" />
84: </FilterPair>
85: </Filters>
86: </Session>
87: </Sessions>
88: <Linking>
89: <CustomSettings />
90: <LinkTypeMappings />
91: </Linking>
92: <WorkFlowType Frequency="ContinuousManual"
93: DirectionOfFlow="Unidirectional"
94: SyncContext="Unidirectional" />
95: <UserIdentityMappings>
96: <UserIdentityLookupAddins />
97: </UserIdentityMappings>
98: </SessionGroup>
99: </Configuration>
We will discuss three topics which are pertinent to this specific configuration template.
Discussion 1 – WorkItemTypes
The default template only migrates work items of type Bug. If you wish to migrate other work item types you have two options:
- Remove explicit work item type definitions, which will process all work item types encountered.
- Add more explicit work item type definitions for other work items types to be migrated.
Discussion 2 – MappedFields
The default template is suited for migrations, in other words moving from source (left) to target (right). If you want to perform synchronizations, you have to not only define the mapping from left to right, but also from right to left as follows:
Note: <- 1 … the * –>* rules means that we are mapping everything from left to right, or right to left, unless a more explicit mapping is defined as is the case for Microsoft.VSTS.Common.Priority in the default template.
Discussion 3 – Disabling Link Relationships
BY default there are custom settings for linking, which means that link relationships will be analyzed and migrated where possible.
If you are wondering why links are getting lost have a look at Why are my WIT Links not migrating and if you wish to change link types have a peek at Why are my WIT Links not migrating? Part II. If you wish to disable linking all together, you can the following change:
Special thanks goes to Omar (ALM MVP) who helped highlight these possible issues/features 