2.5. <tool_message>

Representing student action

2.5.2. Child elements of <tool_message>

2.5.2.1. <meta>
2.5.2.2. <event_descriptor>
2.5.2.3. <semantic_event>
2.5.2.4. <ui_event>
2.5.2.5. <custom_field>
2.5.2.6. <replay>

While the <context_message> places the actions of the student in context of the curriculum, the <tool_message> captures the actions of the student. Create a <tool_message> whenever the student interacts with the tool or the tool itself performs some action.

Figure 10. Structure of a <tool_message> element

2.5.1. Attributes of <tool_message>

<tool_message> has a single, required attribute: context_message_id. The value of this attribute must be the same for all tool and tutor messages described by the opening <context_message>, and it should be identical to the one specified in the <context_message>.

2.5.2. Child elements of <tool_message>

meta
event_descriptor
semantic_event (required)
ui_event
custom_field
replay (unused by DataShop)

2.5.2.1. <meta>

The content model of the <meta> element is identical to the element of the same name contained in the <context_message>. It is described in Section 2.4.2.1, “<meta>”.

2.5.2.2. <event_descriptor>

Optional.

This element describes the specifics of the student's interaction with the tool, primarily the selection, action, and input. It contains the details of a single observable change in the state of the user interface. This change in state is usually the result of a student action, but a tutor could cause a change in tool state as well. In either case, the tool message is used.

Figure 11. Structure of an <event_descriptor> element

Note

The selection, action, and input (SAI) used in an <event_descriptor> element should depend on whether the <event_descriptor> is appearing in a tool message or tutor message, and what the value of the <semantic_event> name attribute is. For example:

the SAI for a HINT_REQUEST semantic event in a tool message specifies the hint button
the SAI for a HINT_MSG semantic event in a tutor message specifies what the student should have done
the SAI for a ATTEMPT semantic event in a tool message specifies what the student actually did
the SAI for a RESULT semantic event in a tutor message specifies what the student should have done

Attributes of <event_descriptor>

event_id: an identifier for the event. This attribute is not used by DataShop and should not be used.

Child elements of <event_descriptor>

<event_descriptor><selection>

Optional.

A description of the interface element that the student selected or interacted with (for example, "LowestCommonDenominatorCell"). It should be unique within the user interface so that the student's action is identifiable. Some actions will involve multiple selections (see the section called “Example of <event_descriptor>” for an example of this usage).

Attributes of <selection>

Optional.

id: unique identifier; can be used when multiple selection-action-inputs (SAIs) are present to tie them together.
type: the role this particular selection plays with respect to the other SAIs.

<event_descriptor><action>

Optional.

A description of the manipulation applied to the selection. Many interface widgets have a single action, but multiple actions are also possible.

Attributes of <action>

Optional.

id: unique identifier; can be used when multiple selection-action-inputs (SAIs) are present to tie them together.
type: the role this particular action plays with respect to the other SAIs.

<event_descriptor><input>

Optional.

The input the student submitted (e.g., the text entered, the text of a menu item or a combobox entry).

Attributes of <input>

Optional.

id: unique identifier; can be used when multiple selection-action-inputs (SAIs) are present to tie them together.
type: the role this particular input plays with respect to the other SAIs.

Example of <event_descriptor>

The following is an example of a tool message from ChemCollective's Virtual Lab (VLab).

<tool_message context_message_id="0CEF2E07">
   <meta>
      <user_id>A1371</user_id>
      <session_id>148852539062A137120</session_id>
      <time>2005-17-9 5:16:42</time>
      <time_zone>US/Eastern</time_zone>
   </meta>
   <semantic_event transaction_id="B503948-9164-DD83" 
      name="SOLUTION_SET_THERMAL" />
   <event_descriptor>
      <selection type="flaskID">2500mL Bottle (ID2)</selection>
      <selection type="flaskName">2500mL Bottle</selection>
      <selection type="flaskTemp">303.15K</selection>
      <selection type="flaskInsulation">false</selection>
      <action>SOLUTION_SET_THERMAL</action>
      <input>303.15</input>
   </event_descriptor>
</tool_message>

2.5.2.3. <semantic_event>

One <semantic_event> or one or more <ui_event> elements required.

The <semantic_event> element describes a high-level, meaningful event, as opposed to a low-level, non-semantic event, which should be captured in the <ui_event> element. This notion of separating UI events and semantic events is taken from the proposed IEEE LTSC specification (Ritter).

This element also occurs in the tutor_message element.

	Note
	`<semantic_event>` is a content-less element: all information is provided in the attributes—not the content—of the element.

	Note
	DataShop expects either a single `<semantic_event>` with a single `<event_descriptor>`, or one or more `<ui_event>` elements, but not both.

Figure 12. Structure of a <semantic_event> element

