roboto.experimental.boards.board#

Module Contents#

class roboto.experimental.boards.board.Board(record, roboto_client=None)#

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:

record (roboto.experimental.boards.record.BoardRecord)
roboto_client (Optional[roboto.http.RobotoClient])

property accessibility: roboto.experimental.boards.record.BoardAccessibility#

only its owner and the organization’s admins, or every member.

Type:: Who can open this board
Return type:: roboto.experimental.boards.record.BoardAccessibility

property board_id: str#

Unique identifier of this board.

Return type:: str

classmethod create(definition, name=None, caller_org_id=None, roboto_client=None)#

Create a board that is personal to the caller.

Parameters:

definition (Union[roboto.experimental.boards.definition.BoardDefinition, dict[str, Any]]) – 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.http.RobotoClient]) – Roboto client instance. Uses the default if omitted.

Returns:

The board.

Raises:

RobotoIllegalArgumentException – No name is given and the definition has no title to take one from. Raised before any request is made.
pydantic.ValidationError – name 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.
RobotoConflictException – The caller already owns a board with this name in the organization.
RobotoFeatureNotAvailableException – Boards are not available to the caller.

Return type:

Board

Examples

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'

property created: datetime.datetime#

Timestamp when this board was created.

Return type:: datetime.datetime

property created_by: str#

User ID of this board’s creator.

Return type:: str

property definition: dict[str, Any]#

This board’s definition as a JSON object.

The object is a copy, so changing it does not change this board. Pass a changed copy to update() to save it.

Return type:: dict[str, Any]

delete()#

Delete this board.

Raises:

RobotoNotFoundException – The board no longer exists.
RobotoUnauthorizedException – 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:

None

Examples

>>> from roboto.experimental.boards import Board
>>> Board.from_id("bd_abc123").delete()

classmethod for_org(org_id=None, roboto_client=None)#

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.http.RobotoClient]) – Roboto client instance. Uses the default if omitted.

Yields:

Each of those boards.

Raises:

RobotoFeatureNotAvailableException – Boards are not available to the caller.

Return type:

collections.abc.Generator[Board, None, None]

Examples

>>> from roboto.experimental.boards import Board
>>> for board in Board.for_org():
...     print(board.name)

classmethod from_id(board_id, roboto_client=None)#

Load a board by ID.

Parameters:

board_id (str) – Unique identifier of the board.
roboto_client (Optional[roboto.http.RobotoClient]) – Roboto client instance. Uses the default if omitted.

Returns:

The board.

Raises:

RobotoNotFoundException – No board with this ID exists, or the caller cannot open it.
RobotoFeatureNotAvailableException – Boards are not available to the caller.

Return type:

Board

Examples

>>> from roboto.experimental.boards import Board
>>> board = Board.from_id("bd_abc123")
>>> board.name
'Event overview'

property modified: datetime.datetime#

Timestamp when this board was last modified.

Return type:: datetime.datetime

property modified_by: str#

User ID of the last user to modify this board.

Return type:: str

property name: str#

The name the board list and board page show.

Return type:: str

property org_id: str#

ID of the organization that owns this board.

Return type:: str

property owner_principal_id: str#

org:<org_id> for a shared board, user:<user_id> for a personal one.

Type:: Principal that owns this board
Return type:: str

property record: roboto.experimental.boards.record.BoardRecord#

The wire-transmissible representation of this board.

Return type:: roboto.experimental.boards.record.BoardRecord

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:: RobotoNotFoundException – The board no longer exists, or the caller can no longer open it.
Return type:: Board

Examples

>>> from roboto.experimental.boards import Board
>>> board = Board.from_id("bd_abc123")
>>> board.refresh().revision
4

property revision: int#

How many times this board’s definition had been written when this instance last read it.

Return type:: int

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:

RobotoConflictException – The organization already has a shared board with this name.
RobotoNotFoundException – The board no longer exists.
RobotoUnauthorizedException – The board is personal, and the caller is neither its owner nor an admin of its organization.

Return type:

Board

Examples

>>> from roboto.experimental.boards import Board
>>> board = Board.from_id("bd_abc123").share_with_org()
>>> board.accessibility
<BoardAccessibility.Organization: 'organization'>

update(definition=NotSet, name=NotSet)#

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.experimental.boards.definition.BoardDefinition, dict[str, Any], roboto.sentinels.NotSetType]) – 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.sentinels.NotSetType]) – 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.ValidationError – Neither 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.
RobotoBoardRevisionConflictException – The board’s definition was written after this instance last read it.
RobotoConflictException – The board’s owner already has another board with this name.
RobotoNotFoundException – The board no longer exists.
RobotoUnauthorizedException – The board is personal, and the caller is neither its owner nor an admin of its organization.

Return type:

Board

Examples

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)