Guide to the Tutor Message format (v4) > The Tutor Message format > <context_message>

2.4. <context_message>

Establishing context with the opening context message

2.4.1. Attributes of <context_message>
2.4.2. Child elements of <context_message>
2.4.2.1. <meta>
2.4.2.2. <dataset>
2.4.2.3. Example of <dataset>
2.4.2.4. <class>
2.4.2.5. <condition>
2.4.2.6. <skill>
2.4.2.7. <custom_field>
2.4.2.8. <dfa>

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:

[Tip]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.

Figure 3. Structure of a <context_message> element

Structure of a <context_message> element

2.4.1. Attributes of <context_message>

A <context_message> has two required attributes:

  • name

  • context_message_id

The name attribute is used to indicate where the student is in the process of working on a tutor or problem. The PSLC DataShop team has established some canonical values for this attribute that should be used, displayed in Table 1, “Recommended values for the <context_message> name attribute”.

Table 1. Recommended values for the <context_message> name attribute

 DescriptionPreferred valueOther possible values
Starting a problem or activitySTART_PROBLEM
  • PROBLEM_START

  • START

  • QUESTION

  • LOAD_PROBLEM

  • LOAD_TUTOR

  • LOAD_AUDIO

  • LOAD_VIDEO

  • LOAD_MEDIA

  • START_TUTOR

  • START_AUDIO

  • START_VIDEO

  • START_MEDIA

Skipping a problem or activitySKIP_PROBLEM
  • SKIP_TUTOR

  • SKIP

Resuming a problem or activityRESUME_PROBLEM
  • RESUME

  • CONTINUE

  • RESUME_TUTOR

  • CONTINUE_PROBLEM

Finishing a problem or activityDONE_PROBLEM
  • DONE

  • FINISHED

Quitting a problem or activityQUIT_PROBLEM
  • QUIT

Resetting a problem or activityRESET_PROBLEM
  • RESET

Reading (REAP)READING 

The context_message_id attribute ties a sequence of tutor-related messages together; when referenced in the other messages, it identifies this message as providing the relevant context.

[Important]Important

The value of the context_message_id attribute must be a globally unique identifier (GUID). In DataShop, messages will be grouped by user_id, session_id, and context_message_id.

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

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; must be one of these accepted formats.

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

Example of <meta>

Here is our XML so far, including the meta element:

<?xml version="1.0" encoding="UTF-8"?>
<tutor_related_message_sequence 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>
2.4.2.2. <dataset>
Required

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

Structure of a <dataset> element

Attributes of <dataset>

None.

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>

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

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. Maximum length of ≤ 100 characters.

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

Table 2. Recommended values for the tutorFlag attribute

 Value of tutorFlag attributeDescription 
tutorDenotes a tutored problem.
testDenotes a test problem.
pre-testDenotes a pre-test problem.
post-testDenotes a post-test problem.
otherUsed 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]Note

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

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

<?xml version="1.0" encoding="UTF-8"?>
<tutor_related_message_sequence 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>
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]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

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

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

2.4.2.7. <custom_field>
Optional.

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

Structure of a <custom_field> element

Child elements of <custom_field>
<custom_field><name>
Required. Maximum length of ≤ 255 characters.

A name for the custom field.

<custom_field><value>
Required. Maximum length of ≤ 255 characters.

A value for the custom field.

Example of <custom_field>
<context_message ... >
 ...
  <custom_field>
    <name>System-Equation</name>
    <value>y=6x-8</value>
  </custom_field>
 ...
</context_message>
2.4.2.8. <dfa>
Optional.

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.