Jan 232016

In this second post I’m going to go through the prototypes and agents I used to make my grading rubric. When I’m done, I’ll have explained everything that doesn’t have to do with grade calculations or export. (Subsequent posts will take up those topics.) The result is a long post that is predictably schematic. If you’re reading, I’ve assumed you’re interested in nuts-n-bolts.

Before I get started though, I should make clear that, in what follows, when I say “the rubric” I’m referring to a prototype that contains a two level hierarchy. Because my rubric is a prototype (called p_essay_rubric) it sits in the container where I store the rest of my prototypes and appears as an option in the assign prototype contextual menu.

The rubric is a prototype

The rubric is a prototype

When I assign this prototype to a new note, that note automatically duplicates the entire prototype hierarchy, providing an editable copy of the rubric that I can use to evaluate an individual student’s work. I will call these editable copies “instances of the rubric.”

I should also mention that the rubric relies upon seven user attributes, each of which is assigned to only one level of the rubric hierarchy as a key attribute.

User Attributes

The user attributes

Of these user attributes, three of them–$RubricCategoryPointValue, $RubricCategoryMax, and $RubricPointValue–are number values used to calculate grades. The rest hold either sets or strings.

The Rubric Hierarchy

The rubric is organized with three levels of hierarchy.

The Root (“The Rubric”)

The top level of the rubric hierarchy has three key attributes: $RubricEssayGrade, $RubricAssignmentName, and $RubricExportFileName. All of these are set automatically by rules, agents or on-add actions. The $HoverExpression is set to display $Subtitle. (A separate rule sets the $Subtitle to the final grade. See below.) The note’s $Text will be presented as a general introductory comment in bold italics on the exported comment sheet. It is blank in the rubric but can be edited in each individual instance of the rubric. If no comment is entered, the export will insert a stock intro. This top-level note is a prototype and is named p_essay_rubric.


The second-level notes identify the criteria used to evaluate the essay. There is one note per criterion.

The criteria in my rubric

The criteria in my rubric

Each note’s $Text contains a brief description of the criterion. When the final comment sheet is exported, this text will be presented as an italicized introduction to the specific feedback. $RubricCategoryPointValue and $RubricCategoryMax appear as key attributes. $RubricCategoryPointValue is calculated by a rule, but $RubricCategoryMax is set manually and establishes the relative weight of the criteria in the calculation of the final grade. (A value of 5 assigns the criteria grade a weight of 5% in the final grade.) Criteria are assigned the prototype p_rubric_category.

Making Revision to the Criteria: Evaluation criteria will likely change when the assignment or the course changes, and so both the number of criteria and their descriptions are fully editable. However, as I have set things up, the grade calculations assume that the sum of the $RubricCategoryMax values across all the criteria will equal 100. To ensure calculations are correct, any changes to the number of criteria or to the max value of individual criteria should be accounted for in changes to other notes’ $RubricCategoryMax attribute. Although $Text descriptions of the criteria can be edited freely, once I have begun grading I do not touch them so that each student’s instance of the rubric will match all the others.


The bottom level of the rubric hierarchy contains descriptors attached to point values. You grade an essay by selecting one descriptor within each criteria by ticking it’s checkbox. $RubricPointValue and $RubricCompDescriptiveName are set as key attributes. Although each note has a default value for both attributes set by the rubric prototype, they may be edited freely. The $Name of each of these notes is set automatically as a composite of the key attribute values and will be updated to reflect any changes made. The note $Text will be exported as the principal feedback on the comment sheet, and so, descriptor texts are completely flexible.

Sample Descriptors

Sample Descriptors

It is possible to have as many or as few descriptor notes as you like for each criteria. There can even be different descriptors that are assigned the same point value. Descriptor notes are assigned the prototype p_rubric_component.


The rubric hierarchy relies upon four prototype notes:

  • p_student
  • p_essay_rubric
  • p_rubric_category
  • p_rubric_component.

Together these prototypes:

  1. recreate the prototype’s hierarchy of notes for each instance of the rubric;
  2. set key attributes in each instance of the rubric;
  3. set a variety of rules and on-add actions that are used to define consistent attribute values in instances of the rubric;
  4. distinguish between levels of the hierarchy, allowing agents to act upon specific sets of notes;
  5. set rules that calculate grades based on checkbox selections in an instance of the rubric.

What follows is a brief explanation of each of the four prototypes.


The p_student prototype is not a part of the rubric itself, but I always create instances of the rubric as a child of a student note. (In my course file, I keep one note per student as a record of ID number, email address, etc.) It makes sense to use on-add actions set by the student note prototype to fill in basic attribute values for the rubric.

The first on-add action links the instance of the rubric to a specific student’s work by having the rubric pull its value for $s_LastName from the student note:


