Jira

Integracja z Jirą daje Q247 dostęp do historii zmian statusów ticketów. Z tego wyliczane są Metryki przepływu, czyli Czas realizacji, Czas cyklu i rozkład przepływu. Dodatkowo Jira pojawia się jako typ źródła na liście Źródeł, przypisywany do projektu Q247 przez klucz projektu Jira.

Bez tej integracji cała grupa Metryk przepływu pozostaje niedostępna, bo Q247 nie ma skąd wziąć momentów przejścia ticketu między statusami.

Droga danych do Q247

Dane o ticketach trafiają do Q247 zdarzeniowo, webhookami z Jiry do Enterprise Plugin. Nie ma trybu okresowego odpytywania jako metody zapasowej: dopóki webhooki nie działają, integracja nie dostarcza żadnych danych o ticketach.

Wtyczka przepuszcza dokładnie trzy zdarzenia i odrzuca wszystkie pozostałe:

Zdarzenie	Co obejmuje
jira:issue_created	utworzenie ticketu
jira:issue_updated	zmianę ticketu, w tym dodanie komentarza
jira:issue_deleted	usunięcie ticketu

Ze zmian zapisywane są tylko te dotyczące statusu i osoby przypisanej. Edycja opisu albo pola własnego nie tworzy w Q247 żadnego wpisu w historii.

Metryki przepływu potrzebują też dostępu do API Jiry

Granice Czasu realizacji i Czasu cyklu rozstrzygane są przez odpytanie API Jiry o listę statusów i ich kategorie. Konektor z poprawnym webhookiem, ale nieprawidłowym tokenem, przyjmie zdarzenia i mimo to policzy metryki źle, bo zamiast kategorii statusów dopasuje granice po nazwach statusów zamiast po ich kategoriach.

Chmura i On-Premise

Oba warianty dostarczają dane tym samym mechanizmem i tą samą trasą webhooka. Różnią się dwiema rzeczami: gdzie stoi odbiornik zdarzeń oraz co trzeba zrobić po stronie Atlassiana.

Wariant	Odbiornik webhooków	Czynność po stronie Atlassiana
Jira Chmura	adres po stronie Q247, Klient go nie podaje	instalacja aplikacji Q247 w witrynie Atlassian i wklejenie w niej klucza API
Jira On-Premise	wtyczka Klienta, pod adresem podanym w formularzu	ręczna rejestracja webhooka w instancji Jiry

W formularzach Q247 warianty nazywają się "Jira Chmura" i "Jira On-Premise". Wariant On-Premise dotyczy instancji, którą Atlassian nazywa Jira Data Center.

Dane dostępne po uruchomieniu

Po uruchomieniu integracji pojawiają się:

• Metryki przepływu na dashboardzie projektu: Czas realizacji, Czas cyklu, rozkład przepływu na Funkcje i Błędy.
• Źródło typu Jira na liście Źródeł, przypisywalne do projektu Q247 przez klucz projektu.
• Wynik kaloryczny ticketów, liczony lokalnie przez wtyczkę z treści ticketu.
• Worklogi w widoku uczestnika, jeśli włączona jest integracja z Tempo.

Dane narastają od momentu uruchomienia

Integracja opiera się na webhookach, więc Q247 dostaje zdarzenia dopiero od chwili, w której webhook zaczyna działać. Metryki liczone są przyrostowo: rosną razem z liczbą zebranych zdarzeń, a nie pojawiają się od razu w pełnej postaci.

Ma to praktyczne skutki przez pierwsze tygodnie. Czas realizacji i Czas cyklu liczone są z ticketów, które w całości przeszły przez proces przy działającej integracji, więc tickety otwarte przed jej uruchomieniem nie wejdą do wyliczeń. Wiarygodny obraz przepływu pojawia się po jednym pełnym cyklu pracy zespołu, zwykle po dwóch, trzech sprintach.

Uzupełnienie historii sprzed uruchomienia integracji (backfill) planowane jest w wydaniu 6.2.3.

Wymagania wstępne

Przed wejściem do formularza konektora trzeba mieć przygotowane:

