Your own connector
Your mission control system (MCS), ground station software or scheduler is not one of ours? Write a connector for it. It is one small program next to your system: it pulls your account's workflow results from Constellation and writes what workflows forecast into your system, the way the Yamcs, COSMOS and Lattice connectors do. It belongs to your account alone: no other Constellation account ever sees it. Delivering to your own connector needs the Operator plan.
your network Constellation (your account only)
───────────────────────────── ──────────────────────────────────────
your bridge + connector.json ─ 1. checks in with its manifest ──▶ "My MCS asks for
│ your results"
│ 2. someone approves it in the Platform
│ 3. a workflow sends it results (an output)
│ ◀── 4. pulls results as its connection ───
▼
your system's API ── 5. reports what it wrote ──▶ the Platform shows it Live, and what it wrote
1. Start from a scaffold
constellation bridge new my-mcs-bridge --lang python # or ts, or go
cd my-mcs-bridge
pip install --require-hashes -r requirements.txt # npm ci for ts, go mod tidy for go
The constellation CLI writes a working bridge: the bridge itself, built on the Bridge base class of the SDK (the results protocol, done), connector.json (your manifest), a test and a Dockerfile. You write two functions: apply(), which writes a run's items into your system, and act(), which carries out an approved action. Build a connector walks through it in Python, TypeScript and Go. In another language, or without the SDK, Receive results is the same loop over plain HTTP.
2. Write the manifest
connector.json names your connector and the settings an operator sets per workflow.
{
"name": "my-mcs-bridge",
"title": "My mission control",
"description": "Forecast passes proposed into my mission control's schedule.",
"version": "0.1.0",
"settings": {
"min_p10_gb": {"type": "number", "title": "Only passes forecast to deliver at least (GB, p10)", "default": 0, "minimum": 0, "maximum": 10000},
"label": {"type": "string", "title": "Label on what the bridge writes", "default": "Constellation forecast", "max_length": 80},
"show_swaps": {"type": "boolean", "title": "Write rain-fade swap advice", "default": true}
}
}
| Field | Rule |
|---|---|
name | Your connection's name and the bridge's consumer: lowercase letters, digits and -, at most 63 characters. Workflows send results to it by this name. |
title, description | What the workflow builder shows: 1 to 80 characters, and up to 300 |
version | Your bridge's version. The bridge sends it as bridge_version and keeps it out of the manifest it checks in with. |
settings | Up to 20, keyed in lowercase snake_case. The workflow builder draws a form from them on each workflow's output. |
Each setting has a type, a title (up to 80 characters), a default, and optionally a description (up to 300):
type | Takes | Bounds |
|---|---|---|
number | Any number | minimum, maximum |
integer | A whole number | minimum, maximum |
boolean | true or false | |
string | Text | max_length: default 200, at most 2,000 |
enum | One of options, 1 to 20 strings |
The default must be a valid value. Constellation checks every workflow's settings against your manifest when the workflow is saved and fills in the defaults for any left out, so your bridge always receives every setting, typed as declared.
Use a setting for what can differ per workflow. Keep what is fixed per install, such as your system's URL and token, in your bridge's own configuration. For something per site, such as which of your antennas a Constellation antenna is, use a string setting your bridge parses, for example comma-separated constellation_id=your_id pairs.
3. Check in, then approve
On start the bridge checks in with POST /predictions/feed/checkin as a custom connector:
{"consumer": "my-mcs-bridge", "system": "custom", "manifest": {"name": "my-mcs-bridge", "title": "...", "description": "...", "settings": {"...": {}}}, "bridge_version": "0.1.0", "target": "My mission control"}
- A name the account has not seen registers the connector as pending. Integrations, Results out lists it as Waiting for approval, and the builder's Deliver to as "My mission control asks for your results", each with Approve and Remove.
- Approving needs a person or key that may edit workflows. The bridge's own key, with only
predictions:read, can propose a connector, never enable one. - A changed manifest, such as a new setting or a changed bound, sends it back to pending, so an operator approves what it now asks for. Checking in with the same manifest changes nothing.
- It lives in the account the key belongs to. Another account never sees it, cannot approve it, and cannot send it a workflow's results.
- Until it is approved, a workflow cannot add it as an output, so no results are sent to it; the bridge keeps polling.
To approve and remove from code: POST /predictions/connectors/{name}/approve with the manifest_sha256 you were shown (409 manifest_changed when the bridge has since sent another), and DELETE /predictions/connectors/{name}. GET /predictions/connectors lists them under custom.
4. What apply() receives
The base class pulls results as your connection and hands apply() each run:
items: the run's results in theconstellation.item/v2shape. A forecast pass hasentity.typepass, its satellite, antenna and station ids,target_at(AOS),until(LOS),value(expected GB asp10,p50andp90),explain(each step's numbers) andentity.track(the ground under the satellite from AOS to LOS). A rain-fade swap is a pass with anaction. With an approve policy an item also carriesaction_status(approved,pendingorrejected; see the protocol). Write every item inapply(); carry out actions only inact(), which receives each approved action once, afterapply(), and never one in any other state.settings: your manifest's settings as the workflow set them, every one present.run: the workflow, its version, the run, and the window it answers for (window_from,window_to). The run is the whole answer for that window: what you wrote for the same workflow inside it thatitemsno longer carries is withdrawn.
apply() returns what it wrote, such as {"passes": 12}. The base class reports it after each run, and the workflow builder shows it on the workflow's output.
5. Rules for what you write
These keep a forecast from ever being mistaken for your own data.
- Never write over your own objects. Write forecasts where your system keeps proposals, plans or forecasts, or as new objects of your own, clearly labelled.
- Propose, never schedule. A forecast pass goes in as proposed, or your system's equivalent; an operator promotes it.
- Label forecasts as forecasts. Name, tag or source everything so an operator reads it as Constellation's forecast at a glance.
- Key writes on
entity.id. A rerun updates what the last run wrote, in place, and withdraws what it no longer carries in its window. - What an operator took is theirs. Once an operator schedules or otherwise takes over a forecast you wrote, stop updating or withdrawing it.
- Retry what may succeed, skip what never will. Raise when your system is unreachable or failing (5xx): the base class retries that run on the next poll and never moves past it. Skip an item your system refuses for good (4xx) and count it in what you report, such as
{"refused": 1}, so one bad item never stops the results.
6. Check it, then go live
constellation conformance -- python bridge.py
The conformance check runs your bridge against a mock Constellation API on your machine, kills it and starts it again. Point the bridge at a test instance of your system: apply() and act() really run. It checks, from the outside, that the bridge checks in with a valid manifest, pulls as its own connection, survives a failed poll, reports each run it applied once, starts at the newest run on a first start, never reports a run in an item shape it was not built for, acts on each approved action exactly once and on nothing else, never past its cancel deadline, acts again on a new approval of the same action, and resumes from its cursor after a restart without acting again. It prints conformant when every check passes. What conformance checks lists all 21.
Then run the bridge against Constellation with a live key that has predictions:read, approve it in the workflow builder, add it as an output to a workflow, and run the workflow.
Contributing a connector
A connector for your own system needs nothing from us but the CLI and an SDK. To add a system Constellation ships to everyone, open a pull request on the connectors repository. Start from the Yamcs or Lattice bridge, in clients/python/src/constellation_space/bridges/, and follow the same rules: pull from the cursor you last applied and keep it in the target system, read only your connection's resources and the item schema you were built for, write idempotently on entity.id, check in and report deliveries, and never fail the loop. It must pass constellation conformance.
Sign off every commit (git commit -s, the Developer Certificate of Origin). The contract comes from Constellation's API as a pinned release, its files under contract/ and their hashes in contract.lock: to propose a change to it, open an issue, and we make it upstream. Report a security problem privately to security@constellation.space, never in a public issue.