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.
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
- In Holarch, creare un token Sola lettura limitato al progetto. Copiarlo.
- Trovare l'id del progetto:
GET /api/v1/projectselenca i propri progetti con il loroid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- 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, comehttps://your-site.atlassian.net.JIRA_EMAILeJIRA_API_TOKEN: l'email di accesso ad Atlassian e il token API.JIRA_PROJECT: la chiave del progetto Jira, comeEO.
- 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}")
- 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=Requirementelenca i requisiti, 500 alla volta.GET /api/v1/projects/<project>/entities/<id>fornisce gli attributi di ogni requisito (qui Status) e il suourl, il link che lo apre in Holarch.- Ogni issue riceve le etichette Jira
holarcheholarch-<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.
- 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).
- Creare per lo script un token Lettura e scrittura al posto di quello di sola lettura.
- 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.
- Aprire Claude, connesso a Holarch con accesso Lettura e proposta di modifiche.
- 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.
- Claude legge il progetto con
list_projects,search_entitieseget_entity. Aggiunge ogni modifica a una proposta conupdate_entity(ocreate_entityerelateper i nuovi requisiti), poi la invia conpropose_changes.Claude risponde con il titolo della proposta e un link per esaminarla.
- In Holarch, aprire ✦ IA ▾ → Rivedi “<title>”…, oppure la notifica sotto la campanella.
- 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
- Creare la demo con Gestisci progetti → File di progetto ▾ → Nuovo progetto demo.
- Creare un token di sola lettura limitato al progetto demo ed eseguire
holarch_to_jira.pysu 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.
- Eseguire di nuovo lo script.
Non stampa nulla: ogni requisito approvato ha già la sua issue.
- 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.
- 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 sintomo | Causa e soluzione |
|---|---|
Holarch answered 401 token-invalid | Il token è errato, revocato o scaduto. Crearne uno nuovo in Impostazioni account → Token API. |
Holarch answered 403 plan-api | Il 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-policy | L'organizzazione del progetto ha disattivato l'accesso API. Rivolgersi a un amministratore dell'organizzazione. |
Holarch answered 403 read-only-token | La scrittura della Jira Key richiede un token Lettura e scrittura. |
Holarch answered 400 unknown-attribute | Il progetto non ha un attributo Jira Key per Requirement. Aggiungerlo in Impostazioni → Schema, oppure omettere il passaggio facoltativo. |
Holarch answered 409 change-control | Il requisito è sotto controllo della configurazione. Modificarlo tramite una richiesta di modifica, oppure conservare la chiave solo in Jira. |
Holarch answered 429 rate-limited | Più 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 400 | Jira 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 403 | Controllare JIRA_EMAIL, JIRA_API_TOKEN e la propria autorizzazione a creare issue nel progetto Jira. |
| Claude non mostra gli strumenti di scrittura di Holarch | La connessione è di sola lettura. Connettersi di nuovo con Lettura e proposta di modifiche, quindi avviare una nuova conversazione. |