Troubleshooting

So you setup TFS Aggregator and it just sits there…. doing nothing…

Well, this is a check list of things to double check.

Server Plugin Checklist #

  • You are using it on a TFS 2013 update 2 or later server
  • You installed the right version for your TFS server
    • You can verify if assembly version matches TFS version using this Powershell code
$pathToAssemblyFile = "C:\Program Files\Microsoft Team Foundation Server 15.0\Application Tier\Web Services\bin\Plugins\TFSAggregator2.ServerPlugin.dll"
[System.Reflection.Assembly]::LoadFile($pathToAssemblyFile).GetCustomAttributesData() | ?{ $_.AttributeType -eq [System.Reflection.AssemblyConfigurationAttribute] } | select ConstructorArguments
  • You copied the DLLs and the Policies file to the plugins location on all TFS Application Tier Servers (Usually at: :\Program Files\Microsoft Team Foundation Server {version}\Application Tier\Web Services\bin\Plugins)
  • You have given permission to the user running the plugin, e.g. add the “TFS Service Account” to the Project Collection Administrators TFS Group; if the user has not permission, you see a similar error in the Event Log of the TFS Server(s)
  • You may have to do this from the command line using tfssecurity /collection:http://server:8080/tfs/DefaultCollection /g+ "Project Collection administrators" "LOCAL SERVICE" if your service account is either LocalService, NetworkService or any other Windows Well-known identity, since they are no longer shown in the permission UI.
  • When using the Impersonation option, make sure the user executing the plugin (generally the TFS Service account) has the “Make requests on behalf of others” permission at the server level
  • If you upgraded your TFS and did not uninstall the TFS Aggregator before doing this TFS upgrade, the Aggregator does not work. Remove the TFS Aggregator from the TFS Program Files folder or run the uninstall of the TFS Aggegrator (backup your policies!). Then re-install the TFS Aggegrator setup or install manually for TFS 2015 or 2017 as described here. Every TFS version has its “own” assembly for the aggregator so it is important to use the right version against the right TFS.

Also if you are having issues we recommend debugging your Policies file using TFSAggregator2.ConsoleApp.exe and trying that out (see below).

Policy / Rules Checklist #

  • You have updated a work item that triggers a rule. (The TFS Aggregation only works once a work item that has aggregation rules on it is updated. This may change in a future version.)
  • If the rule navigates between work items, work items have a proper Link (e.g. Parent-Child).
  • You have valid names for source and destination fields in TFSAggregator2.ServerPlugin.policies.
  • When you saved the policy file you saved it as UTF-8 encoding (in Notepad++ it is called “utf-8 without BOM”) (This should not be an issue, but it does not hurt to check).

Use Console Application #

The TFSAggregator2.ConsoleApp.exe command line tool is extremely useful to test and validate your policy files before applying to TFS.

Sample invocation

TFSAggregator2.ConsoleApp.exe run --logLevel=diagnostic --policyFile=samples\TFSAggregator2.ServerPlugin.policies --teamProjectCollectionUrl=http://localhost:8080/tfs/DefaultCollection --teamProjectName=TfsAggregatorTest1 --workItemId=42

See Console Application for more information on using the command line tool.