Getting Started

ADO Backlog is a NodeJS command line tool, designed primarly to generate self-contained exports of backlogs hosted on an Azure DevOps instance.

In this guide, you will learn how to install the tool, configure it and execute it.

You can also find a separate Reference section, for more in-depth and thorough documentation of the various features offered by this tool.

Installation

This tool is available as an NPM package. To install it, you must have NodeJS installed.

npm install -g ado-backlog

Alternatively, if you do not have NPM/NodeJS installed on your machine, you can download a static binary directly from GitHub, by clicking here.

(Optional) Adding the Binary Command to Path

This section is only relevant if you have downloaded the tool binary manually (as opposed to installing it through NPM),

In those cases, it is recommended that you store it somewhere accessible by your PATH environment variable. This allows you to execute the command from any folder on your computer.

On a Windows machine, press Windows + R. On the newly opened dialog, type the following: cmd.exe, and then press Ctrl + Shift + Enter, to open the command line with elevated Administrator permissions.

On the command line window, enter the following line, replacing the string {{path}} with the full absolute path of the folder where the file ado-backlog.exe is located.

setx /M path "%path%;{{path}}"

DANGER

This action can be dangerous, and erase or corrupt the contents of your PATH variable, if you do not follow these instructions closely.

Usage

To get started working with this tool, we need to create a configuration file first. Configuration files are written in the KDL language. To do so, run the init command, which will create a baseline configuration file for us:

ado-backlog init

When executing this command, you will be prompted with a couple of questions to help you create the configuration file, such as the URL of your organization's Azure DevOps, as well as a token to allow the tool to authenticate and access the backlog.

┌  ado backlog
│
◇  Name of the file to store these configurations?
│  config.kdl_
│
◇  What is your organization's Azure DevOps URL?
│  https://dev.azure.com/{{username}}
│
◇  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                                                     │
│  To create a Personal Access Token, head over to https://dev.azure.com/{{username}}/_usersSettings/tokens and click "New Token".  │
│                                                                                                                                     │
│─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
│
◇  Personal Access Token
│  p1wy46imwhblkosg1s1ya7jirqy8xa5ysn9thx9uz1vmreg57duf
│
◇  File written
│
└  Configuration file created

Generating a Personal Access Token

TODO

In the folder where you executed this command, you should now have a file named config.kdl. Now that we have the configuration file, we can try to generate an export of the backlog.

ado-backlog download --config config.kdl

TIP

If your backlog is not structured in Epics, Features, User Stories and Bugs, the export may not be 100% successful. Regardless, do not worry, as that is just the default configuration, but you can easily change it to fit any backlog structure you have in your project.

Read the next pages for a quick summary of the most useful ways you can change the configurations to match your specific needs.