Azure Wiki
Integracja z Azure Wiki pozwala Q247 zmierzyć wysiłek wkładany w dokumentację prowadzoną w Azure DevOps. Strony analizowane są tak samo jak strony Confluence, a wynik kaloryczny doliczany jest do dorobku autora w typie Dokumentacja.
Azure Wiki pojawia się jako typ źródła na liście Źródeł, identyfikowany przez prefiks ścieżki strony.
Karta integracji "Azure DevOps" jest wspólna dla Azure Boards i Azure Wiki. Jeśli jedno z tych źródeł jest już podłączone, drugie włącza się zaznaczeniem dodatkowego pola w zakresie danych, bez ponownego podawania poświadczeń.
Droga danych do Q247
Enterprise Plugin cyklicznie odpytuje REST API Azure DevOps, czyta strony wiki z wybranych Team Projects i analizuje je lokalnie. Do Q247 trafia sam wynik kaloryczny.
Ta integracja pracuje wyłącznie przez odpytywanie, więc nie wymaga żadnego połączenia przychodzącego do wtyczki ani konfiguracji webhooków po stronie Azure DevOps.
Wymagania wstępne
| Wymaganie | Szczegóły |
|---|---|
| Wersja Azure DevOps | Azure DevOps Server 2022, instalacja lokalna |
| Token | Personal Access Token z uprawnieniami wyłącznie do odczytu |
| Dostęp konta | konto, na którym powstał token, musi widzieć wszystkie Team Projects, których wiki mają być analizowane |
Wymagane zakresy tokenu: Work Items (Read), Wiki (Read), Code (Read), Identity (Read), Project and Team (Read).
Token bez tego uprawnienia przechodzi uwierzytelnienie, ale wtyczka nie jest w stanie pobrać listy projektów, więc nie pobiera niczego. Wtyczka rozpoznaje ten przypadek i odnotowuje brak właśnie tego zakresu.
Uruchomienie krok po kroku
1. Karta integracji w Konfiguracji
Zarządzanie Organizacją, zakładka Konfiguracja, sekcja Documentation, karta Azure DevOps.
| Pole | Co wpisać |
|---|---|
| Nazwa konektora | własna nazwa połączenia, do rozpoznania go na liście |
| Zakres danych | zaznacz Azure Wiki. Zapis wymaga przynajmniej jednego zakresu, przy zerowym pojawia się komunikat "Włącz co najmniej jedno z Azure Boards / Azure Wiki." |
| Adres URL instancji | adres HTTPS serwera Azure DevOps, razem z katalogiem wirtualnym IIS, jeśli jest używany (na przykład /tfs), bez nazwy kolekcji |
| Kolekcja | nazwa kolekcji Azure DevOps |
| Projekty (Team Projects) | lista Team Projects do pobierania. Puste pole oznacza wszystkie projekty widoczne dla tokenu |
| Wersja REST API | dla Azure DevOps Server 2022 właściwa jest wersja 7.0. Wersji 6.0 używaj tylko przy starszych serwerach |
| Częstotliwość skanowania | codziennie w nocy albo co godzinę |
| Okno pobierania wstecz (dni) | jak daleko wstecz sięga pierwsze uruchomienie. Domyślnie 730 dni, czyli dwa lata |
| Personal Access Token (PAT) | token z zakresami wymienionymi wyżej |
Pole nazwy użytkownika zostaw puste, gdy uwierzytelniasz się tokenem. Azure DevOps i tak pomija tę połowę danych logowania.
Pole tokenu przyjmuje też nazwę zmiennej środowiskowej z przedrostkiem $$, na tej samej zasadzie co Konektory. Zmienna musi istnieć na hoście wtyczki.
Kolejne przebiegi pobierają już tylko przyrosty.
2. Przypisanie źródła do projektu
Zarządzanie Organizacją, zakładka Źródła, przycisk dodawania źródła danych. W polu "Wybierz nazwę źródła" wskaż Azure Wiki, a w polu Prefiksy wiki i ścieżki stron podaj obszary dokumentacji, z których praca ma trafiać do tego projektu.
Prefiks to nazwa wiki, opcjonalnie ze ścieżką strony, na przykład MójProjekt.wiki albo MójProjekt.wiki/Projektowanie. Można podać kilka prefiksów naraz.
Podany prefiks obejmuje wszystkie strony poniżej niego. Strony spoza wskazanych ścieżek do projektu nie wchodzą.
Azure DevOps pozwala opublikować jako wiki katalog z repozytorium kodu. Taka wiki nie jest analizowana przez tę integrację, bo jej treść to pliki repozytorium, liczone już jako commity.
Mapowanie tożsamości
Autor strony rozpoznawany jest wyłącznie po realnym adresie e-mail z Azure DevOps. Q247 nie tworzy zastępczych adresów dla kont bez e-maila, więc praca osoby bez adresu nie zostanie przypisana do żadnego uczestnika.
Rozbieżności między adresem w Azure DevOps a kontem w Q247 rozwiązuje się przez scalanie kont i aliasy.
Miejsca, w których widać te Kalorie
Kalorie z Azure Wiki wchodzą do istniejącego typu Dokumentacja, a przez niego do typu Łącznie. Do typu Kodowanie nie wchodzą nigdy.
Widać je więc wszędzie tam, gdzie działa selektor typu kalorii: na wykresach, w tabelach uczestników i w heatmapie, bez żadnych nowych widoków. W szczegółach wykresu pojedynczy przyrost opisany jest jako Współpraca na stronie wiki {path}, z klikalnym odnośnikiem prowadzącym do Azure DevOps.
Zakres przetwarzanych danych
| Rzecz | Stan |
|---|---|
| Strony wiki projektowej | analizowane |
| Wiki publikowana z repozytorium kodu | pomijana |
| Worklogi | poza zakresem pierwszej wersji |
| Azure DevOps Services (wersja chmurowa) | nieobsługiwane, integracja działa tylko z instalacją lokalną |
Usunięcie strony w Azure DevOps nie odbiera Kalorii naliczonych wcześniej za pracę nad nią. Dwa równoległe połączenia wskazujące tę samą instancję również nie zdublują wyniku.
Zobacz też
- Azure Boards: drugi zakres tej samej karty integracji
- Azure DevOps: konektor repozytoriów kodu, osobne połączenie i osobny zakres tokenu
- Confluence: druga integracja mierząca wysiłek dokumentacyjny
- Typ kalorii: podział na Kodowanie i Dokumentację