AirfieldpathOrlando Sanford International

5.7 · The Interchange · Documents

Setup

What each connection needs before it can run live.

No picture for this component.

Document · The Interchange · Documents

Setup

What each connection needs before it can run live.

  1. Sources
  2. Interchange
  3. Twin
  4. Screens
  5. Plan
Kind
Document
Status
not linked
Airport layer
not linked
Airport area
not linked
System
not linked
Sensor type
not linked

Open the detail

Level 2 of 3 This component, complete on its own. Its files, sources and tests are the detail below. Open the detail

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:

  1. 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.
  2. The galaxy's Jira site with the settings above.
  3. 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).
  4. 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).
  5. 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:

  1. A test Jira Service Management project, to be named. Never a client's project.
  2. The active galaxy's Jira settings, read at run time: JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN and JIRA_PROJECT_KEY.
  3. That project's ids: its service desk id and its request type ids, to replace the stub values in adapters/jira/mapping.json.
  4. 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.
  5. 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

PartState
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 i3The 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 exportsETL built on provisional column names; confirm with the site's i3 administrator
Email, SMS, Teams, SlackStub channels; the channel interface is in adapters/alert-channels/interface.mjs
The AI judgeStub (data/ai/stub-judge.json); no model is called
The local relay unitSimulated (tools/relay.mjs); the unit is a design
AWS stream, warehouse, analytics jobsDesigns (docs/architecture.md)
Rules read from policy documentsDesign (docs/document-rules.md)
MQTT, BACnet, OPC UA, Modbus gatewaysNot built; each will post to POST /collect

Source file

FileSizesha256
SETUP.md6 KBd3a5a03d703c1fe97d1ab783517284c3921647356990c7f38fb868c4ed9c0461