Authoring Guide

Back to Table of Contents


This document instructs how to author a simple course and other necessary configuration files needed to run a course using GIFT. By the end of this document, you will have a better understanding of the GIFT domain and model development process as well as how to use the authoring tools available to date.

Where to Start…

Before starting this GIFT authoring guide, please complete the installation and start at least one course to confirm that you have a fully functioning release.


The GIFT architecture has been designed to be highly configurable, interchangeable and distributed. Currently, module configuration is designed around files and database entries, but in the future it may be driven more by the available models (e.g., learner model, pedagogical model). For a detailed look at the dependencies between various GIFT components view the GIFT Dependency Table

The following subsections provide a brief overview of the different types of inputs used to configure and run a GIFT session.


“Surveys” provide a way for the GIFT system to obtain additional information about the user. From domain independent to domain dependent questions and from knowledge probing to biographical information, each response can be analyzed and used to improve learning. Essentially, the term ‘Survey’ refers to a test (pre-test, post-test, etc.) or assessment item (psychological survey, personality survey, etc.). Currently surveys are retrieved from the UMS database and presented during the execution of a course through the Web-Tutor User Interface (WTUI or TUI). These surveys should be authored using the Survey Authoring System but can also be directly imported into the database. For more information on authoring surveys please refer to the GIFT Survey Authoring System Instructions.


Just like surveys, sensors are used to obtain additional information about the learner. The sensor module is designed to support both hardware and software driven sensors, in addition to filtering sensor data and writing sensor data to disk. Currently, the sensor module is configured using a single sensor configuration file. For more information refer to the GIFT Configuration Settings document. Depending on your GIFT release, there might be various survey elements already authored and available. Here are a list of some of the sensors GIFT supports (with configuration):
  • eMotiv EEG headset
  • temperature/humidity sensitive mouse
  • software self-assessment sensor (a proxy sensor which simply generates information)
  • Q Sensor Electro-Dermal Response wristband
  • Kinect

For more information, you can look at the various interfaces, or simply leaf through the preconfigured in the GIFT\config\sensor\configurations directory


The learner module is responsible for determining the learner’s state. Currently the learner module is configured on a per user per course basis using a learner configuration file. The learner configuration files should be authored using the GIFT Authoring Tool (GAT). In addition, this module contains a very simplistic learner model implementation that is expected to drastically change as research is conducted. For more information, refer to the GIFT Configuration Settings document. Depending on your GIFT release, there may be one or more learner configuration files already created and available.


The pedagogical module is responsible for providing instructional strategy request to the domain module. Currently the pedagogical module is configured on a per user per course basis using a pedagogical configuration file. The pedagogical configuration file should be authored using the GIFT Authoring Tool (GAT). This module currently contains two pedagogical models. The first is called the default pedagogical model. This model relies on the state transitions part of a Domain Knowledge File (DKF) to be configured. The second is called the Engine for Management of Adaptive Pedagogy (eMAP). This model uses a learner state as a key to lookup the ideal metadata attributes. These attributes can then be used by the domain module to select the next piece of content to present to the user based on their learner state.

Domain Knowledge

Domain knowledge is configured using a Domain Knowledge File (DKF). The DKF configures the assessment logic for a domain – more specifically for an instance of a training application such as a VBS scenario or PowerPoint show. Multiple DKFs can be used during a course as governed by the course. To author a DKF use the GIFT Authoring Tool (GAT). For more information refer to the GIFT Domain Knowledge File document. Depending on your GIFT release, there maybe one or more DKFs already created and available.


Metadata is used to describe course content files such as PowerPoint shows. Metadata files are authored in GIFT using the web-based GIFT Authoring tool in the “My Tools” section of the GIFT Dashboard. These files are used by the Domain module to find and present content based on Pedagogical requests in a course that contains one or more Merrill’s Branch points.


The course file describes the flow of the domain session. The flow of a course can be fixed or dynamic. A fixed course flow is simply one without a branching (i.e. using Merrill’s branch point course elements) transition authored in the list of transitions for that course. Whereas a dynamic or branching course specifies one or more branching transitions that use learner state characteristics and metadata to present appropriate content during the course. Depending on your GIFT release, there maybe one or more course files already created and available. For more information refer to the GIFT Domain Course File document.


The Gateway module utilizes interop interfaces to handle communication between external training applications (e.g. VBS, TC3 and PowerPoint) and GIFT. These interfaces are configured in the Gateway module using a interopConfig.xml file upon startup. During the execution of a course, management of the interop interfaces and the external training application they communicate with is handled by communication between the Domain module and the Gateway module. For more information refer to the Create a new Interop Interface. Also refer to the “Interop Connection Settings” section in GIFT Configuration Settings.

