Holarch

Référence

Recette : Jira

Reliez les exigences de Holarch aux tickets Jira avec l'API REST, et transformez des tickets Jira en modifications Holarch examinées grâce à Claude ; configuration, script de synchronisation, exemple complet et dépannage.

Utilisation →

Sur cette page
  1. Vue d'ensemble
  2. Prérequis
  3. Mode d'emploi
    1. Quand et pourquoi
    2. Configurer la synchronisation
    3. Créer des tickets Jira à partir des exigences approuvées
    4. Conserver la clé Jira dans Holarch (facultatif)
    5. Transformer un ticket Jira en proposition Holarch avec Claude
    6. Exemple complet : la démo CubeSat EO-1
    7. Conseils
  4. Dépannage
  5. Pages associées

Vue d'ensemble

Cette recette garde le travail d'ingénierie dans Jira lié aux exigences dans Holarch. Elle comporte deux parties :

  • De Holarch vers Jira (API REST) : un script crée un ticket Jira pour chaque exigence approuvée. Chaque ticket renvoie vers l'exigence dans Holarch. Exécutez-le de nouveau à tout moment : il ignore les exigences qui ont déjà un ticket.
  • De Jira vers Holarch (MCP, par Claude) : Claude lit un ticket Jira, comme une demande de modification d'un client, et propose les modifications d'exigences correspondantes dans Holarch. Rien ne change tant que vous n'avez pas examiné et appliqué la proposition dans Holarch.

Holarch n'a pas de connecteur Jira intégré. La recette utilise l'API REST et MCP : vous pouvez donc adapter chaque étape.

Prérequis

  • Une offre avec l'API et MCP : Individual ou Team, ou l'essai Individual. Avec l'offre Free, un compte doté d'une adresse e-mail académique vérifiée ou appartenant à une organisation de cours active en dispose aussi (Offres et limites).
  • Un projet Holarch dont vous êtes éditeur ou propriétaire. Les propositions nécessitent le rôle d'éditeur.
  • Un jeton d'accès personnel : Paramètres du compte → Jetons API → Nouveau jeton. Utilisez Lecture seule pour le script de Holarch vers Jira et limitez-le au projet (Créer un jeton).
  • Jira Cloud : un projet Jira dans lequel vous pouvez créer des tickets, et un jeton API Atlassian (paramètres du compte Atlassian → Security → API tokens). Jira Data Center utilise plutôt les chemins /rest/api/2/ et un jeton d'accès personnel ; consultez sa référence d'API.
  • Python 3.9 ou une version ultérieure avec le paquet requests (python3 -m pip install requests) pour le script.
  • Pour la partie Claude : Claude connecté à Holarch (Connecter Holarch à Claude). Claude ne lit lui-même les tickets Jira que s'il dispose aussi d'un connecteur Jira ; sinon, collez le texte du ticket dans la conversation.

Mode d'emploi

Quand et pourquoi

Les exigences se trouvent dans Holarch ; le travail pour les réaliser et les tester est souvent planifié dans Jira. Relier les deux répond à deux questions : « quel travail Jira met en œuvre cette exigence ? » et « quelles exigences cette demande de modification touche-t-elle ? ». Exécutez la synchronisation après chaque revue des exigences, lorsque de nouvelles exigences atteignent Approved.

Configurer la synchronisation

  1. Dans Holarch, créez un jeton Lecture seule limité au projet. Copiez-le.
  2. Trouvez l'id du projet : GET /api/v1/projects liste vos projets avec leur id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Définissez les variables d'environnement que lit le script :
    • HOLARCH_TOKEN : le jeton Holarch.
    • HOLARCH_PROJECT : l'id du projet.
    • JIRA_URL : votre site Jira, comme https://your-site.atlassian.net.
    • JIRA_EMAIL et JIRA_API_TOKEN : votre e-mail de connexion Atlassian et votre jeton API.
    • JIRA_PROJECT : la clé du projet Jira, comme EO.
  2. Enregistrez le script ci-dessous sous le nom holarch_to_jira.py.

Créer des tickets Jira à partir des exigences approuvées

Le script lit chaque exigence par l'API REST, ignore celles qui ont déjà un ticket Jira et crée une Task pour chaque exigence restante dont le Statut est 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. Exécutez python3 holarch_to_jira.py.

    Vous voyez une ligne par nouveau ticket, comme 2.1 Pointing Accuracy -> EO-12.

Fonctionnement :

  • GET /api/v1/projects/<project>/entities?class=Requirement liste les exigences, 500 à la fois.
  • GET /api/v1/projects/<project>/entities/<id> donne les attributs de chaque exigence (ici Statut) et son url, le lien qui l'ouvre dans Holarch.
  • Chaque ticket reçoit les étiquettes Jira holarch et holarch-<id>. L'exécution suivante les trouve par une recherche Jira et ignore ces exigences.
  • Les exigences sont seulement lues. Le script ne modifie rien dans Holarch.

Conserver la clé Jira dans Holarch (facultatif)

Pour voir la clé Jira sur l'exigence dans Holarch, ajoutez un attribut texte et écrivez-y la clé.

  1. Dans Holarch, ouvrez Paramètres → Schéma, cliquez sur Requirement et ajoutez un attribut nommé Jira Key de type Texte court (Ajouter un attribut à une classe).
  2. Créez un jeton Lecture et écriture pour le script au lieu du jeton en lecture seule.
  3. À la fin de la dernière boucle du script, après la ligne print(…), ajoutez :
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

