Setup
What you need
- Node 22 or later.
zlib.crc32 and Request.formData are used. The tests were run on Node 24.12. - A MissionSight checkout with
contracts/catalogue. Only to refresh the catalogue: a copy is already in vendor/missionsight.
No database, no Docker, no cloud account and no credentials are needed for anything in this repo today.
Install and check
npm install
npm test
npm run writing # the house writing check over the docs
Run the Collector
COLLECTOR_KEY_BHS_GATEWAY=<a key you make> COLLECTOR_KEY_RELAY=<another> npm start
Each source that signs names the environment variable holding its key (data/sources/<id>.json, signature.key_env). A key is never written to a file in this repo.
- A key that is not set. The source's items are rejected with
not_configured, and GET /health says which key is missing. - The Jira address.
jira.base_url in collector.config.json is empty, so tickets wait with that reason. The demo and the tests start a local stub and point the Collector at it.
Refresh what the repo copies
npm run catalogue:sync -- ~/Forks/missionsight-catalogue # MissionSight's catalogue, with its commit
npm run snapshots # sensor snapshots from data/assets
npm run templates # load templates to templates/out (xlsx, csv, instructions)
The sync refuses a MissionSight checkout with uncommitted changes under contracts/, so the copy always names a real commit.
Thresholds come from the Mission Studio
The Studio is the single source of thresholds. The Interchange reads a local copy of its export (thresholds_file in collector.config.json):
node tools/fetch-thresholds.mjs --from <the folder export's thresholds.json>
node tools/fetch-thresholds.mjs --from http://127.0.0.1:4702/api/studio/projects/<id>/thresholds.json
# the Setup Studio now lives in MissionSight (packages/setup-studio, port 4702). The Causeway branch it moved from
# answers the old address, port 4692, only while that branch still runs.
curl -X POST http://127.0.0.1:4720/thresholds/reload # if the Collector is running
The Studio URL needs a signed-in session: the tool reads the cookie from STUDIO_COOKIE in the environment. Without it, the Studio answers "Sign in first" and the tool stops. The copy is checked against the Studio's schema (vendor/mission-studio), and its project, write time and sha256 show at GET /thresholds.
Only a row with usable: true fires a rule. Anything else is a gap with its reason: no export, no row for the asset class, not confirmed, a different unit, no value. On 7 November the Studio's exports have no usable rows, so every interval trend shows a gap.
The Jira hub: credentials and what it needs
The hub reads the Jira credentials of StellarView's active galaxy, the way StellarView does:
- The galaxy.
hub.jira.galaxy in collector.config.json names one. Otherwise it is the active galaxy in ~/Forks/stellarview/galaxies/registry.json (hub.jira.galaxies_dir). - The settings. They come from that galaxy's own
.env at galaxies/pouches/<id>/.env: JIRA_HOST, JIRA_EMAIL and JIRA_API_TOKEN (required)JIRA_PROJECT_KEY (optional)- Never shown. The token is held in memory, never written to a file in this repo and never printed. A missing key is named; a value never is.
Other settings, each read from the environment:
JIRA_WEBHOOK_SECRET: the secret a Jira admin webhook signs with (hub.jira.webhook_secret_env)I3_WEBHOOK_KEY: the key events from i3 are signed with (hub.i3.webhook_key_env)
The hub makes no call to a real Jira until all of these are in place:
- A test project, to be named, in
hub.jira.test_project. Live mode writes to that project only; a write naming any other project stops with an error. - The galaxy's Jira site with the settings above.
- JSM Assets on that site's plan. Check with Atlassian which plans include it. Also read the site's Assets custom field id into
mappings/types.json (jira.assets_field). - The test project's workflow and issue types, checked against
mappings/rules.json (Approved for work, Resolved, Closed) and mappings/events.json (Incident, Problem, Task). - A webhook from the test site to
POST /hooks/jira, with its secret. Check the signature header there.
For i3, the vendor's interface documents are needed through the Authority (Q-35). Until then the i3 transport stays unknown and every call fails visibly.
What a live Jira test needs
The Jira adapter is built and tested against a local stub and fixtures written to Atlassian's documented response shapes. It has never called a real Jira site. --live is an interface only: node adapters/jira/cli.mjs --live exits with status 1 and prints the list below.
A live test needs:
- A test Jira Service Management project, to be named. Never a client's project.
- The active galaxy's Jira settings, read at run time:
JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN and JIRA_PROJECT_KEY. - That project's ids: its service desk id and its request type ids, to replace the stub values in
adapters/jira/mapping.json. - Its workflow's status names, checked against
status_back.by_status_name in the mapping. A status the mapping does not name comes back as unmapped. - Recorded responses from the test project for the two calls, compared field by field with
adapters/jira/fixtures/.
What is a stub, and what is designed
| Part | State |
|---|
| Jira Service Management requests (the ticket listener) | Adapter built, stub-tested; live mode not built |
| The Jira hub (Assets, issues, webhooks) | Built and tested on the fixture site; live waits for a test project to be named |
| Simplify i3 | The boundary only (adapters/simplify-i3). Its interface is not public (Q-35): transport unknown fails every call visibly; simulated is a labelled stand-in for tests and the demo. |
| Simplify i3 exports | ETL built on provisional column names; confirm with the site's i3 administrator |
| Email, SMS, Teams, Slack | Stub channels; the channel interface is in adapters/alert-channels/interface.mjs |
| The AI judge | Stub (data/ai/stub-judge.json); no model is called |
| The local relay unit | Simulated (tools/relay.mjs); the unit is a design |
| AWS stream, warehouse, analytics jobs | Designs (docs/architecture.md) |
| Rules read from policy documents | Design (docs/document-rules.md) |
| MQTT, BACnet, OPC UA, Modbus gateways | Not built; each will post to POST /collect |