Simple Authoring Example

Currently, the most complex portion of a GIFT course is the interaction with a training application (e.g., VBS, PowerPoint). In this exercise you will be guided through authoring a course that utilizes the major components of GIFT.

To limit the amount of procedures to maintain and to assure that this exercise works for each release, this authoring example has been combined with the GIFT release test procedures. To start this exercise open the GIFT Test Procedure Authoring spreadsheet (located in GIFT/docs/testing folder) and select the “Overview” worksheet by clicking on the corresponding tab. Follow the procedures listed to author a GIFT session from scratch.

Connecting your Training Application to GIFT

There more than likely will be instances where you wish to connect your training application with GIFT in order to take advantage of all the other GIFT components offered in a release. The place to do this is in the Gateway module via an interop interface implementation Java class. There are several examples provided in the GIFT source code.

This section will describe some of the challenges to consider and the general steps to follow in order to facilitate this need.


One of first things to consider is how will your training application be used with GIFT. This can mean several things such as:
  • How will GIFT and my training application be presented to the user? i.e. will both screen be shown at the same time (e.g. GIFT TUI and VBS) or will GIFT be in the background (e.g. GIFT TUI and PowerPoint).
  • Can my training application handle simulation management (SIMAN) control (e.g. load, start, pause and stop)?
  • Does my training application already provide assessments? If so,
    • Can the assessment engine be separated from the training application in order to be used for other purposes such as by other training applications or domains?
    • Do you want GIFT to extend the current training application assessment or migrate your assessing to GIFT?
  • What information will your training application provide to GIFT? There are no rules when it comes to what information must be provided to GIFT. It all comes down to what will GIFT assess in order to provided tutoring and what information can your training application provide to help facility those assessments. For example, if your training application provides no game state information to GIFT then how can GIFT be expected to assess the user’s performance in your training application.

Each training application integrated with GIFT has its issues, whether it’s licensing, source code availability and/or other limitations. Therefore there has yet to be a single solution from beginning-to-end when it comes to integrating a third party training application. The purpose of GIFT is to provide a framework for doing so and the current implementation is to adhere to the interop interface in the Gateway module.

Create a new Interop Interface

In order to create a new interop interface to communicate between GIFT and your training application, you will first need to create an interop interface implementation. Yes, unfortunately at this time, this procedure does require a software developer familiar with Java to some degree. There are several examples of implementations provided with GIFT. Each does something slightly different. Take note of the input/output common functionality among all of these implementations:

  • Receiving GIFT messages

  • This method is used to deliver GIFT messages from the Domain module to any active interop interface implementation (more about this later…).
  • The most important messages to start with are the SIMAN messages that coordinate GIFT and the training application. The goal is to make the transition between other aspects of GIFT and the training application as seamless as possible. We don’t want the user to have to follow instructions which can be misunderstood or, potentially, adversely affect the learner’s state thereby limiting any learning potential just to start the training application lesson during a GIFT course. In order to help with this we also use Auto Hot Key (AHK) scripts to execute a series of window management, keyboard and/or mouse operations.
  • Sending GIFT messages

  • These methods are used to send GIFT messages (data classes are in “” and codec by classes in “”) from an interop interface class to GIFT.
  • Only messages from currently active interop interfaces will be sent by the Gateway module (more about this later…).

After you have an interop interface class created you will need to include a reference to it in the GIFT/config/gateway/interopConfig.xml file read by the Gateway module during startup. This is where you can configure properties for your interface such as network addresses, port numbers, etc. If you need to create new configuration properties that you currently will have to edit the GIFT/config/gateway/interopConfig.xsd to do so. Take a look at how the XML element “DIS” and “VBS” is used in that file. And remember, after you edit any of the GIFT xsd files, make sure you build the GIFT source again by executing GIFT/build.bat.

The final step is to author and execute a course that contains a reference to your interop interface. Here are some simple steps to follow as a simple example:
  1. Launch the course authoring tool (CAT).
  2. Provide values for the minimal required high level elements of the course.
  3. Add a “Training Application” transition to the course.
    1. use the simplest.dkf.xml for your "dkfRef" value. Eventually you may want to author your own DKF using the DAT. The DKF contains the assessment configuration for this part of the course (which is referred to as a lesson).
    2. select your interop implementation class for "interops"->"interop"->"InteropImpl". If it's not in the list of choices then use the Browse button to find it. This value will be used to enable this interop interface during this part of the course execution.
    3. select your interop input object for the "InteropInputs" value and provide any inputs you authored when you edited the interopConfig.xsd.
  4. Save/Validate the course.xml file.

