When you have a look at most of the TFS Integration Platform configuration files, you will notice the EnableBypassRuleDataSubmission, as shown in line 23 and 37 in the following Sample Configuration file:

   1: <?xml version="1.0" encoding="utf-16"?>
   2: <Configuration UniqueId="{7439CF38-BBF4-4B16-A8C9-B5CB3B5A82E5}"
   3:                FriendlyName="TR9 HOL AS">
   4:     <Providers>
   5:         <Provider FriendlyName="CR TFS 2010 Migration WIT Provider" 
   6:                 ReferenceName="04201D39-6E47-416f-98B2-07F0013F8455" />
   7:       <Provider FriendlyName="CR TFS 2010 VC Migration Provider" 
   8:                 ReferenceName="FEBC091F-82A2-449e-AED8-133E5896C47A" />
   9:     </Providers>
  10:                   
  11:     <SessionGroup FriendlyName="Session Group Friendly Name AS" 
  12:                           SessionGroupGUID="{06D11897-EF77-4326-888F-96E4F856A2E3}"
  13:                           WorkFlowType="OneDirectionalSynchronizationWithoutContextSync">
  14:       <MigrationSources>
  15:         <!-- WIT Migration Sources -->
  16:         <MigrationSource InternalUniqueId="A0E4FBE9-5E44-4D12-A274-958F259A9B6D" 
  17:                          FriendlyName="TFS2010B1X32T Source AS" 
  18:                          ServerIdentifier="TFS2010B1X32T Source AS" 
  19:                          ServerUrl="http://TFS2010B1X32T:8080/tfs/defaultcollection" 
  20:                          SourceIdentifier="TP-A" 
  21:                          ProviderReferenceName="04201D39-6E47-416f-98B2-07F0013F8455">
  22:           <CustomSettings>
  23:             <!--<CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="false" />-->
  24:             <!--<CustomSetting SettingKey="DisableAreaPathAutoCreation" SettingValue="" />-->
  25:             <!--<CustomSetting SettingKey="DisableIterationPathAutoCreation" SettingValue="" />-->
  26:           </CustomSettings>
  27:           <StoredCredential />
  28:         </MigrationSource>
  29:         
  30:         <MigrationSource InternalUniqueId="EF98D1AE-2101-444F-9FAB-DC9C354E861A" 
  31:                          FriendlyName="TFS2010B1X32T Target AS" 
  32:                          ServerIdentifier="TFS2010B1X32T Target AS" 
  33:                          ServerUrl="http://TFS2010B1X32T:8080/tfs/defaultcollection" 
  34:                          SourceIdentifier="TP-C" 
  35:                          ProviderReferenceName="04201D39-6E47-416f-98B2-07F0013F8455">
  36:           <CustomSettings>
  37:             <!--<CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="false" />-->
  38:           </CustomSettings>
  39:           <StoredCredential />
  40:         </MigrationSource>
  41:  
  42:         <!-- VC Migration Sources -->
  43:         <MigrationSource InternalUniqueId="13828D85-46F5-40A4-9A38-D95CF96B01DB"
  44:                FriendlyName="TFS2010B1X32T VC Source AS"
  45:                ServerIdentifier="TFS2010B1X32T VC Source AS"
  46:                ServerUrl="http://TFS2010B1X32T:8080/tfs/defaultcollection"
  47:                SourceIdentifier="Source System"
  48:                ProviderReferenceName="FEBC091F-82A2-449e-AED8-133E5896C47A">
  49:           <CustomSettings>
  50:             <SettingXml />
  51:             <SettingXmlSchema />
  52:           </CustomSettings>
  53:         </MigrationSource>
  54:         
  55:         <MigrationSource InternalUniqueId="9848394A-112D-4B8B-9866-0E309BB372CB"
  56:                FriendlyName="TFS2010B1X32T VC Target AS"
  57:                ServerIdentifier="TFS2010B1X32T VC Target AS"
  58:                ServerUrl="http://TFS2010B1X32T:8080/tfs/defaultcollection"
  59:                SourceIdentifier="Target System"
  60:                ProviderReferenceName="FEBC091F-82A2-449e-AED8-133E5896C47A">
  61:           <CustomSettings>
  62:             <SettingXml />
  63:             <SettingXmlSchema />
  64:           </CustomSettings>
  65:         </MigrationSource>
  66:       </MigrationSources>
  67:       
  68:       <Sessions>
  69:         <Session SessionUniqueId="CE189D49-EAA3-4CB9-883D-FC68F79656FF"
  70:                  FriendlyName="WIT session AS"
  71:                  LeftMigrationSourceUniqueId="A0E4FBE9-5E44-4D12-A274-958F259A9B6D"
  72:                          RightMigrationSourceUniqueId="EF98D1AE-2101-444F-9FAB-DC9C354E861A"
  73:                          SessionType="WorkItemTracking">
  74: <!-- LAB1 -->
  75:       <CustomSettings />
  76:           <Filters>
  77:             <FilterPair>
  78:               <FilterItem MigrationSourceUniqueId="A0E4FBE9-5E44-4D12-A274-958F259A9B6D" FilterString="" />
  79:               <FilterItem MigrationSourceUniqueId="EF98D1AE-2101-444F-9FAB-DC9C354E861A" FilterString="" />
  80:             </FilterPair>
  81:           </Filters>
  82:         </Session>
  83:  
  84: <!-- LAB 3         
  85:         <Session SessionUniqueId="7092283E-8776-4458-A0BC-1A96385C635F"
  86:                        FriendlyName="Control session AS"
  87:                        LeftMigrationSourceUniqueId="13828D85-46F5-40A4-9A38-D95CF96B01DB"
  88:                        RightMigrationSourceUniqueId="9848394A-112D-4B8B-9866-0E309BB372CB"
  89:                        SessionType="VersionControl">
  90:           <CustomSettings>
  91:           </CustomSettings>
  92:           
  93:           <Filters>
  94:             <FilterPair>
  95:               <FilterItem MigrationSourceUniqueId="13828D85-46F5-40A4-9A38-D95CF96B01DB" FilterString="$/TP-A" />
  96:               <FilterItem MigrationSourceUniqueId="9848394A-112D-4B8B-9866-0E309BB372CB" FilterString="$/TP-C" />
  97:             </FilterPair>  
  98:           </Filters>
  99:         </Session>
 100: LAB 3 -->
 101:       </Sessions>
 102:       
 103:       <Linking EngineProviderReferenceName="04201D39-6E47-416f-98B2-07F0013F8455">
 104:         <!--<CreationTime>0001-01-01T00:00:00</CreationTime>-->
 105:         <CustomSettings>
 106:           <SettingXml />
 107:           <SettingXmlSchema />
 108:         </CustomSettings>
 109:         <LinkTypeMappings /> 
 110:       </Linking>
 111:       
 112:     </SessionGroup>
 113: </Configuration>

