Share via

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).

Comments

  • Anonymous
    October 04, 2011
    Which <MigrationSource> should this <CustomSetting> go under? The old project or the new?

  • Anonymous
    October 04, 2011
    If you have a bi-directional syn it would go under both, if you have a migration from X to Y, you would define it as part of the X custom settings.

  • Anonymous
    June 20, 2012
    The comment has been removed

  • Anonymous
    June 20, 2012
    The comment has been removed

  • Anonymous
    June 27, 2012
    Not sure why soem comments are not getting thru... So I try again Having set up a Prior ID String in every work item type definition for my new team project... called Custom.PriorTDStr And having set up the XML in my migration definition        <CustomSettings> <CustomSetting SettingKey="EnableInsertReflectedWorkItemId" SettingValue="true" /> <CustomSetting SettingKey="ReflectedWorkItemIdFieldReferenceName" SettingValue="Custom.PriorIdStr" />        </CustomSettings> Now running - I get this for every work item created - not just Stories, of course - and the visible field is not populated [6/27/2012 11:53:17 AM] TfsIntegrationService.exe Information: 0 : WorkItemTracking: WorkItem type 'User Story' does not contain field 'TfsMigrationTool.ReflectedWorkItemId'. Writing source item Id will be skipped. I remain flustered - I believe I am follwing all the guidance. Can you help out?

  • Anonymous
    June 27, 2012
    @Jeff, please review "Why is ReflectedWorkItemId not working? (Bug 690647) URL: blogs.msdn.com/.../tfs-integration-tools-why-is-reflectedworkitemid-not-working-bug-690647.aspx as mentioned above. It explains that you cannot define a custom ReflectedWorkItemId in the session configuration. Sorry for the delay in response. In future please raise a thread on social.msdn.microsoft.com/.../threads and include configuration files and log files if you have an issue with the producy, because the team is monitoring that forum.

  • Anonymous
    January 04, 2013
    The comment has been removed

  • Anonymous
    January 18, 2013
    Brian, thanks for the feedback, which I will add to our backlog. It is probably good to highlight that all of the configurations are session specific, in other words if we have a left->right and right->left session the settings need to be configured for both sessions within the session group.