Aggregator is a Rule Interpreter for Work Items events, allowing dynamic calculation of field values and more.
It is the successor to renowned TFS Aggregator. The current Server Plugin version (2.x) will be maintained to support TFS. The Web Service flavour will be discontinued in favour of this new tool for two reasons:
Aggregator 3.x supports two scenarios:
The latter permits replacing the Server Plugin after migrating the Rule code.
Note: This README is a synopsis of the documentation available at https://tfsaggregator.github.io/docs/v3/.
You might also find useful Richard Fennell's post Getting started with Aggregator CLI for Azure DevOps Work Item Roll-up.
To write a Rule is required some basic knowledge of C# language and Azure Boards. In addition you need:
The CLI scenario has two additional requirements:
The Docker scenario requires:
As the name implies, this is a command line tool: you download the latest aggregator-cli*.zip appropriate for your platform from GitHub releases and unzip it on your client machine. Read more below in the Usage section.
Through the CLI you create one or more Azure Functions in your Subscription. The Functions use a library named Aggregator Runtime to run your Rules. A Rule is code that reacts to one or more Azure DevOps event; currently, the only language for writing rules is C#.
The CLI automatically checks GitHub Releases to ensure that you use the more recent version of Aggregator Runtime available. To avoid automatic upgrades, specify the Runtime version or point to a specific Runtime package file, using an http:
or file:
URL.
After you setup the Rules in Azure, you must add at least one Mapping. A mapping is an Azure DevOps Service Hook that send a message to the Azure Function when a specific event occurs. Currently we support only Work Item events. When triggered, the Azure DevOps Service Hook invokes a single Aggregator Rule i.e. the Azure Function hosting the Rule code. Azure DevOps saves the Azure Function Key in the Service Hook configuration.
You can deploy the same Rule in different Instances, map the same Azure DevOps event to many Rules or map multiple events to the same Rule: you choose the best way to organize your code.
You must instruct Aggregator which credential to use.
To do this, run the login.azure
and login.ado
commands.
To create the credentials, you need an Azure Service Principal and a Azure DevOps Personal Access Token. Full details in the Setup section.
Aggregator stores the logon credentials locally and expires them after 2 hours.
The PAT is also stored in the Azure Function settings: whoever has access to the Resource Group can read it!
The Service Principal must have Contributor permission to the Azure Subscription or, in alternative, pre-create the Resource Group in Azure and give the service account Contributor permission to the Resource Group.
If you go this route, remember add the
--resourceGroup
to all commands requiring an instance.
For Docker only Azure DevOps logon is required.
Download and unzip the latest CLI.zip file from Releases.
It requires .Net Core 3.1 installed on the machine.
To run Aggregator run aggregator-cli.exe
(Windows), aggregator-cli
(Linux) or dotnet aggregator-cli.dll
followed by a verb and its options.
There are about 20 commands described in detail at Commands.
They can be grouped in a few categories:
Most commands manage Azure Function, but a few can be used in the Docker scenario.
We collected some usage scenarios at Command Examples.
Pull the latest image from Docker Hub. It works on Linux and Windows. Start a container with the image, setting configuration through environment variables. The Rules are simply files on a Docker volume that the container uses. The container must expose a port reachable from your Azure DevOps instance, either Server or Service. Add one or web hook to Azure DevOps using the container URL. Use one Aggregator API Key to authenticate the call. You may use the CLI to add these mappings.
More details at Docker configuration
Currently we offer only C# as the language to write Rules. The Rules can access a few objects:
See Rule Language for a list of objects and properties to use. For examples see Rule Examples.
Aggregator stores the PAT in the Azure Function configuration. Before the PAT expire you should refresh it from Azure DevOps or save a new PAT using the configure.instance
command.
Read Production Configuration and Administration for recommendations on running Aggregator in production.
Use the Application Insight instance that was created aside the Azure Function.
Details on building your own version and testing are in the Contribute section.