Azure Wiki
The Azure Wiki integration lets Q247 measure the effort put into documentation kept in Azure DevOps. Pages are analyzed the same way as Confluence pages, and the calorie result is added to the author's total in the Documentation type.
Azure Wiki appears as a source type on the Sources list, identified by a page path prefix.
The "Azure DevOps" integration card is shared by Azure Boards and Azure Wiki. If one of these sources is already connected, the other is enabled by checking an additional box in the data scope, without re-entering credentials.
The data path to Q247
The Enterprise Plugin periodically polls the Azure DevOps REST API, reads wiki pages from the selected Team Projects, and analyzes them locally. Only the calorie result reaches Q247.
This integration works exclusively through polling, so it requires no inbound connection to the plugin and no webhook configuration on the Azure DevOps side.
Prerequisites
| Requirement | Details |
|---|---|
| Azure DevOps version | Azure DevOps Server 2022, on-premise installation |
| Token | a Personal Access Token with read-only permissions |
| Account access | the account the token was created on has to see every Team Project whose wiki is to be analyzed |
Required token scopes: Work Items (Read), Wiki (Read), Code (Read), Identity (Read), Project and Team (Read).
A token without this permission passes authentication, but the plugin cannot fetch the project list, so it fetches nothing at all. The plugin recognizes this case and reports the missing scope specifically.
Step-by-step setup
1. The integration card in Configuration
Manage Organization, Configuration tab, Documentation section, the Azure DevOps card.
| Field | What to enter |
|---|---|
| Connector Name | your own name for the connection, to recognize it on the list |
| Data scope | check Azure Wiki. Saving requires at least one scope; with none selected the message "Enable at least one of Azure Boards / Azure Wiki." appears |
| Instance URL | the HTTPS address of the Azure DevOps server, together with the IIS virtual directory if one is used (for example /tfs), without the collection name |
| Collection | the name of the Azure DevOps collection |
| Team Projects | the list of Team Projects to fetch. An empty field means every project visible to the token |
| REST API version | for Azure DevOps Server 2022 the correct version is 7.0. Use version 6.0 only for older servers |
| Scan frequency | daily at night, or hourly |
| Backfill window (days) | how far back the first run reaches. The default is 730 days, that is two years |
| Personal Access Token (PAT) | a token with the scopes listed above |
Leave the username field empty when authenticating with a token. Azure DevOps ignores that half of the login data anyway.
The token field also accepts the name of an environment variable with the $$ prefix, on the same principle as Connectors. The variable has to exist on the plugin host.
Subsequent runs fetch only increments.
2. Assigning the source to a project
Manage Organization, Sources tab, the add data source button. In the "Select a source name" field point at Azure Wiki, and in the Wiki page path prefixes field give the documentation areas whose work is to flow into this project.
A prefix is the name of a wiki, optionally with a page path, for example MyProject.wiki or MyProject.wiki/Design. You can give several prefixes at once.
A given prefix covers every page below it. Pages outside the indicated paths do not enter the project.
Azure DevOps lets you publish a directory from a code repository as a wiki. Such a wiki is not analyzed by this integration, because its content consists of repository files, already counted as commits.
Identity mapping
The author of a page is recognized exclusively by their real email address from Azure DevOps. Q247 does not create substitute addresses for accounts without an email, so the work of a person without an address will not be assigned to any participant.
Discrepancies between the address in Azure DevOps and the account in Q247 are resolved through merging accounts and aliases.
Where these Calories are visible
Calories from Azure Wiki enter the existing Documentation type, and through it the Total type. They never enter the Coding type.
They are therefore visible everywhere the Calories Type selector works: on charts, in participant tables and in the heatmap, with no new views. In the chart details, a single increment is described as Collaboration on wiki page {path}, with a clickable link to Azure DevOps.
Scope of processed data
| Item | State |
|---|---|
| Project wiki pages | analyzed |
| Wiki published from a code repository | skipped |
| Worklogs | out of scope for the first version |
| Azure DevOps Services (cloud version) | unsupported, the integration works only with an on-premise installation |
Deleting a page in Azure DevOps does not take back Calories credited earlier for work on it. Two parallel connections pointing at the same instance also do not duplicate the result.
See also
- Azure Boards: the second scope of the same integration card
- Azure DevOps: the code repository connector, a separate connection and a separate token scope
- Confluence: the other integration measuring documentation effort
- Calories Type: the split into Coding and Documentation