La modification est écrite comme une modification dans l'application : elle est enregistrée sous votre nom et toutes les personnes qui ont ouvert le projet la voient. Définir cet attribut ne renvoie pas une exigence approuvée en revue. Lorsque le projet utilise le contrôle de configuration, les exigences approuvées refusent les modifications directes (409 change-control) ; conservez la clé uniquement dans Jira, ou faites la modification par une demande de modification.

Transformer un ticket Jira en proposition Holarch avec Claude

Utilisez ceci lorsqu'un ticket Jira demande une modification d'exigence, comme une demande d'un client de resserrer une valeur.

  1. Ouvrez Claude, connecté à Holarch avec l'accès Lire et proposer des modifications.
  2. Demandez par exemple : « Lis le ticket Jira EO-31. Trouve les exigences Holarch du projet CubeSat qu'il concerne, et propose les modifications qu'il demande. Mentionne EO-31 dans le résumé de la proposition. »

    Sans connecteur Jira, collez plutôt le résumé et la description du ticket dans le message.

  3. Claude lit le projet avec list_projects, search_entities et get_entity. Il ajoute chaque modification à une proposition avec update_entity (ou create_entity et relate pour les nouvelles exigences), puis l'envoie avec propose_changes.

    Claude répond avec le titre de la proposition et un lien pour l'examiner.

  4. Dans Holarch, ouvrez ✦ IA ▾ → Examiner « <title> »…, ou la notification sous la cloche.
  5. Vérifiez chaque modification. Décochez ce que vous ne voulez pas, puis cliquez sur Appliquer la sélection.

    Les modifications sont appliquées, et une seule annulation défait le tout. Un texte d'exigence modifié marque ses liens de traçabilité pour revue, et une exigence approuvée revient à In Review, comme pour toute modification.

Les scripts peuvent faire la même proposition sans Claude : POST /api/v1/projects/<project>/proposal/changes une fois par modification, puis POST /api/v1/projects/<project>/proposal avec un title et 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

Exemple complet : la démo CubeSat EO-1

  1. Créez la démonstration avec Gérer les projets → Fichiers de projet ▾ → Nouveau projet de démonstration.
  2. Créez un jeton en lecture seule limité au projet de démonstration, et exécutez holarch_to_jira.py sur un projet Jira de test.

    Chaque exigence approuvée reçoit un ticket, comme 2.1 Pointing Accuracy avec le texte « The ADCS shall point the payload boresight within 0.1 degrees of the commanded target. » et le lien vers l'exigence.

  3. Exécutez de nouveau le script.

    Il n'affiche rien : chaque exigence approuvée a déjà son ticket.

  4. Dans Jira, créez un ticket EO-31 qui demande 0,08 degré au lieu de 0,1 degré. Demandez à Claude de proposer la modification, comme ci-dessus.
  5. Dans Holarch, examinez la proposition. Elle modifie le texte de 2.1 Pointing Accuracy, et sa liste Impact affiche TC-04 Pointing Accuracy Test, qui la vérifie.

Conseils

  • Donnez au script de synchronisation son propre jeton en lecture seule, limité au projet. Donnez à Claude une connexion distincte.
  • Conservez les jetons dans votre coffre de secrets ou dans l'environnement, jamais dans le script.
  • Recherchez dans Jira les exigences derrière un sprint avec l'étiquette holarch.
  • Les numéros d'exigence peuvent changer ; l'étiquette holarch-<id>, non. Faites la correspondance sur l'étiquette, pas sur le numéro du résumé.

Dépannage

Message ou symptômeCause et solution
Holarch answered 401 token-invalidLe jeton est erroné, révoqué ou expiré. Créez-en un nouveau sous Paramètres du compte → Jetons API.
Holarch answered 403 plan-apiL'offre du compte ne comprend pas l'API et MCP. Démarrez l'essai Individual ou choisissez une offre ; le jeton fonctionne alors de nouveau.
Holarch answered 403 org-policyL'organisation du projet a désactivé l'accès API. Adressez-vous à un administrateur de l'organisation.
Holarch answered 403 read-only-tokenL'écriture de Jira Key nécessite un jeton Lecture et écriture.
Holarch answered 400 unknown-attributeLe projet n'a pas d'attribut Jira Key pour Requirement. Ajoutez-le dans Paramètres → Schéma, ou omettez l'étape facultative.
Holarch answered 409 change-controlL'exigence est sous contrôle de configuration. Modifiez-la par une demande de modification, ou conservez la clé uniquement dans Jira.
Holarch answered 429 rate-limitedPlus de 600 requêtes ou 120 modifications par minute. Attendez le nombre de secondes indiqué dans Retry-After, puis relancez ; les tickets déjà créés sont ignorés.
Jira répond 400Jira a refusé les champs du ticket, par exemple un type de ticket que le projet n'a pas. Utilisez l'un des types de tickets du projet au lieu de Task.
Jira répond 401 ou 403Vérifiez JIRA_EMAIL, JIRA_API_TOKEN et votre autorisation de créer des tickets dans le projet Jira.
Claude n'affiche pas les outils d'écriture de HolarchLa connexion est en lecture seule. Connectez-vous de nouveau avec Lire et proposer des modifications, puis démarrez une nouvelle conversation.