TFS Integration Platform – What is the EnableInsertReflectedWorkItemId that I noticed in logfiles all about? Q&A-26

  • Article

Secretive Blue Man in a Trench Coat and Hat, Carrying a Box With a Question Mark on it Clipart Illustration Grant C. recently sent us this question: “I saw mention in the log of a TfsMigrationTool.ReflectedWorkItemId field but couldn't find any docs / discussion about it. I added it to my target WIT and also added my own TfsMigrationTool.SourceProject field as you can see in the config, but I'm curious if there are any other TfsMigrationTool.x fields the tool automatically sets. ”

Great question, which allows us to introduce an originally internal Pioneer dog fooding feature, but one that could be invaluable to users of the TFS Integration Platform in WIT migration and/or synchronization scenarios.

Warning: This is an advanced feature for production synchronization environments and is not recommended for the average migration or synchronization environments.

So, what is it?

image

The illustration above shows a hypothetical migration of Work Item Types (WIT) from Source A to Source B. On source A the relevant work items are numbered 1 to 6, as we are working with a brand new server or work items which were the first to be created on the server. When we migrate these work items to source B, the created work items are numbered 13 – 18, not because 13 happens to be my lucky number, but because there were already 12 other work items on the source B server.

I am now working on the source B environment, work item 13 and am wondering what the corresponding work item is on source A. We could dig through log files, look at WIT history … but would it not be ‘nice’ to have that information included in WIT #13?

Well,EnableInsertReflectedWorkItemId delivers a solution by copying the source WIT ID to a predefined reference field during the migration phase, allowing me to see the #13 and #1 relationship visually or creating appropriate work item queries or reports.

How do I configure it?

Looking at the example 1 configuration file below…

  • Line 11 … EnableInsertReflectedWorkItemIddefines whether feature is enabled (true) or disabled (false).
      • The default, if this line is missing, is enabled (true).
  • Line 12 … ReflectedWorkItemIdFieldReferenceNamedefines the reference name of the field to be used, if EnableInsertReflectedWorkItemId is set to true.
      • The default, if this line is missing, is a reference name of TfsMigrationTool.ReflectedWorkItemId.
      • In the example, the reference name is defined as SampleReferenceName.DemoMirrorId.

Example 1 – Feature Enabled ( … indicates that we snipped content)

  1. <SessionGroup CreationTime="…" FriendlyName="…" SessionGroupGUID="…" Creator="…" SyncIntervalInSeconds="0" SyncDurationInMinutes="0">
  2.     <MigrationSources>
  3.       <MigrationSource InternalUniqueId="…" FriendlyName="…" ServerIdentifier="…" ServerUrl="…" SourceIdentifier="…" ProviderReferenceName="…">
  4.         <Settings>
  5.           <UserIdentityLookup />
  6.         </Settings>
  7.         <CustomSettings>
  8.           <CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="" />
  9.           <CustomSetting SettingKey="DisableAreaPathAutoCreation" SettingValue="" />
  10.           <CustomSetting SettingKey="DisableIterationPathAutoCreation" SettingValue="" />
  11.           <CustomSetting SettingKey="EnableInsertReflectedWorkItemId" SettingValue="true" />
  12.           <CustomSetting SettingKey="ReflectedWorkItemIdFieldReferenceName" SettingValue="SampleReferenceName.DemoMirroredId" />
  13.         </CustomSettings>
  14.         <StoredCredential />
  15.       </MigrationSource>
  16.       ...

Example 2 – Feature Disabled:

  1. <SessionGroup CreationTime="…" FriendlyName="…" SessionGroupGUID="…" Creator="…" SyncIntervalInSeconds="0" SyncDurationInMinutes="0">
  2.     <MigrationSources>
  3.       <MigrationSource InternalUniqueId="…" FriendlyName="…" ServerIdentifier="…" ServerUrl="…" SourceIdentifier="…" ProviderReferenceName="…">
  4.         <Settings>
  5.           <UserIdentityLookup />
  6.         </Settings>
  7.         <CustomSettings>
  8.           <CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="" />
  9.           <CustomSetting SettingKey="DisableAreaPathAutoCreation" SettingValue="" />
  10.           <CustomSetting SettingKey="DisableIterationPathAutoCreation" SettingValue="" />
  11.           <CustomSetting SettingKey="EnableInsertReflectedWorkItemId" SettingValue="false" />
  12.         </CustomSettings>
  13.         <StoredCredential />
  14.       </MigrationSource>
  15.       ...

Must I customize my process template?

  • If you do not want to take advantage of the feature you need to do nothing, although turning is off explicitly in the configuration (as shown in line 11 in the second of the above example) is what my Swiss genes would probably suggest me to do. The WIT adapter detects if the relevant field exists in the Work Item Type. The adapter writes the ID if it is present. If not, a trace warning is written (which is why this feature surfaced in the field) and skips writing the ID.
  • If you want to take advantage of the feature, you need to update your work item type definition, add a string field with the configured reference name and configure lines 11 and 12 (in the frirst of the above example) accordingly.

That’s it … another undocumented and general purpose feature has been revealed :)

In the next Q&A we will be introducing the Lookup Service.

UPDATE: 2012-06-20 ...Please also refer to Why is ReflectedWorkItemId not working? (Bug 690647).