The Jira side of the Interchange
Jira feeds the Interchange from the platform side. The Interchange is ours. 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 |
| Transport: not configured, fixture, live | adapters/jira/client.mjs | Built. Live waits for a test project to be named. |
| 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
- 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. - 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. - 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. - 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 site. live needs a test project to be named. - 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.
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.