The first element contained in the <tutor_related_message_sequence> should be a <context_message>. This single message establishes
the context for the following sequence of elements (<tool_message>, <tutor_message>, or <message>).

For a researcher, a <context_message>
can answer questions such as:

Were these data collected in a classroom? If so, what were the
details?

Is there a hierarchy surrounding this data sequence?

Were these data from a particular research condition?

With which problem or activity do these log messages
correspond?

Tip

You only need to log a single <context_message> element per student per single
problem per session (a student can have multiple sessions). Logging
once instead of with every tool and tutor message pair saves space. If
the context changes—if the student logs out or in, or if the problem,
session, or activity changes—then a new context message must be
logged.

2.4.2. Child elements of <context_message>

2.4.2.1. <meta>

The <meta> element supplies the same
information as the OLI <log_action>
element (i.e., user ID, session ID, time, and time zone); it is
redundant to supply this information twice. So if logging from
inside the OLI course delivery system, you may omit the <meta> element; otherwise, you must
include a <meta> element in the context
message and all other messages you send.

Note

If your tutor appears within an OLI course, don't provide a
<meta> element or a <log_action> wrapper; the OLI software
supplies the relevant session information.

Figure 4. Structure of a <meta> element

Attributes of <meta>

None.

Child elements of <meta>

If you are supplying a meta element, you must supply its
four child elements:

<meta><user_id>

Required. Maximum length of ≤ 55
characters.

The user ID of the current user. A single Boolean
attribute, anonFlag, specifies
whether or not the supplied user ID has been anonymized. Its
default value is false. If set to true, then DataShop will not
re-anonymize the user ID.

<meta><session_id>

Required. Maximum length of ≤ 255
characters.

A dataset-unique string that identifies the user's session
with the tutor.

<meta><time>

Required.

Local time; can be of the following formats:

Table 2. Valid time formats

Format

Example and Notes

yyyy-MM-dd HH:mm:ss

2001-07-04 12:08:56

yyyy-MM-dd HH:mm:ss z

2001-07-04 12:08:56 Pacific Standard Time

yyyy-MM-dd HH:mm z

2001-07-04 12:08 PST

MMMMM dd, yyyy hh:mm:ss a z

July 04, 2001 12:08:56 AM PST ** WPI-Assistments
format

MM/dd/yy HH:mm:ss:SSS z

07/04/01 12:08:56:322 PST

MM/dd/yy HH:mm:ss z

07/04/01 12:08:56 GMT-08:00

yyyy-MM-dd HH:mm:ss:SSS

2001-07-04 12:08:39:110 ** Carnegie Learning
format

mm:ss.0 z

08:56.0 PST ** not recommended—this is
the result of Excel applying a date
format

mm:ss.0

12:08:0 ** not recommended—this is the
result of Excel applying a date
format

yyyy-MM-dd HH:mm:ss.SSSSS

2001-07-04 12:08:39.11000 ** OLI format - 5 digit
millisecond

MM/dd/yy HH:mm:ss

07/04/01 12:08:56

MM/dd/yy HH:mm

07/04/01 12:08

long

1239939193

double

01239939193.31

yyyy-MM-dd HH:mm:ss.SSS

2010-05-11 16:06:11.908 ** CTAT format

yyyy/MM/dd HH:mm:ss.SS

2010/05/11 16:06:28.65

MM/dd/yyyy HH:mm:ss

2/24/2007 17:18:02

<meta><time_zone>

Required. Maximum length of ≤ 50
characters.

The local time zone name, such as one from the "TZ" column
in this List
of zoneinfo time zones. Three-letter time zone
abbreviations such as "EST" and "PST" are still valid, but are
deprecated.

Attributes of <dataset>

Child elements of <dataset>

<dataset><conversion_date>

Optional.

If you are converting these data to the Tutor Message
format from another format, include the date and, optionally,
the time, that these data were converted.

Attributes of <conversion_date>

None.

<dataset><converter_info>

Optional.

If you are converting these data to the Tutor Message
format from another format, include the name of the tool used to
perform the conversion, the tool's version, and the date the
tool was created or released.

Attributes of <converter_info>

Example

<dataset><name>

Required.

A <dataset> requires a single
<name> element, the value of which
will appear in the DataShop as the title of the dataset.

Note

Dataset <name> must be kept
consistent—it determines the "bucket" in DataShop where your
data are stored and displayed. If no name is provided, your
data will fall into the default bucket, making it difficult to
find later.

<dataset><level>

Required.

Nested <level> elements describe
the curriculum hierarchy, a positioning of the problem within an
organization you define. While nested <level> elements are common, only a single
<level> is required.