• Konto serwisowe w Jirze z uprawnieniem przeglądania projektów (Browse Projects) na wszystkich projektach objętych integracją. Bez niego wtyczka nie odczyta ticketów ani ich historii.
• Token API wygenerowany na tym koncie. Ścieżki różnią się między wariantami, patrz Tokeny API niżej.
• Dostęp administratora Jiry, jednorazowo i niekoniecznie tej samej osoby: do zainstalowania aplikacji Q247 (Chmura) albo zarejestrowania webhooka (On-Premise).
• Aplikacja Q247 zainstalowana w witrynie Atlassian, wyłącznie dla wariantu Chmura. Link instalacyjny dostarcza administrator Execon, aplikacja nie jest publiczna w Atlassian Marketplace.
• Wtyczka Q247 działająca i widoczna w Konfiguracji, do której konektor zostanie przypisany, z włączoną obsługą Jiry. Konfiguruje ją zespół wdrożeniowy Q247, patrz Instalacja Enterprise Plugin.

Ruch sieciowy

Komunikacja z Jirą jest dwukierunkowa: wtyczka odpytuje API Jiry o tickety, statusy i worklogi, a Jira w drugą stronę wysyła webhooki do odbiornika zdarzeń. Wariant wdrożenia decyduje o tym, gdzie ten odbiornik stoi, a więc czy ruch przychodzący dotyczy sieci Klienta.

Połączenie	Kierunek	Wymagane
Wtyczka → Jira (odczyt ticketów, statusów, worklogów)	wychodzące od Klienta	tak
Wtyczka → Q247 (wysyłka wyników)	wychodzące od Klienta	tak
Jira Chmura → odbiornik Q247 (webhooki)	z Atlassiana do Q247	tak
Jira On-Premise → wtyczka Klienta (webhooki)	przychodzące do sieci Klienta	tak, w tym wariancie

W wariancie Chmura webhooki trafiają pod adres po stronie Q247, więc Klient nie otwiera u siebie żadnego portu i nie prowadzi listy dozwolonych adresów po stronie Atlassiana. W wariancie On-Premise instancja Jiry musi dosięgnąć wtyczki: domyślny port nasłuchu dodatku to 60001 dla HTTP i 443 dla HTTPS.

Tokeny API

Wariant	Ścieżka wygenerowania tokenu
Atlassian Cloud	avatar konta → Account Settings → Security → Create and manage API tokens → Create API token. Nadaj nazwę i ustaw datę wygaśnięcia.
Jira Data Center	avatar konta → Profil → Osobiste tokeny dostępu → Utwórz token. Nadaj nazwę i odznacz automatyczne wygaśnięcie.
Tempo (Chmura)	Apps → Tempo → Settings → API Integration → New token.

Pełne, aktualne ścieżki opisuje dokumentacja Atlassiana; tutaj podajemy je skrótowo, bo Atlassian zmienia swoje UI niezależnie od nas.

Jeden token na dwa produkty

Token wygenerowany w Atlassian Cloud obsługuje jednocześnie Jirę i Confluence. Jeśli konfigurujesz obie integracje, wygeneruj go raz i użyj w obu konektorach.

Poświadczenia ze zmiennych środowiskowych

Zamiast wpisywać poświadczenia wprost, można w polu podać nazwę zmiennej środowiskowej z przedrostkiem $$. Wtyczka odczytuje ją ze swojego środowiska w momencie łączenia się z Jirą, a w bazie Q247 zapisana jest tylko nazwa zmiennej.

Obsługiwane są oba pola danych dostępowych, i to niezależnie od siebie:

Pole formularza	Wartość w formularzu	Zmienna na hoście wtyczki
E-mail konta (Chmura) albo Nazwa użytkownika API (On-Premise)	$$JIRA_USER	JIRA_USER=q247-service@firma.pl
Token API	$$JIRA_TOKEN	JIRA_TOKEN=ATATT3xFfGF0...
Token API Tempo	$$TEMPO_TOKEN	TEMPO_TOKEN=...

Sekcja danych dostępowych Tempo korzysta z tego samego mechanizmu, więc token Tempo także da się trzymać poza panelem.

Pełny opis składni, skutków dla bezpieczeństwa i typowego błędu z nieustawioną zmienną znajdziesz w Konektorach. Przedrostek to dokładnie dwa znaki dolara, zmienna musi istnieć na hoście wtyczki, a jej brak ujawnia się dopiero jako nieudane uwierzytelnienie przy pierwszym połączeniu, bez błędu na etapie zapisu.

Uruchomienie krok po kroku

1. Utworzenie konektora w Q247

W Konfiguracji, w sekcji Dokumentacja, przy pozycji Jira, przycisk "+" przy liście Konektory otwiera dwustopniowy formularz. Pierwszy krok to dane połączenia.

