Intro

This page provides guidelines to History and Participation Awareness (HPA) service logging specification. It was created during the Time-Line Based Analysis (TLBA) development and requirements elicitation as an effort to unite (have a common) understanding onto fields in HPA logs. Field's properties that are being discussed within this page are (according to the HPA specification of Event) Action, Object Type, Properties (Custom Properties), Comment and Custom Data.

See elaboration on guidelines by viewing first(info) and second(info) discussion round.

TLBA & HPA interaction

Time-line based analysis or TLBA, the tool that will be used for analyzing purposes, relies in high extend on data that are stored in HPA repository as logs. Each log represents an event/action that happened in some end-user tool in KP-Lab platform and was stored to the HPA repository. At this time - M44 - only Knowledge Practices Environment (KPE), Map-It and Activity System Design Tools (ASDT) are sending requests to store such events into the HPA repository.

TLBA will extract data from HPA logs (via the HPA Query service interface) and visualize them according to needs of the user who is running the TLBA application. For the extraction to be made as 'error-prone' as it could be and the data returned to be as reliable as they should be, common properties have to be used by all the tools that use HPA for storing events/actions. Also to be able to retrieve every event/action made in the end-user tool, those events have to be logged by tools used within KP-Lab platform.

Data Extraction Principles

According to the work in progress System Usage Scenarios (SUS) for the TLBA it is clear that TLBA will visualize events/actions always from a 'container' based perspective on Shared Space (super-class). Which means that all actions taken in the Shared Space (SS) has to be visualized. Due to the design of the HPA log structure, which allows us to store single event, a custom property can be added to specify each time that an event had taken place in particular 'container' - a Shared Space for TLBA targeted purposes.

The easiest way how to accomplish such a requirement of visualization is to use aggregated query functions of the HPA for retrieving data in two phases:

  • retrieve logs for the SS object itself,
  • use the filter where the ID of the Shared Space would be used to retrieve all events that taken place in the Shared Space container on the basis of custom property.

From above it is quite straight forward that ID of the Shared Space has to be unique identifier to filter out the correct events and the Shared Space URI fits into this condition. The other constrain which must be full-filed is the custom property name which should be same for any tool that logs events.

TLBA is going to show differently different events/actions in its GUI. For example creation event could be visualized as a blue circle and modification event as a green star, or use different icon schemes for different actions. What matters here is:

  • to use same name for actions to log across all KP-Lab tools and
  • the meaning (semantics) of that action name have to be same.

To ease action target identification (you might want to ask question as: what was created, or what object was modified) for TLBA and HPA tools should also fill HPA Event field objectType where type of object can be specified. By use of this hints technique mostly all of logged events could be easily recognized and no deeper identifications would be necessary (as querying the Knowledge Repository). HPA can use similar hints for better translation mechanisms to Reference Model when needed.

Same demands apply for appending object type field as it is with the action or custom properties ones.

End User Tools

Here you can find list of end-user tools that are sending logs to the HPA and should comply to the guidelines.
Tool name Since Logging Part of Tool Logging Methods
KPE M33 SSGUI M30 list
ASDT M36 ASDT service M36 list work in progress
Map-It M33 Map-It ServerM33 list

Logging Actions

Based on the HPA actions log dump (contains all names of activities recorded until dump was made) and on the 'quite' close requirements following actions will be recognized i.e. shown in GUI of the TLBA appliccation.

In the following table

  • Activity Name is the String value passed via HPA interface of the Action field in the HPA Event,
  • Enforced Custom Properties are String key values passed via HPA interface of the property field (key / value pair) in the HPA Event that has to be filled in for proper filtering of HPA logs (see next section for detail on Custom Properties).

Activity Name HPA's Object Type Enforced Custom Properties
creation is mandatory SSPID, title, description, fromObjectID, toObjectID
modification is not SSPID, title, description, toObjectID, fromObjectID
deletion is not SSPID
opening is not SSPID

Notes

  • Action and Custom Property names are case sensitive.
  • HPA's Event field objectType has to be always filed in for creation actions. It is not mandatory for modification, deletion or opening like actions. (see Object Type section).
  • SSPID is used always for every action performed.
    • SSPID is filled with Root Space ID when manipulating with Shared Space object itself.
  • toObjectID is mandatory all the time when recording actions as creation, modification or deletion that recognize other objects coupled to this action. For example in actions like linking, chatting, assigning (assigning an object to an object or an object to a person - creating responsibility), submitting, commenting or tagging, etc. where it is needed to record object to where link, assignment, submission or tag has been made.
  • fromObjectID has to be filled in when dealing with links or in actions where, similarly as with linking, the connection between two objects is made.
  • title and/or description will not be filled in for modification action, if their value has not been changed,
  • opening occurs when some container (Shared Space, Task, CLSession) is trying to be viewed. For example loading up a Shared Space content will be recorded as HPA opening Event.
  • Actions assigning and linking require additional custom properties to be filled in. See notes on Custom Properties section on properties fromObjectID and toObjectID.