Important

DataShop expects consistent levels—consistent both in
terms of depth and type—throughout the dataset. For example,
if a context message describes a unit that contains sections,
other context messages in the dataset should also describe a
unit-section hierarchy.

Attributes of <level>

Child elements of <level>

A <level> is composed of a <name>, and
either another <level> or a <problem>. This
structure can either repeat—a nested <level> element—or a <problem> element can be included. There
is no limit on the depth of the level hierarchy.

<dataset><level><name>

Required. Maximum length of ≤ 100
characters.

Provide a name for your level. For example, a name of
"Understanding Fractions", when combined with a level type
of "Section", produces "Section Understanding
Fractions".

<dataset><level><problem>

Required at the bottom-most level.

The <problem> element
contains both a <name> and a <context>.

Note

Only one <problem> element
is expected within the entire <dataset> element, and it is expected
to be within the deepest <level>
element. Similarly, every <problem> must be placed within at
least one <level>.

Attributes of <problem>

The <problem> element has
two attributes: The tutorFlag attribute can be any of the
following values:

Used to describe a problem that does not fit
any of the above categories. If tutorFlag is other, then the
other attribute must be
filled in with application-specific data indicating
where the problem falls in the spectrum between
tutor and test. If tutorFlag is one of the
other values in this table, then the other attribute is
ignored.

Note

If tutorFlag is not set or empty,
the default value will be tutor.

How DataShop considers problems to be the same or
unique

For two given problem instances to be considered
the same "problem" by DataShop, they must have the
following identical elements and attributes:

<name>

<context>

tutorFlag (attribute)

other (attribute)

If any of these elements or attributes are
different between the two instances, DataShop will not
increment the "problem view" field, which tracks the
number of instances of the problem the student
saw.

Child elements of <problem>

<dataset><level><problem><name>

Required. Maximum length of ≤ 255
characters.

The name of the problem (e.g.,
"FractionAddition-1-2plus1-3").

<dataset><level><problem><context>

Optional.

The <context>
element's value can be any string that provides more
information—a text prompt to the student, a scenario,
or other descriptor—but should not be HTML: HTML is
not validated as part of the schema or by DataShop,
and it has the potential to break the DataShop
interface when viewed.

2.4.2.3. Example of <dataset>

The following code snippet defines a problem with a
"unit-section" curriculum hierarchy. The problem "ChemPT1" falls
within "Unit A", "Section One".

2.4.2.4. <class>

Optional.

The <class> element is used to
describe the context of tutor usage in a school.

Of its child elements, only <instructor> can occur more than once.

Note

If class name is not filled in, but period is, then period
will be used as the class name. If class name and period name are
not filled in, but description is, then the description will be
used as the class name.

Figure 7. Structure of a <class> element

Child elements of <class>

<class><name>

Optional. Maximum length of ≤ 75
characters.

The name of the class in which the tutor is used (eg,
"Intro to Chemistry").

<class><school>

Optional. Maximum length of ≤ 100
characters.

The school in which the tutor is used (eg, "Perrysville
Elementary").

<class><period>

Optional.

The class period in which the data are collected (eg,
"5").

<class><description>

Optional.

A description of the class in which the tutor is
used.

<class><instructor>

Optional.

The class instructor(s). If multiple, use an <instructor> element to name each
instructor.

2.4.2.5. <condition>

Optional.

A <condition> describes a study
condition, in the case that these data are being collected in the
context of a research study.

Zero or more <condition> elements
are allowed.

Figure 8. Structure of a <condition> element

Child elements of <condition>

If a <condition> is included, it
must have a <name>, which cannot be an
empty element. Optionally, <condition>
can include a <type> and <desc>, or description.

<condition><name>

Required. Maximum length of ≤ 80
characters.

The name of the condition (eg, "Unworked").

Important

In DataShop, condition name must be unique within a
dataset, so do not rely on <type> or
<desc> elements to distinguish
conditions.

<condition><type>

Optional. Maximum length of ≤ 255
characters.

A condition classification (eg, "Experimental",
"Control").

<condition><desc>

Optional.

A description of the condition.

2.4.2.6. <skill>

Optional.

A <skill> in a context message is a
description of a knowledge component that may be exercised by the
student in the course of solving the problem or activity. It's
primary purpose is to describe the probability of the student
knowing the skill at the beginning of the
problem. This probability is commonly used to track student mastery
of knowledge components ("mastery learning") through a
knowledge-tracing algorithm.

Note

A <skill> element contained in the
context message is currently not imported by DataShop.