roboto.experimental.boards
Boards a person builds on the Roboto platform and opens again from anywhere.
A board is a named JSON document, stored on the platform, describing panels arranged on a canvas and the stages that provide their data. A board is either personal to the user who owns it or shared with every member of its organization.
Submodules
Package Contents
Board
A board: panels arranged on a canvas, and the stages that provide their data.
A board is stored on the platform as a named JSON document, its definition, which the Roboto web app reads to draw the board. A board is created personal to its creator, and share_with_org() shares it with every member of its organization. Sharing a board does not share data: each viewer sees only the data they could already reach.
A definition is given either as a BoardDefinition, which checks the definition’s outline as it is built, or as a dict. A dict is refused before any request is made if BoardDefinition refuses its top level. The panels and stages in a definition are stored as given.
Each write of a board’s definition advances its revision. update() sends the revision this instance last read, so a change made from an outdated copy of the board is refused instead of replacing someone else’s edit.
Parameters
roboto_client Optional[roboto.Properties
Board.accessibility
Who can open this board: only its owner and the organization’s admins, or every member.
Board.create()
Create a board that is personal to the caller.
Parameters
definition Union[roboto.The board’s definition.
name Optional[str]The name the board list and board page show. Defaults to the definition’s title. When both are given they must match.
caller_org_id Optional[str]Organization to create the board in. Required when the caller belongs to more than one.
roboto_client Optional[roboto.Roboto client instance. Uses the default if omitted.
Returns
The board.
Raises
No name is given and the definition has no title to take one from. Raised before any request is made.
pydantic.ValidationErrorname is empty, is longer than 120 characters, or differs from the definition’s title, or BoardDefinition refuses the definition’s top level. Raised before any request is made.
The caller already owns a board with this name in the organization.
Boards are not available to the caller.
Usage
Check a definition’s outline, then save it as a board named after its title:
from roboto.experimental.boards import Board, BoardDefinition
definition = BoardDefinition.model_validate(
{
"schema_version": 1,
"title": "Event overview",
"time_range": "90d",
"stages": [
{
"id": "stage-event-counts",
"name": "EventCounts",
"body": {
"kind": "entity.query",
"target": "events",
"aggregate": {"op": "count", "groupBy": "name"},
},
}
],
"panels": [
{
"kind": "table",
"id": "event-counts-table",
"bindings": [{"name": "event_counts", "stage": "stage-event-counts"}],
}
],
}
)
board = Board.create(definition)
board.name
# 'Event overview'Properties
Board.created
Timestamp when this board was created.
Board.delete()
Delete this board.
Raises
The board no longer exists.
The caller is not an admin of the board’s organization, and the board is shared or is another member’s personal board.
Return type
Usage
from roboto.experimental.boards import Board
Board.from_id("bd_abc123").delete()Board.for_org()
List an organization’s shared boards and the caller’s own personal boards, ordered by name.
Another member’s personal board is never listed. An admin of the organization can still load one with from_id().
Parameters
org_id Optional[str]Organization whose boards to list. Required when the caller belongs to more than one.
roboto_client Optional[roboto.Roboto client instance. Uses the default if omitted.
Yields
Each of those boards.
Raises
Boards are not available to the caller.
Return type
Usage
from roboto.experimental.boards import Board
for board in Board.for_org():
print(board.name)Board.from_id()
Load a board by ID.
Parameters
board_id strUnique identifier of the board.
roboto_client Optional[roboto.Roboto client instance. Uses the default if omitted.
Returns
The board.
Raises
No board with this ID exists, or the caller cannot open it.
Boards are not available to the caller.
Usage
from roboto.experimental.boards import Board
board = Board.from_id("bd_abc123")
board.name
# 'Event overview'Properties
Board.modified
Timestamp when this board was last modified.
Board.owner_principal_id
Principal that owns this board: org:<org_id> for a shared board, user:<user_id> for a personal one.
Board.record
The wire-transmissible representation of this board.
Board.refresh()
Re-read this board from the platform, replacing every property backed by its record.
Call it when something other than this instance may have changed the board, for example before retrying an update() that was refused because the board had changed.
Returns
This board.
Raises
The board no longer exists, or the caller can no longer open it.
Usage
from roboto.experimental.boards import Board
board = Board.from_id("bd_abc123")
board.refresh().revision
# 4Properties
Board.revision
How many times this board’s definition had been written when this instance last read it.
Board.share_with_org()
Share this board with every member of its organization, permanently.
Ownership moves to the organization, and no request makes a shared board personal again. From then on every member can open and change the board, and only an admin of the organization can delete it. The definition and the revision stay as they are.
Returns
This board.
Raises
The organization already has a shared board with this name.
The board no longer exists.
The board is personal, and the caller is neither its owner nor an admin of its organization.
Usage
from roboto.experimental.boards import Board
board = Board.from_id("bd_abc123").share_with_org()
board.accessibility
# <BoardAccessibility.Organization: 'organization'>Board.update()
Replace this board’s definition, rename it, or both.
The change is made only if the board is still at the revision this instance last read. Otherwise it is refused with RobotoBoardRevisionConflictException, whose current_board holds the stored board’s record as a JSON object. Call refresh(), apply the change to the refreshed definition, and update again.
Parameters
definition Union[roboto.The definition that replaces the stored one whole. When it has a title and no name is given, the board takes the title as its name.
name Union[str, roboto.The board’s new name. A title the stored definition already has is rewritten to match. When a definition with a title is also given, the two must match.
Returns
This board.
Raises
pydantic.ValidationErrorNeither a definition nor a name is given, name is empty or longer than 120 characters, name differs from the given definition’s title, or BoardDefinition refuses the definition’s top level. Raised before any request is made.
The board’s definition was written after this instance last read it.
The board’s owner already has another board with this name.
The board no longer exists.
The board is personal, and the caller is neither its owner nor an admin of its organization.
Usage
Change the time range a board opens with:
from roboto.experimental.boards import Board
board = Board.from_id("bd_abc123")
definition = board.definition
definition["time_range"] = "30d"
board = board.update(definition=definition)BoardAccessibility
Bases: roboto.compat.StrEnum
Who can open a board.
A new board is user: only the user who created it and the organization’s admins can open it. Sharing it with UpdateBoardAccessRequest makes it organization, for good: every member of the organization can then open and edit it. BoardRecord.accessibility says which applies to a board.
BoardCalendar
Bases: _DefinitionPart
The time zone a board reads its times in, and the day its weeks start on.
The Roboto web app shows every time on the board in this zone, and divides time into days, weeks and other calendar periods in it, with weeks beginning on week_start: for a chart’s time units and weekly groups, for the rows a click on one of those periods selects, and for the periods of a metric aggregate. The bounds of a custom time_range, each a date ("2026-09-06") or a date and time written without a zone or offset ("2026-09-06T14:00"), are read in this zone too.
Parameters
data AnyAttributes
BoardCalendar.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
BoardCalendar.time_zone
The zone’s name in the IANA time zone database, in the database’s letter case, such as "America/Los_Angeles". This model does not check the name. The web app reports the definition as invalid when the name is not in the database, is an offset such as "+05:30", is written in another letter case such as "america/los_angeles", or is CET, EET, MET or WET, which Roboto reads as fixed offsets without daylight saving time when it aggregates metrics; name such a zone by area and location instead, such as "Europe/Paris" for CET.
BoardCalendar.week_start
The day the board’s weeks start on.
BoardColumnControlDomain
Bases: _DefinitionPart
A value control’s choices taken from the distinct values of a column in the result of the one stage the control reads.
Parameters
data AnyBoardControlFilterBody
Bases: _DefinitionPart
Keeps the rows of the stage’s first input that match the values chosen in the value control it reads second.
The stage’s inputs name the data stage and then the value control. A control that is not required and has no value filters nothing.
Parameters
data AnyAttributes
BoardControlFilterBody.column
The column of the data stage’s result that the filter compares with the chosen values.
BoardControlFilterBody.columnHolds
What the column holds: value, a value of the control’s type, which matches when it is a chosen value; or entity-id, the id of an entity of the control’s entity-field domain, which matches when that entity’s field holds a chosen value. value when absent.
BoardControlOption
Bases: _DefinitionPart
One choice a value control lists, and the label the control shows for it.
Parameters
data AnyBoardDefinition
Bases: _DefinitionPart
A board definition whose outline is checked as the model is built.
The platform refuses a definition whose top level this model refuses, with the entries of panels and stages set aside, and stores the panels and stages in it as given; the web app decides what a definition means when it opens the board. This model checks a definition’s outline:
- the top-level keys, the calendar’s members, and the keys every panel, stage, section and selection carries;
- the members of a control or control-filter stage, and how many inputs it names;
- that no two stages share an id;
- that each stage a panel or another stage names is declared;
- that a control-filter reads a data stage (a stage that is not a control), then a value control.
It does not check what lies deeper, such as a stage’s query or a chart’s specification, nor whether the calendar’s time zone is one the web app accepts, so the web app can still report a definition this model accepts, or a panel or stage in it, as invalid.
At the top level and in the calendar, a key the models do not declare is refused, as the web app refuses it. Elsewhere below the top level, such a key is kept as given. An optional key left as None is omitted when the model is serialized.
Parameters
data AnyAttributes
BoardDefinition.calendar
The time zone the board reads its times in, and the day its weeks start on. Without one, the board reads its times in UTC and its weeks start on Monday.
BoardDefinition.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
BoardDefinition.selections
Named selections that panels publish to and filter by.
BoardDefinition.stages
The stages that provide the panels’ data, and the controls above the canvas.
BoardDefinition.time_range
The time range the board opens with: a preset such as "90d", or a JSON object describing a custom or relative range.
BoardDefinition.title
The board’s title. The platform keeps a board’s name equal to a title that is a non-empty string.
BoardDefinition.validate_stage_ids_and_references()
Reject a reused stage id, a reference to an undeclared stage, and a control-filter reading the wrong stages.
A control-filter reads a data stage, then a value control. A control-filter input that names no stage, or an id several stages share, is reported only as an undeclared or a reused stage id.
Return type
BoardEntityFieldControlDomain
Bases: _DefinitionPart
A value control’s choices taken from the values a field holds on one kind of entity.
Parameters
data AnyAttributes
BoardEntityFieldControlDomain.field
The field, for example name, or custom.<field_name> for a custom field.
BoardEntityFieldControlDomain.kind
Marks the choices as an entity field’s values.
BoardEntityFieldControlDomain.target
The kind of entity, for example sessions or devices.
BoardFieldControlBody
Bases: _DefinitionPart
A control above the canvas in which a viewer chooses which field a chart or query reads.
The fields it offers belong to exactly one kind of entity (target) or one topic (topic). The stage reads no input.
Parameters
data AnyAttributes
BoardFieldControlBody.default
The field the control holds when the board opens and the board’s URL has no control.<name> key for the control, and after the control is reset to its default from the control bar.
BoardFieldControlBody.options
The fields the control lists, when it lists fewer than its entity or topic has.
BoardFieldControlBody.target
The kind of entity whose fields the control offers, for example sessions.
BoardFieldControlBody.topic
The name of the topic whose fields the control offers.
BoardFieldControlBody.validate_target_or_topic()
Reject a field control that declares both or neither of a target and a topic.
Return type
BoardFieldControlOption
Bases: _DefinitionPart
One field a field control lists, and the label the control shows for it.
Parameters
data AnyBoardPanel
Bases: _DefinitionPart
A panel on the board’s canvas: a chart, a table, or a map.
Only the keys every panel carries are checked. Everything else a panel holds, such as its title, its placement on the canvas and a chart’s spec, is kept as given and is not checked.
Parameters
data AnyAttributes
BoardPanel.bindings
The stage results the panel draws. A panel has at least one.
BoardPanelBinding
Bases: _DefinitionPart
One stage’s result, under the name a panel draws it by.
Parameters
data AnyBoardRecord
Bases: pydantic.BaseModel
A wire-transmissible representation of a board.
Parameters
data AnyProperties
BoardRecord.accessibility
Computed from owner_principal_id: organization when the org principal owns the board, user otherwise.
Attributes
BoardRecord.board_definition
The board definition as a JSON object, describing panels arranged on a canvas and the stages that provide their data.
The definition carries its own schema version for the clients that read it. The platform writes only its top-level title, which is kept equal to name while it is a non-empty string. A request is refused when BoardDefinition refuses its definition’s top level. The panels and stages inside are stored as sent, so a panel or stage that a client cannot parse comes back unchanged, and a person can fix it in the board’s JSON editor.
The platform stores the definition as parsed JSON, so it may return keys in a different order, keep only the last of a duplicated key, and write a number differently from how it was sent.
BoardRecord.created_by
User ID of the board’s creator. Audit metadata only; ownership is carried by owner_principal_id.
BoardRecord.name
Human-readable name for the board, which the board list and board page show. Unique per owner within an organization; boards with different owners may share a name, so by-name lookups can match more than one board.
BoardRecord.owner_principal_id
Principal that owns the board, serialized in the RobotoPrincipal ptype:id format.
org:<org_id> for a board shared with the organization, user:<user_id> for a personal board. The owner alone decides who can open the board: any member of the organization for a shared board, the owning user or an org admin for a personal one. Board names are unique per owner within an organization.
BoardRecord.revision
How many times the board’s definition content has been written, starting at 0.
The server advances it on each write of definition content: a new definition, or a rename that rewrites the definition’s title. Sharing a board, and renaming one whose definition has no title, leave it unchanged. Clients never set it. They send the value they loaded back as base_revision when writing definition content, so the server can reject a write built on an outdated revision instead of erasing someone else’s edit.
BoardSection
Bases: _DefinitionPart
A titled region of the canvas. A panel joins a section by naming the section in its own placement.
Parameters
data AnyAttributes
BoardSelection
Bases: _DefinitionPart
A named selection that panels publish to and filter by.
Parameters
data AnyBoardStage
Bases: _DefinitionPart
One stage of the board’s data: a query of the platform, a transformation of other stages’ results, a control above the canvas whose result is the value a viewer chooses, or a filter of a stage’s rows by such a control.
Parameters
data AnyAttributes
BoardStage.body
What the stage does.
BoardStage.id
Identifies the stage within the board, so no two stages of a board share an id. Panels and other stages refer to the stage by it. Starts with a letter or digit, and holds only letters, digits, underscores and hyphens.
BoardStage.name
The name the stage’s result goes by, for example as a table in another stage’s SQL. Starts with a letter or digit, and holds only letters, digits, underscores and hyphens. A control’s name is also what a $name reference names, so it starts with a letter and holds only letters, digits and underscores.
BoardStage.read_body_as_its_kind()
Read a body as the model of its kind, so a mistake in it is reported at the key it was made in.
Parameters
body AnyReturn type
BoardStage.validate_control_name_and_inputs()
Reject a control name a $name reference cannot hold, and a control or control-filter with wrong inputs.
A control reads no input, except a value control whose choices are a column’s values, which reads the one stage holding the column. A control-filter reads a data stage and then a value control.
Return type
BoardStageBody
Bases: _DefinitionPart
What a stage does, for a kind of stage this module has no model of.
Each kind of stage has its own keys, which are kept as given and are not checked. A control or a control-filter is read as BoardValueControlBody, BoardFieldControlBody or BoardControlFilterBody instead.
Parameters
data AnyAttributes
BoardStaticControlDomain
Bases: _DefinitionPart
A value control’s choices listed in the definition.
Parameters
data AnyAttributes
BoardStaticControlDomain.options
The choices the control lists, in order.
BoardValueControlBody
Bases: _DefinitionPart
A control above the canvas in which a viewer chooses one or several values of a type.
The stage’s result is the chosen values. A control-filter stage that reads it keeps the rows of its data stage that match the choice, and SQL text, stage expressions, chart specifications and panel titles read the choice as $name, where name is the stage’s name. The stage reads no input, except the one stage whose column a BoardColumnControlDomain lists.
Parameters
data AnyAttributes
BoardValueControlBody.default
The value the control holds when the board opens and the board’s URL has no control.<name> key for the control, and after the control is reset to its default from the control bar or by the reset operation of a control interaction: one tagged JSON object, or a list of them when multi is true.
BoardValueControlBody.domain
Where the control’s choices come from. Absent, the viewer types the value.
BoardValueControlBody.label
The control’s caption. Absent or blank, the caption is the display name of the entity field the control takes its choices from (a custom field’s display name, a catalog field’s display name such as “Device ID” for device_id, or a metadata path as written), or else the stage’s name.
BoardValueControlBody.multi
Whether the viewer may choose several values. False when absent.
BoardValueControlBody.required
Whether the stages and panels that read the control wait for a value. False when absent, and a control that is not required and has no value filters nothing.
BoardValueControlBody.validate_default_matches_multi()
Reject a default that is a list when the control holds one value, or one value when it holds several.
Return type
Attributes
BoardValueControlBody.valueType
The type of the values the control holds, as a JSON object with a type, for example {"type": "string"}.
BoardValueControlDomain
Where a value control’s choices come from.
CreateBoardRequest
Bases: pydantic.BaseModel
Request body for POST /v1/boards/create.
The board is personal: the caller owns it. UpdateBoardAccessRequest shares it with the organization.
Parameters
data AnyAttributes
CreateBoardRequest.board_definition
The board definition as a JSON object, stored as board_definition describes. A top-level title that is a non-empty string must equal name, and a request in which they differ fails validation. A definition with no title is stored without one.
A definition whose top level BoardDefinition refuses fails validation: for example, one with an unknown top-level key, a missing time_range or panels, a panels that is not a list, a stages that is neither a list nor null, a title that is neither a string nor null, or a malformed section or selection. The panels and stages in it are not checked and are stored as given, so the web app can show a broken one beside the rest of the board.
CreateBoardRequest.name
The name the board list and board page show. Must not be empty: an empty name shows nothing in the board list, and the platform keeps a name equal to a definition title only while the title is a non-empty string.
CreateBoardRequest.validate_definition_top_level()
Reject a definition whose top level BoardDefinition refuses.
Parameters
board_definition dict[str, Any]Return type
CreateBoardRequest.validate_name_and_title_agree()
Reject a name that differs from the definition’s non-empty title.
Return type
UpdateBoardAccessRequest
Bases: pydantic.BaseModel
Request body for PUT /v1/boards/id/<board_id>/access.
Shares a board with the organization, permanently: ownership moves to the org principal. The definition and revision stay unchanged. No request makes a shared board personal again; to get a personal board, create a new board from a copy of this board’s definition.
Parameters
data AnyAttributes
UpdateBoardAccessRequest.accessibility
Must be organization, which moves ownership to the org principal. A request for user accessibility fails validation.
UpdateBoardRequest
Bases: pydantic.BaseModel
Request body for PUT /v1/boards/id/<board_id>.
Carries a new name, new definition content, or both. UpdateBoardAccessRequest changes who can open a board.
Parameters
data AnyAttributes
UpdateBoardRequest.base_revision
The revision you loaded (revision), not the revision you want.
Required whenever the request writes definition content: a board_definition replacement, or a name for a board whose stored definition has a title that is a non-empty string, since keeping the two equal rewrites that title. The record you loaded shows which case applies.
The server compares a supplied base revision with the stored revision, on a rename that writes no definition content as well, and rejects a mismatch with RobotoBoardRevisionConflictException, so a save built on an outdated revision cannot erase someone else’s edit.
UpdateBoardRequest.board_definition
board_definition Annotated[dict[str, Any], ValidatedAgainst(BoardDefinition)] | roboto.The board definition as a JSON object, replacing the stored one whole. A top-level title that is a non-empty string is kept equal to the board’s name: with no name in the request, the board takes the title as its name. A definition with no title leaves the name alone, and the platform never adds a title.
A definition whose top level BoardDefinition refuses fails validation: for example, one with an unknown top-level key, a missing time_range or panels, a panels that is not a list, a stages that is neither a list nor null, a title that is neither a string nor null, or a malformed section or selection. The panels and stages in it are not checked and are stored as given, so the web app can show a broken one beside the rest of the board.
UpdateBoardRequest.model_config
model_config #Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
UpdateBoardRequest.name
name Annotated[str, pydantic.The name of the board. Rewrites a title the stored definition already has, and never adds one.
Must not be empty: the platform keeps the name equal to a definition title only while the title is a non-empty string, so an empty name written into the title would leave the two unequal, and no later rename could make them equal again. To keep the name, omit the field.
UpdateBoardRequest.validate_at_least_one_change()
Reject a request with neither name nor board_definition, which would change nothing.
Return type
UpdateBoardRequest.validate_base_revision_with_definition()
Require base_revision with a board_definition.
A rename of a board whose stored definition has a title needs one too. The server enforces that case, since only the stored board shows whether the title is there.
Return type
UpdateBoardRequest.validate_definition_top_level()
Reject a definition whose top level BoardDefinition refuses.
Parameters
board_definition Union[dict[str, Any], roboto.Return type
UpdateBoardRequest.validate_name_and_title_agree()
Reject a request whose name differs from its definition’s non-empty title.
The platform keeps the two equal, and such a request gives it no basis for choosing between them.
Return type
definition_title()
Return the definition’s top-level title when it is a non-empty string, else None.
BoardRecord.name is kept equal to the title this returns. A null or empty title is stored as sent, leaves the name alone, and reads here as None. A request whose title is any other kind of value is refused.
Parameters
board_definition dict[str, Any]Return type