Reference
Recipe: Jira
Connect Holarch requirements to Jira issues with the REST API, and turn Jira issues into reviewed Holarch changes through Claude; setup, a sync script, a worked example and troubleshooting.
On this page
Overview
This recipe keeps engineering work in Jira tied to the requirements in Holarch. It has two parts:
- Holarch to Jira (REST API): a script creates one Jira issue for each approved requirement. Each issue links back to the requirement in Holarch. Run it again at any time: it skips requirements that already have an issue.
- Jira to Holarch (MCP, through Claude): Claude reads a Jira issue, such as a customer change request, and proposes the matching requirement changes in Holarch. Nothing changes until you review and apply the proposal in Holarch.
Holarch has no built-in Jira connector. The recipe uses the REST API and MCP, so you can adapt every step.
Prerequisites
- A plan with the API and MCP: Individual or Team, or the Individual trial. On the Free plan, an account with a verified academic email address or in an active class organization also has them (Plans and limits).
- A Holarch project you are an editor or owner of. Proposals need the editor role.
- A personal access token: Account Settings → API tokens → New token. Use Read only for the Holarch-to-Jira script and limit it to the project (Create a token).
- Jira Cloud: a Jira project where you can create issues, and an Atlassian API token (Atlassian account settings → Security → API tokens). Jira Data Center uses the
/rest/api/2/paths and a personal access token instead; check its API reference. - Python 3.9 or later with the
requestspackage (python3 -m pip install requests) for the script. - For the Claude part: Claude connected to Holarch (Connect Holarch to Claude). Claude reads Jira issues itself only when it also has a Jira connector; otherwise paste the issue text into the conversation.
How to use it
When and why
Requirements live in Holarch; the work to build and test them is often planned in Jira. Linking the two answers two questions: "which Jira work implements this requirement?" and "which requirements does this change request touch?". Run the sync after each requirements review, when new requirements reach Approved.
Set up the sync
- In Holarch, create a Read only token limited to the project. Copy it.
- Find the project id:
GET /api/v1/projectslists your projects with theirid.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
- Set the environment variables the script reads:
HOLARCH_TOKEN: the Holarch token.HOLARCH_PROJECT: the project id.JIRA_URL: your Jira site, such ashttps://your-site.atlassian.net.JIRA_EMAILandJIRA_API_TOKEN: your Atlassian sign-in email and API token.JIRA_PROJECT: the Jira project key, such asEO.
- Save the script below as
holarch_to_jira.py.
Create Jira issues from approved requirements
The script reads every requirement through the REST API, skips those that already have a Jira issue, and creates a Task for each remaining requirement whose Status is 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}")
- Run
python3 holarch_to_jira.py.You see one line per new issue, such as
2.1 Pointing Accuracy -> EO-12.
How it works:
GET /api/v1/projects/<project>/entities?class=Requirementlists the requirements, 500 at a time.GET /api/v1/projects/<project>/entities/<id>gives each requirement's attributes (here Status) and itsurl, the link that opens it in Holarch.- Each issue gets the Jira labels
holarchandholarch-<id>. The next run finds them with a Jira search and skips those requirements. - Requirements are only read. The script changes nothing in Holarch.
Keep the Jira key in Holarch (optional)
To see the Jira key on the requirement in Holarch, add a text attribute and write the key into it.
- In Holarch, open Settings → Schema, click Requirement, and add an attribute named Jira Key with the type Short text (Add an attribute to a class).
- Create a Read and write token for the script instead of the read-only one.
- At the end of the script's last loop, after the
print(…)line, add:
holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})
The change is written like an edit in the app: it is recorded under your name and everyone with the project open sees it. Setting this attribute does not send an approved requirement back to review. When the project uses configuration control, approved requirements refuse direct changes (409 change-control); keep the key in Jira only, or make the change through a change request.
Turn a Jira issue into a Holarch proposal with Claude
Use this when a Jira issue asks for a requirement change, such as a customer request to tighten a value.
- Open Claude, connected to Holarch with Read and propose changes access.
- Ask, for example: "Read Jira issue EO-31. Find the Holarch requirements in the CubeSat project that it affects, and propose the changes it asks for. Mention EO-31 in the proposal summary."
Without a Jira connector, paste the issue's summary and description into the message instead.
- Claude reads the project with
list_projects,search_entitiesandget_entity. It adds each change to a proposal withupdate_entity(orcreate_entityandrelatefor new requirements), then sends it withpropose_changes.Claude answers with the proposal's title and a link to review it.
- In Holarch, open ✦ AI ▾ → Review “<title>”…, or the notification under the bell.
- Check each change. Untick what you do not want, then click Apply Selected.
The changes are applied, and a single Undo takes it all back. Changed requirement text marks its trace links for review, and an approved requirement goes back to In Review, as for any edit.
Scripts can make the same proposal without Claude: POST /api/v1/projects/<project>/proposal/changes once per change, then POST /api/v1/projects/<project>/proposal with a title and 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
Worked example: the CubeSat EO-1 demo
- Create the demo with Manage Projects → Project Files ▾ → New Demo Project.
- Create a read-only token limited to the demo project, and run
holarch_to_jira.pyagainst a test Jira project.Each approved requirement gets an issue, such as 2.1 Pointing Accuracy with the text "The ADCS shall point the payload boresight within 0.1 degrees of the commanded target." and the link to the requirement.
- Run the script again.
It prints nothing: every approved requirement already has its issue.
- In Jira, create an issue EO-31 asking for 0.08 degrees instead of 0.1 degrees. Ask Claude to propose the change, as above.
- In Holarch, review the proposal. It changes the text of 2.1 Pointing Accuracy, and its Impact list shows TC-04 Pointing Accuracy Test, which verifies it.
Tips
- Give the sync script its own read-only token, limited to the project. Give Claude a separate connection.
- Keep tokens in your secret store or environment, never in the script.
- Search Jira for the requirements behind a sprint with the label
holarch. - Requirement numbers can change; the
holarch-<id>label does not. Match on the label, not on the number in the summary.
Troubleshooting
| Message or symptom | Cause and fix |
|---|---|
Holarch answered 401 token-invalid | The token is wrong, revoked or expired. Create a new one under Account Settings → API tokens. |
Holarch answered 403 plan-api | The account's plan does not include the API and MCP. Start the Individual trial or choose a plan; the token then works again. |
Holarch answered 403 org-policy | The project's organization turned API access off. Ask an organization admin. |
Holarch answered 403 read-only-token | The Jira Key write needs a Read and write token. |
Holarch answered 400 unknown-attribute | The project has no Jira Key attribute for Requirement. Add it in Settings → Schema, or drop the optional step. |
Holarch answered 409 change-control | The requirement is under configuration control. Change it through a change request, or keep the key in Jira only. |
Holarch answered 429 rate-limited | More than 600 requests or 120 changes a minute. Wait the seconds in Retry-After, then run again; finished issues are skipped. |
| Jira answers 400 | Jira refused the issue fields, for example an issue type the project does not have. Use one of the project's issue types instead of Task. |
| Jira answers 401 or 403 | Check JIRA_EMAIL, JIRA_API_TOKEN and your permission to create issues in the Jira project. |
| Claude does not show the Holarch write tools | The connection is read only. Connect again with Read and propose changes, then start a new conversation. |