Skip to content

Account Manifest

Everything that configures a Busroot account lives in one JSON document: the account manifest. Plants, station groups, stations, shift patterns, reasons, SKUs, Tasks, feature flags and account-wide settings are all sections of this single document — there is no separate configuration store behind the admin pages.

There are two ways the manifest is managed:

  • Through the admin UI (the default). Every admin page — Account, Plants, Stations, SKUs, Shift Patterns, Reasons — reads and writes a section of the manifest on your behalf. Most users never need to look at the document itself.
  • As a whole document. Output Industries operators can replace an account's entire manifest in one operation through the configuration API — used to set up a new account or migrate configuration between environments.

Document structure

The configuration hierarchy is account → plants → station groups → stations, with groups and stations nested inline under their parents. Shift patterns, reasons, Tasks and SKUs are defined once at the account level and referenced by code from elsewhere in the document.

{
  "version": "v1",
  "account": {
    "id": "account_0000000000000000000",
    "domain": "example.com",
    "currency": "GBP",
    "shiftPatterns": [ { "code": "24-7", "title": "24/7", "shifts": [ ... ] } ],
    "reasons":       [ { "code": "mechanical", "description": "Mechanical", "type": ["downtime"] } ],
    "tasks":         [ ... ],
    "taskLists":     [ ... ],
    "skus":          [ { "code": "WIDGET-001", "name": "Widget Type A", "unitsPerHour": 120 } ],
    "plants": [
      {
        "code": "plant1",
        "name": "Plant 1",
        "timezone": "Europe/London",
        "dayStartHour": 6,
        "stationGroups": [
          {
            "code": "line-1",
            "name": "Line 1",
            "shiftPatternCode": "24-7",
            "stations": [
              { "code": "STATION1", "name": "Station 1" }
            ]
          }
        ]
      }
    ]
  }
}

version is always "v1".

Every field in every section is documented in the Schema Reference, and what each setting does to the rest of the platform is covered in How Manifest Settings Drive Busroot.

Codes are identifiers

Every entity in the manifest carries a code — a short identifier used wherever one part of the configuration refers to another. A station group names its shift pattern with shiftPatternCode; a production schedule names its SKU with a SKU code; include/exclude lists name reason and Task codes. Codes are for referencing; the name, title and description fields are what people see.

Warning

Station codes are permanent. A station's code is the physical key that ties all of its recorded history — production, downtime, energy — to the station. Renaming a station's code orphans everything recorded under the old one. Change the name freely; never change the code of a station that has data. See How Manifest Settings Drive Busroot.

Validation

The manifest is validated every time it is read and every time it is saved:

  • Unknown fields are rejected. Every object in the schema is strict, so a misspelled field name is an error rather than silently ignored.
  • Cross-references must resolve. A shiftPatternCode must name an existing shift pattern; includeReasonCodes/excludeReasonCodes must name existing reasons (children of nested reasons count); includeTaskCodes/excludeTaskCodes and a SKU's Task codes must name existing Tasks; totalEnergyStationCodes must name non-archived stations in the same plant (or the same group, for a group-level list).
  • A code cannot be both included and excluded at the same level.
  • A station cannot be both meter-only and scheduling-only.
  • New station codes must be unique across the whole account. Creating a station whose code is already in use — case-insensitively, and including archived stations, whose historical data survives archiving so their codes stay reserved — is rejected.

A manifest that fails validation is rejected rather than stored, so the account keeps running on the configuration it already had.

The JSON Schema

The manifest's machine-readable definition is published as a JSON Schema, with every field's description included:

  • manifest.schema.json — the schema for the current Busroot release, served alongside this documentation.
  • Every running Busroot instance also serves its own copy at /manifest.schema.json — that is the version to trust for a specific deployment.

When changes take effect

A saved change applies immediately to the web app and API, and within about a minute to background processing — data aggregation and the handling of incoming device messages. That is true however the change was made: through the admin UI or through the configuration API. No service is restarted for a manifest change.

In this section