roboto.domain.dashboards#

Saved metrics dashboards for visualizing an organization’s data on the Roboto platform.

A dashboard is a named JSON document describing the sections, cards, and time parameters the web UI renders, stored on the platform so it can be reopened and shared. The platform stores that document verbatim and never interprets it: the definition is self-describing, carrying its own schema version for whichever client understands the schema. Ownership (owner_principal_id) is the sole source of truth for visibility: a dashboard owned by the org principal is shared with every member of the owning organization, while one owned by a user principal is personal (visible only to that user). Create and update requests express the choice via the accessibility knob, which the server folds into ownership. Dashboard names must be unambiguous for each viewer within their organization.

Submodules#

Package Contents#

class roboto.domain.dashboards.CreateDashboardRequest(/, **data)#

Bases: pydantic.BaseModel

Request body for POST /v1/metrics/dashboards/create.

Parameters:: data (Any)

accessibility: roboto.domain.dashboards.record.DashboardAccessibility#: Whether the dashboard is org-wide or personal. The server derives owner_principal_id from this — the org principal for organization, the creator’s user principal for user — and ownership is the stored source of truth; this field is not persisted separately.

dashboard_definition: dict[str, Any]#: The dashboard definition as a JSON object. Stored verbatim and never interpreted by the platform; it carries its own schema version for the clients that read it.

name: str = None#: The name of the dashboard.

class roboto.domain.dashboards.DashboardAccessibility#

Bases: roboto.compat.StrEnum

Controls who can view a dashboard.

On create/update requests this is a knob that the server folds into DashboardRecord.owner_principal_id. On DashboardRecord it is a derived computed field — always in sync with the owner principal so API consumers never need to parse the principal string themselves.

Organization = 'organization'#: All members of the organization owning the dashboard can view it.

User = 'user'#: Just the user who created the dashboard can view it.

class roboto.domain.dashboards.DashboardRecord(/, **data)#

Bases: pydantic.BaseModel

A wire-transmissible representation of a dashboard

Parameters:: data (Any)

property accessibility: DashboardAccessibility#

organization when owned by the org principal, user otherwise.

Type:: Derived from owner_principal_id
Return type:: DashboardAccessibility

created: datetime.datetime#: Timestamp when the dashboard was created.

created_by: str#: User ID of the dashboard’s creator. Audit metadata only; ownership is carried by owner_principal_id.

dashboard_definition: dict[str, Any]#

The dashboard definition as a JSON object.

Opaque to the platform, which stores and returns it verbatim. The definition is self-describing: it carries its own schema version, and the client that understands the schema is the one that reads it.

dashboard_id: str#: Unique identifier for the dashboard.

modified: datetime.datetime#: Timestamp when the dashboard was last modified.

modified_by: str#: User ID of the last user to modify the dashboard.

name: str#: Human-readable name for the dashboard. Unique per owner within an organization; dashboards with different owners may share a name, so by-name lookups can match more than one dashboard.

org_id: str#: Organization ID that owns the dashboard.

owner_principal_id: str#

Principal that owns the dashboard, serialized in the RobotoPrincipal ptype:id format.

org:<org_id> for organization-wide dashboards, user:<user_id> for personal dashboards. This is the sole source of truth for org-wide vs personal — a dashboard is org-wide exactly when its owner is the org principal. Ownership anchors authorization — a personal dashboard is editable by its owner or an org admin, an org-wide dashboard by any org member — and scopes name uniqueness: dashboard names are unique per owner within an organization.

revision: int = 0#

How many times the dashboard definition has been written, starting at 0.

A definition-generation counter, not a row version: it advances only when dashboard_definition is replaced, and is deliberately untouched by a rename or an accessibility change. Clients never set it — the server owns it — but they must echo the value they loaded back as base_revision when writing a new definition, so a write built on a stale copy can be rejected rather than silently erasing someone else’s edit.

class roboto.domain.dashboards.UpdateDashboardRequest(/, **data)#

Bases: pydantic.BaseModel

Request body for PUT /v1/metrics/dashboards/id/<dashboard_id>.

Parameters:: data (Any)

accessibility: roboto.domain.dashboards.record.DashboardAccessibility | roboto.sentinels.NotSetType#: Whether the dashboard should become org-wide or personal. The server re-derives owner_principal_id from this — to the org principal for organization, back to the creator’s user principal for user; ownership is the stored source of truth.

base_revision: int | roboto.sentinels.NotSetType = None#

The revision you loaded — not the revision you want.

Required when dashboard_definition is present, and rejected otherwise. The server compares it against the stored revision and rejects the write if the definition has been replaced in the meantime, so a save built on a stale copy cannot silently erase someone else’s edit. A rename or accessibility change carries no base revision: neither touches the definition, so neither can clobber it.

dashboard_definition: dict[str, Any] | roboto.sentinels.NotSetType#: The dashboard definition as a JSON object. Replaces the stored definition wholesale; it carries its own schema version, so no separate version field accompanies it.

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str | roboto.sentinels.NotSetType = None#: The name of the dashboard.

validate_base_revision_with_definition()#

Require a base revision for definition writes, and only for definition writes.

The presence checks use NotSetType rather than truthiness: base_revision=0 is the commonest real value — a dashboard whose definition has never been rewritten — and a falsy test would reject exactly that.

Return type:: UpdateDashboardRequest