Pola wspólne dla obu wariantów:

Pole	Co robi	Przykład
Nazwa konektora	własna nazwa do rozpoznania na liście	Jira produkcyjna
Dane główne	przełącznik Aktywny/Nieaktywny dla całej integracji	Aktywny
Token API	poświadczenie konta serwisowego	ATATT3xFfGF0... albo $$JIRA_TOKEN
E-mail konta	adres konta, na którym wygenerowano token	q247-service@firma.pl

Pola tylko dla wariantu Chmura:

Pole	Co robi	Przykład
Adres URL witryny Atlassian	podstawowy adres witryny w Atlassian Cloud	https://firma.atlassian.net
Tempo	checkbox odsłaniający pola danych dostępowych Tempo	zaznaczony, gdy organizacja używa Tempo

Pola tylko dla wariantu On-Premise:

Pole	Co robi	Przykład
Jira Wersja	wersja instancji, wybierana z listy	9.15.2
Jira Podstawowy URL	adres instancji Jiry	https://jira.firma.pl
Adres URL serwera wtyczki	adres, pod którym Jira zobaczy wtyczkę	https://ep-plugin.firma.pl
Port serwera wtyczki	tylko gdy wtyczka nasłuchuje na niestandardowym porcie	8443
Adres URL instancji Tempo	osobny adres Tempo, jeśli różni się od adresu Jiry	https://jira.firma.pl/rest/tempo-timesheets
Nazwa użytkownika API	login konta serwisowego, opcjonalny	zostaw pusty przy uwierzytelnianiu tokenem

Wersję instancji sprawdzisz w Jirze: ikona zębatki, następnie Aplikacje. Wyświetli się nazwa z numerem, na przykład "Jira Software 9.15.2".

Właściwe przeznaczenie adresu serwera wtyczki

To pole służy wyłącznie do zbudowania adresu webhooka, który skopiujesz i wkleisz w Jirze. Q247 nigdy się pod ten adres nie łączy, więc nie musi on być dostępny z internetu. Wystarczy, że dosięgnie go instancja Jiry. Wartość zależy od modelu wdrożenia: przy wtyczce we własnej infrastrukturze to jej adres wewnętrzny, przy wtyczce hostowanej przez Q247 adres wskazuje domenę Q247.

Przycisk "Zapisz konektor" zamyka pierwszy krok i odsłania drugi.

2a. Wariant Chmura: aplikacja Q247 w witrynie Atlassian

Drugi krok formularza pokazuje pole Klucz API EP Connect z przyciskiem "Skopiuj klucz". Ten klucz łączy aplikację zainstalowaną w witrynie Atlassian z Twoją organizacją w Q247.

Po stronie Atlassiana, jeśli aplikacja nie jest jeszcze zainstalowana:

1. Otwórz link instalacyjny otrzymany od administratora Execon i kliknij Get app.
2. W polu wyboru witryny wskaż instancję, w której ma działać integracja, i kliknij Install. Jeden link obejmuje Jirę i Confluence.

Następnie połącz aplikację z organizacją:

1. W Jirze przejdź do Apps → (…) → Manage apps → Take me there.
2. Znajdź aplikację Q247 i wybierz (…) → Configure.
3. W polu Q247 Cloud API Key wklej skopiowany klucz i zatwierdź przyciskiem Proceed.

Komunikat w formularzu podaje nieaktualną ścieżkę

Drugi krok formularza odsyła do "Ustawienia → Połączone aplikacje". Taka ścieżka nie istnieje w obecnym UI Jiry. Obowiązuje ta z listy wyżej, przez Manage apps.

2b. Wariant On-Premise: webhook w instancji Jiry

Drugi krok formularza pokazuje pole URL webhooka EP z przyciskiem "Skopiuj URL". Ten adres zawiera w sobie losowy klucz przypisany do Twojej organizacji, więc traktuj go jak sekret.

Rejestracja po stronie Jiry:

1. Ikona zębatki, następnie Systemowy.
2. W lewym panelu Zaawansowane → WebHooki.
3. Przycisk Utwórz WebHook.
4. Wypełnij pola: Imię (dowolna nazwa opisowa), Status (zostaw Włączone), Adres URL (wklejony adres z Q247).
5. W sekcji Zdarzenia zaznacz utworzenie, aktualizację i usunięcie zgłoszenia. Pozostałe zdarzenia wtyczka odrzuci, więc ich zaznaczanie tylko zwiększa ruch.
6. Kliknij Utwórz.