“So what is this feature all about”, some of you are asking?

What does it do?
Smart Blue Man Seated With His Legs Crossed, Brainstorming and Writing Ideas Down in a Notebook, Lightbulb Over His Head Clipart Illustration

The best  is to work through the TFS Integration Platform – Getting Started Basic Scenario, which performs a bi-direction synchronization with the EnableBypassRuleDataSubmission enabled and then the TFS Integration Platform – Getting Started Advanced Scenario which repeats the walkthrough, but with the feature disabled. Seeing is believing and working through the walkthrough, or watching the forthcoming video recordings of the two scenarios, will explain the feature better than a blog consisting of a large amount of descriptive text.

When this feature is enabled the WIT Adapter will, in particular the TfsMigrationWorkItemStore class, will react accordingly and submit WIT changes using a XmlDocument  with the BypassRule enabled.

   if (ByPassrules)
        SubmitChangesWithUpdateDoc(changeGroup, changeResult, sourceSideSourceId);
   else
        SubmitChangesWithWitOM(changeGroup, changeResult, sourceSideSourceId);

This enforces, that all WITD rule evaluations, such as valid value list and state transitions, are disabled for submitted WIT data and that changes are applied as instructed ... no questions asked. Additionally, turning on bypass-rule for WIT changes submission is requisite for higher migration content fidelity. In particular, the author of the source WIT change, regardless being a valid user or not on the target TFS server, is preserved. If bypass-rule is disabled, the migration service account will be the author of *all* the migrated WIT changes on the target TFS server.

What are the ranges of SettingValue?
a Blue Man on Another Man's Shoulders, Holding up a Bar in a Graph Clipart Illustration

The SettingValue is ignored at this stage. To enable the EnableBypassRuleDataSubmission, add the following line to the WIT session configuration:
   <MigrationSource InternalUniqueId="EF98D1AE-2101-444F-9FAB-DC9C354E861A"
                    FriendlyName="TFS2010B1X32T Target AS" 
                    ServerIdentifier="TFS2010B1X32T Target AS" 
                    ServerUrl="http://TFS2010B1X32T:8080/tfs/defaultcollection" 
                    SourceIdentifier="TP-C" 
                    ProviderReferenceName="04201D39-6E47-416f-98B2-07F0013F8455">
       <CustomSettings>
           <CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="false" />
       </CustomSettings>
       <StoredCredential />
   </MigrationSource>

In addition to enabling the rule, you must also ensure that the user account that will be performing the synchronization and submitting the WIT changes, is a member of the Team Foundation Service Group and thus authorised to bypass the rule evaluations.

The following is a sample script file used as part of the TFS Integration Platform – Getting Started Basic Scenario:

   1: cd "C:\Program Files\Microsoft Visual Studio 10.0\Common7\IDE>"
   2: tfssecurity /g+ srv: tfs2010b1x32t\Administrator /server:tfs2010b1x32t\defaultcollection
   3: pause

To disable, either remove it or comment it out as shown:

   <CustomSettings>
       <!--<CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="false" />—>
   </CustomSettings>

When should you use this rule?

Blue Businessman Seated at a Desk, Instructing Employees Clipart Illustration Bypassing any rule is extending a huge trust to the user submitting the WIT changes and as possible state and data corruption is possible, the recommendation is not to use this feature. Instead use the new conflict resolution tool to create appropriate rules. That said, we recommend to enable (use) the BypassRule, if the preservation of the “original author” in the migrated work items is important, and avoid it in all other cases.

Acronyms Used

| TFS – Team Foundation Server | WIT – Work Item Tracking | WITD – WIT Definition |