Holarch

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.

How to use it →

On this page
  1. Overview
  2. Prerequisites
  3. How to use it
    1. When and why
    2. Set up the sync
    3. Create Jira issues from approved requirements
    4. Keep the Jira key in Holarch (optional)
    5. Turn a Jira issue into a Holarch proposal with Claude
    6. Worked example: the CubeSat EO-1 demo
    7. Tips
  4. Troubleshooting
  5. Related pages

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 requests package (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

  1. In Holarch, create a Read only token limited to the project. Copy it.
  2. Find the project id: GET /api/v1/projects lists your projects with their id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Set the environment variables the script reads:
    • HOLARCH_TOKEN: the Holarch token.
    • HOLARCH_PROJECT: the project id.
    • JIRA_URL: your Jira site, such as https://your-site.atlassian.net.
    • JIRA_EMAIL and JIRA_API_TOKEN: your Atlassian sign-in email and API token.
    • JIRA_PROJECT: the Jira project key, such as EO.
  2. 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}")
  1. 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=Requirement lists the requirements, 500 at a time.
  • GET /api/v1/projects/<project>/entities/<id> gives each requirement's attributes (here Status) and its url, the link that opens it in Holarch.
  • Each issue gets the Jira labels holarch and holarch-<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.

  1. 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).
  2. Create a Read and write token for the script instead of the read-only one.
  3. 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.

  1. Open Claude, connected to Holarch with Read and propose changes access.
  2. 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.

  3. Claude reads the project with list_projects, search_entities and get_entity. It adds each change to a proposal with update_entity (or create_entity and relate for new requirements), then sends it with propose_changes.

    Claude answers with the proposal's title and a link to review it.

  4. In Holarch, open ✦ AI ▾ → Review “<title>”…, or the notification under the bell.
  5. 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

  1. Create the demo with Manage Projects → Project Files ▾ → New Demo Project.
  2. Create a read-only token limited to the demo project, and run holarch_to_jira.py against 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.

  3. Run the script again.

    It prints nothing: every approved requirement already has its issue.

  4. 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.
  5. 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 symptomCause and fix
Holarch answered 401 token-invalidThe token is wrong, revoked or expired. Create a new one under Account Settings → API tokens.
Holarch answered 403 plan-apiThe 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-policyThe project's organization turned API access off. Ask an organization admin.
Holarch answered 403 read-only-tokenThe Jira Key write needs a Read and write token.
Holarch answered 400 unknown-attributeThe project has no Jira Key attribute for Requirement. Add it in Settings → Schema, or drop the optional step.
Holarch answered 409 change-controlThe requirement is under configuration control. Change it through a change request, or keep the key in Jira only.
Holarch answered 429 rate-limitedMore than 600 requests or 120 changes a minute. Wait the seconds in Retry-After, then run again; finished issues are skipped.
Jira answers 400Jira 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 403Check JIRA_EMAIL, JIRA_API_TOKEN and your permission to create issues in the Jira project.
Claude does not show the Holarch write toolsThe connection is read only. Connect again with Read and propose changes, then start a new conversation.