ActionLogger Tutorial

This tutorial describes how to set up and use the ActionLogger in the context of scaffolding apps and labs in the Go-Lab project. The ActionLogger is a middleware component to ease developers the implementation of action logging features; not caring about the actual sending of actions.

Preparations

To make use of the ActionLogger, it is neccessary to include the following Javascript sources:

• the jquery.cookie library, e.g. from http://plugins.jquery.com/cookie (to read the user cookie)
• the ILS library, https://github.com/go-lab/ils/blob/master/main/ils.js (to fill the metadata with information from the ILS)
• the client-commons utils library, e.g from http://projects.collide.info/projects/golab/repository/changes/trunk/client/commons/js/utils.js (to generate UUIDs; any other UUID generation is acceptable, too)
• the MetadataHandler, https://github.com/go-lab/ils/blob/master/metadata/MetadataHandler.js
• and the ActionLogger itself, https://github.com/go-lab/ils/blob/master/applog/ActionLogger.js

Creating an ActionLogger instance

To create an ActionLogger instance, an instance of the GoLabMetadataHandler has to be created first. The MetadataHandler holds information about the current user, document, tool and ILS. This metadata will be automatically added to every log action. The MetadataHandler needs to be initialized with a default set of metadata, where some items will be automatically overridden with information from the ILS metawidget. A developer has to provide a document type (e.g. "conceptMap" or "hypotheses") and a tool name (e.g. "ut.tools.conceptmapper" or "ut.tools.hypothesisScratchpad") with the default metadata set, as these information is specific for each tool.

Please note: The GoLabMetadataHandler (and the ILS library functions it is using) are implemented to operate from within an OpenSocial gadget in an ILS space. It will not work from with the ILS itself (unless modified).

Please note: Creating a MetadataHandler requires to use a callback function, since the creation requires to use aynchronous OpenSocial calls from the ILS libaray.

The following code snippet presents an example of how to create an instance of the ActionLogger:

var documentType = "newDocumentType";
var toolName = "golab.newtool";
var initialMetadata = {
"id": "",
"published": "",
"actor": {
"objectType": "person",
"id": "unknown",
"displayName": "unknown"
},
"target": {
"objectType": documentType,
"id": ut.commons.utils.generateUUID(),
"displayName": "unnamed " + documentType
},
"generator": {
"objectType": "application",
"url": window.location.href,
"id": ut.commons.utils.generateUUID(),
"displayName": toolName
},
"provider": {
"objectType": "ils",
"url": window.location.href,
"id": "unknown",
"inquiryPhase": "unknown",
"displayName": "unknown"
}
};
new window.golab.ils.metadata.GoLabMetadataHandler(initialMetadata, function(metadataHandler) {
var actionLogger = new window.ut.commons.actionlogging.ActionLogger(metadataHandler);
actionLogger.setLoggingTarget("opensocial");
// for development, using the following line might be helpful,
// as it sets the ActionLogger to log to the console for easy debugging
// actionLogger.setLoggingTarget("console");
//here, actionLogger is ready for usage
});

Using the ActionLogger

Using the ActionLogger basically means deciding on a "verb" (a plain string) and defining an "object" (in JSON format). The verb describes what has been done, whereas the object defines the content of an action. The list of valid verbs has been organized in a taxonomy, which looks as follows:

• content-oriented verbs (i.e. verbs that describe changes in the content of a document)
  • add
  • change
  • remove
• process-oriented verbs (i.e. verbs that don't describe a change in the working document, but denote an otherwise interesting event)
  • access (e.g. accessing a tab, changing the ILS phase, opening a help text, etc.)
  • start (e.g. starting a simulation, an animation etc.)
  • cancel (e.g. stopping a simulation, canceling an editing process, etc.)
  • send (e.g. sending a message, responding to a question etc.)
  • receive (e.g. receiving a message, getting a popup notification from LA backend etc.)
• storage-oriented verbs (i.e. verbs that describe the creation, reading, etc. of resources)
  • open
  • create
  • update
  • delete

The objects describes the content of an action. It needs to have an object type, an identifier (which typically identifies the added/changed/removed object in the working document), and arbitrary additional content. The examples a few lines below include possible objects. To ease the developer's life, separate functions have been created that will take care of the verb, so only the object needs to be defined.

Content-oriented verbs

For the content-oriented verbs, this means the ActionLogger provides functions called logAdd(object), logRemove(object), logChange(object). As a rule of thumb, the content-oriented action logging messages should be enough to sufficient to replicate the state of the working document and to replay its changes over time. Please consider the following examples, that describe the creation, the modification and the removal of a concept in the Concept Mapper tool.

// an new concept with the default text "new concept" is created
var logObject = {
"objectType": "concept",
"id": "613028e9-c037-46a6-a196-5a590a5505a6",
"content": "new concept"
}
actionLogger.logAdd(logObject);
// the same concept (cf. "id") is then modified to hold the new term "gravity"
var logObject = {
"objectType": "concept",
"id": "613028e9-c037-46a6-a196-5a590a5505a6",
"content": "gravity"
}
actionLogger.logChange(logObject);
// the same concept is then removed again
var logObject = {
"objectType": "concept",
"id": "613028e9-c037-46a6-a196-5a590a5505a6",
}
actionLogger.logRemove(logObject);

Process-oriented verbs

Actions, that do not change the content of the working document, but describe noteworthy activities nevertheless, are logged using process-oriented verbs. To this end, the ActionLogger provides the following functions: logAccess(object), logStart(object), logCancel(object), logSend(object), logReceive(object).

// examples follow

Storage-oriented verbs

Actions that are related to storing and retrieving documents from e.g. the Vault are categorized into storage-oriented verbs. These are handled through the functions logLoad(resource), logSaveAs(resource), logSave(resource), logDelete(resource). Please note, that the parameter of the storage-oriented functions is called "resource" (instead of "object") to indicate that these functions expect a resource object, as defined here. objectType and id will be generated automatically from the information in the resource.

// examples follow