Open questions

  • Some actions on tool's GUI side (KPE) as linking is transformed to the HPA as creation event which means that in TLBA GUI the linking activity will be translated on the basis of HPA object nature. Same applies for the tagging, commenting and assigning of objects. Other tools took different approach - direct naming of the action which means that for example assigning is not logged as HPA creation Event, but as HPA assignment Event. The question is: Which approach should be commonly enforced (see log dump )?
    • JW: we can simply extend the list of actions, so there will be linking event. Tools should store events as speficic as they can, so HPA can capture most information about what is going on
    • actions will not be extended -> Based on discussions only creation, modification, deletion and opening actions names are allowed. Their specifications are derived by using HPA's Event field object type. For example creating link would be stored as creation with link object type, or modification of comment as modification with comment object type.
  • By use of coupled logging mechanism where one action in the tool's GUI (for example adding new Content Item into the Shared Space, or removing item from the Tailored View) produces more than one HPA Event, events has to be logged in all container levels (see multiple leveled containers question in Custom Properties)
    • Based on discussion coupled logging principle will NOT be used for storing events to HPA repository.
  • How the opening will be defined for Content Items (Uploadable, External, Note, etc.)?
    • Still open question if loading up info in KPE's info bar is treated as opening action.

Logging Object Type

As briefly noted in the introduction, HPA's Event field Object Type will be used as a hint to get the action endpoint type. On the HPA'log dump basis several types of object could be identified and some more are added to ease the identification of action (see table):
Object Type Name Representing Class Example Comment / Description
assignment as demonstrated in example 5, class depends on the end-user tool data model
comment TLO#Comment anytime a commenting is performed
submission CL#CLHomeworkSubmission submitting finished homework to public
content item TLO#ContentItem, CL#TriangleModel Comment Christoph: I would suggest that we do not log "Content Item" as an Object Type but list all Object Types that are subsumed under this category. This way we provide more information to the user and avoid that the somewhat tricky concept of Content Item to show up in the data analysis. (I think it is still tricky, because it is not clear why for example a visual model shouldn't be a content item as well.
wiki page ss#Wiki
file TLO#UploadableContentItem
web link TLO#ExternalContentItem
note ss#Note
sketch TLO#ContentItem (use TLO#dc_format property)
Scorm/IMS file TLO#ScormImsContentItem
background image ss#BackgroundImage, TLO#UploadableContentItem
visual modeling language TLO#VisualModellingLanguage
link TLO#Relationship a class that is created when linking is performed
milestone TLO#Milestone
shared space TLO#CollectiveSpace, CL#CLSpace any child of Shared Space
tag (is a property TLO#hasSemanticTag)
vocabulary TLO#Ontology, core#ConceptScheme
tailored view ss#TailoredView
task TLO#Task
visual model TLO#VisualModel
context chat TLO#ContentItem (use TLO#dc_format property)

Notes

  • Colored Object Type Names are extensions to already logging constants.
  • End-user tools can still fill in other types of object types for example as map-it meeting, etc. These are just ones that will ease the TLBA parsing procedure.
  • See that list for more types and used terms in the KPE.

Logging Custom Properties

Custom Properties HPA log dump shows list of property keys used up to date the dump has been made. Following table introduces Common Custom Property keys which will be used for:
  • filtering logged HPA Events,
  • providing necessary additional information to properly introduce HPA Event into the TLBA.

Custom Property Key Custom Property Value Example
SSPID Shared Space URI http://www.kp-lab.org/ontologies/CL#CLSpace:_x
title String Test Note
description String Some description can be here
fromObjectID object's URI http://www.kp-lab.org/ontologies/CL#CLTriangleModel:_1
toObjectID object's URI http://www.kp-lab.org/ontologies/ss#Note:_090223

Notes

  • Custom Property names are case sensitive,
  • SSPID value can be any instance of Shared Space parent class of the TLO ontology,
    • SSPID contains root space URI only if the shared space is manipulated with,
  • fromObjectID and toObjectID are properties that must be filled in if the tool is logging either linking or assignment action. In those cases fromObjectID represents object from where the link or assignment is made and toObjectID represents target of the action. It could represent either an object URI or user URI.
  • title has to be appended for linking actions as well. Title in this scenario represent meaning of link created, not its actual name as for naming some shared space. Those could be of values for example contributes to, or is part of.
  • title has to be appended for modification action if meaning of the link has changed, not for modifying start or end points of links.

Open Questions

  • Custom property key name for the multiple leveled containers could be derived from following principle. The highest container which is always Shared Space will have grounded property SSPID. For each lower container the property key name would derive from the name of the key and a two digit number which would represent depth level of container.
Depth Level Property Key Container
0 SSPID Shared Space
1 contLevel01 Tailored View, CLSession
2 contLevel02 CLTheme
    • This scheme is not necessary anymore since there would not be coupled logging mechanism.

Logging Comments

TLBA does not enforce any restrictions on the Comment field of the HPA's Event.

Logging Custom Data

TLBA does not enforce any restrictions on the Custom data field of the HPA's Event.

Examples

Example 1

Action in GUI
  • Creating new CLSpace
Sent Log
  • One Events will be dispatched to the HPA:
Event No Subject ID Object ID Object Type Action Type Property Key Property Value Comment
1 http://www.kp-lab.org/system-model/TLO#Student_Mary http://www.kp-lab.org/ontologies/CL#CLSpace:_x shared space creation SSPID http://www.kp-lab.org/system-model/TLO#Root_Space establishing a new Change Laboratory space
title Michal's CLSpace
description CLSpace used for demonstration
Note:
  • Event No. is not part of the HPA's Event interface structure.
  • SSPID contains root space ID

Example 2

Action in GUI
  • User has added Note into the Shared Space
Sent Log
  • One Events will be dispatched to the HPA:
Event No Subject ID Object ID Object Type Action Type Property Key Property Value Comment
2 http://www.kp-lab.org/system-model/TLO#Student_Mary http://www.kp-lab.org/system-model/TLO#ContentItem_6 content item creation SSPID http://www.kp-lab.org/system-model/TLO#CollectiveSpace_Course_1234 creating content item
title Mary's Item
description Some
Note:
  • Event No. is not part of the HPA's Event interface structure.
  • Both title and description has to be logged, because there was no entry for them in past.

Example 3

Action in GUI
  • User has modified the description of the content item
Sent Log
  • One Events will be dispatched to the HPA:
Event No Subject ID Object ID Object Type Action Type Property Key Property Value Comment
3 http://www.kp-lab.org/system-model/TLO#Student_Mary http://www.kp-lab.org/system-model/TLO#ContentItem_6 modification SSPID http://www.kp-lab.org/system-model/TLO#CollectiveSpace_Course_1234 modifying content item's description
description Mary's extended description
Note:
  • Event No. is not part of the HPA's Event interface structure.
  • Object Type does not need to be filled in.
  • title was not recorded, because it has not been modified.

Example 4

Action in GUI
  • Linking two content items
Sent Log
  • One Events will be dispatched to the HPA:
Event No Subject ID Object ID Object Type Action Type Property Key Property Value Comment
4 http://www.kp-lab.org/system-model/TLO#Student_Mary tp://www.kp-lab.org/system-model/TLO#Relationship:_081 link creation SSPID http://www.kp-lab.org/system-model/TLO#CollectiveSpace_Course_1234 linking...
title is part of
toObjectID http://www.kp-lab.org/system-model/TLO#ContentItem_61
fromObjectID http://www.kp-lab.org/system-model/TLO#ContentItem_06
Note:
  • Event No. is not part of the HPA's Event interface structure.

Example 5

Action in GUI
  • Assigning a content item to CLTheme
Sent Log
  • One Events will be dispatched to the HPA:
Event No Subject ID Object ID Object Type Action Type Property Key Property Value Comment
5 http://www.kp-lab.org/system-model/TLO#Student_Mary http://www.kp-lab.org/ontologies/CL#CLTheme:_09 assignment creation SSPID http://www.kp-lab.org/ontologies/CL#CLSpace:_x assigning content item to CLTheme
toObjectID http://www.kp-lab.org/system-model/TLO#ContentItem_61
Note:
  • Event No. is not part of the HPA's Event interface structure.
  • ASDT updates only one property for assignments in its data model, so fromObjectID is not necessary to fill in because it is embedded in HPA's Object ID field.

Summary

  • These guidelines are meant to serve as common logging principles for KP-Lab end-user tools.
  • Actions that are logged in end-user tools are atomic.
  • Guidelines does not deal with requirements which are needed for pedagogical research, they suppose to be principles on how to store data into HPA repository.
  • There should not be dual logging mechanism in KP-Lab end user tool.
  • Basic structure of common HPA's logged Event is:
    • Subject ID, Object ID, Object Type, Action, Custom Properties,
    • Object Type will serve as a hint for distinguishing specialized action flavors and manipulated objects,
    • Custom Properties are means to filter logged data,
    • Custom Properties must record always SSPID key/value pair.
  • It is not forbidden to use different properties or object types, however those might not be correctly recognized by the TLBA.

References

Attachments

  Page Info My Prefs Log in
This page (revision-68) last changed on 18:24 25-Mar-2017 by Patrick Ausderau.
 
JSPWiki v2.4.102
[RSS]