Blackboard service
The blackboard is a key-value store that powers
Dataflow, for example between skills during
process execution. Skills or Python script nodes can write their return value to the blackboard and
other skills or Python script nodes can consume these return values to inform their own execution. The
blackboard service
(ExecutiveBlackboard) gives
programmatic access to the entire blackboard when needed.
The blackboard facilitates data flow during execution. Thus writing to the blackboard during process execution via the blackboard service is not possible. Reading values is designed for debugging and introspection. Skill implementations must only use their provided parameters as inputs and never read from the blackboard directly.
Blackboard values
A blackboard is always linked to a loaded operation. Thus all calls to the blackboard service must include the name of the operation that the request pertains to. Likewise deleting an operation also deletes all blackboard values associated with that operation.
The main identifier for a value in the blackboard is its key. This could for example be the name of the return value of a skill.
In addition, each blackboard value has a scope. This is important to separate blackboard values between different reusable processes in the same operation. The scope of a reusable process is determined by the executive when loading the operation. Not specifying a scope for a service call defaults to blackboard values in the main process tree. In most cases it is thus easiest to leave the scope unset.
An individual value on the blackboard is thus uniquely identified by its key, scope, and operation name.
Values on the blackboard are always protobuf messages.
Primitive types like strings or ints are wrapped using standard wrapper protos like google.protobuf.StringValue.
Reading values
The blackboard service allows introspection of values written to the blackboard
by skills or Python script nodes via GetBlackboardValue.
This can be useful for debugging. Blackboard values can be read during or after execution.
Listing values
The entire blackboard can be inspected using the
ListBlackboardValues.
RPC of the service. This returns all keys and their associated values from the
blackboard. The value of each blackboard key is encoded as a
google.protobuf.Any wrapping a specific proto. Listing blackboard values
will not return the full value for each key by default. Instead, each value
Any only retains its type URL. This allows seeing what kind of data each
blackboard key holds without having to transfer the values for all blackboard
keys, which can be quite expensive.
It is possible to opt-in to returning the full value for each key by setting the
view to FULL on the list request. This may transfer large amounts of data.
Prefer using GetBlackboardValue for specific values instead.
Writing values
Manually writing to the blackboard should only be necessary prior to starting an operation. Never write to the blackboard during execution.
The
UpdateBlackboardValue
call allows to write a new value to an already existing blackboard value.
The google.protobuf.Any being passed must be of the same type of the value already stored on the blackboard.
Snapshots
The blackboard service supports saving and restoring the entire state of the blackboard via snapshots. This is useful for crash recovery or to revert the blackboard to a known state during debugging.
Saving snapshots
Use CreateBlackboardSnapshot to capture a snapshot of current values from an operation's blackboard. To facilitate later identification, the request supports two optional metadata fields that do not affect snapshot functionality:
This saves all values currently on the blackboard to the snapshot.
The request allows specifying a display_name and a snapshot_source (e.g., USER or AUTOMATIC) to help identify the snapshot later.
The display_name is intended to describe the snapshot such that the user can identify it later (for example, a hint to what it covers).
The snapshot_source is intended to categorize snapshots that have been taken manually, for example during debugging (USER), and snapshots that have been automatically generated by a tool, for example when recovering a process failure (AUTOMATIC).
Both display_name and snapshot_source are optional and do not affect the functionality of snapshots.
The response contains a handle which uniquely identifies the snapshot.
Restoring snapshots
A previously saved snapshot can be restored into an operation's blackboard using
LoadBlackboardSnapshot.
This merges the values from the snapshot into the current blackboard. Existing values with the same key are updated, and new values are added.
During restoration, the executive attempts to migrate values (e.g., skill return values) to match the skills loaded in the current solution. This is only relevant during development, where a skill has been sideloaded between saving and restoring the snapshot. The response contains diagnostic information if there were issues restoring specific values.
Managing snapshots
Snapshots can be listed using
ListBlackboardSnapshots
and deleted using
DeleteBlackboardSnapshot.
Users are currently responsible for clearing old snapshots to prevent excessive memory consumption.
Please consult the API documentation for further RPCs.