Holarch

Referenz

Rezept: Jira

Verbinden Sie Holarch-Anforderungen über die REST-API mit Jira-Issues und machen Sie über Claude aus Jira-Issues geprüfte Holarch-Änderungen; Einrichtung, ein Synchronisationsskript, ein durchgearbeitetes Beispiel und Fehlerbehebung.

So gehen Sie vor →

Auf dieser Seite
  1. Überblick
  2. Voraussetzungen
  3. So setzen Sie es ein
    1. Wann und warum
    2. Die Synchronisierung einrichten
    3. Jira-Issues aus genehmigten Anforderungen erstellen
    4. Den Jira-Schlüssel in Holarch aufbewahren (optional)
    5. Ein Jira-Issue mit Claude in einen Holarch-Vorschlag umwandeln
    6. Durchgehendes Beispiel: die CubeSat-EO-1-Demo
    7. Tipps
  4. Fehlerbehebung
  5. Verwandte Seiten

Überblick

Dieses Rezept hält die Entwicklungsarbeit in Jira mit den Anforderungen in Holarch verbunden. Es hat zwei Teile:

  • Holarch nach Jira (REST-API): Ein Skript erstellt für jede genehmigte Anforderung ein Jira-Issue. Jedes Issue verlinkt zurück zur Anforderung in Holarch. Führen Sie es jederzeit erneut aus: Es überspringt Anforderungen, die bereits ein Issue haben.
  • Jira nach Holarch (MCP, über Claude): Claude liest ein Jira-Issue, etwa einen Änderungsantrag eines Kunden, und schlägt die passenden Anforderungsänderungen in Holarch vor. Nichts ändert sich, bis Sie den Vorschlag in Holarch prüfen und anwenden.

Holarch hat keinen eingebauten Jira-Konnektor. Das Rezept verwendet die REST-API und MCP, sodass Sie jeden Schritt anpassen können.

Voraussetzungen

  • Ein Tarif mit API und MCP: Individual oder Team oder die Testphase Individual. Im Tarif Free hat auch ein Konto mit einer bestätigten akademischen E-Mail-Adresse oder in einer aktiven Kursorganisation sie (Tarife und Grenzen).
  • Ein Holarch-Projekt, in dem Sie Bearbeiter oder Eigentümer sind. Vorschläge erfordern die Rolle Bearbeiter.
  • Ein persönliches Zugriffstoken: Kontoeinstellungen → API-Token → Neues Token. Verwenden Sie Nur lesen für das Skript von Holarch nach Jira und beschränken Sie es auf das Projekt (Ein Token erstellen).
  • Jira Cloud: ein Jira-Projekt, in dem Sie Issues erstellen können, und ein Atlassian-API-Token (Atlassian-Kontoeinstellungen → Security → API tokens). Jira Data Center verwendet stattdessen die Pfade /rest/api/2/ und ein persönliches Zugriffstoken; prüfen Sie dessen API-Referenz.
  • Python 3.9 oder neuer mit dem Paket requests (python3 -m pip install requests) für das Skript.
  • Für den Teil mit Claude: Claude mit Holarch verbunden (Holarch mit Claude verbinden). Claude liest Jira-Issues nur selbst, wenn es auch einen Jira-Konnektor hat; andernfalls fügen Sie den Text des Issues in das Gespräch ein.

So setzen Sie es ein

Wann und warum

Anforderungen liegen in Holarch; die Arbeit, sie umzusetzen und zu testen, wird oft in Jira geplant. Die Verknüpfung beider beantwortet zwei Fragen: „Welche Jira-Arbeit setzt diese Anforderung um?“ und „Welche Anforderungen berührt dieser Änderungsantrag?“. Führen Sie die Synchronisierung nach jedem Anforderungsreview aus, wenn neue Anforderungen Approved erreichen.

Die Synchronisierung einrichten

  1. Erstellen Sie in Holarch ein Token mit Nur lesen, beschränkt auf das Projekt. Kopieren Sie es.
  2. Ermitteln Sie die Projekt-ID: GET /api/v1/projects listet Ihre Projekte mit ihrer id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Setzen Sie die Umgebungsvariablen, die das Skript liest:
    • HOLARCH_TOKEN: das Holarch-Token.
    • HOLARCH_PROJECT: die Projekt-ID.
    • JIRA_URL: Ihre Jira-Site, etwa https://your-site.atlassian.net.
    • JIRA_EMAIL und JIRA_API_TOKEN: Ihre Atlassian-Anmelde-E-Mail und Ihr API-Token.
    • JIRA_PROJECT: der Schlüssel des Jira-Projekts, etwa EO.
  2. Speichern Sie das folgende Skript als holarch_to_jira.py.

