Guide to the Tutor Message format (v4)

a standard XML vocabulary for logging student and tutor actions

Version 1.0 for tutor_message_v4.xsd, tutor_message_v4.dtd

15 April 2013

Table of Contents

1. About this document
1.1. Who should read this document?
1.2. How to use this document
1.3. What is a tutoring application?
1.4. What is the difference between a tool and a tutor?
1.5. What is media logging?
1.6. Where to go for more information
2. The Tutor Message format
2.1. Validating your XML
2.2. Root element
2.3. Message types
2.4. <context_message>
2.4.1. Attributes of <context_message>
2.4.2. Child elements of <context_message> <meta> <dataset> Example of <dataset> <class> <condition> <skill> <custom_field> <dfa>
2.5. <tool_message>
2.5.1. Attributes of <tool_message>
2.5.2. Child elements of <tool_message> <meta> <event_descriptor> <semantic_event> <ui_event> <custom_field> <replay>
2.6. <tutor_message>
2.6.1. Attributes of <tutor_message>
2.6.2. Child elements <action_evaluation> <skill> <tutor_advice> <interpretation>
2.7. <message>
3. Media Logging
3.1. Similarity between media logging and tutor logging
3.2. <context_message> (media logging)
3.2.1. Media embedded within a tutor
3.2.2. Media not embedded within a tutor
3.2.3. XML examples of <context_message>
3.3. <tool_message> (media logging)
3.3.1. <semantic_event> (media logging)
3.3.2. <event_descriptor> (media logging)
3.3.3. XML Examples of tool messages for logging media events
A. XML Examples
B. Frequently Asked Questions (FAQ)
C. History of changes to the Tutor Message format
D. Content model figures

List of Figures

1. The OLI log_action element with embedded XML (tutor_related_message_sequence).
2. Message types, which appear within the tutor_related_message_sequence
3. Structure of a <context_message> element
4. Structure of a <meta> element
5. Structure of a <dataset> element
6. Unit-section hierarchy (top), and module-lesson-section hierarchy (bottom), each consistent across context messages for a dataset
7. Structure of a <class> element
8. Structure of a <condition> element
9. Structure of a <custom_field> element
10. Structure of a <tool_message> element
11. Structure of an <event_descriptor> element
12. Structure of a <semantic_event> element
13. Structure of a <ui_event> element
14. Structure of a <tutor_message> element
15. Structure of an <action_evaluation> element
16. Structure of a <skill> element
17. Structure of a <tutor_advice> element
18. Structure of a <message> element

List of Tables

1. Recommended values for the <context_message> name attribute
2. Recommended values for the tutorFlag attribute
3. Recommended values for the <action_evaluation> element
4. Recommended values for the <context_message> name attribute for a media object
5. Recommended values for the <semantic_event> name attribute for a media object
6. Recommended values forthea <semantic_event> trigger attribute for a media object
7. Format of an <event_descriptor> selections, action, and input values for a media object

1. About this document

1.1. Who should read this document?

This guide is intended for a software developer who wants to evaluate, implement, or update logging in an educational tutoring application, or convert existing logs created by a tutoring application. In addition, a developer working on a learning environment could describe the application's events in the format described in this document. By doing so, that application would satisfy the "recordability" metric for a tool (Ritter and Blessing 1998), describing events in a format that the Cognitive Tutor Authoring Tools (CTAT) software could read. CTAT could then record those application events (for playback later) or provide tutoring for a student using that application.

This document may also be of interest to an educator or researcher who wants to better understand the tutor message logging format, the standard logging format espoused by the Pittsburgh Science of Learning Center (PSLC).

1.2. How to use this document

Start at the beginning if you are unfamiliar with logging from tutoring applications, or are not sure you should implement logging to the format described in this document.

If you are familiar with logging but not the Tutor Message format or the Online Learning Initiative logging format, start with Section 2, “The Tutor Message format”.

If you are in the process of implementing logging, consider using this guide as a reference for the Tutor Message format. It details the requirements of the format, and describes scenarios for logging the various message types. In addition, examples of tutor interfaces and XML logging sequences may make the logging specification more concrete.

Lastly, this guide describes DataShop processing expectations, which are not expressed in the XML Schema or DTD. While validating is an important step in ensuring your XML conforms to this format, it is only part of correctness.

Conventions used in this document

<element> represents an XML element. attribute represents an XML attribute of an element.

<extended_code_examples> appear in this typeface. Blue text represents new code added to an example.

In the diagrams of XML content models in this document, a box represents an XML element. In a box, the first line of text denotes the name of the element, while indented text within a box represents an attribute. Numbers in parentheses describe the number of times that element can or should appear. For example, the number "1" means that one instance of this element must be included in your XML to be valid, while the number "0" means that the element is optional. Colors in the diagrams are used to show elements with identical content models appearing in different message types. The <meta> element, for example, appears in all message types.

1.3. What is a tutoring application?

A tutoring application tracks the student as he or she works, and provides hints and feedback in response to student actions.

The tutor message format is designed to capture the details of student sessions with tutoring applications. If an application provides no tutoring—if it is primarily for assessment, or provides a simulation only—the tutor message format may be a useful logging format: you can describe audio and video actions and user interface events using the tutor message format. Contact the DataShop team if you're uncertain whether or not your application should log to this specification. See Section 1.6, “Where to go for more information” for contact information.

1.4. What is the difference between a tool and a tutor?

This tutor message format describes student and tutor actions in terms of the "tool" and the "tutor". This distinction is useful as deciding which message type to record or send depends on knowing what the source of that action is (tool or tutor).

A tool is an interactive application with which a user interacts. A tutor is the component of an application that provides tutoring to the user. In general, a student's action with the application is captured in a tool message, while the tutor's response to the student's action(s) is captured in a tutor message.

Where a single application may be a tutoring application, it can be considered to have both of these components. This distinction is made in the 1996 paper "An architecture for plug-in tutor agents" by Steve Ritter and Kenneth Koedinger, in which the authors propose architectural principals for adding tutoring to an application (Ritter and Koedinger 1996).

1.5. What is media logging?

Media logging, described in this document in Section 3, “Media Logging”, is an extension of the Tutor Message format to log student interactions with media. It was designed with video and audio in mind, but attempts to remain applicable to any media type. It captures when the media was initially presented to the student, and how the student interacts with that media. For example, it captures when the student stops, starts, cues, or mutes any media. It provides support for both tutored and untutored media.

1.6. Where to go for more information

Both the Tutor Message format and Java Logging Library are maintained by the Pittsburgh Science of Learning Center (PSLC) DataShop team. They can be reached by email at

The Flash Logging Library is developed and maintained by the Cognitive Tutor Authoring Tools (CTAT) team. This logging library is bundled with CTAT, and is also available as a standalone download. The CTAT team can be contacted at