Workspace events

The workspace sends event notifications for certain actions such as creating a workspace, saving or copying an object, etc. System administrators can specify event listeners in the deploy.cfg file (see deploy.cfg.example) for examples. An Apache Kafka based event listener is provided (see below), and custom listeners can be implemented.

Warning

Events can contain mutable data such as names, hidden / deletion states, permissions, etc. as a convenience. However, this information is stale as soon as it is emitted, and event failures can occur, so if accurate information is important be sure to pull the latest state from the workspace rather than relying on the data snapshot in the event.

Configure an event listener

Event listeners are configured in the deploy.cfg file. At minimum, the listener factory class must be specified and the listener must be added to the list of active listeners. For example, given a listener factory class of us.kbase.workspace.test.listener.NullListenerFactory and a name of nulllistener the configuration would look like:

listeners=nulllistener
listener-nulllistener-class=us.kbase.workspace.test.listener.NullListenerFactory

This will cause the listener implemented in the NullListenerFactory class to be loaded and initialized at startup, and it will be fed events as they occur. The nulllistener name has no meaning other than to group related parameters together and provide a way to specific which listener is activated. listeners is a comma separated list of active listeners. To deactivate the NullListenerFactory, for example, remove nulllistener from the list of listeners.

Some listeners may require configuration, like so:

listener-nulllistener-config-key1=value1
listener-nulllistener-config-key2=value2

In this case the NullListenerFactory will be passed a mapping of key1 -> value1 and key2 -> value2 at startup.

Custom listeners

To create a custom listener, implement the us.kbase.workspace.listener.WorkspaceEventListenerFactory interface. The map passed to the configure method at startup comes from the listener-<name>-config values in the deploy.cfg file.

Note

Note that some administration commands, such as saving an object, allow an administrator to impersonate another user. In this case, the username passed to the event listener will be that of the impersonated user. Additionally, for some commands that do not require an administrator to impersonate a user (such as setting user permissions), the user name passed to the event listener may be null.

Kafka listener

Configure the Kafka listener like so:

listeners=listener1, ... , Kafka, ... , listenerN
listener-Kafka-class=us.kbase.workspace.modules.KafkaNotifierFactory
listener-Kafka-config-topic=<Kafka topic where events will be sent>
listener-Kafka-config-bootstrap.servers=<the Kafka bootstrap servers>

Again, the Kafka name in this context serves only to group parameters together and allow for an activation / deactivation mechanism.

The config-topic must abide by the Kafka constraints, but in addition may not include . or _ characters to avoid ambiguity in how Kafka processes those characters.

bootstrap.servers is identical to the Kafka bootstrap.servers configuration item.

The Kafka event listener messages are JSON objects:

{
  "user": <the user that triggered the event.
      May be null if the user is an administrator>,
  "wsid": <the workspace id of the workspace involved in the event>,
  "objid": <the object id of the object involved in the event.
      May be null>
  "ver": <the version of the object involved in the event.
      May be null>
  "time": <the time the event took place in epoch milliseconds>
  "evtype": <the event type>
  "objtype": <the type of the object involved in the event.
      May be null>
  "perm": <the permission set for one or more users. May be null>
  "permusers": <the list of users for whom permissions were altered.
      May be empty>
}

The evtype, time, and wsid fields are always present, but other fields are present or not based on the event type:

Event

Event type

Addl. Fields

Null admin user

save object

NEW_VERSION

No

copy one version

NEW_VERSION

No

copy all versions

COPY_OBJECT

objid

No

revert object

NEW_VERSION

No

rename object

RENAME_OBJECT

objid

No

set object un/deleted

OBJECT_DELETE_STATE_CHANGE

objid

No

set object un/hidden

OBJECT_HIDE_STATE_CHANGE

objid

No

clone workspace

CLONE_WORKSPACE

No

set permission

SET_PERMISSION

perm, permusers

Yes

set global permission

SET_GLOBAL_PERMISSION

No

set workspace un/deleted

WORKSPACE_DELETE_STATE_CHANGE

Yes

create workspace

WORKSPACE_STATE_CHANGE

No

rename workspace

WORKSPACE_STATE_CHANGE

No

alter workspace metadata

WORKSPACE_STATE_CHANGE

No

lock workspace

WORKSPACE_STATE_CHANGE

No

set workspace description

WORKSPACE_STATE_CHANGE

Yes

set workspace owner

WORKSPACE_STATE_CHANGE

Yes

  1. objid, ver, objtype

Regarding the user field, see the note under Custom listeners above.