How to configure and use the Azure DevOps Connector
ℹ️ This feature is currently in our beta phase. This means we are testing it with our customers. The user experience may also not be ideal yet. If you are running into issues, please let us know at support@columinity.com
Columinity allows teams to collect flow metrics from Azure DevOps through, specifically cycle time, work-in-progress and throughput. This provides a useful additional source of data to include when analyzing overall team effectiveness. Process metrics are available under "Insights" in the Team Report, Teams Dashboard and Coaching Center.
- A "Professional"- or "Enterprise"-plan.
- A cloud-based instance of Azure DevOps, with an API endpoint accessible for us to query.
- A Personal Access Token (PAT) for Azure DevOps with "Read" scope for "Project and Team" and "Work Items". Adding more scopes is unnecessary and insecure. Read how to set up a PAT.
- A user account in Columinity with administrative permissions in at least 1 Teams Dashboard.
- Go to a Teams Dashboard. If you have multiple Teams Dashboard, you can repeat this process if you wish to import metrics from the same or another Azure DevOps instance into other Teams Dashboards.
- Click "My account".
- Click "Integrations".
- Click "New".
- For "Platform", choose "Azure DevOps".
- For "Platform URL", enter the URL of the Azure Dev Ops instance. This is typically https://dev.azure.com/[yourcompany], but it can be a custom domain. A url with https:// is required.
- For "Platform secret", enter the Personal Access Token (PAT) you created for Azure DevOps. For best security, please select only the "Read" scope for "Project and Team" and "Work Items". If you can't see "Project and Team", click "Show all scopes" at the bottom of the screen or ask someone with more permissions.
- For "Enabled", choose "Enabled", unless you wish to create an inactive integration first.
- Click "Save" to create the integration.
Once the integration is created, it will pull metrics from all teams in your Azure DevOps every few hours. A green checkmark will appear in front of the integration (see above) to indicate successful communication. If communication has not yet happened, or there was a failure, a yellow warning sign will appear. However, one final step is required to see flow metrics though, which is to map teams from Azure DevOps to teams in Columinity.
Although this integration pulls metrics from all teams in an Azure DevOps instance, it only stores those that have been mapped to teams in Columinity. This mapping has to be created manually for each team.
- In the "Integrations" page (see previous step), click the bullets behind the Azure DevOps integration you wish to map teams for.
- Click "Team mappings"
- If there are teams available that can be mapped, you have the option to add a new one. Otherwise you either have to create more teams in Columinity, or wait up to 24 hours for new teams from Azure DevOps to be imported into Columinity.
- Under "Remote source", select the remote team from Azure DevOps.
- Under "Team to map to", select the team in Columinity to map the remote team or board to.
- Under "Workflow state indicating 'To Do'", enter the name of the state, column or swim lane that indicates work items that are planned, but not yet started. This can also be states like 'Ready' or 'Backlog', as long as a work item leaving this state for any of the other states except 'Done' and excluded states indicates that this team starts actively working on it.
- Under "Workflow state indicating 'Done'", enter the name of the state, column or swim lane that indicates work items that are completed by this team. This can also be states like 'Completed' or 'Finished', as long as a work item entering this state indicates that this team has finished all work on it.
- Under "Workflow states indicating 'In Progress'", you can manually provide the names of states, columns or swim lanes that indicate that a work item should be considered in progress for this team. If left empty, Columinity will treat any state other than what is provided under 'To Do' and 'Done' as 'In Progress'. This is useful when there are certain pre-work states that should not be counted, or when there are strong reasons to exclude certain states.
Once you're done mapping teams, it can now take up to 24 hours for Columinity to retrieve flow metrics from Azure DevOps. A team report will show the most recent process metrics from at most 1 month back from the start date of the snapshot. This allows you to see changes over time in process metrics.
- The Personal Access Token (PAT) is stored in an encrypted form (with row-level salt) in a separate, isolated service. The token is removed when the integration is removed.
- Our integration queries work items from the past 28 days, and only uses their ID, start date and completion date. We calculate process metrics from this metadata, and only store the metrics themselves.
- No personal information is queried by our integration (i.e. creator, email addresses, etc).
- Personal Access Tokens (PAT) are valid for up to a year. You have to renew the PAT manually and update it in Columinity to ensure that the integration continues working.