TFS Integration Platform – What is the EnableBypassRuleDataSubmission in the Configuration File? Question & Answer 7

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="https://TFS2010B1X32T:8080/tfs/defaultcollection" 
   20:                          SourceIdentifier="TP-A" 
   21:                          ProviderReferenceName="04201D39-6E47-416f-98B2-07F0013F8455">
   22:           <CustomSettings>
   23:             <!--<CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="true" />-->
   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="https://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="https://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="https://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="https://TFS2010B1X32T:8080/tfs/defaultcollection"
SourceIdentifier="TP-C"
ProviderReferenceName="04201D39-6E47-416f-98B2-07F0013F8455">
<CustomSettings>
           <CustomSetting SettingKey="EnableBypassRuleDataSubmission" SettingValue="true" />
</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="true" />—>
</CustomSettings>

When should you use this rule?

Blue Businessman Seated at a Desk, Instructing Employees Clipart Illustration Although bypassing any rule is extending a huge trust to the account submitting the WIT changes, the feature is recommended in the following situations:

  1. When processing large volumes of work items, where volume of conflict and associated resolutions would be overwhelming.
  2. When you would like to see “Updated by <migration account> on behalf of <Real User Name>” in bug comments. Disabling this feature would result in a truncated comment “Updated by <migration account>”, which omits the real user (owner) name of the work item.

Acronyms Used

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