# The Jira hub

Jira is the Interchange's primary hub. It is off the shelf and known by many, and its APIs are easy to build on. The owner's systems stay
the systems of record (RFP 2027-006, section 1.1). The hub copies and links, and it changes a record in another
system only where a rule says so and a person has acted.

**State, 7 November 2026: built and tested on fixtures. No real Jira and no real i3 has been called.**

## The parts

| Part | Where | State |
| --- | --- | --- |
| Credentials, read as StellarView reads them | `adapters/jira/credentials.mjs` | Built; tested on a test galaxy folder of dummy values |
| JSM Assets: schema, object types, attributes, objects | `adapters/jira/assets.mjs` | Built; tested on the fixture site |
| Issues linked to Assets objects | `adapters/jira/issues.mjs` | Built; tested on the fixture site |
| Webhooks in | `adapters/jira/webhook.mjs` | Built; the signature header is to confirm on the test site |
| The fixture site | `adapters/jira/fixture-site.mjs` | Answers in Atlassian's published shapes; nothing recorded live |
| Simplify i3 | `adapters/simplify-i3/` | The boundary only (Q-35). See its README. |
| Mappings: tags, types, rules, events | `mappings/`, `contracts/mappings/` | Data, versioned, each with its source |
| Flows | `src/hub/hub.mjs` | Built; tested both ways |
| The AI hook | `docs/ai-hook.md`, `prompts/ai/` | The hook is built; the call is StellarView's to implement |

## The flows

1. **Interchange to Jira.** An event updates the target's JSM Assets object. When a chosen path names jira, the event
   also opens a Jira issue linked to that object. The issue type and priority come from `mappings/events.json`, and
   the labels and components from `mappings/tags.json`. While the hub is on, the older ticket listener stands aside.
2. **Jira to i3.** A person moves the issue to Approved for work. The webhook arrives, and rule `approved-to-i3`
   sends the work order to i3 with a comment on the issue.
3. **i3 to Jira.** An i3 event arrives at `POST /hooks/i3` and becomes an Interchange event: a `cmms.*` type in the
   catalogue, through the one contract. Rule `i3-completed` then comments, moves the issue to Resolved, updates the
   Assets object and raises an AI request.
4. **A person accepts.** `POST /hub/accept/<key>` closes the issue and tells i3. Jira never closes itself.

## Rules

Rules live in `mappings/rules.json`. The rules that match a message apply in priority order (higher first), then by
id. A value no map names stops the message, and so do two rules writing different values to one field. Neither is a
guess. A disabled rule says why: `asset-edit-to-i3` is off because i3 is the system of record for assets.

## Every hop

Each hop writes a line to `hub-evidence.jsonl` with:
- the flow, the step and the attempt
- its label: fixture, simulated or real
- the version and sha256 of each mapping used

A hop whose system cannot be reached is retried (`hub.retry.attempts`). If it still fails, the message is parked
with its error and the actions still to do. `GET /hub/parked` lists parked messages, and
`POST /hub/parked/<id>/retry` resumes one where it stopped.

## Turning it on

Set `hub.enabled` in `collector.config.json`. Then choose the transports:
- **Jira:** `not_configured` is the default, and every call fails visibly. `fixture` uses the in-process fixture
- **i3:** `unknown` is the default, and every call fails visibly (Q-35). `simulated` is for tests and the demo.

`npm run demo:jira` runs the round trip on fixtures.

## The product catalogue in Assets and Jira

**State, 8 November 2026: built and tested on the fixture site only. No real Jira has been called.**

The product catalogue (product-catalogue@1, in `missionsight-product-catalogue`) says what equipment a site has and
what a plan would add. `mappings/catalogue.json` maps it onto JSM Assets and Jira as data, checked against
`contracts/mappings/catalogue.schema.json`:
- Each installed base item becomes an Installed item object. It carries its class, maker, model, installed date,
  count, zone, 3D component, site, installed base version and sources.
- Each catalogue model a placement names becomes a Catalogue model object. It carries its maker, kind, status, price
  band, documents and sources.
- Each placement of one plan option becomes a proposed install issue, linked to the Installed item it serves. A
  person decides in Jira. The issue is never an order.

A value the catalogue holds as `not_known` is written as "not known", with its reason and what would answer it. Every
object carries a Data label attribute, and every issue a label, saying it was written to the fixture site.

The input is a snapshot file, the same one the Exploder build reads (`studio/catalogue.py pull` in the exploder kit).
The catalogue's tenant routes take signed calls only, so a snapshot keeps the run reproducible and keeps the key out
of this repository.

```bash
npm run demo:catalogue -- <snapshot.json> [--option recommended]
```

The run refuses any Jira transport but the fixture site. It writes what it made to `evidence/catalogue-fixture-*.json`.
`test/catalogue.test.mjs` runs it on a cut of the snapshot in `test/fixtures/catalogue-snapshot.json`.