By setting this value immediately, I avoid the situation where I forget to label a rubric and can’t figure out to whom the comments should go.

The second action creates an instance of the rubric by setting the prototype of the note I create to p_essay_rubric:


Finally, I set $RubricAssignmentName:

$RubricAssignmentName="Essay One (Moby Dick)";

This last action has to be updated each time the rubric is used for a new assignment. It could probably be automated somehow, but I haven’t taken the time to figure out how. I don’t mind changing the string manually when I move from one assignment to another. Together, these actions look like this on the action tab of the p_student inspector:

On-add actions for student note

On-add actions for student note


I began this post by pointing out that my rubric is a prototype. This is that prototype, and except for its $Name, it and its descendent are identical to the instance of the rubric I use in the screencapped demonstration included in my last post.

The prototype hierarchy

The prototype hierarchy

This is possible because the attribute $PrototypeBequeathsChildren is set to true for this prototype. Setting this attribute to true means that when a new note is assigned this prototype, the criteria notes inside this prototype—along with their text, their rules, their on-add actions, etc.—will automatically be created inside the new note as well. Because student notes automatically assign this prototype to their children, all I have to do is create a new note as a child of a student note to create complete instance of the rubric.

[Update: if you are thinking about using prototypes to bequeath children in this way, it’s very important that none of those children are prototypes in their own right. Instead, assign the children prototypes that are outside the bequeathed hierarchy. The TbRef entry on prototypes can give additional info.]

This attribute allows prototypes to create notes in a container

Creating notes in a container with a prototype

In addition to setting key attributes, this prototype contains one non-calculation rule:


This sets the subtitle to show the final grade as a fraction over “/100.” It could just as easily be set to display it as a percentage labelled “%”. I’ve also set the hover expression of this note to $Subtitle.

I’ll explain the calculation rule in the next post.

p_rubric_category & p_rubric_component

These prototypes are assigned to criteria and descriptor notes respectively and are relatively simple. They set key attributes and identify the notes in a way that can be queried by agents. In addition, p_rubric_category assigns a calculation rule. As with p_essay_rubric, $PrototypeBequeathsChildren is set as true for p_rubric_category. That’s it.


The final piece of the basic layout is a set of three agents.


The most important of these agents sets the file name that will be used when the comment sheet is exported. The agent queries for the p_essay_rubric prototype and then performs this action:


In the demonstration I included in my previous post, this action produces the file name: 123456–Brian-Essay One (Moby Dick).

Here’s how.

First off, everything looks simpler if we ignore the parentheses for a moment. If we do, it’s clear that the opening number sequence is being reported as the value of $s_IDNumber and “Brian” is being reported as the value of $s_FirstName. I’ve formatted these two results to make them easier to read by separating them with an m-dash by adding:


I’ve used the same technique to place a dash between my name and the assignment name later on.

Now those parentheses…

I only figured out what to do here with help offered on the TBX user forums (link to thread). Using my agent’s action, I’m going explain what I learned there. To make things clearer though, I’m initially going to ignore everything from my agent except the ID Number.

Consider the following action:


This action will cause the export file name assigned to a note to be the same as the ID number assigned to that same note. I can’t use this action in the rubric because the student ID number is stored in a student note while the export file name is stored in the rubric. To make the rubric’s export file name use the container’s student ID number, I need to point the action to the information I want in the student note. So I tried doing this by pointing the action toward its parent:


Unfortunately, this doesn’t work either. Why? Well, agents work on the aliases of notes that they gather using their query (and not directly on the original note). So when my agent action pulled the ID Number from the parent note, it wasn’t pulling the information from the parent of my rubric. It was pulling it from the parent of the alias created by the agent, which is the agent. And the agent didn’t have any student ID information. What I needed was to point my action not to the parent of the alias but to the parent of the original note. To do this, I need this:


Make the same changes to the first name attribute, and I end up with an agent that set the needed export file name by pulling information from three different attributes.

Action to set export file name

Action to set export file name

a_set Rubric Component Name & a_set_rubric_Name

The remaining two agents simply maintain note names. The first queries for the prototype “p_essay_rubric” and sets $Name using the export file name:


The second updates the $Name of a descriptor to reflect any revisions to the point value or the descriptive name. It queries for the prototype p_rubric_component and then performs this action:

$Name=$RubricPointValue+”: “+$RubricCompDescriptiveName;

Because the attribute being set by this action is part of the same note as the attributes holding the information it is using, there is no need for parentheses this time.

Wrapping Up

So this has been a long post, and a boring one too I think, but hopefully it lays out the basic strategy I used to make the creation of a specific instances of my rubric more-or-less effortless.

Next time, I’ll explain how I’ve set up the calculations.

 January 23, 2016  Hypertext Tagged with:

Sorry, the comment form is closed at this time.