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 Read permission on the Project and Team and the Work Items groups as shown in the pictures below:
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 thr URL of your Azure DevOps organization instance. The URL https://dev.azure.com/pacemkr is an example of what can be entered in this field.
- Personal Access Token: Paste in this area the PAT explained previously in this tutorial
Step 2 - Selecting a project
Once you are connected, PaceMkr retrieves the projects, boards and queries from your Azure DevOps instance.
Click the drop down menu to choose the project in which your Kanban board is located
Step 3 - Selecting your Azure board
With your project selected, you now choose the Azure board from which you want to generate the metrics from. In the screen shot below, the board Issues is selected.
Step 4 - Selected your queries
Work items and Azure boards are not strongly linked in Azure DevOps. We need queries to retrieve the work items that are either flowing or have gone through your Azure board.
The Preparation section of this tutorial explained how to create those queries. Now, in this step, it is time to select them. The following screen sot shows the queries "Done query" and "WIP query" were selected.
These are the queries that PaceMkr will execute to fetch the work items used to calculate the various metrics of PaceMkr.
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.
Based on the number of work items, the speed of your network connection and the way your Azure DevOps instance is setup, this process can take from a few seconds to a few minutes.
During this process, PaceMkr displays the id of the work items it is fetching to inform you it is still working. Once PaceMkr is done, the button will be renamed "Done". Clicking it will close the wizard and the metrics will be shown.
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.
This instance of PaceMkr is hosted on a http server. Using this version of PaceMkr to connect to your OnPrem instance server on http. As PaceMkr is 100% run in your browser, there's no risk your data will go outside your private network.