Confluence
Integracja z Confluence pozwala Q247 zmierzyć wysiłek wkładany w dokumentację. Strony i komentarze analizowane są tak samo jak kod i tickety, a ich wynik kaloryczny doliczany jest do dorobku autora. Confluence pojawia się też jako typ źródła na liście Źródeł, identyfikowany przez klucz przestrzeni, a nie klucz projektu jak w Jirze.
Ta integracja nie zasila Metryk przepływu. Te wymagają Jiry, bo liczone są z historii statusów ticketów.
Droga danych do Q247
Tak jak w Jirze, dane o stronach i komentarzach trafiają do Q247 jedną z dwóch dróg, zależnie od wybranego sposobu pobierania. W trybie webhook zdarzenia wysyła Confluence, a miejsce ich odbiornika zależy od wariantu wdrożenia, opisanego w podsekcji niżej. W trybie API wtyczka sama cyklicznie odpytuje REST API Confluence. W obu przypadkach treść analizowana jest lokalnie, a do Q247 idzie wynik.
W trybie webhook integracja nie dostarcza bieżącej aktywności, dopóki webhook nie działa. Wtyczka reaguje wtedy na trzy zdarzenia:
| Zdarzenie | Co obejmuje |
|---|---|
page_created | utworzenie strony |
page_updated | aktualizację strony |
comment_created | dodanie komentarza |
Chmura i On-Premise
Podział jest taki sam jak przy Jirze i z tego samego powodu. W trybie webhook wariant Chmura kieruje zdarzenia do odbiornika po stronie Q247, wariant On-Premise do wtyczki pod adresem podanym w formularzu. W formularzach Q247 warianty nazywają się "Confluence Chmura" i "Confluence On-Premise", a Atlassian nazywa je Confluence Cloud i Confluence Data Center.
Dane dostępne po uruchomieniu
- Wynik kaloryczny stron i komentarzy, doliczany do dorobku autora obok kodu i ticketów.
- Źródło typu Confluence na liście Źródeł, przypisywalne do projektu Q247 przez klucz przestrzeni.
- Widoczność wkładu osób zajmujących się dokumentacją, bez commitów w repozytoriach. Bez tej integracji ich praca nie pojawia się w metrykach Q247.
Wymagania wstępne
- Konto serwisowe w Confluence z prawem odczytu przestrzeni objętych integracją.
- Token API wygenerowany na tym koncie. W Atlassian Cloud to ten sam token, który obsługuje Jirę, więc jeśli konektor Jiry już działa, wystarczy użyć go ponownie. Ścieżki generowania opisuje strona Jiry.
- Dostęp administratora Confluence, tylko w trybie webhook, jednorazowo: do instalacji aplikacji Q247 (Chmura) albo rejestracji webhooka (On-Premise).
- Aplikacja Q247 w witrynie Atlassian, tylko dla wariantu Chmura w trybie webhook. Jeśli została zainstalowana przy okazji Jiry, drugi raz nie trzeba jej instalować, bo jeden link instalacyjny obejmuje oba produkty. Z organizacją w Q247 łączy się ją w Confluence osobno, w kroku 2a.
- Wtyczka Q247 z włączoną obsługą Confluence, konfigurowana przez zespół wdrożeniowy Q247, patrz Instalacja Enterprise Plugin.
Wymagania sieciowe pokrywają się z tymi opisanymi dla Jiry: ruch wychodzący od wtyczki do Confluence i do Q247, a w wariancie On-Premise w trybie webhook dodatkowo ruch z instancji Confluence do wtyczki.
W instancji musi być włączone Administration → General Configuration → User List → Show user email addresses to all users. Gdy ta opcja jest wyłączona, wtyczka może nie odczytać adresu autora i podstawia wtedy adres zastępczy. Integracja działa pozornie poprawnie: strony są przetwarzane, status konektora pokazuje Operacyjny, a wkład przypisuje się do nieistniejących osób. Żaden komunikat w interfejsie Q247 o tym nie ostrzega.
Sposób pobierania danych
Konektor Confluence pobiera dane na jeden z dwóch sposobów. Wybór stoi w formularzu konektora, w grupie opcji "Sposób pobierania danych", z dwiema pozycjami:
| Pozycja | Jak działa |
|---|---|
| Webhook - Confluence wysyła zdarzenia do plugina | Confluence sam wysyła zdarzenia: w wariancie On-Premise webhookiem zarejestrowanym w instancji, do wtyczki, a w wariancie Chmura przez aplikację Q247 dla Atlassian, do odbiornika po stronie Q247 |
| Odpytywanie API - plugin cyklicznie czyta Confluence | Enterprise Plugin sam czyta historię stron i komentarze przez REST API Confluence, według harmonogramu |
Tryb API działa z Confluence Cloud i Confluence Data Center i wymaga Enterprise Plugin w wersji q247-enterprise-plugin-linux-v2.6.0 lub nowszej. W starszej wtyczce to ustawienie nie działa.
Przesłanki wyboru trybu API
Odpytywanie API nie wymaga żadnego połączenia przychodzącego do wtyczki. Odpada rejestracja webhooka po stronie Confluence i wymaganie, żeby instancja widziała adres wtyczki. Przy tym trybie kroki 2a i 2b poniżej są zbędne.
Ustawienia trybu API
Górna ramka na zrzucie obejmuje ustawienia trybu API, a dolna obejmuje blok "Backfill historyczny", opisany w sekcji Uzupełnianie danych historycznych.
| Pole | Co robi |
|---|---|
| Częstotliwość skanowania | Codziennie (w nocy) albo Co godzinę. Tryb dzienny działa w nocy, według czasu hosta wtyczki, i nie obciąża Confluence w godzinach pracy. Tryb godzinowy daje świeższe dane kosztem cogodzinnego ruchu API do Confluence. Pole jest widoczne tylko w trybie API |
| Przestrzenie | klucze przestrzeni Confluence do odpytywania, oddzielone przecinkami, na przykład ENG, DOCS. Puste pole, z podpowiedzią Wszystkie przestrzenie, oznacza wszystkie przestrzenie, które konto konektora może odczytać |
Zapis listy przestrzeni zastępuje poprzednią listę w całości.
Pole "Przestrzenie" wyznacza, które przestrzenie wtyczka odpytuje i uzupełnia. Do którego projektu Q247 należy dana przestrzeń, ustala się osobno, przy przypisaniu źródła do projektu.
O tym, co jest liczone, decyduje konto konektora: strony i komentarze, których to konto nie może odczytać, nie są liczone. Do trybu API użyj konta serwisowego z prawem odczytu wszystkich przestrzeni, które mają być liczone.
Każdy komentarz jest pobierany i liczony jeden raz, z datą dodania. Późniejsza edycja komentarza nie jest liczona ponownie. Treść wpisów blogowych nie wchodzi do wyliczeń.
Tryb API korzysta z tych samych danych dostępowych co webhook, opisanych w kroku 1. W wariancie On-Premise osobisty token dostępu wpisany w pole "Token API / hasło" wystarcza sam, a hasło podaje się razem z polem "Nazwa użytkownika API".
Formularz nie pozwoli zapisać konektora bez adresu instancji albo bez tokenu. Komunikat wskazuje brakujące pole: w wariancie On-Premise Proszę podać: Confluence Podstawowy URL albo Proszę podać: Token API / hasło, w wariancie Chmura Proszę podać: Adres URL witryny Atlassian albo Proszę podać: Token API.
Przejście z webhooków na tryb API
Przy przełączeniu aktywność z ostatnich 24 godzin jest uzgadniana z tym, co dostarczyły już webhooki.
Po zapisaniu zmiany usuń webhook w instancji Confluence (On-Premise) albo, jeśli była używana, aplikację Q247 z listy aplikacji Confluence (Chmura), czyli wpis skonfigurowany w kroku 2a. Wtyczka przyjmuje i odrzuca webhooki nadal dostarczane dla tego konektora, więc te zdarzenia nie są liczone drugi raz, ale sam webhook zostaje niepotrzebnie aktywny.
Diagnostyka trybu API
Osobnego ekranu dla tego trybu nie ma. Kolumna Ostatnie skanowanie w tabeli Źródeł pokazuje dla źródeł Confluence N/D w każdym trybie, a karta konektora w Konfiguracji pokazuje tylko, czy konektor jest włączony: Operacyjny albo Nie działa. Żadne z tych miejsc nie sygnalizuje błędów odpytywania.
Przestrzeń z listy, której konto konektora nie może odczytać albo która nie istnieje, jest pomijana i odnotowywana w logu wtyczki, a pozostałe przestrzenie są pobierane normalnie. Gdy nie da się odczytać żadnej z podanych przestrzeni, przebieg kończy się błędem. Przy braku danych z części przestrzeni sprawdź najpierw klucze na liście i uprawnienia konta konektora.
Uzupełnianie danych historycznych
Q247 może uzupełnić dane z okresu sprzed uruchomienia integracji z Confluence. Enterprise Plugin pobiera przez API historię wersji stron i komentarze, które zasilają Kalorie w typie Dokumentacja.
Ustawienia uzupełniania
Uzupełnianie ustawia się w bloku "Backfill historyczny" formularza konektora, widocznym w dolnej ramce zrzutu.
Blok ma dwa pola:
| Pole | Co robi |
|---|---|
| Backfill włączony | przełącznik uzupełniania, domyślnie wyłączony. Po włączeniu historyczna aktywność z okna jest jednorazowo wczytywana i dopisywana do minionych okresów w Kaloriach. Przy wyłączonym przełączniku konektor zbiera od teraz tylko nową aktywność |
| Okno backfillu (dni) | liczba dni wstecz, którą obejmuje uzupełnianie, całkowita od 1 do 7300. Pole podpowiada 730 dni, czyli dwa lata, i jest nieaktywne, dopóki przełącznik jest wyłączony |
Uzupełnienie obejmuje wersje stron zmienione w oknie, także na stronach utworzonych wcześniej, oraz komentarze dodane w oknie. Wersje wpisów blogowych nie są uzupełniane.
Zakres przestrzeni wyznacza ta sama lista co w trybie API: pole "Przestrzenie", a przy pustym polu wszystkie przestrzenie, które konto konektora może odczytać. Strony, do których konto nie ma dostępu, nie są liczone.
Uzupełnianie działa w obu sposobach pobierania danych. Przebieg odbywa się w nocy, według czasu hosta wtyczki. Późniejsze zwiększenie okna uruchamia jednorazowy przebieg tylko dla dodanego zakresu. Zmniejszenie okna albo wyłączenie przełącznika nie usuwa danych, które już zostały uzupełnione.
Poza ustawieniem okna potrzebne są jeszcze dwie rzeczy: funkcja musi być udostępniona organizacji, a Enterprise Plugin musi być w wersji q247-enterprise-plugin-linux-v2.6.3 lub nowszej.
Uzupełnione dane w Kaloriach
Uzupełnione wersje stron i komentarze trafiają do Kalorii z datą powstania, więc zasilają okresy sprzed uruchomienia integracji. Ani kolumna Ostatnie skanowanie, ani status konektora nie pokazują przebiegów uzupełniania, podobnie jak w trybie API. Przestrzeń z listy, której konto konektora nie może odczytać, jest pomijana na tej samej zasadzie co w trybie API.
Próg "Ukryj przyrosty powyżej" obejmuje wszystkie dane z Confluence, w tym uzupełnione.
Uruchomienie krok po kroku
1. Utworzenie konektora w Q247
W Konfiguracji, w sekcji Dokumentacja, przy pozycji Confluence, przycisk "+" przy liście Konektory otwiera dwustopniowy formularz. W tym samym formularzu wybiera się sposób pobierania danych.
Wariant Chmura wymaga adresu witryny oraz danych dostępowych:
| Pole | Co robi | Przykład |
|---|---|---|
| Nazwa konektora | własna nazwa do rozpoznania na liście | Confluence firmowy |
| Adres URL witryny Atlassian | podstawowy adres witryny w Atlassian Cloud | https://firma.atlassian.net |
| Token API | poświadczenie konta serwisowego, ten sam co dla Jiry | ATATT3xFfGF0... albo $$ATLASSIAN_TOKEN |
| Email konta | adres konta, na którym wygenerowano token | q247-service@firma.pl albo $$ATLASSIAN_USER |
Oba pola danych dostępowych przyjmują nazwę zmiennej środowiskowej z przedrostkiem $$ zamiast samej wartości, tak jak w Jirze. Jeśli konektor Jiry już z tego korzysta, tutaj można wskazać te same zmienne, bo token w Atlassian Cloud jest wspólny dla obu produktów.
Wariant On-Premise zamiast adresu witryny prosi o wersję instancji i dwa adresy:
| Pole | Co robi | Przykład |
|---|---|---|
| Confluence Wersja | wersja instancji, wybierana z listy | 8.5.6 |
| Confluence Podstawowy URL | adres instancji Confluence | https://wiki.firma.pl |
| Adres URL serwera wtyczki | adres, pod którym Confluence zobaczy wtyczkę | https://ep-plugin.firma.pl |
| Port serwera wtyczki | port, na którym wtyczka faktycznie nasłuchuje, zwykle port HTTPS | 8443 |
| Token API / hasło | poświadczenie konta serwisowego: osobisty token dostępu albo hasło podawane razem z nazwą użytkownika API | osobisty token dostępu konta serwisowego |
| Nazwa użytkownika API | login konta serwisowego, opcjonalny | zostaw pusty przy uwierzytelnianiu tokenem |
Wersję instancji sprawdzisz w Confluence: ikona zębatki, następnie Konfiguracja główna, a w niej Administrator → Informacje systemowe. Wyświetli się nazwa z numerem, na przykład "Confluence 8.5.6".
Pola adresu i portu serwera wtyczki pojawiają się tylko w trybie webhook. Adres URL serwera wtyczki działa tak samo jak w Jirze i podlega temu samemu zastrzeżeniu: służy wyłącznie do zbudowania adresu webhooka do skopiowania, a Q247 sam się pod ten adres nie łączy.
Kroki 2a i 2b dotyczą tylko trybu webhook. W trybie odpytywania API są zbędne i po zapisaniu formularza można przejść od razu do kroku 3.
2a. Wariant Chmura: połączenie aplikacji z organizacją
Drugi krok formularza pokazuje pole Klucz API EP Connect z przyciskiem "Skopiuj klucz".
Confluence ma na liście Manage apps własny wpis, niezależny od wpisu Jiry, i inaczej nazwane pole:
- W Confluence przejdź do listy zainstalowanych aplikacji i znajdź Q247.
- Wybierz Configure.
- Wklej klucz w pole Connect with your existing Q247 account.
Instalacja samej aplikacji, jeśli jeszcze jej nie ma, opisana jest na stronie Jiry. Ten sam link instalacyjny obsługuje oba produkty, a każdy z nich konfiguruje się osobno.
2b. Wariant On-Premise: webhook w instancji Confluence
Drugi krok formularza pokazuje pole URL webhooka EP z przyciskiem "Skopiuj URL". Adres zawiera losowy klucz Twojej organizacji, więc obchodź się z nim jak z hasłem.
Rejestracja po stronie Confluence:
- Ikona zębatki, następnie Konfiguracja główna.
- W lewym panelu Ustawienia → Elementy webhook.
- Przycisk Utwórz element webhook.
- Wypełnij Nazwę i wklej adres w pole URL.
- W sekcji Zdarzenia zaznacz utworzenie strony, aktualizację strony i utworzenie komentarza.
- Kliknij Testuj połączenie. To jedyne wbudowane sprawdzenie po stronie Atlassiana i warto z niego skorzystać, zanim zapiszesz.
- Kliknij Zapisz.
Kreator konektora On-Premise podaje w instrukcji nazwę drugiego produktu Atlassiana, przez co odsyła do instancji Jiry. Jest to ten sam błąd komunikatu, który opisuje strona Jiry.
3. Przypisanie źródła do projektu
W Źródłach przycisk "Dodaj źródła" pozwala dodać źródło typu Confluence, podając klucz przestrzeni i projekt Q247, do którego ma należeć. Alternatywnie robi się to z poziomu Projektu, przez "Przypisz źródło".
Jedna przestrzeń należy do jednego projektu Q247. Gdy dokumentacja jednego produktu jest rozproszona po kilku przestrzeniach, wpisz wszystkie ich klucze w jednym formularzu, rozdzielone przecinkami, na przykład SUPPORT, DOCS, PLATFORM.
Formularz przypisania i pozostałe typy źródeł opisuje zakładka Źródła w szczegółach projektu.
Weryfikacja i diagnostyka
Statusy konektora i kolejność sprawdzania przy braku danych są takie same jak dla Jiry, z dwiema różnicami. Sygnały właściwe dla trybu odpytywania API opisuje osobna podsekcja.
Pierwsza różnica dotyczy trybu webhook: przycisk testu połączenia w formularzu webhooka Confluence On-Premise od razu powie, czy instancja w ogóle dosięga wtyczki. To eliminuje część możliwych przyczyn, zanim zaczniesz szukać dalej.
Druga: gdy strony są przetwarzane, ale wkład nie pojawia się przy właściwych osobach, sprawdź opcję widoczności adresów e-mail opisaną w wymaganiach wstępnych. Ten objaw nie wygląda na problem z integracją, bo integracja formalnie działa.
Zakres przetwarzanych danych
Treść strony i jej historia zmian analizowane są lokalnie przez wtyczkę. Do Q247 trafiają wynik kaloryczny i metadane zdarzenia, między innymi identyfikator strony, klucz przestrzeni, adres URL, imię i nazwisko oraz adres e-mail autora, rodzaj zdarzenia (wersja strony albo komentarz), czas zdarzenia, lista zmienionych pól, liczbowe podsumowanie zmian oraz adres instancji Confluence podany w formularzu konektora.
Przy uzgadnianiu ostatnich 24 godzin po przejściu na tryb API i przy uzupełnianiu danych historycznych wtyczka przekazuje dodatkowo identyfikator konta autora w Confluence i jego aliasy. W wariancie On-Premise wśród aliasów może się znaleźć adres zastępczy opisany w wymaganiach wstępnych.
Q247 rozpoznaje powiązanie strony z ticketem, wyszukując jego identyfikator w treści strony, tytule i opisie wersji. Rozpoznany identyfikator jest przekazywany do Q247, więc fragment treści strony trafia do backendu, jeśli zawiera odwołanie do ticketu. Poza tym przypadkiem treść stron i komentarzy nie opuszcza infrastruktury, w której działa wtyczka.
Zakres wymiany danych z wtyczką opisuje szerzej Bezpieczeństwo Enterprise Plugin.
Zobacz też
- Jira: tokeny, ruch sieciowy i diagnostyka opisane szczegółowo
- Źródła: przypisanie przestrzeni do projektu Q247
- Instalacja Enterprise Plugin: włączenie dodatku Confluence
- Bezpieczeństwo Enterprise Plugin: zakres wymiany danych