Aligned docs for 2.3 RC

.gitignore

@@ -1,2 +1,3 @@
 node_modules
-static/json/search.json
+static/json/search.json
+.vscode/

content/CHANGELOG.md

@@ -1,5 +1,15 @@
 # History of Changes
 
+## What’s new in v2.3 (RC1)
+
+ * Support for TFS 2017 Update 2
+ * Reading and removal of Work item Links [`self.WorkItemLinks`]({{< ref "self-object.md#workitemlinks-property-v2-3" >}}) [`self.RemoveWorkItemLink`]({{< ref "self-object.md#removeworkitemlink-method-v2-3" >}})
+ * Global List editing with [`AddItemToGlobalList`]({{< ref "store-object.md#additemtogloballist-method-v2-3" >}}) and [`RemoveItemFromGlobalList`]({{< ref "store-object.md#removeitemfromgloballist-method-v2-3" >}})
+ * Fix SendMail (see [#206](https://github.com/tfsaggregator/tfsaggregator/issues/206))
+ * Fix TF26027 error using `TransitionToState` with non-English templates (see [#232](https://github.com/tfsaggregator/tfsaggregator/issues/232))
+ * Fix `BasicAuthenticationToken` bug (see [PR #5](https://github.com/tfsaggregator/tfsaggregator-webhooks/pull/5))
+ * New code layout, contributors are urged to read [Source Code]({{< ref "source-code.md" >}})
+
 ## What’s new in v2.3 (beta)
 
  * Support for VSTS & TFS 2015 / 2017 Web Hooks via Web Service

content/admin/logging/index.md

@@ -38,6 +38,8 @@ We would recommend adding the `*TFSAggregator*` filter to DebugView so that you
 ![](./dbg-view-filter.png)
 
 Make sure to enable the **Capture Global Win32** option.
+![](./dbg-view-capture.png)
+
 Download DebugView at <http://technet.microsoft.com/en-us/sysinternals/bb896647>.
 
 

content/admin/troubleshooting/index.md

@@ -22,10 +22,10 @@ $pathToAssemblyFile = "C:\Program Files\Microsoft Team Foundation Server 15.0\Ap
 ```
 
  -  You copied the DLLs and the Policies file to the plugins location on all TFS Application Tier Servers (Usually at: <Drive>`:\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.
-  - You may have to do this from the commandline 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.
+ -  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) ![](./most-common-tfs30063.png)
+  - 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](https://msdn.microsoft.com/en-us/library/ms252587.aspx)
- -  If you upgraded your TFS from 2013.x to 2015.* or to 2017.* and from 2015 RTM to 2015.1 and did not uninstall the TFS Aggregator before doing this TFS upgrade the aggregator does not work. Remove the TFS Aggregator from the TFS 2013 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](/admin/install). Every TFS version has its "own" assembly for the aggregator so it is important to use the right version against the right TFS.
+ -  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](/admin/install). 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).

content/contrib/continuous-integration.md

@@ -2,7 +2,7 @@
 title: "Continuous Integration"
 weight: 450
 prev: /contrib/debugging
-next: /
+next: /contrib/documentation
 toc: true
 ---
 We moved to [VSTS](https://tfsaggregator.visualstudio.com/) for Continuous Integration.

content/contrib/developer-intro.md

@@ -18,12 +18,13 @@ These check can be:
 - source code conditional compile
 - WiX sources
 - MSBuild project files
-So, _caveat emptor_: TFS versions are scattered all-over the places.
+So, _caveat emptor_: TFS versions are scattered in many places.
 
 
 ## Compile
 
-Note that to rebuild, edit or debug the code you must use Visual Studio 2015, Community or Professional Edition at a minimum (see [Local build](/contrib/local-build) for details).
+Note that to rebuild, edit or debug the code you must use Visual Studio 2017, Community or Professional Edition at a minimum (see [Local build](/contrib/local-build) for details).
+The Community edition is free.
 TFS is not required locally: you can use Remote Debugging. 
 
 The [CI build](/contrib/continuous-integration) page explains some important things of our CI build infrastructure in [VSTS](https://tfsaggregator.visualstudio.com/).
@@ -35,10 +36,12 @@ The [CI build](/contrib/continuous-integration) page explains some important thi
 |-----------|-----------|---------------|
 | master    | Yes | Released code, versions are tagged |
 | hotfix/*  | Yes | Fast release cycle for bug fixes, branches from tag, merged to master after Issuer confirms fix is working |
-| release/* | Yes | Release candidates, branch named after soon-to-be-relased version, tags mark interim releases |
+| release/* | Yes | Release candidates, branch named after soon-to-be-released version, tags mark interim releases |
 | develop   | No  | Integration branch for developers |
 | feature/* | No  | New feature, idea |
 
+Note: you must take care of using the same branches in all the repositories involved in a change.
+
 
 ## Documentation
 
@@ -51,13 +54,13 @@ To prepare documentation for a future release, use a branch as in the code repos
  - collect solved issues
  - prepare Markdown release notes
  - update tfsaggregator-docs-hugo `release/v#` branch
- - tag repo
+ - tag all three repos
  - merge `release/v#` branch to `master` (use PR when possible)
- - create GitHub Release pasting release notes
+ - create GitHub Release by pasting release notes
  - merge tfsaggregator-docs-hugo `release/v#` branch to `master` and delete it
  - download binaries and upload to Release
  - merge `master` branch to `develop`
  - increment v# in `develop` branch and push
- - update Visual Studio Gallery pasting release notes
+ - update Visual Studio Marketplace extensions pasting release notes
  - spread the news: Twitter, Blog
  - wait for bugs to arrive

content/contrib/documentation.md

@@ -0,0 +1,21 @@
+---
+title: "Documentation"
+weight: 460
+prev: /contrib/continuous-integration/
+next: /
+toc: true
+---
+
+The source for documentation is [tfsaggregator-docs-hugo](https://github.com/tfsaggregator/tfsaggregator-docs-hugo).
+Note that you need to pull down also the theme submodule.
+
+The `master` branch content must match the latest release.
+To prepare documentation for a future release, use a branch as in the code repository.
+
+Get [Hugo](https://gohugo.io/getting-started/installing/) Hugo v0.18.1.
+
+
+Run `hugo server` to test the changes locally.
+
+Read the full details in this [blog post](http://blog.casavian.eu/2017/03/07/automate-publishing-documentation-using-hugo-and-github-pages/).
+

content/contrib/local-build.md

@@ -7,12 +7,14 @@ toc: true
 ---
 ## Building the Solution
 
-To rebuild, edit or debug the code you must use Visual Studio 2015, Community or Professional Edition at a minimum.
+To rebuild, edit or debug the code you must use Visual Studio 2017, Community or Professional Edition at a minimum.
 In addition you must install the following extensions from Visual Studio Gallery:
-- WiX 3.10
+
 - xUnit.net 1.0
+- WiX 3.10 (optional)
 
-TFS is not required to build nor debugging (for this latter you can use [Remote Debugging](https://msdn.microsoft.com/en-us/library/y7f5zaaa.aspx)).
+TFS is not required to build nor debugging if you copy locally the required DLLs (for this latter you can use [Remote Debugging](https://msdn.microsoft.com/en-us/library/y7f5zaaa.aspx)).
+WiX is not required if you use the `build-installer.proj` MSBuild script.
 
 
 ### References
@@ -24,6 +26,7 @@ Building requires a number of TFS assemblies that cannot be redistributed. You c
  - TFS 2015 Update 1: `References/2015.1/PLACEHOLDER.txt`
  - TFS 2015 Update 2: `References/2015.2/PLACEHOLDER.txt`
  - TFS 2017: `References/2017/PLACEHOLDER.txt`
+ - TFS 2017 Update 2: `References/2017.2/PLACEHOLDER.txt`
 
 if you have TFS installed on your development machine, the assemblies for that version will be loaded automatically from the installation folder.
 
@@ -34,6 +37,8 @@ The Build Configuration selected, like _Debug-2013_ or _Release-2015_, determine
 
 Sadly, similar [to the release of TFS 2013 update 2 when there were breaking changes](http://blogs.ripple-rock.com/rorystreet/2014/05/08/WhereIsWorkItemChangedEventInTFS2013Update2.aspx), [TFS 2015 Update 1 introduces a breaking change in the API](http://blogs.msdn.com/b/visualstudioalm/archive/2015/10/13/breaking-change-in-tfs-2015-update-1-for-server-side-plugins.aspx), so you can find some [conditionally compiled](https://msdn.microsoft.com/en-us/library/4y6tbswk.aspx) code based on the symbols `TFS2013`, `TFS2015` or `TFS2015u1`.
 
+See [Supported TFS versions](/intro#supported-tfs-versions) for the full list.
+
 
 ### Version numbers
 
@@ -49,16 +54,16 @@ The `build-installer.proj` MSBuild script takes care of generating the Windows I
 The MSI packages all three Aggregator flavors, one for each supported TFS version.
 The installer detects the TFS version installed and deploy the correct assemblies.
 
-The MSBuild script builds three times the `TFS-Aggregator-2.sln` solution, one for each supported TFS version.
+The MSBuild script builds multiple times the `tfs-aggregator-plugin.sln` solution, one for each supported TFS version.
 Then the files are copied in a simple layout in the `_collect` folder. Some WiX source is generated and finally the `Setup.Aggregator\Setup.Aggregator.wixproj` is launched to produce the MSI package.
 
-> **Caveat: TFS versions values are all-over the places**, e.g.
+> **Caveat: TFS versions values are in multiple places**, e.g.
 > - source code conditional compile
 > - WiX sources
 > - MSBuild project files
 
 
-To generate the MSI, in an _MSBuild Command Prompt_ (VS2015) or a _Developer Command Prompt_ (VS2013) run
+To generate the MSI, in an _MSBuild Command Prompt_ (VS2015+) or a _Developer Command Prompt_ (VS2013) run
 
 ```
 msbuild build-installer.proj /p:Configuration=Release

content/contrib/source-code.md

@@ -9,21 +9,31 @@ This page explains the design and internal organization of TFS Aggregator v2's c
 If you want to rebuild, customize, submit changes this is the place to start.
 
 
-
-# Major Components
+## Major Components
 
 The `Aggregator.Core` assembly contains the logic to process a Work Item and run the aggregate scripts.
 It is normally used by `Aggregator.ServerPlugin` which intercept the TFS server side events and forward them to Aggregator.Core.
 `Aggregator.ConsoleApp` is a simple console app that helps users in developing and testing policies without installing the server plugin.
+`Aggregator.WebHooks` (new in 2.3) is a WebAPI application that uses Web Hooks to receive notifications from TFS/VSTS.
 
 
 
-# Source Code Organization
+## Source Code Organization (up to v2.2.1)
 
 The project is available on [GitHub](https://github.com/tfsaggregator/tfsaggregator).
 We use a simple master/develop/pull-request branching scheme.
 All the source is available in the `TFS-Aggregator-2.sln` Visual Studio 2015 solution.
-To produce the MSI, see [Local build/contrib/local-build).
+To produce the MSI, see [Local build](/contrib/local-build).
+
+
+## Source Code Organization (up to v2.3 and later)
+Code is split in three repositories:
+ 1. _tfsaggregator-core_ contains the core code of Aggregator; there are 2 different project files `Aggregator.Core.Plugin.csproj` and `Aggregator.Core.WebHooks.csproj` both producing `Aggregator.Core.dll`, they **must** be manually synched using a tool like [Beyond Compare](https://www.scootersoftware.com/) or [WinMerge](http://winmerge.org/); in addition the repo holds the Unit tests.
+ 2. _tfsaggregator_ use _tfsaggregator-core_ as submodule; it contains the `tfs-aggregator-plugin.sln` solution that produce the Server Plugin; see [Local build](/contrib/local-build) for MSI details.
+ 3. _tfsaggregator-webhooks_ use _tfsaggregator-core_ as submodule; it contains the `TFS-Aggregator-WebHook.sln` solution that produce the Web Service which is not included in the MSI
+
+> **Git Tip**: add remotes to each submodule so they reference each other and you can quickly synchronize the local folders.
+
 
 
 ## Policy data
@@ -51,7 +61,7 @@ See [Scripting](/using/scripting) for an introduction.
 
 Aggregator.Core/Script contains the build and execute logic for all scripting engines.
 For C# and VB, the script code is compiled once and the produced assembly is reused until the plug-in restarts.
-The `DotNetScriptEngine` base class contains all the logic while `CSharpScriptEngine` and `VBNetScriptEngine` define how to sew the script's code snippets toghether.
+The `DotNetScriptEngine` base class contains all the logic while `CSharpScriptEngine` and `VBNetScriptEngine` define how to sew the script's code snippets together.
 Powershell support is experimental.
 
 

content/intro/index.md

@@ -7,17 +7,15 @@ title: Introduction
 weight: 100
 ---
 
-TFS Aggregator is a extension for Team Foundation Server (TFS) and Visual Studio Team Services (VSTS)
+TFS Aggregator is an extension for Team Foundation Server (TFS) and Visual Studio Team Services (VSTS)
 that enables running custom script when Work Items change,
 allowing dynamic calculation of field values in TFS and more.
 (For example: Dev work + Test Work = Total Work).
 
-You can use the [**Server Plugin**](https://github.com/tfsaggregator/tfsaggregator), for TFS 2013 update 2 up to TFS 2017 RTM, or the [**Web Service**](https://github.com/tfsaggregator/tfsaggregator-webhooks) version, for VSTS or TFS 2015 and later.
+You can use the [**Server Plugin**](https://github.com/tfsaggregator/tfsaggregator), for TFS, or the [**Web Service**](https://github.com/tfsaggregator/tfsaggregator-webhooks) version, for VSTS or TFS 2015 and later.
 
-> The Web Service version is still in beta.
-
-> TFS Server API changed frequently in the past: the Server Plugin contains specific checks for the TFS version.
-> TFS Aggregator Server Plugin binaries will work only with a specific TFS version.
+> TFS Server API changed frequently in the past: the Server Plugin contains code specific for each TFS version,
+> which means that TFS Aggregator Server Plugin binaries must be build for a specific TFS version.
 
 See the [Changelog](/CHANGELOG/) for an history of releases.
 
@@ -59,31 +57,28 @@ You can pick development binaries directly from VSTS, asking access to the team,
 Is it not working? Here is the troubleshooting and how to get help page: [TFS Aggregator Troubleshooting](/admin/troubleshooting)
 
 
-## Migrating from v2.x
-No action required.
-
+## Supported TFS versions
+The following table lists the TFS version supported by the Server Plugin.
 
-## Migrating from v1
-If you used TFS Aggregator in the past, [here](/using/upgrade-from-v1) are the instructions on switching from older versions.
 
-If you're looking for the latest version of V1 (including a large number of fixes and security updates), you can still find it [here](https://github.com/tfsaggregator/tfsaggregator/tree/8ae990810f580c161247a6f6f4720d9b72d98288). 
+|TFS version|Breaking changes|Supported|Build configuration|
+|----------:|:--------------:|:-------:|:------------------|
+| 2013 RTM  |                | **No**  |  n/a              |
+| 2013.5    |   Yes          |  Yes    |  2013             |
+| 2015 RTM  |   Yes          |  Yes    |  2015             |
+| 2015.1    |   Yes          | **No**  |  2015.1           |
+| 2015.2    |   Yes          | **No**  |  2015.2           |
+| 2015.2.1  |                | **No**  |  2015.2           |
+| 2015.3    |                | **No**  |  2015.2           |
+| 2015.4    |                |  Yes    |  2015.2           |
+| 2017 RTM  |   Yes          |  Yes    |  2017             |
+| 2017.1    |                |  Yes    |  2017             |
+| 2017.2    |   Yes          |  Yes    |  2017.2           |
+| 2017.3    |                |_Not yet_|  n/a              |
+| 201x RTM  |                |_Not yet_|  n/a              |
 
-**Note**: we won't provide any further support on this old version. But if you have a large investment in the old-style rules, it may provide you a better, stabler version until you're ready to move to V2. 
 
-**Note**: You can run both V1 and V2 side-by-side on the same TFS system, you will have to be extra careful not to create infinite loops though.
 
 ## Build and customize
-We used Visual Studio Community Edition 2015 Update 2 to develop this version.
-Compiling requires a number of TFS assemblies that cannot be redistributed. 
-
-You can find the complete list in these files:
-
- - 2013 Update 2 and later: `References/2013/PLACEHOLDER.txt`
- - 2015 RTM: `References/2015/PLACEHOLDER.txt`
- - 2015 Update 1: `References/2015.1/PLACEHOLDER.txt`
- - 2015 Update 2 or 3: `References/2015.2/PLACEHOLDER.txt`
- - 2017 RTM: `References/2017/PLACEHOLDER.txt`
-
-If you have TFS installed on your development machine, the assemblies for that version will be loaded automatically from the installation folder.
-
-More information on customizing and the internal design of TFS Aggregator is [here](/contrib/developer-intro).
+We used Visual Studio Community Edition 2017 Update 2 to develop this version.
+In the [Contributor](/contrib) section you will find all the details to rebuild and customize TFS Aggregator.

content/using/objects-reference/self-object.md

@@ -83,6 +83,19 @@ Add an hyperlink to an URL, with an optional comment.
 self.AddHyperlink("https://github.com/tfsaggregator/tfsaggregator", "Automatically added");
 ```
 
+## WorkItemLinks property (**v2.3**)
+Collection of existing work item links.
+```
+foreach (var link in self.WorkItemLinks) {
+   if (link.Target.Id == 1) {
+       logger.Log(
+           "RemoveLinkRule removing {0} to #{1}"
+           , link.LinkTypeEndImmutableName, link.Target.Id);
+       break;
+   }
+}
+```
+
 ## RemoveWorkItemLink method (**v2.3**)
 Remove a link to another work item.
 ```

content/using/objects-reference/store-object.md

@@ -13,6 +13,8 @@ It exposes these methods:
  * `GetWorkItem`
  * `MakeNewWorkItem`
  * `GetGlobalList`
+ * `AddItemToGlobalList` (**v2.3**)
+ * `RemoveItemFromGlobalList` (**v2.3**)
 
 
 ## GetWorkItem method
@@ -52,3 +54,23 @@ var items = store.GetGlobalList("Aggregator - UserParameters");
 ```
 
 > The global list name must be unique per-collection.
+
+
+## AddItemToGlobalList method (**v2.3**)
+Add an element to the named Global List. If the Global List does not exists, it is created.
+
+```
+store.AddItemToGlobalList("Aggregator - UserParameters","userValue1");
+```
+
+> The global list name must be unique per-collection.
+
+
+## RemoveItemFromGlobalList method (**v2.3**)
+Remove an element from the named Global List.
+
+```
+store.RemoveItemFromGlobalList("Aggregator - UserParameters","userValue1");
+```
+
+> The global list name must be unique per-collection.

content/using/policy-syntax.md

@@ -166,6 +166,7 @@ All scopes must match for the policy to apply (logical _and_).
 ```
 
 **templateScope**: Scope the policy to Team Projects using a particular Process Template. (Optional, Repeatable)
+> DEPRECATED: our implementation does not work with VSTS or recent versions of TFS.
 
  - **name**: Name of Process Template matching. (Mandatory, mutually exclusive with typeid)