Kreator wskazuje niewłaściwy produkt

Drugi krok formularza konektora Jira On-Premise każe przejść do instancji Confluence Data Center, a kreator Confluence odsyła symetrycznie do Jiry. Webhook rejestruje się w tym produkcie, którego konektor konfigurujesz.

3. Przypisanie źródła do projektu

Po podłączeniu konektora zdarzenia z Jiry już płyną, ale nie mają jeszcze przypisania: dopóki nie wskażesz kluczy projektów Jiry, wszystkie trafiają do projektu Welcome Project, który każda organizacja ma od początku. Dane są więc zbierane, tylko zebrane w jednym miejscu zamiast rozdzielone na właściwe projekty.

Przypisanie kluczy porządkuje to na przyszłość. Zdarzenia zarejestrowane wcześniej zostają w Welcome Project, bo przypisanie do projektu rozstrzyga się w momencie rejestracji zdarzenia, o czym mówi Zasięg czasowy reguł. Klucze warto więc podać zaraz po uruchomieniu konektora.

Integrację podpina się przyciskiem Przypisz źródło, dostępnym w Źródłach oraz w zakładce Źródła w szczegółach projektu. W polu "Wybierz źródło danych" wskazuje się Jirę, a następnie podaje klucze projektów Jiry, których zdarzenia mają trafiać do tego projektu Q247.

Klucze rozdziela się przecinkami, na przykład CORE, API, PAY, i przyjmują wyłącznie wielkie litery, cyfry i podkreślenia. Jeden projekt Q247 może w ten sposób zbierać zdarzenia z kilku kluczy Jiry naraz.

Rozdzielanie commitów po kluczu ticketu to osobna funkcja

Zakładka Dodatkowe reguły w szczegółach projektu dotyczy commitów, nie zdarzeń z Jiry. Przypisuje commit do projektu na podstawie klucza ticketu znalezionego w commicie, co przydaje się, gdy jedno repozytorium obsługuje kilka projektów biznesowych. Opisują ją Dodatkowe reguły.

4. Worklogi z Tempo, opcjonalnie

Zaznaczony checkbox Tempo odsłania osobną sekcję Dane dostępowe Tempo z polem Token API Tempo. W wariancie Chmura Tempo wymaga własnego tokenu, generowanego w Apps → Tempo → Settings → API Integration. W wariancie On-Premise wtyczka używa ponownie danych dostępowych Jiry.

Pole nazwy użytkownika przy Tempo zostaw puste

Wpisanie tam czegokolwiek psuje uwierzytelnianie. Dotyczy to wyłącznie sekcji Tempo.

Worklogi pobierane są na żądanie, w momencie gdy użytkownik otwiera sekcję worklogów w widoku uczestnika. Q247 tworzy wtedy po jednym zapytaniu na ticket i pokazuje postęp ładowania, a raz pobrane worklogi trafiają do bufora i nie są odpytywane ponownie. Nie działa tu żaden harmonogram, więc pierwsze otwarcie widoku dla osoby z wieloma ticketami zajmuje chwilę.

Pobierane są tylko worklogi, których autorem jest Tempo. Natywne rejestrowanie czasu pracy w Jira Data Center działa bez Tempo i bez tej integracji.

Ticket i Kalorie łączy klucz ticketu z wiadomości commita

Zalogowany czas pochodzi z Tempo, a Kalorie z commitów, więc zestawienie ich w jednej tabeli wymaga wskazania, który commit dotyczy którego ticketu. Q247 wyszukuje klucz ticketu w wiadomości commita i to on tworzy powiązanie: Kalorie przy danym tickecie to suma Kalorii tych commitów uczestnika, w których wiadomości pojawił się klucz tego ticketu.

Wynika z tego jeden warunek wdrożeniowy: zespół musi zapisywać klucz w wiadomościach commitów. Commit bez klucza jest normalnie liczony do metryk uczestnika, ale nie doliczy się do żadnego ticketu, więc tabela pokaże czas zalogowany bez odpowiadających mu Kalorii. Zalecana konwencja wiadomości commita opisuje, jak zapisywać klucz, żeby dał się rozpoznać.

Weryfikacja i diagnostyka

Kolumna Status na liście konektorów przyjmuje jedną z sześciu wartości:

