This page explains how to prepare, connect and load your data into PaceMkr.
Preparation
Before you launch the Azure DevOps wizard in PaceMkr, you need to setup a few things in your instance.
Personal Access Token (PAT)
Your first step to prepare your access to Azure DevOps from PaceMkr is to create a Personal Access Token (PAT) in Azure DevOps. This PAT is used by PaceMkr as your identity when it access your Azure DevOps.
To create a PAT in Azure DevOps, follow this sequence of steps:
- Log in to your Azure DevOps instance.
- Click on the user settings icon in the top right corner of your window.
3. Click on the Personal Access Token menu item from the drop down list.
4. Click on the "New Token" button.
5. A menu on the right will display a configuration panel where you will create your PAT. Describe your PAT by entering the following information:
- Name: Give it ia recognizable name to easily find it as you manage the PATs of your users.
- Organization: From the drop down list, choose the organization you want to grant access too.
- Expiration: This tells the expiration date of your PAT. When trying PaceMkr, you can set it to 30 days. If you've become a registered user, you can add a longer period based on the security policies of your organization.
6. Assign permissions to your PAT
Your PAT must have the following permissions:
- Read permission on the Project and Team
- Read permission and the Work Items groups
- Read permission on the Analytics service
In case you do not see these groups, look for the Show All Scope link at the bottom of the panel.
7. Click the "Create" button. You will see your token appear for the first and only time. Make sure to copy and paste it to a secure location as it will be required each time you connect to Azure DevOps.
Finally, your PAT will appear in the list of PATs with its permissions. It is marked as active meanning it can be used to connect to your Azure DevOps instance.
Queries
The second part of preparing Azure DevOps is to create two queries. There are no strong relationship between a Azure board and a Azure work item. To retrieve work items flowing through your Azure board, we need to create two queries:
- WIP query: This query list the active work items currently in your board.
- Done query: This query list the completed work items who have gone through your board and are now finished.
DONE query
The simplest way of creating a query to extract completed item is to look for all the work items whose state is now at Done. The following screen shot from the query editor shows you how this can look:
If you want to filter out items, you can add additional conditions in this query so these work items are not processed by PaceMkr.
WIP query
In it's simplest form, the query to extract current work in process is the opposite of the Done Query. This means the State field will be different than Done as shown below:
Going through the wizard
The Azure DevOps wizard guides you through the necessary steps to extract your work items from the right Kanban board.
Step 1 - Authentication
The first step in the wizard is authenticating yourself to your Azure DevOps instance.
You do so with the following parameters:
- Azure DevOps Url: This is the URL of your Azure DevOps organization instance.
- Personal Access Token: Paste in this area the PAT explained previously in this tutorial
Step 2 - Select a team
Once you are connected, PaceMkr retrieves the teams of your Azure DevOps instance.
Click the drop-down menu to choose the team in which your Kanban board is located
Step 3 - Select your board
With your team selected, you now choose the board from which you want to generate the metrics from. In the screen shot below, the board Issues is selected.
Step 4 - Select the area path
A team is always assigned a default area path when it gets created. Based on your team organization, choose the area path which reflects the work items you want to retrieve.
Step 5 - Fetch the work items
In this final step, you press the "Fetch" button to launch the process of recovering the work items from your queries.
PaceMkr displays the columns of your board and offers a limit on the number of completed work items you want to fetch. For example, it might not be important to import more than 3 months of completed work items.
When you are ready, press the 'Fetch' button. It takes a few seconds to download your work items. Once the export is completed, the button is renamed 'Next' with a short text above informing you how many work items were downloaded.
Pressing the 'Next' button will generate the flow metrics for your board.
Troubleshooting
Cannot connect on step 1
Here are some things to check for when you cannot connect to Azure DevOps:
- Is your Personal Access Token (PAT) still valid in Azure DevOps?
OnPrem instance on http
If your OnPrem instance is running on a http server, you need a PaceMkr served on a http server. Browsers do not support a PaceMkr serverd on https to query a AzureDevOps on a http server.