Referencia
Receta: Jira
Conecte requisitos de Holarch con incidencias de Jira mediante la API REST y convierta incidencias de Jira en cambios revisados de Holarch a través de Claude; configuración, un script de sincronización, un ejemplo práctico y solución de problemas.
Resumen
Esta receta mantiene el trabajo de ingeniería en Jira ligado a los requisitos de Holarch. Tiene dos partes:
- De Holarch a Jira (API REST): un script crea una incidencia de Jira por cada requisito aprobado. Cada incidencia enlaza de vuelta con el requisito en Holarch. Ejecútelo de nuevo en cualquier momento: omite los requisitos que ya tienen una incidencia.
- De Jira a Holarch (MCP, mediante Claude): Claude lee una incidencia de Jira, como una solicitud de cambio de un cliente, y propone los cambios de requisitos correspondientes en Holarch. Nada cambia hasta que usted revisa y aplica la propuesta en Holarch.
Holarch no tiene un conector de Jira integrado. La receta usa la API REST y MCP, por lo que puede adaptar cada paso.
Requisitos previos
- Un plan con la API y MCP: Individual o Team, o la prueba de Individual. En el plan Free, una cuenta con una dirección de correo académica verificada o en una organización de clase activa también los tiene (Planes y límites).
- Un proyecto de Holarch del que sea editor o propietario. Las propuestas necesitan el rol de editor.
- Un token de acceso personal: Ajustes de la cuenta → Tokens de API → Nuevo token. Use Solo lectura para el script de Holarch a Jira y limítelo al proyecto (Crear un token).
- Jira Cloud: un proyecto de Jira en el que pueda crear incidencias, y un token de API de Atlassian (ajustes de la cuenta de Atlassian → Security → API tokens). Jira Data Center usa en su lugar las rutas
/rest/api/2/y un token de acceso personal; consulte su referencia de la API. - Python 3.9 o posterior con el paquete
requests(python3 -m pip install requests) para el script. - Para la parte de Claude: Claude conectado a Holarch (Conectar Holarch a Claude). Claude lee las incidencias de Jira por sí mismo solo cuando también tiene un conector de Jira; en caso contrario, pegue el texto de la incidencia en la conversación.
Cómo usarlo
Cuándo y por qué
Los requisitos están en Holarch; el trabajo para construirlos y probarlos se planifica a menudo en Jira. Vincular ambos responde a dos preguntas: «¿qué trabajo de Jira implementa este requisito?» y «¿qué requisitos afecta esta solicitud de cambio?». Ejecute la sincronización después de cada revisión de requisitos, cuando requisitos nuevos lleguen a Approved.
Configurar la sincronización
- En Holarch, cree un token de Solo lectura limitado al proyecto. Cópielo.
- Busque el id del proyecto:
GET /api/v1/projectsenumera sus proyectos con suid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Establezca las variables de entorno que lee el script:
HOLARCH_TOKEN: el token de Holarch.HOLARCH_PROJECT: el id del proyecto.JIRA_URL: su sitio de Jira, comohttps://your-site.atlassian.net.JIRA_EMAILyJIRA_API_TOKEN: el correo electrónico con el que inicia sesión en Atlassian y su token de API.JIRA_PROJECT: la clave del proyecto de Jira, comoEO.
- Guarde el script siguiente como
holarch_to_jira.py.
Crear incidencias de Jira a partir de requisitos aprobados
El script lee todos los requisitos mediante la API REST, omite los que ya tienen una incidencia de Jira y crea una Task para cada requisito restante cuyo Estado es 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}")
- Ejecute
python3 holarch_to_jira.py.Verá una línea por cada incidencia nueva, como
2.1 Pointing Accuracy -> EO-12.
Cómo funciona:
GET /api/v1/projects/<project>/entities?class=Requirementenumera los requisitos, de 500 en 500.GET /api/v1/projects/<project>/entities/<id>da los atributos de cada requisito (aquí Estado) y suurl, el enlace que lo abre en Holarch.- Cada incidencia recibe las etiquetas de Jira
holarchyholarch-<id>. La siguiente ejecución las encuentra con una búsqueda de Jira y omite esos requisitos. - Los requisitos solo se leen. El script no cambia nada en Holarch.
Guardar la clave de Jira en Holarch (opcional)
Para ver la clave de Jira en el requisito en Holarch, añada un atributo de texto y escriba en él la clave.
- En Holarch, abra Ajustes → Esquema, haga clic en Requirement y añada un atributo llamado Jira Key con el tipo Texto corto (Añadir un atributo a una clase).
- Cree un token de Lectura y escritura para el script en lugar del de solo lectura.
- Al final del último bucle del script, después de la línea
print(…), añada:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
El cambio se escribe como una edición en la aplicación: se registra con su nombre y todos los que tienen el proyecto abierto lo ven. Establecer este atributo no devuelve a revisión un requisito aprobado. Cuando el proyecto usa control de configuración, los requisitos aprobados rechazan los cambios directos (409 change-control); guarde la clave solo en Jira o haga el cambio mediante una solicitud de cambio.
Convertir una incidencia de Jira en una propuesta de Holarch con Claude
Use esto cuando una incidencia de Jira pide un cambio de requisito, como la solicitud de un cliente de ajustar un valor.
- Abra Claude, conectado a Holarch con el acceso Leer y proponer cambios.
- Pida, por ejemplo: «Lee la incidencia de Jira EO-31. Busca los requisitos de Holarch del proyecto CubeSat a los que afecta y propón los cambios que pide. Menciona EO-31 en el resumen de la propuesta.»
Sin un conector de Jira, pegue en su lugar el resumen y la descripción de la incidencia en el mensaje.
- Claude lee el proyecto con
list_projects,search_entitiesyget_entity. Añade cada cambio a una propuesta conupdate_entity(ocreate_entityyrelatepara requisitos nuevos) y después la envía conpropose_changes.Claude responde con el título de la propuesta y un enlace para revisarla.
- En Holarch, abra ✦ IA ▾ → Revisar «<título>»…, o la notificación de la campana.
- Compruebe cada cambio. Desmarque lo que no quiera y haga clic en Aplicar seleccionados.
Los cambios se aplican, y un solo Deshacer lo revierte todo. El texto cambiado de un requisito marca sus vínculos de trazabilidad para revisión, y un requisito aprobado vuelve a In Review, como en cualquier edición.
Los scripts pueden hacer la misma propuesta sin Claude: POST /api/v1/projects/<project>/proposal/changes una vez por cambio y después POST /api/v1/projects/<project>/proposal con un title y 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
Ejemplo práctico: la demostración CubeSat EO-1
- Cree la demo con Gestionar proyectos → Archivos de proyecto ▾ → Nuevo proyecto de demostración.
- Cree un token de solo lectura limitado al proyecto de demostración y ejecute
holarch_to_jira.pycon un proyecto de Jira de prueba.Cada requisito aprobado recibe una incidencia, como 2.1 Pointing Accuracy con el texto «The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.» y el enlace al requisito.
- Ejecute el script de nuevo.
No imprime nada: cada requisito aprobado ya tiene su incidencia.
- En Jira, cree una incidencia EO-31 que pida 0,08 grados en lugar de 0,1 grados. Pida a Claude que proponga el cambio, como antes.
- En Holarch, revise la propuesta. Cambia el texto de 2.1 Pointing Accuracy, y su lista Impacto muestra TC-04 Pointing Accuracy Test, que lo verifica.
Consejos
- Dé al script de sincronización su propio token de solo lectura, limitado al proyecto. Dé a Claude una conexión aparte.
- Guarde los tokens en su almacén de secretos o en el entorno, nunca en el script.
- Busque en Jira los requisitos que hay detrás de un sprint con la etiqueta
holarch. - Los números de requisito pueden cambiar; la etiqueta
holarch-<id>no. Busque por la etiqueta, no por el número del resumen.
Solución de problemas
| Mensaje o síntoma | Causa y solución |
|---|---|
Holarch answered 401 token-invalid | El token es incorrecto, está revocado o caducado. Cree uno nuevo en Ajustes de la cuenta → Tokens de API. |
Holarch answered 403 plan-api | El plan de la cuenta no incluye la API ni MCP. Inicie la prueba de Individual o elija un plan; el token vuelve entonces a funcionar. |
Holarch answered 403 org-policy | La organización del proyecto desactivó el acceso por API. Pregunte a un administrador de la organización. |
Holarch answered 403 read-only-token | La escritura de Jira Key necesita un token de Lectura y escritura. |
Holarch answered 400 unknown-attribute | El proyecto no tiene ningún atributo Jira Key para Requirement. Añádalo en Ajustes → Esquema, u omita el paso opcional. |
Holarch answered 409 change-control | El requisito está bajo control de configuración. Cámbielo mediante una solicitud de cambio, o guarde la clave solo en Jira. |
Holarch answered 429 rate-limited | Más de 600 solicitudes o 120 cambios por minuto. Espere los segundos indicados en Retry-After y vuelva a ejecutar; las incidencias ya creadas se omiten. |
| Jira responde 400 | Jira rechazó los campos de la incidencia, por ejemplo un tipo de incidencia que el proyecto no tiene. Use uno de los tipos de incidencia del proyecto en lugar de Task. |
| Jira responde 401 o 403 | Compruebe JIRA_EMAIL, JIRA_API_TOKEN y su permiso para crear incidencias en el proyecto de Jira. |
| Claude no muestra las herramientas de escritura de Holarch | La conexión es de solo lectura. Conéctese de nuevo con Leer y proponer cambios y después inicie una conversación nueva. |