参考
实践示例:Jira
通过 REST API 将 Holarch 需求连接到 Jira 问题,并借助 AI 应用将 Jira 问题转为经评审的 Holarch 变更;涵盖设置、同步脚本、完整示例和故障排除。
本页内容
概述
本实践示例将 Jira 中的工程工作与 Holarch 中的需求关联起来。它分为两部分:
- Holarch 到 Jira(REST API):脚本为每个已审批的需求创建一个 Jira 问题。每个问题都链接回 Holarch 中的需求。可随时再次运行:已有问题的需求会被跳过。
- Jira 到 Holarch(MCP,通过 AI 应用):AI 应用读取一个 Jira 问题(例如客户变更请求),并在 Holarch 中提议相应的需求更改。在您于 Holarch 中评审并应用提议之前,不会有任何更改。
Holarch 没有内置的 Jira 连接器。本实践示例使用 REST API 和 MCP,因此每一步都可以按需调整。
前提条件
- 包含 API 和 MCP 的方案:Individual 或 Team,或 Individual 试用。在 Free 方案中,拥有已验证学术邮箱地址或属于活跃班级组织的账户也可使用它们(方案和限制)。
- 一个 Holarch 项目,您是其编辑者或所有者。提议需要编辑者角色。
- 个人访问令牌:账户设置 → API 令牌 → 新令牌。为 Holarch 到 Jira 的脚本使用只读,并将其限制在该项目内(创建令牌)。
- Jira Cloud:一个您可以在其中创建问题的 Jira 项目,以及一个 Atlassian API 令牌(Atlassian 账户设置 → Security → API tokens)。Jira Data Center 则使用
/rest/api/2/路径和个人访问令牌;请查阅其 API 参考。 - 用于运行脚本的 Python 3.9 或更高版本及
requests包(python3 -m pip install requests)。 - AI 应用部分:已连接到 Holarch 的 AI 应用(将 Holarch 连接到 AI 应用)。只有在该 AI 应用还拥有 Jira 连接器时,它才能自己读取 Jira 问题;否则请将问题文本粘贴到对话中。
如何使用
何时使用及原因
需求存放在 Holarch 中;构建和测试它们的工作通常在 Jira 中规划。将两者关联可以回答两个问题:“哪些 Jira 工作实现了这个需求?”和“这个变更请求涉及哪些需求?”。每次需求评审之后、新需求达到 Approved 时,运行同步。
设置同步
- 在 Holarch 中创建一个限制在该项目内的只读令牌。复制它。
- 查找项目 ID:
GET /api/v1/projects列出您的项目及其id。
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- 设置脚本读取的环境变量:
HOLARCH_TOKEN:Holarch 令牌。HOLARCH_PROJECT:项目 ID。JIRA_URL:您的 Jira 站点,例如https://your-site.atlassian.net。JIRA_EMAIL和JIRA_API_TOKEN:您的 Atlassian 登录邮箱和 API 令牌。JIRA_PROJECT:Jira 项目键,例如EO。
- 将下面的脚本另存为
holarch_to_jira.py。
根据已审批的需求创建 Jira 问题
该脚本通过 REST API 读取每个需求,跳过已有 Jira 问题的需求,并为其余状态为 Approved 的每个需求创建一个 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}")
- 运行
python3 holarch_to_jira.py。每个新问题显示一行,例如
2.1 Pointing Accuracy -> EO-12。
工作原理:
GET /api/v1/projects/<project>/entities?class=Requirement列出需求,每次 500 个。GET /api/v1/projects/<project>/entities/<id>给出每个需求的属性(此处为状态)及其url,即在 Holarch 中打开它的链接。- 每个问题都会获得 Jira 标签
holarch和holarch-<id>。下次运行时通过 Jira 搜索找到它们,并跳过这些需求。 - 需求只会被读取。脚本不会更改 Holarch 中的任何内容。
在 Holarch 中保存 Jira 键(可选)
要在 Holarch 的需求上看到 Jira 键,请添加一个文本属性并将键写入其中。
- 在 Holarch 中打开设置 → 架构,点击 Requirement,然后添加一个名为 Jira Key、类型为短文本的属性(为类添加属性)。
- 为脚本创建一个读写令牌,代替只读令牌。
- 在脚本最后一个循环的末尾、
print(…)行之后,添加:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
该更改与应用中的编辑一样写入:以您的名义记录,所有打开该项目的人都能看到。设置此属性不会将已审批的需求退回评审。当项目使用配置控制时,已审批的需求会拒绝直接更改(409 change-control);请只在 Jira 中保存该键,或通过变更请求进行更改。
借助 AI 应用将 Jira 问题转化为 Holarch 提议
当 Jira 问题要求更改需求时(例如客户要求收紧某个值),请使用此方法。
- 打开以读取并提出更改访问权限连接到 Holarch 的 AI 应用。
- 例如,可以询问:“读取 Jira 问题 EO-31。在 CubeSat 项目中找出它影响的 Holarch 需求,并提议它所要求的更改。在提议摘要中提及 EO-31。”
没有 Jira 连接器时,请改为将问题的摘要和描述粘贴到消息中。
- AI 应用使用
list_projects、search_entities和get_entity读取项目。它用update_entity(对于新需求,用create_entity和relate)将每项更改添加到提议中,然后用propose_changes发送。AI 应用会回复提议的标题和评审链接。
- 在 Holarch 中打开 ✦ AI ▾ → 评审“<title>”…,或铃铛下的通知。
- 检查每项更改。取消勾选不需要的内容,然后点击应用所选项。
这些更改会被应用,一次撤销即可全部撤回。更改的需求文本会将其追溯关联标记为待审查,已审批的需求会退回 In Review,与任何编辑一样。
脚本无需 AI 应用也能提出相同的提议:每项更改 POST 一次 /api/v1/projects/<project>/proposal/changes,然后带 title 和 summary POST /api/v1/projects/<project>/proposal。
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
实例:CubeSat EO-1 演示
- 通过管理项目 → 项目文件 ▾ → 新建演示项目创建演示。
- 创建一个限制在演示项目内的只读令牌,并针对一个测试 Jira 项目运行
holarch_to_jira.py。每个已审批的需求都会得到一个问题,例如 2.1 Pointing Accuracy,文本为“The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.”,并附有指向该需求的链接。
- 再次运行脚本。
它不输出任何内容:每个已审批的需求都已有其问题。
- 在 Jira 中创建一个问题 EO-31,要求将 0.1 度改为 0.08 度。按上述方法让 AI 应用提议该更改。
- 在 Holarch 中评审该提议。它更改 2.1 Pointing Accuracy 的文本,其影响列表显示验证它的 TC-04 Pointing Accuracy Test。
提示
- 为同步脚本提供其自己的只读令牌,并限制在该项目内。为 AI 应用提供单独的连接。
- 将令牌保存在您的密钥存储或环境变量中,绝不要写在脚本里。
- 在 Jira 中用标签
holarch搜索某个冲刺背后的需求。 - 需求编号可能会变;
holarch-<id>标签不会变。请按标签匹配,而不是按摘要中的编号匹配。
故障排除
| 消息或症状 | 原因和解决方法 |
|---|---|
Holarch answered 401 token-invalid | 令牌错误、已撤销或已到期。请在账户设置 → API 令牌下创建新令牌。 |
Holarch answered 403 plan-api | 账户的方案不包含 API 和 MCP。请开始 Individual 试用或选择方案;之后令牌即可再次使用。 |
Holarch answered 403 org-policy | 项目所属组织已关闭 API 访问。请联系组织管理员。 |
Holarch answered 403 read-only-token | 写入 Jira Key 需要读写令牌。 |
Holarch answered 400 unknown-attribute | 项目中 Requirement 没有 Jira Key 属性。请在设置 → 架构中添加它,或省略这一可选步骤。 |
Holarch answered 409 change-control | 该需求处于配置控制之下。请通过变更请求更改它,或只在 Jira 中保存该键。 |
Holarch answered 429 rate-limited | 每分钟超过 600 个请求或 120 次更改。请等待 Retry-After 中的秒数,然后再次运行;已完成的问题会被跳过。 |
| Jira 返回 400 | Jira 拒绝了问题字段,例如项目中没有的问题类型。请使用项目中的某个问题类型代替 Task。 |
| Jira 返回 401 或 403 | 请检查 JIRA_EMAIL、JIRA_API_TOKEN 以及您在该 Jira 项目中创建问题的权限。 |
| AI 应用不显示 Holarch 写入工具 | 该连接为只读。请以读取并提出更改重新连接,然后开始新的对话。 |