參考資料
範例做法: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 議題的需求,並為其餘 Status 為 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>會提供每個需求的屬性(此處為 Status)及其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.08 度取代 0.1 度。依上述方式請 AI 應用程式提議變更。
- 在 Holarch 中審查提議。它會變更 2.1 Pointing Accuracy 的文字,其影響清單會顯示驗證它的 TC-04 Pointing Accuracy Test。
提示
- 為同步指令碼提供專屬的唯讀權杖,並限制在該專案。為 AI 應用程式提供另一個獨立的連線。
- 將權杖保存在您的密鑰存放區或環境中,絕不放在指令碼裡。
- 以標籤
holarch在 Jira 中搜尋某個衝刺背後的需求。 - 需求編號可能會變更;
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 寫入工具 | 連線為唯讀。請以讀取並提出變更重新連線,然後開始新的對話。 |