Now Launch GIFT, login through the Tutor User Interface (TUI) and select your course form the list of courses.

When you reach the part of the course where your training application transition resides, a message will be sent from the domain module to the gateway module indicating which interop interfaces should be enabled. Then a set of simulation management messages (SIMAN) will be sent to the gateway module (e.g. load, start, pause, stop). Any message coming from GIFT, like SIMAN messages, will be delivered by the Gateway module to any active interop interface implementation classes via the “handleGIFTMessage” method (mentioned above).

Migrating Authored Content to Latest GIFT Version

In order to migrate authored content (e.g. courses, surveys, DKFs) from a previous version of GIFT to another, please follow refer to the sections, based on GIFT version, below.

The challenge with up converting courses is to get survey elements that you authored using the SAS into a format that can be consumed by another GIFT. In addition, you will want any survey references you made in any courses or DKFs you authored (i.e. survey context id, survey keys, survey question ids, etc) to be updated according to the changed ids for those elements in the new database as they will be imported into the database as new rows in the various database’s tables.

Conversion Wizards

To up-convert a single XML file at a time that you authored (e.g. course, dkf, sensor configuration), simply open the file in the GIFT Authoring Tool and it will automatically convert your file and back it up. In some cases, only the version number will change as a result of running this process. In other instances your XML element values will be converted to the new XML schema format leaving you to author new required elements before having a valid XML file in the latest GIFT version.


There is just one question to consider when up-converting courses.

  1. Does the course (or any DKF referenced in the course) have references to Surveys that weren’t included with GIFT?
    1. If Yes, follow these steps to import your course with survey references:
      1. Setup your new GIFT with your previous GIFT UMS database by first backing up the new GIFT GIFT\config\ums\ums.hibernate.cfg.xml file (you will use it again later) and then over-writing that same named file with the one from your previous GIFT.
      2. Copy the previous GIFT domain folder (including the course and all necessary files for the course) to the new GIFT Domain folder.
      3. Run the new GIFT Export Tutor application (GIFT\scripts\tools\launchExportTool.bat) to create an export of the GIFT course (result is a zip file).
        1. Select the course you want to export.
        2. Select the “Domain Content Only” checkbox export tutor option.
      4. Switch new GIFT to use the original database by changing the name of the ums.hibernate.cfg.xml backup file created earlier to the original name of ums.hibernate.cfg.xml.
      5. Run the Import Domains tool (GIFT\scripts\tools\importDomains.bat) to select and then import the exported GIFT course.
      6. At this point the course files are in your new GIFT Domain folder and the survey elements have been added to the UMS database as new rows in the database. In addition the course survey references in course and DKFs have been updated with the new ids associated with that database operation. Now you will need to up-convert the XML files that were exported to be new GIFT compliant, please follow the Conversion Wizards section below.
  2. If No, then simply follow the Conversion Wizards section below.

Survey Elements

There are a few questions to consider when up-converting survey elements (e.g. surveys, questions, survey questions, list options, etc.):

  1. Is the survey element used by a survey?
    1. If Yes, please proceed to the next question.
    2. If No, then the only way, currently, to migrate that is to create a survey that uses that element and then please follow the Orphaned Survey Export section below.
  2. Is the survey that you want to export referenced by a survey context and that survey context id is referenced by a course/DKF?
    1. If Yes,
      1. Do you want to migrate the course/DKF into the latest version of GIFT as well?
        1. If Yes, follow the Courses section.
        2. If No, then please follow the Orphaned Survey Export section below.
      2. If No, then please follow the Orphaned Survey Export section below.

Orphaned Survey Export

Follow these steps to export a survey from a previous GIFT version and import it as a new survey in the latest GIFT version.

  1. Launch the GAS in previous GIFT version (GIFT\scripts\launchGAS.bat) and then open the SAS webpage (http://localhost:8080/sas/) in Internet Explorer.
  2. Select the “Surveys” tab to view the list of surveys.
  3. Click the “Export” button for the survey you wish to migrate to the latest GIFT version. The exported survey will be saved to a file in GIFT\data\surveyExports.
  4. Copy the survey export file from the previous GIFT version directory to the same named directory in the latest GIFT version.
  5. Close the SAS webpage and then close GAS.
  6. Launch the GAS in the latest GIFT version (GIFT\scripts\tools\launchGAS.bat), and then open the SAS webpage (http://localhost:8080/sas/) in Internet Explorer.
  7. Select the “Surveys” tab.
  8. Click the “Import Survey” button near the top and select the file you copied earlier. Then select the “Import” button. After the import completes, close the Import Survey dialog.
  9. Check that your survey was added to the end of the list of surveys.