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.

warning

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 seperate 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.

info

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

warning

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.

note

Please consult the API documentation for further RPCs.