Status	Znaczenie
Nowy	konektor zapisany, wtyczka jeszcze go nie podjęła
Oczekujący	wtyczka podjęła konektor, trwa pierwsze połączenie
Gotowy	połączenie nawiązane, brak jeszcze przetworzonych danych
Operacyjny	integracja działa i dostarcza dane
Błąd	ostatnia próba połączenia zakończyła się niepowodzeniem
Zarchiwizowany	konektor wyłączony z użycia, dane historyczne zostają

Po stronie Źródeł potwierdzeniem jest kolumna z datą ostatniego skanowania. Dla źródeł Jira i Confluence kolumna Interwał pokazuje "N/D", bo synchronizacja jest zdarzeniowa, nie harmonogramowa.

Gdy dane nie pojawiają się, sprawdź w tej kolejności:

1. Czy webhook w Jirze jest włączony i ma poprawny adres. Adres zawiera klucz organizacji, więc literówka daje odrzucenie z kodem 401, a nie pusty wynik.
2. Czy token nie wygasł. Token z ustawioną datą wygaśnięcia przestaje działać bez żadnego komunikatu w Q247, a status konektora zmienia się na Błąd.
3. Czy konto serwisowe ma dostęp do projektu. Konto bez uprawnienia przeglądania danego projektu odczyta zero ticketów, choć samo połączenie będzie poprawne.
4. Czy źródło jest przypisane do projektu Q247. Bez przypisania dane trafiają do Q247, ale nie mają gdzie się pokazać.
5. Logi wtyczki (q247-plugin.log) pokazują odebrane zdarzenia i błędy wysyłki. To najszybsza droga do rozstrzygnięcia, czy problem jest po stronie Jiry, czy po stronie Q247.

Jeśli te punkty nie wskażą przyczyny, zgłoś sprawę zespołowi wdrożeniowemu Q247: część ustawień wtyczki obsługującej integrację jest po naszej stronie i nie widać ich w panelu.

Ustawienia zależne od Jiry

Sam konektor dostarcza dane, ale część funkcji liczonych z Jiry ma jeszcze własne ustawienia w innych miejscach panelu. Zebrane są niżej w jednym miejscu:

Funkcja	Co jeszcze ustawić
Czas realizacji i Czas cyklu	granice statusów w Metrykach przepływu. Wartości domyślne, oparte o kategorie "In Progress" i "Done", działają bez żadnej zmiany, więc do tej sekcji wchodzi się tylko wtedy, gdy proces w Jirze ma nietypowe kategorie statusów.
Rozkład przepływu na Funkcje i Błędy	przypisanie nazw typów ticketów do dwóch grup, w tej samej sekcji. Bez przypisania własnych albo przetłumaczonych nazw typów część ticketów wyląduje w grupie "Inne".
Granice per projekt	zakładka Metryki przepływu w szczegółach projektu, gdy jeden projekt ma inny proces niż reszta organizacji.
Dni robocze w metrykach czasowych	Kalendarz pracy, czyli strefa czasowa i dni wolne organizacji. Bez uzupełnienia świąt Czas realizacji i Czas cyklu liczą je jako dni robocze.
Dzienniki pracy (worklogi)	zaznaczona sekcja Tempo w formularzu konektora oraz klucz ticketu w wiadomościach commitów, patrz Dzienniki pracy.
Przypisanie commitów po kluczu ticketu	Dodatkowe reguły, gdy jedno repozytorium obsługuje kilka projektów.
Wynik kaloryczny ticketów	nic, liczy się od razu po uruchomieniu konektora.

Zakres przetwarzanych danych

Treść ticketu, obejmująca tytuł, opis i komentarze, analizowana jest lokalnie przez wtyczkę, tak samo jak kod źródłowy w Konektorach. Do Q247 trafia wynik tej analizy oraz metadane potrzebne do metryk: klucz i typ ticketu, adres URL, osoba przypisana, historia zmian statusu wraz z momentem każdej zmiany, oraz wynik kaloryczny. Sama treść ticketu i komentarzy nie opuszcza infrastruktury, w której działa wtyczka.

Pełną, techniczną specyfikację wraz z listą przechowywanych pól znajdziesz w Bezpieczeństwie Enterprise Plugin.

Zobacz też

• Confluence: druga integracja Atlassiana, ten sam token, inne pola
• Źródła: przypisanie klucza projektu Jira do projektu Q247
• Metryki przepływu: co Q247 liczy z historii statusów
• Instalacja Enterprise Plugin: włączenie dodatku Jira i port nasłuchu
• Bezpieczeństwo Enterprise Plugin: pełny zakres wymiany danych