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

Updated 30/Sep/21 to reflect changes in the Aggregator CLI setup process

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. This is a successor to the TFS Aggregator Plug-in and is a far more mature project than my tool and actively under development, allow hosting as an Azure Function or a Docker container.

However, I have found the Aggregator CLI a little hard to get started with. The best ‘getting started’ documentation seems to be in the command examples, but I is not that easy to find. So 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 <ID>

    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 <sub-id> -c <client-id> -t <tenant-id> -p <pwd>
  • 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 <pat>
  • 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 test\test1.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