roboto.experimental.boards.board
Module 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)