Willy's Reflections - Visual Studio ALM Rangers

| Willy-Peter Schaub | Visual Studio ALM Rangers | In search of IT simplicity, quality and tranquility |

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

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

  • Comments 8

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

  • Which <MigrationSource> should this <CustomSetting> go under? The old project or the new?

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

  • This still remains a bit elusive... a more complete illustration is surely in order. I am trying to do a one-way migration of work items only...

    From another link out on the web...

     • Define the following field in the target work item type definitions, whereby refname must be defined as highlighted and the name can be any custom value.

          <FIELD refname="TfsMigrationTool.ReflectedWorkItemId" name="Your Custom Name" type="String">

    But what appears elsewhere in this Migration XML? I want to map source work item System.Id to target Custom.PriorId field on all my target work items. Is it only the work item definitions that change and nothing in the "Fieldmaps"?

    And then I struggle with the Line 17 & 18 referenced in your text... they do not exist at all.

    Experience suggests that I can wait a long time waiting only to find out that the integration platform and my XML file are still not doing what I need. I have tweaked my work item definitions... I have created the lines 11 & 12 from the Feature Enabled code with SettingValue="Custom.PriorID" .

    Is anything missing? is this all correct?

    I am still curious about refname="TfsMigrationTool.ReflectedWorkItemId"  - do I have to name my field "TfsMigrationTool.ReflectedWorkItemId" ? I was kinf of hoping for refname "Cust.PriorID".. is this the refname managed in the work item definition and the database? Does the toolkit really impose this specific refname on the work item definition?

  • Jeff, thanks for the comments. Let me work through your feedback:

    We have more detailed illustrations focused on migrations, field and value mappings, etc. in the product documentation and other blog posts. If you can elaborate on what you would like to see in the illustration and how we can make it more complete, I can either point you at appropriate documentation and/or update the diagram in this post. The intent of this post, however, is only to cover the ReflectedWorkItemId feature and allowing you to have a reference between source and target work item IDs.

    Also refer to Why is ReflectedWorkItemId not working? (Bug 690647), which answers your question on the custom value. The refname must be defined as TfsMigrationTool.ReflectedWorkItemId. URL: blogs.msdn.com/.../tfs-integration-tools-why-is-reflectedworkitemid-not-working-bug-690647.aspx.

    Lines 17 & 18 … fixed.

    Experience shows that I can wait a long time … we recommend that you pilot and test your migrations and synchronizations in an isolated environment with a subset of data. The analysis and migration instruction creation phase can take very long if your WIT/VC history is large. Test your configurations with a subset of your data and then transfer your configuration once all gremlins have been chased out of your session.

    Does this answer your questions?

  • 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?

  • @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.

  • Willy, it would be great to see the migration guidance document (on Codeplex) updated with information from your October 4, 2011 response (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).

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

Page 1 of 1 (8 items)
Leave a Comment
  • Please add 1 and 7 and type the answer here:
  • Post