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

Mechanizm jest wspólny z Jirą: zdarzenia płyną webhookami z Confluence do Enterprise Plugin, treść analizowana jest lokalnie, do Q247 idzie wynik. Bez działającego webhooka integracja nie dostarcza niczego, bo nie istnieje zapasowy tryb okresowego skanowania przestrzeni.

Wtyczka reaguje na trzy zdarzenia:

Zdarzenie	Co obejmuje
page_created	utworzenie strony
page_updated	aktualizację strony
comment_created	dodanie komentarza

W wariancie On-Premise aktualizacja strony ma dodatkowy warunek: liczy się tylko wtedy, gdy powodem zmiany była faktyczna edycja treści. Przeniesienie strony między przestrzeniami albo zmiana uprawnień nie generuje w Q247 żadnego wpisu.

Chmura i On-Premise

Podział jest taki sam jak przy Jirze i z tego samego powodu. 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"; drugi z nich Atlassian nazywa 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, jednorazowo: do instalacji aplikacji Q247 (Chmura) albo rejestracji webhooka (On-Premise).
• Aplikacja Q247 w witrynie Atlassian, tylko dla wariantu Chmura. Jeśli została zainstalowana przy okazji Jiry, drugi raz nie trzeba jej instalować, bo jeden link obejmuje oba produkty.
• 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 dodatkowo ruch z instancji Confluence do wtyczki.

Adresy e-mail muszą być widoczne w Confluence On-Premise

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 nie odczyta adresu autora i podstawia adres zastępczy. Integracja działa wtedy pozornie poprawnie: strony są przetwarzane, status konektora pokazuje Operacyjny, a wkład przypisuje się do nieistniejących osób. Żaden komunikat o tym nie ostrzega.

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.

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
E-mail 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	tylko przy niestandardowym porcie nasłuchu	8443
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".

Pole adresu 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.

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:

1. W Confluence przejdź do listy zainstalowanych aplikacji i znajdź Q247.
2. Wybierz Configure.
3. 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:

1. Ikona zębatki, następnie Konfiguracja główna.
2. W lewym panelu Ustawienia → Elementy webhook.
3. Przycisk Utwórz element webhook.
4. Wypełnij Nazwę i wklej adres w pole URL.
5. W sekcji Zdarzenia zaznacz utworzenie strony, aktualizację strony i utworzenie komentarza.
6. Kliknij Testuj połączenie. To jedyne wbudowane sprawdzenie po stronie Atlassiana i warto z niego skorzystać, zanim zapiszesz.
7. 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.

Pierwsza: 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ą identyfikator strony, klucz przestrzeni, adres URL, autor i wynik kaloryczny.

Jedno zastrzeżenie do zakresu

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.

Pełną listę przechowywanych pól opisuje 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: pełny zakres wymiany danych