Jira-Issues aus genehmigten Anforderungen erstellen

Das Skript liest jede Anforderung über die REST-API, überspringt die, die bereits ein Jira-Issue haben, und erstellt für jede verbleibende Anforderung, deren Status Approved ist, einen Task.

# 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. Führen Sie python3 holarch_to_jira.py aus.

    Sie sehen eine Zeile pro neuem Issue, etwa 2.1 Pointing Accuracy -> EO-12.

So funktioniert es:

  • GET /api/v1/projects/<project>/entities?class=Requirement listet die Anforderungen, jeweils 500.
  • GET /api/v1/projects/<project>/entities/<id> liefert die Attribute jeder Anforderung (hier Status) und ihre url, den Link, der sie in Holarch öffnet.
  • Jedes Issue erhält die Jira-Labels holarch und holarch-<id>. Der nächste Lauf findet sie mit einer Jira-Suche und überspringt diese Anforderungen.
  • Anforderungen werden nur gelesen. Das Skript ändert nichts in Holarch.

Den Jira-Schlüssel in Holarch aufbewahren (optional)

Um den Jira-Schlüssel an der Anforderung in Holarch zu sehen, fügen Sie ein Textattribut hinzu und schreiben Sie den Schlüssel hinein.

  1. Öffnen Sie in Holarch Einstellungen → Schema, klicken Sie auf Requirement und fügen Sie ein Attribut mit dem Namen Jira Key und dem Typ Kurzer Text hinzu (Einer Klasse ein Attribut hinzufügen).
  2. Erstellen Sie für das Skript statt des Tokens mit Nur-Lesen-Zugriff ein Token mit Lesen und schreiben.
  3. Fügen Sie am Ende der letzten Schleife des Skripts, nach der Zeile print(…), Folgendes hinzu:
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

Die Änderung wird wie eine Bearbeitung in der App geschrieben: Sie wird unter Ihrem Namen erfasst, und jeder, der das Projekt geöffnet hat, sieht sie. Das Setzen dieses Attributs schickt eine genehmigte Anforderung nicht zurück ins Review. Wenn das Projekt Konfigurationsmanagement verwendet, lehnen genehmigte Anforderungen direkte Änderungen ab (409 change-control); bewahren Sie den Schlüssel nur in Jira auf oder nehmen Sie die Änderung über einen Änderungsantrag vor.

Ein Jira-Issue mit Claude in einen Holarch-Vorschlag umwandeln

Verwenden Sie dies, wenn ein Jira-Issue eine Anforderungsänderung verlangt, etwa die Bitte eines Kunden, einen Wert zu verschärfen.

  1. Öffnen Sie Claude, mit Holarch verbunden mit dem Zugriff Lesen und Änderungen vorschlagen.
  2. Fragen Sie zum Beispiel: „Lies das Jira-Issue EO-31. Finde die Holarch-Anforderungen im CubeSat-Projekt, die es betrifft, und schlage die Änderungen vor, die es verlangt. Erwähne EO-31 in der Zusammenfassung des Vorschlags.“

    Ohne Jira-Konnektor fügen Sie stattdessen die Zusammenfassung und die Beschreibung des Issues in die Nachricht ein.

  3. Claude liest das Projekt mit list_projects, search_entities und get_entity. Es fügt jede Änderung mit update_entity (oder create_entity und relate für neue Anforderungen) einem Vorschlag hinzu und sendet ihn dann mit propose_changes.

    Claude antwortet mit dem Titel des Vorschlags und einem Link, um ihn zu prüfen.

  4. Öffnen Sie in Holarch ✦ KI ▾ → „<title>“ prüfen… oder die Benachrichtigung unter der Glocke.
  5. Prüfen Sie jede Änderung. Entfernen Sie den Haken bei allem, was Sie nicht wollen, und klicken Sie dann auf Auswahl anwenden.

    Die Änderungen werden angewendet, und ein einziges Rückgängigmachen nimmt alles zurück. Geänderter Anforderungstext markiert ihre Trace-Links zur Prüfung, und eine genehmigte Anforderung geht zurück auf In Review, wie bei jeder Bearbeitung.

