Holarch

Referencja

Przepis: Jira

Połącz wymagania Holarch ze zgłoszeniami Jira przez REST API i zamieniaj zgłoszenia Jira w przejrzane zmiany Holarch za pośrednictwem Claude; konfiguracja, skrypt synchronizacji, przykład krok po kroku i rozwiązywanie problemów.

Jak z niego korzystać →

Na tej stronie
  1. Przegląd
  2. Wymagania wstępne
  3. Jak z niego korzystać
    1. Kiedy i dlaczego
    2. Konfiguracja synchronizacji
    3. Tworzenie zgłoszeń Jira z zatwierdzonych wymagań
    4. Przechowywanie klucza Jira w Holarch (opcjonalnie)
    5. Zamiana zgłoszenia Jira w propozycję Holarch za pomocą Claude
    6. Przykład: demo CubeSat EO-1
    7. Wskazówki
  4. Rozwiązywanie problemów
  5. Powiązane strony

Przegląd

Ten przepis wiąże prace inżynierskie w Jira z wymaganiami w Holarch. Ma dwie części:

  • Z Holarch do Jira (REST API): skrypt tworzy jedno zgłoszenie Jira dla każdego zatwierdzonego wymagania. Każde zgłoszenie zawiera łącze zwrotne do wymagania w Holarch. Można go uruchomić ponownie w dowolnej chwili: pomija wymagania, które mają już zgłoszenie.
  • Z Jira do Holarch (MCP, przez Claude): Claude odczytuje zgłoszenie Jira, np. wniosek klienta o zmianę, i proponuje odpowiadające mu zmiany wymagań w Holarch. Nic się nie zmienia, dopóki nie przejrzysz i nie zastosujesz propozycji w Holarch.

Holarch nie ma wbudowanego konektora Jira. Przepis korzysta z REST API i MCP, więc każdy krok można dostosować.

Wymagania wstępne

  • Plan z API i MCP: Individual lub Team albo okres próbny Individual. W planie Free mają je też konta ze zweryfikowanym akademickim adresem e-mail lub w aktywnej organizacji zajęć (Plany i limity).
  • Projekt Holarch, którego jesteś edytorem lub właścicielem. Propozycje wymagają roli edytora.
  • Osobisty token dostępu: Ustawienia konta → Tokeny API → Nowy token. Dla skryptu z Holarch do Jira użyj Tylko do odczytu i ogranicz token do projektu (Tworzenie tokenu).
  • Jira Cloud: projekt Jira, w którym możesz tworzyć zgłoszenia, oraz token API Atlassian (ustawienia konta Atlassian → Security → API tokens). Jira Data Center używa zamiast tego ścieżek /rest/api/2/ i osobistego tokenu dostępu; sprawdź jej dokumentację API.
  • Python 3.9 lub nowszy z pakietem requests (python3 -m pip install requests) dla skryptu.
  • Dla części z Claude: Claude połączony z Holarch (Podłączanie Holarch do Claude). Claude sam odczytuje zgłoszenia Jira tylko wtedy, gdy ma też konektor Jira; w przeciwnym razie wklej tekst zgłoszenia do rozmowy.

Jak z niego korzystać

Kiedy i dlaczego

Wymagania znajdują się w Holarch; prace nad ich realizacją i testowaniem są często planowane w Jira. Powiązanie obu odpowiada na dwa pytania: “które prace w Jira realizują to wymaganie?” i “których wymagań dotyczy ten wniosek o zmianę?”. Uruchamiaj synchronizację po każdym przeglądzie wymagań, gdy nowe wymagania osiągną status Approved.

Konfiguracja synchronizacji

  1. W Holarch utwórz token Tylko do odczytu ograniczony do projektu. Skopiuj go.
  2. Znajdź id projektu: GET /api/v1/projects wymienia Twoje projekty z ich id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Ustaw zmienne środowiskowe odczytywane przez skrypt:
    • HOLARCH_TOKEN: token Holarch.
    • HOLARCH_PROJECT: id projektu.
    • JIRA_URL: Twoja witryna Jira, np. https://your-site.atlassian.net.
    • JIRA_EMAIL i JIRA_API_TOKEN: e-mail logowania Atlassian i token API.
    • JIRA_PROJECT: klucz projektu Jira, np. EO.
  2. Zapisz poniższy skrypt jako holarch_to_jira.py.

Tworzenie zgłoszeń Jira z zatwierdzonych wymagań

Skrypt odczytuje każde wymaganie przez REST API, pomija te, które mają już zgłoszenie Jira, i tworzy Task dla każdego pozostałego wymagania, którego Status to Approved.

# holarch_to_jira.py: one Jira issue per approved Holarch requirement. Safe to run again.
import os

import requests

HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
JIRA = os.environ["JIRA_URL"].rstrip("/")
JIRA_AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
JIRA_PROJECT = os.environ["JIRA_PROJECT"]


def holarch(method, path, **kw):
    r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
    if r.status_code >= 400:
        d = r.json()
        raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
    return r.json()


def requirements():
    offset = 0
    while True:
        page = holarch("GET", f"/projects/{PROJECT}/entities",
                       params={"class": "Requirement", "limit": 500, "offset": offset})
        yield from page["entities"]
        offset += page["limit"]
        if offset >= page["total"]:
            return


def linked_in_jira():
    """The Jira labels holarch-<requirement id> already on issues of the Jira project."""
    seen, token = set(), None
    while True:
        params = {"jql": f'project = "{JIRA_PROJECT}" AND labels = holarch', "fields": "labels", "maxResults": 100}
        if token:
            params["nextPageToken"] = token
        r = requests.get(JIRA + "/rest/api/3/search/jql", params=params, auth=JIRA_AUTH, timeout=60)
        r.raise_for_status()
        d = r.json()
        for issue in d.get("issues", []):
            seen.update(x for x in issue["fields"]["labels"] if x.startswith("holarch-"))
        token = d.get("nextPageToken")
        if not token:
            return seen


seen = linked_in_jira()
for req in requirements():
    if "holarch-" + req["id"] in seen:
        continue
    e = holarch("GET", f"/projects/{PROJECT}/entities/{req['id']}")["entity"]
    if e["attributes"].get("Status") != "Approved":
        continue
    text = (e["description"] + "\n\n" if e["description"] else "") + "Requirement in Holarch: " + e["url"]
    fields = {
        "project": {"key": JIRA_PROJECT},
        "issuetype": {"name": "Task"},
        "summary": f"{e['number']} {e['name']}".strip(),
        "labels": ["holarch", "holarch-" + e["id"]],
        "description": {"type": "doc", "version": 1, "content": [
            {"type": "paragraph", "content": [{"type": "text", "text": text}]}]},
    }
    issue = requests.post(JIRA + "/rest/api/3/issue", json={"fields": fields}, auth=JIRA_AUTH, timeout=60)
    issue.raise_for_status()
    key = issue.json()["key"]
    print(f"{e['number']} {e['name']} -> {key}")
  1. Uruchom python3 holarch_to_jira.py.

    Pojawia się jeden wiersz na nowe zgłoszenie, np. 2.1 Pointing Accuracy -> EO-12.

Jak to działa:

  • GET /api/v1/projects/<project>/entities?class=Requirement wymienia wymagania, po 500 naraz.
  • GET /api/v1/projects/<project>/entities/<id> podaje atrybuty każdego wymagania (tu Status) i jego url, łącze otwierające je w Holarch.
  • Każde zgłoszenie otrzymuje etykiety Jira holarch i holarch-<id>. Następne uruchomienie znajduje je wyszukiwaniem w Jira i pomija te wymagania.
  • Wymagania są tylko odczytywane. Skrypt niczego nie zmienia w Holarch.

Przechowywanie klucza Jira w Holarch (opcjonalnie)

Aby widzieć klucz Jira przy wymaganiu w Holarch, dodaj atrybut tekstowy i zapisz w nim klucz.

  1. W Holarch otwórz Ustawienia → Schemat, kliknij Requirement i dodaj atrybut o nazwie Jira Key typu Krótki tekst (Dodawanie atrybutu do klasy).
  2. Utwórz dla skryptu token Odczyt i zapis zamiast tokenu tylko do odczytu.
  3. Na końcu ostatniej pętli skryptu, po wierszu print(…), dodaj:
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

Zmiana jest zapisywana jak edycja w aplikacji: jest rejestrowana pod Twoim nazwiskiem i widzi ją każdy, kto ma projekt otwarty. Ustawienie tego atrybutu nie odsyła zatwierdzonego wymagania z powrotem do przeglądu. Gdy projekt używa kontroli konfiguracji, zatwierdzone wymagania odrzucają bezpośrednie zmiany (409 change-control); przechowuj klucz tylko w Jira albo wprowadź zmianę przez wniosek o zmianę.

Zamiana zgłoszenia Jira w propozycję Holarch za pomocą Claude

