संदर्भ
विधि: Jira
REST API से Holarch आवश्यकताओं को Jira issues से कनेक्ट करें, और Claude के ज़रिए Jira issues को समीक्षित Holarch परिवर्तनों में बदलें; सेटअप, सिंक स्क्रिप्ट, एक पूरा उदाहरण और समस्या निवारण।
इस पृष्ठ पर
अवलोकन
यह रेसिपी Jira के इंजीनियरिंग कार्य को Holarch की आवश्यकताओं से जोड़े रखती है। इसके दो हिस्से हैं:
- Holarch से Jira (REST API): एक स्क्रिप्ट हर अनुमोदित आवश्यकता के लिए एक Jira issue बनाती है। हर issue Holarch में आवश्यकता से वापस लिंक होता है। इसे किसी भी समय फिर से चलाएं: यह उन आवश्यकताओं को छोड़ देती है जिनका पहले से issue है।
- Jira से Holarch (MCP, Claude के ज़रिए): Claude किसी Jira issue, जैसे ग्राहक का परिवर्तन अनुरोध, को पढ़ता है और Holarch में संबंधित आवश्यकता परिवर्तन प्रस्तावित करता है। जब तक आप Holarch में प्रस्ताव की समीक्षा करके उसे लागू न करें, कुछ नहीं बदलता।
Holarch में कोई बिल्ट-इन Jira कनेक्टर नहीं है। रेसिपी REST API और MCP का उपयोग करती है, इसलिए आप हर चरण को अपने अनुसार ढाल सकते हैं।
पूर्वापेक्षाएं
- API और MCP वाला प्लान: Individual या Team, या Individual ट्रायल। Free प्लान पर सत्यापित शैक्षणिक ईमेल पते वाले या सक्रिय कक्षा संगठन के खाते के पास भी ये होते हैं (प्लान और सीमाएं)।
- एक Holarch प्रोजेक्ट जिसके आप संपादक या स्वामी हैं। प्रस्तावों के लिए संपादक की भूमिका चाहिए।
- एक पर्सनल एक्सेस टोकन: खाता सेटिंग्स → API टोकन → नया टोकन। Holarch-से-Jira स्क्रिप्ट के लिए केवल पढ़ें का उपयोग करें और इसे प्रोजेक्ट तक सीमित करें (टोकन बनाएं)।
- Jira Cloud: एक Jira प्रोजेक्ट जहाँ आप issue बना सकते हैं, और एक Atlassian API टोकन (Atlassian खाता सेटिंग्स → Security → API tokens)। Jira Data Center इसके बजाय
/rest/api/2/पथ और एक पर्सनल एक्सेस टोकन का उपयोग करता है; उसका API संदर्भ देखें। - स्क्रिप्ट के लिए
requestsपैकेज (python3 -m pip install requests) के साथ Python 3.9 या बाद का संस्करण। - Claude वाले हिस्से के लिए: Holarch से कनेक्ट किया गया Claude (Holarch को Claude से कनेक्ट करें)। Claude स्वयं Jira issue तभी पढ़ता है जब उसके पास Jira कनेक्टर भी हो; अन्यथा issue का टेक्स्ट बातचीत में पेस्ट करें।
इसका उपयोग कैसे करें
कब और क्यों
आवश्यकताएं 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 प्रोजेक्ट key, जैसेEO।
- नीचे दी गई स्क्रिप्ट को
holarch_to_jira.pyके रूप में सहेजें।
अनुमोदित आवश्यकताओं से Jira issue बनाएं
स्क्रिप्ट REST API से हर आवश्यकता पढ़ती है, जिनका पहले से Jira issue है उन्हें छोड़ देती है, और बाकी हर उस आवश्यकता के लिए एक Task बनाती है जिसकी स्थिति 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}")
python3 holarch_to_jira.pyचलाएं।आपको हर नए issue के लिए एक पंक्ति दिखती है, जैसे
2.1 Pointing Accuracy -> EO-12।
यह कैसे काम करता है:
GET /api/v1/projects/<project>/entities?class=Requirementआवश्यकताओं को एक बार में 500 सूचीबद्ध करता है।GET /api/v1/projects/<project>/entities/<id>हर आवश्यकता के एट्रिब्यूट (यहाँ स्थिति) और उसकाurlदेता है, वह लिंक जो उसे Holarch में खोलता है।- हर issue को Jira लेबल
holarchऔरholarch-<id>मिलते हैं। अगला रन उन्हें Jira खोज से ढूंढता है और उन आवश्यकताओं को छोड़ देता है। - आवश्यकताएं केवल पढ़ी जाती हैं। स्क्रिप्ट Holarch में कुछ नहीं बदलती।
Jira key को Holarch में रखें (वैकल्पिक)
Holarch में आवश्यकता पर Jira key देखने के लिए एक टेक्स्ट एट्रिब्यूट जोड़ें और उसमें key लिखें।
- Holarch में सेटिंग्स → स्कीमा खोलें, Requirement पर क्लिक करें, और छोटा टेक्स्ट प्रकार के साथ Jira Key नाम का एक एट्रिब्यूट जोड़ें (किसी क्लास में एट्रिब्यूट जोड़ें)।
- स्क्रिप्ट के लिए केवल-पढ़ने वाले टोकन के बजाय एक पढ़ें और लिखें टोकन बनाएं।
- स्क्रिप्ट के अंतिम लूप के अंत में,
print(…)पंक्ति के बाद, जोड़ें:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
परिवर्तन ऐप में संपादन की तरह लिखा जाता है: यह आपके नाम से दर्ज होता है और प्रोजेक्ट खोले हुए हर व्यक्ति को दिखता है। यह एट्रिब्यूट सेट करने से अनुमोदित आवश्यकता वापस समीक्षा में नहीं जाती। जब प्रोजेक्ट कॉन्फ़िगरेशन नियंत्रण का उपयोग करता है, तो अनुमोदित आवश्यकताएं सीधे परिवर्तन अस्वीकार करती हैं (409 change-control); key को केवल Jira में रखें, या परिवर्तन किसी परिवर्तन अनुरोध से करें।
Claude से Jira issue को Holarch प्रस्ताव में बदलें
इसका उपयोग तब करें जब कोई Jira issue किसी आवश्यकता परिवर्तन की मांग करे, जैसे किसी मान को सख्त करने का ग्राहक अनुरोध।
- पढ़ें और परिवर्तन प्रस्तावित करें पहुँच के साथ Holarch से कनेक्ट किया गया Claude खोलें।
- उदाहरण के लिए पूछें: "Jira issue EO-31 पढ़ें। CubeSat प्रोजेक्ट में वे Holarch आवश्यकताएं ढूंढें जिन्हें यह प्रभावित करता है, और जो परिवर्तन यह मांगता है उन्हें प्रस्तावित करें। प्रस्ताव के सारांश में EO-31 का उल्लेख करें।"
Jira कनेक्टर के बिना, इसके बजाय issue का सारांश और विवरण संदेश में पेस्ट करें।
- Claude
list_projects,search_entitiesऔरget_entityसे प्रोजेक्ट पढ़ता है। वह हर परिवर्तनupdate_entity(या नई आवश्यकताओं के लिएcreate_entityऔरrelate) से एक प्रस्ताव में जोड़ता है, फिर उसेpropose_changesसे भेजता है।Claude प्रस्ताव के शीर्षक और उसकी समीक्षा के लिंक के साथ उत्तर देता है।
- Holarch में ✦ AI ▾ → “<title>” की समीक्षा करें… खोलें, या घंटी के नीचे की सूचना।
- हर परिवर्तन जांचें। जो नहीं चाहिए उससे टिक हटाएं, फिर चयनित लागू करें पर क्लिक करें।
परिवर्तन लागू होते हैं, और एक ही बार पूर्ववत करने से सब वापस हो जाता है। बदला गया आवश्यकता टेक्स्ट उसके ट्रेस लिंक को समीक्षा के लिए चिह्नित करता है, और अनुमोदित आवश्यकता वापस In Review में जाती है, जैसे किसी भी संपादन के लिए।
स्क्रिप्ट Claude के बिना वही प्रस्ताव बना सकती हैं: हर परिवर्तन के लिए एक बार 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चलाएं।हर अनुमोदित आवश्यकता को एक issue मिलता है, जैसे 2.1 Pointing Accuracy, टेक्स्ट "The ADCS shall point the payload boresight within 0.1 degrees of the commanded target." और आवश्यकता के लिंक के साथ।
- स्क्रिप्ट फिर से चलाएं।
यह कुछ नहीं छापती: हर अनुमोदित आवश्यकता का पहले से issue है।
- Jira में 0.1 डिग्री के बजाय 0.08 डिग्री मांगने वाला एक issue EO-31 बनाएं। ऊपर की तरह Claude से परिवर्तन प्रस्तावित करने को कहें।
- Holarch में प्रस्ताव की समीक्षा करें। यह 2.1 Pointing Accuracy का टेक्स्ट बदलता है, और इसकी प्रभाव सूची TC-04 Pointing Accuracy Test दिखाती है, जो इसे सत्यापित करता है।
सुझाव
- सिंक स्क्रिप्ट को उसका अपना केवल-पढ़ने वाला टोकन दें, प्रोजेक्ट तक सीमित। Claude को एक अलग कनेक्शन दें।
- टोकन को अपने सीक्रेट स्टोर या एनवायरनमेंट में रखें, स्क्रिप्ट में कभी नहीं।
- लेबल
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 | आवश्यकता कॉन्फ़िगरेशन नियंत्रण में है। इसे परिवर्तन अनुरोध से बदलें, या key को केवल Jira में रखें। |
Holarch answered 429 rate-limited | एक मिनट में 600 से अधिक अनुरोध या 120 परिवर्तन। Retry-After में दिए सेकंड प्रतीक्षा करें, फिर से चलाएं; पूरे हो चुके issue छोड़ दिए जाते हैं। |
| Jira 400 लौटाता है | Jira ने issue फ़ील्ड अस्वीकार कर दिए, उदाहरण के लिए ऐसा issue type जो प्रोजेक्ट में नहीं है। Task के बजाय प्रोजेक्ट के issue type में से किसी एक का उपयोग करें। |
| Jira 401 या 403 लौटाता है | JIRA_EMAIL, JIRA_API_TOKEN और Jira प्रोजेक्ट में issue बनाने की अपनी अनुमति जांचें। |
| Claude Holarch के लिखने वाले टूल नहीं दिखाता | कनेक्शन केवल-पढ़ने वाला है। पढ़ें और परिवर्तन प्रस्तावित करें के साथ फिर से कनेक्ट करें, फिर नई बातचीत शुरू करें। |