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

<?xml version="1.0" encoding="UTF-8"?>
<tutor_related_message_sequence 
  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
  xsi:noNamespaceSchemaLocation='http://learnlab.web.cmu.edu/dtd/tutor_message_v4.xsd'
  version_number="4"
>
  <context_message 
    context_message_id="0CEF2E07-24DE-BFDA-9BAB-957C3AE236CE" 
    name="START_PROBLEM">
    <meta>
      <user_id>student01</user_id>
      <session_id></session_id>
      <time>2005/02/22 06:43:47.002</time>
      <time_zone>US/Eastern</time_zone>
    </meta>
  </context_message>
</tutor_related_message_sequence>

The <dataset> element and its descendant elements describe the DataShop dataset to which the data should belong; the hierarchy of "levels" in which the current problem exists; and the current problem.

Figure 5. Structure of a <dataset> element

Child elements of <dataset>

• conversion_date

• converter_info

• name (required)

• level (required)

<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>

None.

Example

<context_message ... >
  <dataset>
    <conversion_date>2007/06/29</conversion_date>
    <converter_info>Geometry Protocol Translator 4.11 June 27, 2007
    </converter_info>
    ...
  </dataset>

<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. Figure 6. Unit-section hierarchy (top), and module-lesson-section hierarchy (bottom), each consistent across context messages for a dataset

Attributes of <level>

This element has a single attribute:

• type: the type of level, usually something like "unit", "section", "chapter", etc.

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.

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:

• tutorFlag: can be any of the values specified in Table 2, “Recommended values for the tutorFlag attribute”

• other: a value not listed in Table 2, “Recommended values for the tutorFlag attribute”; stored only if tutorFlag is other.

Table 2. Recommended values for the tutorFlag attribute

Value of tutorFlag attribute	Description
tutor	Denotes a tutored problem.
test	Denotes a test problem.
pre-test	Denotes a pre-test problem.
post-test	Denotes a post-test problem.
other	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.

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.

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

<?xml version="1.0" encoding="UTF-8"?>
<tutor_related_message_sequence 
  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
  xsi:noNamespaceSchemaLocation='http://learnlab.web.cmu.edu/dtd/tutor_message_v4.xsd'
  version_number="4"
>
  <context_message context_message_id="0CEF2E07-24DE-BFDA-9BAB-957C3AE236CE"
    name="START_PROBLEM">
    <dataset>
      <name>Stoichiometry Study 1 - Spring 2005</name>
      <level type="Unit">
        <name>A</name>
        <level type="Section">
          <name>One</name>
          <problem>
            <name>ChemPT1</name>
            <context>Chemistry Problem One</context>
          </problem>
        </level>
      </level>
    </dataset>
  </context_message>
</tutor_related_message_sequence>

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

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.

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.

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

<condition><desc>

Optional.

A description of the condition.

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.

For a description of the skill content model, see Section 2.6.2.2, “<skill>” in tutor_message.

Use this element to describe other contextual information not adequately captured by the other context message elements.

Zero or more <custom_field> elements are permissible.

	Note
	While DataShop does not use or show this information in its reports, the content of a <custom_field> element is both stored and included in data exports.

Figure 9. Structure of a <custom_field> element

<context_message ... >
 ...
  <custom_field>
    <name>System-Equation</name>
    <value>y=6x-8</value>
  </custom_field>
 ...
</context_message>

DFA is an element that describes the results of a difficulty factors analysis. It has no attributes and contains no child elements. This element is not used by DataShop.