Holarch

Riferimento

Ricetta: Jira

Collegare i requisiti di Holarch alle issue di Jira con la REST API e trasformare le issue di Jira in modifiche di Holarch revisionate tramite Claude; configurazione, uno script di sincronizzazione, un esempio svolto e risoluzione dei problemi.

Come usarlo →

In questa pagina
  1. Panoramica
  2. Prerequisiti
  3. Come usarlo
    1. Quando e perché
    2. Configurare la sincronizzazione
    3. Creare issue di Jira dai requisiti approvati
    4. Conservare la chiave Jira in Holarch (facoltativo)
    5. Trasformare una issue di Jira in una proposta Holarch con Claude
    6. Esempio pratico: la demo CubeSat EO-1
    7. Suggerimenti
  4. Risoluzione dei problemi
  5. Pagine correlate

Panoramica

Questa ricetta mantiene il lavoro di ingegneria in Jira legato ai requisiti in Holarch. Si compone di due parti:

  • Da Holarch a Jira (REST API): uno script crea una issue di Jira per ogni requisito approvato. Ogni issue rimanda al requisito in Holarch. Eseguirlo di nuovo in qualsiasi momento: salta i requisiti che hanno già una issue.
  • Da Jira a Holarch (MCP, tramite Claude): Claude legge una issue di Jira, come una richiesta di modifica di un cliente, e propone le modifiche corrispondenti ai requisiti in Holarch. Nulla cambia finché non si esamina e si applica la proposta in Holarch.

Holarch non ha un connettore Jira integrato. La ricetta usa la REST API e MCP, quindi ogni passaggio si può adattare.

