Under the Hood - Under the Hood - Runtime Engine Components
Previous  Top  Next

In order to deliver the user experience described above, the MentorWizard runtime engine contains a number of components. Some of these components, such as the Step Stack and Task Cache, are used by all MentorWizard applications. Others, such as Context, are not required; however, they are utilized by most applications.

The Step Stack

The flexibility to traverse a network of steps is provided by a stack of steps waiting to be presented to the user. The use of the Step Stack can be represented diagrammatically as a continuous loop, as follows:

SuperWizard Execution Cycle

Operationally, the Step Stack is managed by logic embedded in the steps themselves. Consider the following example:
A tax program step asks the user if he or she has a business on the side. If the answer is "Yes", then the next steps will collect the data needed to complete Schedule C. If the answer is "No", these steps will be skipped. After the data for Schedule C has been collected, the task continues with the step that the user would have seen next if no Schedule C data were required.  

In this example, the step that asks about the optional Schedule C sub-task will first put the step that follows the Schedule C sub-task on the Step Stack. If user input indicates that the user should fill out Schedule C, the first step in the Schedule C sub-task is added to the Step Stack – on top of the step already there. When the current step exits, the stack has one or two steps on it waiting to be presented to the user in last-in-first-out (LIFO) order.

The stack sequence for this example can be illustrated as follows:

Step Stack Example

Each step can put one or more steps on the stack either 1) as part of the actions taken when the step is opened, 2) in response to user input, and/or 3) as part of the actions taken when a step exits. When a step exits, the next step presented to the user will be the one on the top of the Step Stack. Of course, before you start a new MentorWizard task you must place at least one step on the stack. Moreover, when the stack is empty, the MentorWizard application is done and exits automatically.

The Task Cache

In a traditional application, the state of the user as well as information entered by the user is kept in variables defined within the program. These variables are defined in a programming language and compiled into the application logic. MentorWizard, however, does not know what information a user might enter: this information is generated as the user carries out a task. Since the steps are defined outside of the runtime engine logic, the information collected during execution of a task data must be stored outside of the MentorWizard runtime engine. That is where the Task Cache comes in: it is a repository for the state of the user (including the Step Stack) as well as the information collected by the user.

Since the contents of the Task Cache is not known until the steps are loaded and executed, the cache contains an identifier for each item as well as its raw value. The Task Cache, in fact, contains such a complete record of the state of a task that a task can be easily interrupted and resumed later. When a task is interrupted, its Task Cache is saved to disk. To resume the task, all that is needed is to reload the Task Cache from disk and the user can resume execution of the task.

The Task Cache is segmented into areas for each different type of data, as described in the following table:

Task Cache Datum
Task variables
Task variables hold the information that is required to perform a task. From time to time, some of these values may be written to persistent storage, such as a database. Task variables are also used to evaluate context rules (see below).
Step Stack
The Step Stack holds a LIFO stack of steps waiting to be displayed to the user.
Undo/Redo Data
This is the data needed to undo and redo steps.
Step History
The step history is a hierarchical list of all steps taken since the beginning of an application, including those in all sub-tasks. This history is maintained so that a user who can't remember his or her current location within an application can see where they are and how they got there.


In many tasks, the sequence of steps and even the individual options within a step are often different depending on conditions that cannot be determined in advance. For example, preparation of an income tax form may be different for a client who is not a citizen – a fact that becomes known during execution of a tax preparation application. In traditional applications, this context logic is written into the code: it is fixed in the executable program. MentorWizard applications also use context logic to tailor each task to such conditions; however, the context logic is built into a task's steps as needed and interpreted dynamically by the MentorWizard runtime engine. Before a step is presented to the user, the context rules embedded in the step are evaluated based on data held in the Task Cache. Context may be applied to whole steps or to individual widgets on a step. When all context rules evaluate true, the step or widget is displayed; when one or more rules evaluate false, the step or widget is not displayed. When a widget is taken out of a step by a context rule, the step's other widgets are repositioned so that the step appears as if the missing widget were never present.

Context provides a powerful way to tailor MentorWizard tasks, since each step's context rules are applied to data in the Task Cache at the time the step appears in a task sequence. Of course, action scripts should also have access to the Task Cache so that they can contain context logic when that is appropriate. However, it is both easier to build and safer to change when application logic is externalized into context rules.

Context is based on values stored in the Task Cache as attribute-value pairs. The attribute acts as a tag to identify a value. For example, if the attribute is "Role" then the associated value might be "Accountant". If a context rule requires that the user must be an accountant, then if the value of "Role" in the Task Cache is set to "Accountant" the context is True. If the Task Cache has no value for "Role" or its value is equal to "CPA" or some other value, then the context is False. The following table contains samples of Boolean operators used in MentorWizard context rules:

Boolean Operator
In Context IF…
The current Task Cache value is identical to the rule's literal text.
The rule's literal text is not identical to the current Task Cache value.
The rule's literal text is present in the current Task Cache value.
The rule's literal text is not present in the current Task Cache value.
The rule's literal text is identical to the current Task Cache value when both are converted to the context rule's data type (for example number, date, time, or date/time).
The rule's literal text is greater than the current Task Cache value when both are converted to the context rule's data type (for example number, date, time, or date/time).
The rule's literal text is less than the current Task Cache value when both are converted to the context rule's data type (for example number, date, time, or date/time).


Events of various kinds are generated when the user interacts with step widgets. Steps contain definitions of what happens when such events occur at runtime. Each step contains a list of those events that should trigger a change in the state of the application. Associated with each such event is a list of actions to be taken when that event occurs. The MentorWizard runtime engine supplies a number of pre-programmed actions that are commonly required by performance support applications. Other actions can be programmed in a scripting language such as Python or JavaScript.

The following table describes some useful predefined MentorWizard actions:
Action Name
Direct Branch
List of Steps
Each item in the list specifies the name of a step in the current task that is pushed on the step stack. A special name - "[this]" - may be included in the list to specify that the current step be put back on the Step Stack.
Computed Branch
Value Name Branch Table
Execute a branch to one of the steps in a step table. The first parameter is the name of a variable in the Task Cache: the second parameter is the name of a branch table. The branch table contains a list of string pairs. The first member of the pair is a value and the second is the name of a step. For this action the runtime engine takes the value name, looks up its value in the Task Cache, searches for a match of this value with the first member of a string pair in the branch table, then pushes the associated step on the Step Stack. The table may specify a default step name to be used when no match is found.
Remove Steps
Step Count
The specified number of steps are removed from the Step Stack and discarded.
Exit Step
Discard the current step and display the next step on the Step Stack. (This action is taken automatically when a Selector widget is selected.)
Load Widget From Cache
Widget Name Value Name
The first parameter specifies the name of a widget displayed in the current step, the second parameter the name of a value in the Task Cache. The runtime engine retrieves the named value from the Task Cache and writes it to the specified widget for display.
Save Widget To Cache
Widget Name Value Name
This action is the same as the Load Widget From Cache action except the runtime engine writes data from the widget to the Task Cache instead of vice versa.
Set Cache Value
Value Name Value Contents
The runtime engine writes the specified value contents to the Task Cache under the specified value name.
Message ID Client ID List of Value Names
The runtime engine looks up the current content in the Task Cache for each value name in the list and sends them (using the HTTP POST protocol) to the current MentorWizard enterprise server.
The runtime engine executes the script.