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.