Prerequisiti

  • Un piano con l'API e MCP: Individual o Team, oppure la prova di Individual. Nel piano Free, li ha anche un account con un indirizzo email accademico verificato o in un'organizzazione di classe attiva (Piani e limiti).
  • Un progetto Holarch di cui si è editor o proprietari. Le proposte richiedono il ruolo di editor.
  • Un token di accesso personale: Impostazioni account → Token API → Nuovo token. Usare Sola lettura per lo script da Holarch a Jira e limitarlo al progetto (Creare un token).
  • Jira Cloud: un progetto Jira in cui si possono creare issue e un token API di Atlassian (impostazioni dell'account Atlassian → Security → API tokens). Jira Data Center usa invece i percorsi /rest/api/2/ e un token di accesso personale; consultare il suo riferimento API.
  • Python 3.9 o successivo con il pacchetto requests (python3 -m pip install requests) per lo script.
  • Per la parte con Claude: Claude connesso a Holarch (Connettere Holarch a Claude). Claude legge da solo le issue di Jira solo quando ha anche un connettore Jira; altrimenti incollare il testo della issue nella conversazione.

Come usarlo

Quando e perché

I requisiti risiedono in Holarch; il lavoro per realizzarli e testarli è spesso pianificato in Jira. Collegare i due risponde a due domande: “quale lavoro in Jira implementa questo requisito?” e “quali requisiti tocca questa richiesta di modifica?”. Eseguire la sincronizzazione dopo ogni revisione dei requisiti, quando nuovi requisiti raggiungono Approved.

Configurare la sincronizzazione

  1. In Holarch, creare un token Sola lettura limitato al progetto. Copiarlo.
  2. Trovare l'id del progetto: GET /api/v1/projects elenca i propri progetti con il loro id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Impostare le variabili d'ambiente lette dallo script:
    • HOLARCH_TOKEN: il token di Holarch.
    • HOLARCH_PROJECT: l'id del progetto.
    • JIRA_URL: il proprio sito Jira, come https://your-site.atlassian.net.
    • JIRA_EMAIL e JIRA_API_TOKEN: l'email di accesso ad Atlassian e il token API.
    • JIRA_PROJECT: la chiave del progetto Jira, come EO.
  2. Salvare lo script seguente come holarch_to_jira.py.

Creare issue di Jira dai requisiti approvati

Lo script legge ogni requisito tramite la REST API, salta quelli che hanno già una issue di Jira e crea un Task per ogni requisito rimanente il cui Status è 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. Eseguire python3 holarch_to_jira.py.

    Si vede una riga per ogni nuova issue, come 2.1 Pointing Accuracy -> EO-12.

Come funziona:

  • GET /api/v1/projects/<project>/entities?class=Requirement elenca i requisiti, 500 alla volta.
  • GET /api/v1/projects/<project>/entities/<id> fornisce gli attributi di ogni requisito (qui Status) e il suo url, il link che lo apre in Holarch.
  • Ogni issue riceve le etichette Jira holarch e holarch-<id>. L'esecuzione successiva le trova con una ricerca in Jira e salta quei requisiti.
  • I requisiti vengono solo letti. Lo script non modifica nulla in Holarch.

Conservare la chiave Jira in Holarch (facoltativo)

Per vedere la chiave Jira sul requisito in Holarch, aggiungere un attributo di testo e scrivervi la chiave.

  1. In Holarch, aprire Impostazioni → Schema, fare clic su Requirement e aggiungere un attributo chiamato Jira Key con il tipo Testo breve (Aggiungere un attributo a una classe).
  2. Creare per lo script un token Lettura e scrittura al posto di quello di sola lettura.
  3. Alla fine dell'ultimo ciclo dello script, dopo la riga print(…), aggiungere:
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

La modifica viene scritta come una modifica nell'app: viene registrata con il proprio nome e chiunque abbia il progetto aperto la vede. L'impostazione di questo attributo non rimanda in revisione un requisito approvato. Quando il progetto usa il controllo della configurazione, i requisiti approvati rifiutano le modifiche dirette (409 change-control); conservare la chiave solo in Jira, oppure effettuare la modifica tramite una richiesta di modifica.

Trasformare una issue di Jira in una proposta Holarch con Claude

Usare questa procedura quando una issue di Jira chiede una modifica a un requisito, come la richiesta di un cliente di restringere un valore.

  1. Aprire Claude, connesso a Holarch con accesso Lettura e proposta di modifiche.
  2. Chiedere, per esempio: “Leggi la issue Jira EO-31. Trova i requisiti Holarch del progetto CubeSat che riguarda e proponi le modifiche che richiede. Cita EO-31 nel riepilogo della proposta.”

    Senza un connettore Jira, incollare invece nel messaggio il riepilogo e la descrizione della issue.

  3. Claude legge il progetto con list_projects, search_entities e get_entity. Aggiunge ogni modifica a una proposta con update_entity (o create_entity e relate per i nuovi requisiti), poi la invia con propose_changes.

    Claude risponde con il titolo della proposta e un link per esaminarla.

  4. In Holarch, aprire ✦ IA ▾ → Rivedi “<title>”…, oppure la notifica sotto la campanella.
  5. Controllare ogni modifica. Togliere la spunta da ciò che non si vuole, quindi fare clic su Applica selezionati.

    Le modifiche vengono applicate, e un solo annullamento revoca tutto. Il testo modificato di un requisito contrassegna i suoi collegamenti di tracciabilità da rivedere e un requisito approvato torna a In Review, come per qualsiasi modifica.

Gli script possono fare la stessa proposta senza Claude: POST /api/v1/projects/<project>/proposal/changes una volta per modifica, poi POST /api/v1/projects/<project>/proposal con un title e un 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

Esempio pratico: la demo CubeSat EO-1

  1. Creare la demo con Gestisci progetti → File di progetto ▾ → Nuovo progetto demo.
  2. Creare un token di sola lettura limitato al progetto demo ed eseguire holarch_to_jira.py su un progetto Jira di prova.

    Ogni requisito approvato riceve una issue, come 2.1 Pointing Accuracy con il testo “The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.” e il link al requisito.

  3. Eseguire di nuovo lo script.

    Non stampa nulla: ogni requisito approvato ha già la sua issue.

  4. In Jira, creare una issue EO-31 che chiede 0,08 gradi invece di 0,1 gradi. Chiedere a Claude di proporre la modifica, come sopra.
  5. In Holarch, esaminare la proposta. Modifica il testo di 2.1 Pointing Accuracy e il suo elenco Impatto mostra TC-04 Pointing Accuracy Test, che lo verifica.

Suggerimenti

  • Dare allo script di sincronizzazione il proprio token di sola lettura, limitato al progetto. Dare a Claude una connessione separata.
  • Conservare i token nel proprio archivio di segreti o nell'ambiente, mai nello script.
  • Cercare in Jira i requisiti alla base di uno sprint con l'etichetta holarch.
  • I numeri dei requisiti possono cambiare; l'etichetta holarch-<id> no. Abbinare in base all'etichetta, non al numero nel riepilogo.

Risoluzione dei problemi

Messaggio o sintomoCausa e soluzione
Holarch answered 401 token-invalidIl token è errato, revocato o scaduto. Crearne uno nuovo in Impostazioni account → Token API.
Holarch answered 403 plan-apiIl piano dell'account non include l'API e MCP. Avviare la prova di Individual o scegliere un piano; il token torna allora a funzionare.
Holarch answered 403 org-policyL'organizzazione del progetto ha disattivato l'accesso API. Rivolgersi a un amministratore dell'organizzazione.
Holarch answered 403 read-only-tokenLa scrittura della Jira Key richiede un token Lettura e scrittura.
Holarch answered 400 unknown-attributeIl progetto non ha un attributo Jira Key per Requirement. Aggiungerlo in Impostazioni → Schema, oppure omettere il passaggio facoltativo.
Holarch answered 409 change-controlIl requisito è sotto controllo della configurazione. Modificarlo tramite una richiesta di modifica, oppure conservare la chiave solo in Jira.
Holarch answered 429 rate-limitedPiù di 600 richieste o 120 modifiche al minuto. Attendere i secondi indicati in Retry-After, quindi eseguire di nuovo; le issue già create vengono saltate.
Jira risponde 400Jira ha rifiutato i campi della issue, per esempio un tipo di issue che il progetto non ha. Usare uno dei tipi di issue del progetto invece di Task.
Jira risponde 401 o 403Controllare JIRA_EMAIL, JIRA_API_TOKEN e la propria autorizzazione a creare issue nel progetto Jira.
Claude non mostra gli strumenti di scrittura di HolarchLa connessione è di sola lettura. Connettersi di nuovo con Lettura e proposta di modifiche, quindi avviare una nuova conversazione.