Skripte können denselben Vorschlag ohne Claude machen: POST /api/v1/projects/<project>/proposal/changes einmal pro Änderung, dann POST /api/v1/projects/<project>/proposal mit title und 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

Durchgehendes Beispiel: die CubeSat-EO-1-Demo

  1. Erstellen Sie die Demo mit Projekte verwalten → Projektdateien ▾ → Neues Demoprojekt.
  2. Erstellen Sie ein Token mit Nur-Lesen-Zugriff, beschränkt auf das Demoprojekt, und führen Sie holarch_to_jira.py gegen ein Jira-Testprojekt aus.

    Jede genehmigte Anforderung erhält ein Issue, etwa 2.1 Pointing Accuracy mit dem Text „The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.“ und dem Link zur Anforderung.

  3. Führen Sie das Skript erneut aus.

    Es gibt nichts aus: Jede genehmigte Anforderung hat bereits ihr Issue.

  4. Erstellen Sie in Jira ein Issue EO-31, das 0,08 Grad statt 0,1 Grad verlangt. Bitten Sie Claude wie oben, die Änderung vorzuschlagen.
  5. Prüfen Sie den Vorschlag in Holarch. Er ändert den Text von 2.1 Pointing Accuracy, und seine Liste Auswirkung zeigt TC-04 Pointing Accuracy Test, der sie verifiziert.

Tipps

  • Geben Sie dem Sync-Skript ein eigenes Token mit Nur-Lesen-Zugriff, beschränkt auf das Projekt. Geben Sie Claude eine eigene Verbindung.
  • Bewahren Sie Token in Ihrem Geheimnisspeicher oder Ihrer Umgebung auf, nie im Skript.
  • Suchen Sie in Jira mit dem Label holarch nach den Anforderungen hinter einem Sprint.
  • Anforderungsnummern können sich ändern; das Label holarch-<id> nicht. Gleichen Sie über das Label ab, nicht über die Nummer in der Zusammenfassung.

Fehlerbehebung

Meldung oder SymptomUrsache und Behebung
Holarch answered 401 token-invalidDas Token ist falsch, widerrufen oder abgelaufen. Erstellen Sie ein neues unter Kontoeinstellungen → API-Token.
Holarch answered 403 plan-apiDer Tarif des Kontos enthält API und MCP nicht. Beginnen Sie die Testphase Individual oder wählen Sie einen Tarif; das Token funktioniert dann wieder.
Holarch answered 403 org-policyDie Organisation des Projekts hat den API-Zugriff ausgeschaltet. Fragen Sie einen Organisationsadmin.
Holarch answered 403 read-only-tokenDas Schreiben des Jira Key erfordert ein Token mit Lesen und schreiben.
Holarch answered 400 unknown-attributeDas Projekt hat für Requirement kein Attribut Jira Key. Fügen Sie es in Einstellungen → Schema hinzu oder lassen Sie den optionalen Schritt weg.
Holarch answered 409 change-controlDie Anforderung unterliegt dem Konfigurationsmanagement. Ändern Sie sie über einen Änderungsantrag oder bewahren Sie den Schlüssel nur in Jira auf.
Holarch answered 429 rate-limitedMehr als 600 Anfragen oder 120 Änderungen pro Minute. Warten Sie die Sekunden in Retry-After und führen Sie es dann erneut aus; fertige Issues werden übersprungen.
Jira antwortet mit 400Jira hat die Issue-Felder abgelehnt, zum Beispiel einen Issue-Typ, den das Projekt nicht hat. Verwenden Sie statt Task einen der Issue-Typen des Projekts.
Jira antwortet mit 401 oder 403Prüfen Sie JIRA_EMAIL, JIRA_API_TOKEN und Ihre Berechtigung, im Jira-Projekt Issues zu erstellen.
Claude zeigt die Holarch-Schreibwerkzeuge nicht anDie Verbindung hat nur Lesezugriff. Verbinden Sie erneut mit Lesen und Änderungen vorschlagen und beginnen Sie dann ein neues Gespräch.