Użyj tego, gdy zgłoszenie Jira wymaga zmiany wymagania, np. wniosek klienta o zaostrzenie wartości.

  1. Otwórz Claude połączony z Holarch z dostępem Odczyt i proponowanie zmian.
  2. Zapytaj na przykład: “Przeczytaj zgłoszenie Jira EO-31. Znajdź wymagania Holarch w projekcie CubeSat, których dotyczy, i zaproponuj zmiany, o które prosi. Wymień EO-31 w podsumowaniu propozycji.”

    Bez konektora Jira wklej zamiast tego do wiadomości podsumowanie i opis zgłoszenia.

  3. Claude odczytuje projekt za pomocą list_projects, search_entities i get_entity. Dodaje każdą zmianę do propozycji za pomocą update_entity (lub create_entity i relate dla nowych wymagań), a następnie wysyła ją za pomocą propose_changes.

    Claude odpowiada tytułem propozycji i łączem do jej przeglądu.

  4. W Holarch otwórz ✦ AI ▾ → Przejrzyj “<title>”… albo powiadomienie pod dzwonkiem.
  5. Sprawdź każdą zmianę. Odznacz to, czego nie chcesz, a następnie kliknij Zastosuj zaznaczone.

    Zmiany zostają zastosowane, a jedno polecenie Cofnij wycofuje całość. Zmieniony tekst wymagania oznacza jego powiązania śledzenia do przeglądu, a zatwierdzone wymaganie wraca do In Review, jak przy każdej edycji.

Skrypty mogą utworzyć tę samą propozycję bez Claude: POST /api/v1/projects/<project>/proposal/changes raz na każdą zmianę, a następnie POST /api/v1/projects/<project>/proposal z title i summary.

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"op": "update", "entity": "<requirement id>", "description": "The ADCS shall point the payload boresight within 0.08 degrees of the commanded target."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "EO-31: tighter pointing", "summary": "Customer request EO-31 tightens pointing accuracy to 0.08 degrees."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal

Przykład: demo CubeSat EO-1

  1. Utwórz projekt demonstracyjny poleceniem Zarządzaj projektami → Pliki projektów ▾ → Nowy projekt demonstracyjny.
  2. Utwórz token tylko do odczytu ograniczony do projektu demonstracyjnego i uruchom holarch_to_jira.py na testowym projekcie Jira.

    Każde zatwierdzone wymaganie otrzymuje zgłoszenie, np. 2.1 Pointing Accuracy z tekstem “The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.” i łączem do wymagania.

  3. Uruchom skrypt ponownie.

    Nic nie wypisuje: każde zatwierdzone wymaganie ma już swoje zgłoszenie.

  4. W Jira utwórz zgłoszenie EO-31 z prośbą o 0,08 stopnia zamiast 0,1 stopnia. Poproś Claude o zaproponowanie zmiany, jak powyżej.
  5. W Holarch przejrzyj propozycję. Zmienia ona tekst 2.1 Pointing Accuracy, a jej lista Wpływ pokazuje TC-04 Pointing Accuracy Test, który ją weryfikuje.

Wskazówki

  • Daj skryptowi synchronizacji własny token tylko do odczytu, ograniczony do projektu. Daj Claude osobne połączenie.
  • Przechowuj tokeny w magazynie sekretów lub w środowisku, nigdy w skrypcie.
  • Wyszukuj w Jira wymagania stojące za sprintem za pomocą etykiety holarch.
  • Numery wymagań mogą się zmieniać; etykieta holarch-<id> nie. Dopasowuj według etykiety, a nie według numeru w podsumowaniu.

Rozwiązywanie problemów

Komunikat lub objawPrzyczyna i rozwiązanie
Holarch answered 401 token-invalidToken jest błędny, unieważniony lub wygasł. Utwórz nowy w Ustawienia konta → Tokeny API.
Holarch answered 403 plan-apiPlan konta nie obejmuje API i MCP. Rozpocznij okres próbny Individual lub wybierz plan; token znów zadziała.
Holarch answered 403 org-policyOrganizacja projektu wyłączyła dostęp przez API. Zwróć się do administratora organizacji.
Holarch answered 403 read-only-tokenZapis Jira Key wymaga tokenu Odczyt i zapis.
Holarch answered 400 unknown-attributeProjekt nie ma atrybutu Jira Key dla Requirement. Dodaj go w Ustawienia → Schemat lub pomiń krok opcjonalny.
Holarch answered 409 change-controlWymaganie podlega kontroli konfiguracji. Zmień je przez wniosek o zmianę lub przechowuj klucz tylko w Jira.
Holarch answered 429 rate-limitedPonad 600 żądań lub 120 zmian na minutę. Odczekaj liczbę sekund podaną w Retry-After, a następnie uruchom ponownie; gotowe zgłoszenia są pomijane.
Jira odpowiada 400Jira odrzuciła pola zgłoszenia, na przykład typ zgłoszenia, którego projekt nie ma. Zamiast Task użyj jednego z typów zgłoszeń projektu.
Jira odpowiada 401 lub 403Sprawdź JIRA_EMAIL, JIRA_API_TOKEN i swoje uprawnienie do tworzenia zgłoszeń w projekcie Jira.
Claude nie pokazuje narzędzi zapisu HolarchPołączenie jest tylko do odczytu. Połącz ponownie z dostępem Odczyt i proponowanie zmian, a następnie rozpocznij nową rozmowę.