# dashboards/

Superset dashboards as code and the operator scripts that import them. Not baked into the
image, so changes here do not rebuild or restart Superset.

- `atoma/`: ATOMA's two dashboards for the Petrolyst app (PD-12, PD-13; SPEC.md §10):
  `overview` (fleet totals) and `site` (one site, its four sections as tabs), named `atoma-overview` and `atoma-site` until 30 Oct. The
  app embeds them; admins open them in Superset, with the filter column. `SPEC.md` is the
  design; `build_bundle.py` generates the import bundle and `import_bundle.py` imports it
  (overwriting the objects the bundle defines).

  Build and import:

      docker cp atoma/import_bundle.py petrolyst-superset-1:/tmp/
      docker exec petrolyst-superset-1 /app/.venv/bin/python /tmp/import_bundle.py --show-database
      python3 atoma/build_bundle.py --database-uuid <printed uuid> --out atoma-dashboards.zip
      docker cp atoma-dashboards.zip petrolyst-superset-1:/tmp/
      docker exec petrolyst-superset-1 /app/.venv/bin/python /tmp/import_bundle.py /tmp/atoma-dashboards.zip --user <username>

  Exit status 2 means a dataset's columns differ from its view: regenerate `atoma/columns.tsv`
  (command in its header), rebuild and import again.

  An import never deletes. Where they exist, delete these by hand after importing: the
  dashboards from before 28 Oct ("ATOMA - Sites", "ATOMA - Site Detail") and their charts M1,
  M3, M4 and M5; the ATOMA dashboard (slug `atoma`, retired 29 Oct with PD-13) and its chart D0
  "Site"; the one-tab dashboards `atoma-site-summary`, `-fuel`, `-runtime` and `-baseline`
  (replaced by `atoma-site` on 29 Oct); and the role "ATOMA Reader".

  The dashboards get no role; the app shows them with guest passes (see "Embedding" in the
  parent README; local stack only). Add `--embedded-out FILE --embed-domain <app origin>` to the
  import to make them embeddable from the app's origin; FILE then receives
  `{slug: embedding id}` for the Petrolyst server. The ids stay the same across imports. Local
  stack:

      docker exec fmdb-scratch-superset /app/.venv/bin/python /tmp/import_bundle.py /tmp/atoma-dashboards.zip \
          --user admin --embedded-out /tmp/embedded-dashboards.json --embed-domain http://127.0.0.1:8098
      docker cp fmdb-scratch-superset:/tmp/embedded-dashboards.json <Petrolyst>/.local/fmdb-scratch/

Export from a running instance (inside the container, as the server's deploy user):

    docker exec petrolyst-superset-1 superset export-dashboards -f /tmp/dashboards.zip
    docker cp petrolyst-superset-1:/tmp/dashboards.zip .

Import is the reverse with `superset import-dashboards -p <zip> -u <username>`. The
username must be an existing Superset user, which here means someone who has signed in
through Keycloak at least once.