Attributes of <semantic_event>

transaction_id: a string that uniquely identifies the event within the session. If this tool message is intended to be paired with a tutor message, the transaction_id value should correspond with the one defined in the tutor message.

name: a semantic description of the event. When exported by DataShop, the value is shown in "Student Response Type" column.

Note

DataShop expects a variety of semantic event names in tool messages and correspondingly paired event names in tutor messages. Though you can enter any event name, conforming to one of the existing pairs may be more useful for analysis in DataShop.

Current pairs include:

ATTEMPT and RESULT
HINT_REQUEST and HINT_MSG

In these pairs, the first value would appear in the name attribute of the <semantic_event> in the tool message, while the second value would appear in the same location in the tutor message.

For an example of this usage, see the section called “Examples of <semantic_event>” below.

trigger: The agent that caused the change in state within the tool. Should be USER if the user caused (or performed) the action; DATA if the tool caused (or performed) the action. This attribute is not imported by DataShop.
subtype: A further classification for this semantic event. For example, the CTAT software describes tool-performed actions as having subtype tutor-performed and trigger data (for an XML example, see the section called “Examples of <semantic_event>”). When exported by DataShop, this attribute value is shown in the "Student Response Subtype" column.

Examples of <semantic_event>

Corresponding semantic event elements in tool and tutor messages.

<tool_message context_message_id="C2badc36e:113e3ba9c5c:-7fe5">
  <problem_name>kl</problem_name>
  <semantic_event transaction_id="T2badc36e:113e3ba9c5c:-7fe7" 
    name="ATTEMPT" />
  <event_descriptor>
    <selection>dorminMultipleChoice1</selection>
    <action>UpdateMultipleChoice</action>
    <input>Option0</input>
  </event_descriptor>
</tool_message>

<tutor_message context_message_id="C2badc36e:113e3ba9c5c:-7fe5">
  <problem_name>kl</problem_name>
  <semantic_event transaction_id="T2badc36e:113e3ba9c5c:-7fe7" 
    name="RESULT" />
  <event_descriptor>
    <selection>dorminMultipleChoice1</selection>
    <action>UpdateMultipleChoice</action>
    <input>Option2</input>
  </event_descriptor>
  <action_evaluation>INCORRECT</action_evaluation>
</tutor_message>

Tutor-performed action as logged by CTAT. In this example, the tutor performs two steps for the student.

<tool_message context_message_id="C-793fdeed:11489b4f0f8:-7f9e">
  <problem_name>13-26</problem_name>
  <semantic_event transaction_id="T-793fdeed:11489b4f0f8:-7f6e" 
    name="ATTEMPT" trigger="DATA" subtype="tutor-performed" />
  <event_descriptor>
    <selection>convertDenom2</selection>
    <action>UpdateTextField</action>
    <input>6</input>
  </event_descriptor>
</tool_message>

<tool_message context_message_id="C-793fdeed:11489b4f0f8:-7f9e">
  <problem_name>13-26</problem_name>
  <semantic_event transaction_id="T-793fdeed:11489b4f0f8:-7f68" 
    name="ATTEMPT" trigger="DATA" subtype="tutor-performed" />
  <event_descriptor>
    <selection>unreducedDenom</selection>
    <action>UpdateTextField</action>
    <input>6</input>
  </event_descriptor>
</tool_message>

2.5.2.4. <ui_event>

One <semantic_event> or one or more <ui_event> elements required.

Use this element to log low-level user interface events that are non-semantic. For example, you could use a <ui_event> to describe a mouse click; a special format for machine processing (aimed at fine-grained reproduction during playback); or a description intended for human readers.

	Note
	DataShop imports only the first `<ui_event>` element if more than one are contained in a single tool message. DataShop uses the `name` attribute of the `<ui_event>` as the "Student Response Type" and sets the "Student Response Subtype" to "UI Event".

Figure 13. Structure of a <ui_event> element

Attributes of <ui_event>

id: an identifier for the event. This attribute is not used by DataShop and should not be used.
name: a classification for the event

Example of <ui_event>

<tool_message context_message_id="0CEF2E07">         
   <ui_event name="VLAB_RESIZE ">The virtual Lab is resized to a width 
     of 780 and a height of 550</ui_event>
</tool_message>

2.5.2.5. <custom_field>

Optional.

A tool message may include zero or more <custom_field> elements. See Section 2.4.2.7, “<custom_field>” for details on the content model of this element.

2.5.2.6. <replay>

Optional.

The <replay> element's content model allows for any content (character data or other elements). It is intended as a free-form area where a tool (such as the Chemistry VLab) can put extra information so that these logs can be fed back into the tool for replay.

	Note
	DataShop does not import the content of the `<replay>` element.

Prev	Up	Next
2.4. <context_message>	Home	2.6. <tutor_message>