Getting started with Aggregator CLI for Azure DevOps Work Item Roll-up

author Richard Fennell calendar Jun 12, 2020 · 4 min read · VSTS VSTS  ·
Share on: linkedin copy

Updated 30/Sep/21 to reflect changes in the Aggregator CLI setup process Updated 27/Mar/22 to fix broken links

Background

Back in the day I wrote a tool, TFS Alerts DSL, to do Work Item roll-up for TFS. Overtime I updated this to support VSTS (as Azure DevOps was then called), it’s final version is still available in the Azure DevOps Marketplace as the Azure DevOps Service Hooks DSL. So when I recently had a need for Work Item roll-up I did consider using my own tool, just for a short while. However, I quickly realised a much better option was to use the Aggregator CLI.

Aggregator CLI is a successor to the TFS Aggregator Plug-in and is a far more mature project than my tool and actively under development, allowing hosting as an Azure Function or a Docker container.

As I have found the Aggregator CLI a little hard to get started with, I thought this blog post was a good idea, so I don’t forget the details in the future.

Architecture

In this latest version of the Aggregator the functionality is delivered using Azure Functions, one per rule. Note: A docker container is an other option, but one I have not explored These Azure Functions are linked to Azure DevOps Service hook events. The command line tool setup process configures all of the parts required setting up Azure resources, Azure DevOps events and managing rules.

Preparation

  • Download the latest release from https://github.com/tfsaggregator/aggregator-cli/releases, pick the version for the operating system you are planning to use to setup the tool.
  • Next you need to setup an Azure Service Principle App registration for the Aggregator and connect it to a Subscription
    1. Login to Azure az login
    2. Pick the correct subscription az account set --subscription
    3. Create the service principle az ad sp create-for-rbac --name AggregatorServicePrincipal
    4. From the root of the Azure Portal pick the Subscription you wish to create the Azure Functions in.
    5. In the Access (IAM ) section grant the ‘contributor role’ for the subscription to the newly created Service Principle

Using the Aggregator CLI

At a command prompt we need to now start to use the tool to link up Azure Services and Azure DevOps

  • First we log the CLI tool into Azure. You can find the values required from Azure Portal, in the Subscription overview and App Registration overview. You create a password from ‘client and secrets’ section for the App Registration. .aggregator-cli.exe logon.azure -s -c -t -p

  • Next login to Azure DevOps, create the PAT as detailed in the documentation .aggregator-cli.exe logon.ado -u https://dev.azure.com/<org> -mode PAT -t

  • Now we can create the Instance of the Aggregator in  Azure Note: I had long delays and timeout problems here due to what turned out to be a  poor WIFI links. The strange thing was it was not obviously failing WIFI, but just unstable enough to cause issues. As soon as I swapped to Ethernet the problems went away. The basic form of the install command is as follows, this will create a new resource group in Azure and then the required Web App, Storage, Application Insights etc. As this is  done using an ARM template so it is idempotent i.e. it can re run as many times as you wish, it will just update the Azure services if they already exist. .aggregator-cli.exe install.instance -verbose -n yourinstancename -l westeurope If you do get problems, goto the Azure Portal, find th reosurce group and look at the deployment logs

  • When this completes, you can see the new resources in the Azure Portal, or check them with command line .aggregator-cli.exe list.instances

  • You next need to register your rules. You can register as many as you wish. A few samples are provided in the test folder in the downloaded ZIP, these are good for a quick tests, thought you will usually create your own for production use. When you add a rule, behind the scenes this creates an Azure Function with the same name as the rule. .aggregator-cli.exe add.rule -v -i yourinstancename -n test1 -file testtest1.rule

  • Finally you map a rule to some event in Azure DevOps instance .aggregator-cli.exe map.rule -v -p yourproject -e workitem.updated -i yourinstancename -r test1

Once all this done you should have a working system. If you are using the the test rules the quickest option to see it is working is to

  1. Go into the Azure Portal
  2. Find the created Resource Group
  3. Pick the App Service for the Azure Functions
  4. Pick the Function for the rule under test
  5. Pick the Monitor
  6. Pick Logs
  7. Open Live Metric
  8. You should see log entries when you perform the event on a work item you mapped to the function.

An alternative is to look in the AppInsights Logs or live telemetry. So I hope this helps my future self remember how get this tool setup quickly