Project

General

Profile

Documentation 2018-1 »

Configuration Settings

Back to Table of Contents

Overview

This document instructs how to configure GIFT for execution and development and gives more insight into the GIFT system.

Course File

A “course file” is an XML file which contains the information needed to execute a course. A GIFT course can contain, among other things, surveys, guidance, training application execution and presentation of lesson material. For detailed information about course files please refer to the GIFT Domain Course File document.

Domain Knowledge File

A domain knowledge file (DKF) is an XML file which contains the information needed to assess a user during a training application scenario (e.g. VBS). For detailed information about DKFs please refer to the GIFT Domain Knowledge File document.

GIFT Property Files

There are numerous property files used by the various GIFT applications in the GIFT/config directory. In addition a hierarchy of property value precedence exists that allows for the sharing of common properties where applicable.

The property file hierarchy is depicted in the figure below where:
  • Modules include: Tutor, Domain, Pedagogical, Learner, Sensor, LMS, UMS and Monitor
  • Authoring Tools include those applications in the src/mil/arl/gift/tools/authoring directory of GIFT.
  • Tools include the applications included in src/mil/arl/gift/tools that are not in the authoring directory.

Here is an example of the hierarchy precedence for the Domain module’s use of a property. 

Example:       
              (domain.properties)                 ActiveMQURL=tcp://localhost:61617
              (module.common.properties)          ActiveMQURL=tcp://10.1.21.28:61617
              (common.properties)                 ActiveMQURL=tcp://GIFT-Desktop:61617
tcp://localhost:61617 will be used for the ActiveMQURL property value.

Common Properties

GIFT/config/common.properties

DomainDirectory
Path to Domain Knowledge Directory
Required
Sets the folder to search for domain content (relative paths are allowed). Any recursive file search is not guaranteed to follow shortcuts to retrieve files but it will follow symbolic links.
DomainDirectory=../Domain/

ExportDirectory
Path where export zip files are placed until they are downloaded or cleaned up
Required
Sets the folder where export zip files go when a user creates a GIFT export.
ExportDirectory=../Domain/Exports/

ImportDirectory
Path where import zip files are placed until they are extracted and the courses imported.
Required
Sets the folder where import zip files go when a user chooses to import a GIFT export.
ImportDirectory=../Domain/Imports/

SensorConfigDirectory
Path to Sensor Module Configuration files Directory
Required
Sets the folder where sensor configuration files are located.
SensorConfigDirectory=config/sensor/configurations/

LearnerConfigDirectory
Path to Learner Module Configuration files Directory
Required
Sets the folder where learner configuration files are located.
LearnerConfigDirectory=config/learner/configurations/

PedagogicalConfigDirectory
Path to Pedagogical Module Configuration files Directory
Required
Sets the folder where pedagogical configuration files are located.
PedagogicalConfigDirectory=config/ped/configurations/

GatewayConfigDirectory
Path to Gateway Module Configuration files Directory
Required
Sets the folder where gateway configuration files are located.
GatewayConfigDirectory=config/gateway/

Database_Backups_Path
Directory Path
Optional (default: will not be able to create or select database backups in GIFT)
The directory where to put and get database backups from
Database_Backups_Path=data/umsDbBackups

GIFTWebsite
URL
Optional (default: https://gifttutoring.org)
This URL is presented to provide users with a way to find out more information about GIFT.
InfoURL=https://gifttutoring.org

DeploymentMode
DeploymentModeEnum {DeploymentModeEnum values are Desktop, Experiment, Server}
Optional (default: Desktop)
The mode the tutor should use. Different modes will alter logic such as the login webpage shown to the user.
DeploymentMode=Desktop

UseDefaultBrowser {true, false}
Optional (default: false)
Whether or not to use the default browse (according to the operating system) instead of Internet Explorer (the GIFT standard) to launch GIFT webpages (e.g. Dashboard, TUI, GAT).

AuthoringToolPath
URL
Optional (default: gat)
The URL of the GIFT Authoring Tool relative to the GAS; a web browser will be launched with this URL when the Authoring Tool button is pressed.
AuthoringToolPath= gat

EventReportToolPath
URL
Optional (default: ert)
The URL of the Event Report Tool relative to the GAS; a web browser will be launched with this URL when the Event Report Tool button is pressed.
EventReportPath= ert

GiftAdminServerUrl
URL
Optional (default: http://localhost:8080)
The URL of the GIFT Admin Server is used to monitor the online status of the server.
GiftAdminServerUrl=http://localhost:8080

SurveySystemPath
URL
Optional (default: sas)
The URL of the Survey System relative to the GAS; a web browser will be launched with this URL when the Survey System button is pressed.
SurveySystemPath= sas

ASAT_URL
URL
Required
The URL for the AutoTutor script authoring tool. If no value is specified, the launch button will be disabled.
ASAT_URL=http://asat.gifttutoring.org/?helpOn=1

TRADEM_URL
URL
Required
The URL for TRADEM. If no value is provided, the launch button will be disabled.
TRADEM_URL=tradem.gifttutoring.org

TutorURL
URL
Required
The URL to launch in a web browser once the SPL has finished loading. This URL should point to the Tutor Module Webpage.
TutorURL= "http://localhost:8090/tutor"

DashboardPath
URL
Required
The URL of the Dashboard relative to the GAS; a web browser will be launched with this URL when the Dashboard webpage is to be shown.
DashboardPath=dashboard

ValidateCoursesAtCourseListRequest {true, false}
Optional (default: true)
Whether all courses that are found should be validated when a course list is requested.
This applies to loading the available courses in the course selection screen of the Tutor User Interface (TUI) webpage.
Setting this value to 'false' will enable a faster loading of the course list by removing the logic that checks the course and its references (e.g. DKF) against GIFT validation logic (i.e. is the referenced website/file/etc. reachable).
The course and its references (e.g. DKF) will be validated against the GIFT XML schemas.
Please be cautious when changing this property, there is no way of knowing every outcome of what will happen if a resources is not available when a learner runs the course that wasn't fully validated.
ValidateCoursesAtCourseListRequest=true

ValidateSurveysAtCourseListRequest {true, false}
Optional (default: true)
Whether all survey elements referenced in all courses that are found should be validated when a course list is requested.
This applies to loading the available courses in the course selection screen of the Tutor User Interface (TUI) webpage.
Setting this value to 'false' will enable a faster loading of the course list by removing the logic that checks the course's references survey elements against the connected survey system.
Please be cautious when changing this property, for example, if a survey element is not found when a learner runs the course the course will end. However, if you know that you have validated courses which will be unchanged (e.g. a classroom setting), this is a way in which you can save loadtimes.
ValidateSurveysAtCourseListRequest=true

ApplyLMSRecordsAtCourseListRequest {true, false}
Optional (default: true)
Whether the LMS records found for a user should be applied to the courses the user can run when a course list is requested. This means having GIFT label courses as recommended or refresher based on internal algorithms.
ApplyLMSRecordsAtCourseListRequest=true

UseHttps {true, false}
Optional (default: false)
Indicates the protocol that should be used in GIFT (http:// or https:// protocol).
UseHttps=false

UsePortForwarding {true, false}
Optional (default: false)
Indicates if port forwarding is being used on the server where GIFT is deployed. This means that GIFT may not need to construct urls with ports in certain cases. One example is the DomainContentHost url, when portforwarding is enabled, GIFT doesn't use the port, since the server redirects the url to the proper port.
UsePortForwarding=false

MessageAckTimeoutMs {Positive Integer}
Optional (default: 10000 milliseconds)
Indicates the timeout (in milliseconds) for when an 'ack' should be considered timed out.
MessageAckTimeoutMs=10000

ModuleStatusMonitorTimeoutMs {Positive Integer}
Optional (default: 10000 milliseconds)
The timeout value (in milliseconds) for the module status monitor. If a module status is not retrieved within this time period, then the module will be timed out and removed.
ModuleStatusMonitorTimeoutMs=10000

TrustedLtiConsumers {json list of trusted consumers}
Optional
The TrustedLtiConsumers property is a JSON object that contains a mapping of trusted lti consumers that are allowed by GIFT (running as an LTI provider). The Json format is used below and could be all on a single line, but for readability is split into multiple lines using the '\' character at the end of each line. New consumers can be added by following the JSON format. A description of each field for a consumer is provided here:
  • name - The name of the consumer (used to identify the consumer). This name must be unique for each consumer in the list.
  • consumerKey - The consumer key that must be unique for each consumer in the list. Typically this is a UUID that is generated for the consumer by the Tool Provider.
  • consumerSharedSecret - The shared secret which should be unique for each consumer and different than the consumer key. This also typically is a UUID that is generated. The shared secret is used to validate the incoming LTI launch request for a specific consumer.
    The LTI specification recommends that different keys are used for different environments such as development or production environments. Additionally it is recommended that the production values are not committed into the normal SVN configuration, but kept specific to the production deploy of GIFT.

An example of the format for this setting follows:

TrustedLtiConsumers={ \
  "trusted_consumers": [ \
           { "name" : "EdX_Test1", "consumerKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "consumerSharedSecret":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"}, \
           { "name" : "EdX_Test2", "consumerKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "consumerSharedSecret":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"} \
      ] \
}

TrustedLtiProviders {json list of trusted providers}
Optional
The TrustedLtiProviders property is a JSON object that contains a mapping of trusted lti providers that are allowed by GIFT (running as an LTI consumer). The Json format is used below and could be all on a single line, but for readability is split into multiple lines using the '\' character at the end of each line. New providers can be added by following the JSON format. A description of each field for a provider is provided here:
  • name - The name of the provider (used to identify the provider). This name must be unique for each provider in the list.
  • providerKey - The provider key that must be unique for each provider in the list. Typically this is a UUID that is generated for the consumer (GIFT) by the Tool Provider.
  • providerSharedSecret - The shared secret which should be unique for each provider and different than the provider key. This also typically is a UUID that is generated. The shared secret is used by the Tool Provider to validate the GIFT LTI request and used again to validate the score response the Tool Provider sends to the GIFT consumer.
    The LTI specification recommends that different keys are used for different environments such as development or production environments. Additionally it is recommended that the production values are not committed into the normal SVN configuration, but kept specific to the production deploy of GIFT.

An example of the format for this setting follows:

TrustedLtiProviders={ \
  "trusted_providers": [ \
           { "name" : "Provider_Test1", "providerKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "providerSharedSecret":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"}, \
           { "name" : "Provider_Test2", "providerKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "providerSharedSecret":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"} \
      ] \
}

LtiTimeoutDashboardMs {Positive Integer}
Optional (default: 10000 milliseconds)
Specifies the timeout (in milliseconds) of when an lti launch is considered 'stale' from the time the initial launch request is received from the server to the time the gift dashboard is connected to. This is an lti security measure to prevent stale launch requests from accessing the gift course.
Allow 10 seconds from the initial lti launch request from the lti servlet to the connection to the gift dashboard.
LtiTimeoutDashboardMs=10000

LtiTimeoutTutorMs {Postive Integer}
Optional (default: 3600000)
Specifies the timeout (in milliseconds) of when an lti launch is considered 'stale' from the time the initial launch request is received from the server to the time the lti course is requested to be started. This is an lti security measure to prevent stale launch requests from accessing the gift course.
Allow 60 minutes from the initial lti launch request from the lti servlet to tutor to start the course.
LtiTimeoutTutorMs=3600000

LtiUrlSubPath {String}
Optional (default: lti)
Specifies the lti sub path where the lti servlet is hosted. This must match the <servlet-mapping> in the web.xml for where the servlet lives. For example, the full url to the lti servlet may look like this: http://localhost:8080/dashboard/lti where /lti is the subpath pointing to the lti servlet.
LtiUrlSubPath=lti

LtiHelpPageUrl {String}
Optional (default: https://gifttutoring.org/projects/gift/wiki/Gift_Lti_Integration_2018-1X)
The URL that is used as the help page for the LTI Configuration Wiki. This is used by the GIFT Course Creator to allow users to see help documentation for configuration of the LTI parameters.
LtiHelpPageUrl=https://gifttutoring.org/projects/gift/wiki/Gift_Lti_Integration_2018-1X

Module Properties

Each module has a Module Properties File associated with it. Refer to the properties file on instructions for how to add new properties to it.

In addition, there is a common module properties file (GIFT/config/module.common.properties) where properties can be specified for all modules.

Property Description Template

PropertyName
Property Value Type
{ Required | Optional (default: <default value> ) }
Property Description
Example

Common Module Properties

Each module may have properties specific to it, but all modules share these common properties:

ModuleName
String
Required
Sets the name of the module
ModuleName=MyModuleName

ActiveMQURL
URL
Required
Sets the URL of ActiveMQ that the module connects to
ActiveMQURL=tcp://localhost:61617

MessageEncodingType {JSON}
Required
Sets type of encoding used by messages sent by this module
MessageEncodingType=JSON

IgnoreIPAddrAllocation {true, false}
Optional (default: false)
This flag indicates whether or not to ignore any ip address filtering when it comes to module allocation for message clients.
Note: In most circumstances the gateway module will need to be on the same computer as the learner, due to training application automation logic handled by the gateway module. Furthermore, the domain module is usually on the same computer as the learner. Therefore when the domain module searches for a gateway module to use, it should use IP address filtering. One instance where you might not want filtering for this type of allocation is during development/testing of new functionality.
IgnoreIPAddrAllocation=true

StartXMLRpcPythonServer {true, false}
Optional (default: false)
This flag indicates whether the module should start an XML Rpc Python server. In the case of the learner module, the learner module will use this parameter to determine if the learner module will start the xml rpc server. The module is responsible for starting and stopping the python server instance.

XMLRpcPythonServerPort
Positive Integer
Optional (default: 0 – invalid port)
This specifies the port that the python server will be started on. The StartXMLRpcPythonServer setting must be set to true to use this setting. The port should be configured to be a valid port that is not in use.

XMLRpcPythonServerClassName
String
Optional (default: “” <empty string>)
The python class that will be registered to use with the xml rpc python server. This class must exist in some python script located in the GIFT/src.py/xml.rpc.server/ folder and must be registered as an import in the main python script GIFT/src.py/xml.rpc.server/XmlRpcServer.py file.

Domain Module Settings

GIFT/config/domain/domain.properties

ValidateCoursesAtStartup {true, false}
Optional (default: false)
Sets whether or not the domain module should validate all courses that are found when the domain module starts. Enabling this property means that the domain module will take more time to start which may have an effect on SPL timeout (a property found in spl.properties)
ValidateCoursesAtStartup=true

BypassSurveyQuestions {true, false}
Optional (default: false)
Sets if survey questions should be skipped in the domain session, useful for quickly getting to the scenario
BypassSurveyQuestions=true

BypassChatWindows {true, false}
Optional (default: false)
This is a flag to indicate whether a bypass type button (e.g. "continue") will be presented on the chat window displayed by the TUI. Basically this indicates whether or not to allow the user to continue w/o having to complete the chat.
BypassSurveyQuestions=true

AutoCompleteScenario
Positive Integer
Optional (default: -1 ) (note: -1 implies AutoCompleteScenario is off)
Sets the number of seconds until the scenario will auto complete after being started. This is intended as a debugging tool.
AutoCompleteScenario=5000

RestartScenario {true, false}
Optional (default: false)
Sets if the training application used in a course should be placed into a state where it can run the next or following training application course element. This relies on the logic being in place to manage this either in the Gateway module interop plugin or the training application itself. (e.g. GIFT manages VBS by using a combination of Auto Hot Key scripts and VBS scripting interface to reset VBS after a scenario and place VBS back on the main menu screen)
RestartScenario=false

EntityTableEntityTimeoutMillis
Positive Integer
Optional (default: 10000)
Threshold used to identify stale entities (entities that are not being updated) and mark them for removal from the EntityTable. Typical values 5000 to 30000 milliseconds.
EntityTableEntityTimeoutMillis=5000

EnityTableDeadReckoningInterval
Positive Integer
Optional (default: 100)
Interval between dead reckoning calculations in milliseconds. Typical values are 30 – 100 milliseconds.
EntityTableDeadReckoningInterval=50

DomainContentServerPort
Positive Integer
Optional (default: The domain content is not hosted – meaning courses can’t contain reference files (e.g. html, pdf) )
Sets port number for a file server that hosts domain content to be hosted from
DomainContentServerPort=8885

DomainContentServerHost
String
Optional (default: The domain content is hosted using the domain modules IP address – which is suitable for individual computer configurations)
Sets the host name to use for the domain content server. If this is not defined the domain module’s IP address will be used instead. No matter what value is used you must considered whether the computer running the tutor client (i.e. web browser) will have access to it (i.e. can the request make it through firewalls, port configurations, proxies, etc.).
DomainContentServerHost=gifttutoring.org

ShowNodeStatusTool {true, false}
Optional (default: false)
Sets if the DKF Performance Node tool is shown for each training application course element. This tool will display the status of every task and concept and is meant as a debugging tool.
ShowNodeStatusTool=false

CommunicationAppDirectory
String (relative to GIFT directory)
Required
This is the directory that is hosted by the domain module jetty instance and contains the
files needed to execute the Communication application Java Web Start instance (i.e. Gateway module).
CommunicationAppDirectory=bin/war

CommunicationAppFile
String (relative to CommunicationAppDirectory property)
Required
This is the Java Web Start file that is hosted by the domain module jetty instance. It is downloaded by the user and executed on the user's computer in order to run the Communication application Java Web Start instance (i.e. Gateway module)
CommunicationAppFile= jws/gift_communication_app.jnlp

Gateway Module Settings

GIFT/config/gateway/gateway.properties

InteropConfig
File path
Required
The interop configuration file to use to configure this instance of the Gateway module.
InteropConfig=config/gateway/configurations/default.interopConfig.xml

LMS Module Settings

GIFT/config/lms/lms.properties

LMS_Connections_Filename
File path
Required
The file name to use as the LMS connections configuration file which is used to configure the LMS connections when the LMS modules starts.
LMS_Connections_Filename=GIFT/config/lms/LMSConnections.xml
(See the below XML file for additional properties)

GIFT/config/lms/LMSConnections.xml

enabled
Boolean (true or false)
Required
Determines whether the implementation will be used, along with its parameters.

impl
implementation (pointer to code or plugin)
Required
Determines the code to execute for LMS connections. Currently supported are: lms.impl.LmsDatabase and lms.impl.Lrs

name
String
Required
Determines the name of the connection

LRS Implementation Parameters

GIFT/config/lms/lmsConnections.xml

networkAddress
URL
Optional (default: No LRS will be used)
The Endpoint of the Learning Record Store(LRS) that GIFT will consume from and publish data to.
networkAddress=http://my.lrs.endpoint.com

username
STRING
Optional (default: No LRS will be used)
The username of the HTTP Basic Auth credentals for the LRS Endpoint.
username=myusername

password
STRING
Optional (default: No LRS will be used)
The password of the HTTP Basic Auth credentals for the LRS Endpoint.
password=myPassword

NOTE: you can set up an LRS for free at https://lrs.adlnet.gov/ (no client app required). A working configuration file may look like the below:

Monitor Module Settings

GIFT/config/tools/monitor/monitor.properties

MessageDisplayBufferSize
Positive Integer
Optional (default: 1000)
Set the size of the message list buffer. Size is number of messages
MessageDisplayBufferSize=150

PostDomainSessionBookmarkTimeoutSeconds
Positive Integer
Optional (default: 60)
The time in seconds to keep a domain session entry in the bookmark editing panel after the domain session has completed.
PostDomainSessionBookmarkTimeoutSeconds=120

WebTutorModulePath
URL
Optional (default: The TUI Webpage cannot be launched from the Monitor)
The URL of the Web Tutor Module relative to the Tutor Web Server; a web browser will be launched with this URL when the TUI Webpage button is pressed.
WebTutorModulePath=tutor

WebTutorModulePort
Positive Integer
Optional (default: The TUI Webpage cannot be launched from the Monitor)
The port of the Tutor Web Server for a Tutor Module; a web browser will be launched with this URL when the TUI Webpage button is pressed.
WebTutorModulePort=8090

EnableWebcamViewing
boolean
Optional (default: false)
Whether or not to show the webcam tab on the monitor. If the tab is enabled and the camera is configured correctly (see “Camera settings [Monitor]”), then snapshots from the camera(s) will be shown.
EnableWebcamViewing=true

MaximumWebcamFPS
Positive Integer
Optional (default: 1)
The maximum number of webcam snapshots to show per second (“frames per second”) on the monitor. A higher number may consume more resources on the workstation running the monitor. This property is not used if the “EnableWebcamViewing” property is set to false.
MaximumWebcamFPS=30

RemoteLaunchDiscoveryBroadcastAddress
IP Address
Optional (default behavior is for module to ascertain the broadcast address on its own).
If set, this is the broadcast address used by the ModuleMonitor to announce its presence to the Remote Launch Service instances running on the local area network.
RemoteLaunchDiscoveryBroadcastAddress=10.1.21.255

RemoteLaunchWorkstationListenPortList
Positive Integer (range: 1024 – 65535)
Optional (default: 50601)
This is a space delimited list of port numbers on which the MonitorModule will broadcast its presence to the Remote Launch Service instances running on the local area network. In most cases a single port number will suffice. List of more than one port is supported in case one or more of the desired GIFT hosts has a port conflict. Note that the port values used by the various Remote Launch Service instances for their RemoteLaunchWorkstationListenPort property must be present in the list.
Example 1: RemoteLaunchWorkstationListenPortList=50601
Example 2: RemoteLaunchWorkstationListenPortList=50601 50602 50603

RemoteLaunchMonitorListenPort
Positive Integer (range: 1024 – 65535)
Optional (default: 50600)
Port number used by the remote launch capability to listen for heartbeats sent by the learner workstations.
RemoteLaunchMonitorListenPort=50600

RemoteLaunchHeartbeatInterval
Positive Integer
Optional (default: 5000)
Heartbeat interval for sending heartbeat broadcast messages. The value used here should match the value used for the RemoteLaunchHeartbeatInterval in the configuration file of the Remote Launch Service.
RemoteLaunchHeartbeatInterval=5000

ApplicationTitle
String
Optional (default: Monitor Module)
Window title to use for the Monitor Module JPanel
ApplicationTitle=GIFT Monitor Module

Pedagogical Module Settings

GIFT/config/ped/ped.properties

UseGUI {true, false}
Optional (default: false)
Sets if the GUI to change pedagogical models during runtime should be displayed
UseGUI=false

PedagogicalConfigurationFile
File path
Required (default: config/ped/Default.pedagogicalconfig.xml)
This is the file that configures the Pedagogical module’s engines. Currently it contains the configuration for the engine for Management of Adaptive Pedagogy (eMAP).
PedagogicalConfigurationFile=config/ped/Default.pedagogicalconfig.xml

Sensor Module Settings

GIFT/config/sensor/sensor.properties

SensorConfigurationFile
File path
Optional
This is the file that configures the sensor module with the sensors, filters and writers that will be used during a domain session. If not file is specified, the sensor module will be configured with no sensors.
SensorConfigurationFile=config/sensor/SensorConfigurations/Emotiv.sensorconfig.xml

MinSecBtwErrors
Positive Double
Optional (default: 5.0)
This is the minimum amount of seconds between the same errors being sent over the network by a sensor instance.
For example, the Q Sensor sends error message of "There was an error" at t=1.23 and t=3.45, only the first error message will be sent.
This prevents sensor implementations from over-whelming the message infrastructure with errors reported w/in a small timeframe.
MinSecBtwErrors=3.0

Learner Module Settings

GIFT/config/learner/learner.properties

LearnerConfigurationFile
File path
Optional (default: config/learner/Default.learnerconfig.xml)
This is the file that configures the learner module to support building learner states from inputs such as sensor data and performance assessments.
LearnerConfigurationFile=config/learner/Default.learnerconfig.xml

Tutor Module Settings

GIFT/config/tutor/tutor.properties

LandingPageMessage
String
Optional
This message is shown on the login page of the TUI. It can be used to notify the user of schedule maintenance or other reasons.
LandingPageMessage=This tutor will be down for some quick maintenance on June 19th 2014 at 1pm EDT

Web Server Port
GIFT/config/tutor/server/jetty.xml

Refer to the Jetty documentation for changing the port the Tutor User Interface is hosted on (http://docs.codehaus.org/display/JETTY/Quick+Start)

UMS Module Settings

GIFT/config/ums/ums.properties

SystemMessageLogDuration
Positive Integer
Optional (default: 24)
The duration, in hours, that a system message log file should contain messages for. The start time is when the first message is written.
SystemMessageLogDuration=24

Remote Launch Service Properties

GIFT/config/tools/remote/remote.launch.service.properties

RemoteLaunchWorkstationListenPort
Positive Integer
Optional (default: 50601)
Port on which the remote launch service will listen for heartbeat and start command messages coming from the monitor. If a non-default value is entered here it MUST also be added to the RemoteLaunchWorkstationListenPortList in the Monitor Module Properties.
RemoteLaunchWorkstationListenPort=50601

RemoteLaunchHeartbeatInterval
Positive Integer
Optional (default: 5000)
Interval in milliseconds between heartbeats sent (via UDP unicast) to the monitor.
If set to a non-default value, that value should be also used to set RemoteLaunchHeartbeatInterval in the Monitor Module properties.
RemoteLaunchHeartbeatInterval=5000

Tool Properties

Each tool (e.g., Survey Authoring System [SAS] ) may or may not have a properties file associated with it. Refer to the properties file on instructions for how to add new properties to it.

Authoring Tool Common Properties

GIFT/config/tools/authoring/authoring.common.properties

UseDBConnection {true, false}
Optional (default: false)
Flag used to indicate whether to connect to the survey database for retrieving survey information (e.g. available surveys).
UseDBConnection=true

Control Panel Tool

GIFT/config/tools/controlpanel/controlpanel.properties

Course Authoring Tool (CAT)

GIFT/config/tools/authoring/cat/cat.properties

CourseSchemaFile
File path
Optional (default: config/domain/course/course.xsd)
This is the XML schema file the CAT uses to build and validate Course XML content.
CourseSchemaFile= config/domain/course/course.xsd

GenerateLessonMaterialFile {true, false}
Optional (default: false)
Whether or not to automatically generate a lesson material XML file based on the entries authored in a course file when it is being saved using the CAT.
Having the CAT generated a lesson material XML file allows the author to easily share common lesson material across course/domains.
GenerateLessonMaterialFile= false

DKF Authoring Tool (DAT)

GIFT/config/tools/authoring/dat/dat.properties

DKFSchemaFile
File path
Optional (default: config/domain/dkf/dkf.xsd)
This is the XML schema file the DAT uses to build and validate DKF XML content.
DKFSchemaFile=src/mil/arl/gift/common/dkf/schema/dkf.xsd

Event Report Tool (ERT)

GIFT/config/tools/ert/ert.properties

defaultEventTypes
List of event types {MessageTypeEnum name values, mil.arl.gift.tools.ert.server.SensorWriterEventSourceParser.SENSOR_WRITER_EVENT_NAME value, mil.arl.gift.tools.ert.server.BookmarkEventSourceParser.BOOKMARK_EVENT_NAME vale}
Optional (default: empty list)
The list of event types will be used to check the boxes next to those respective event types on the user interface of the ERT. By having those boxes checked, the event types will be used in any generated report output files.
defaultEventTypes=LearnerState,PedagogicalRequest,SensorData,SensorFilterData,PerformanceAssessment,Bookmark

Learner Configuration Authoring Tool (LCAT)

GIFT/config/tools/authoring/lcat/lcat.properties

LearnerConfigSchemaFile
File path
Optional (default: config/learner/learnerConfig.xsd)
This is the XML schema file the LCAT uses to build and validate Learner configuration XML file content.
LearnerConfigSchemaFile=config/learner/learnerConfig.xsd

Metadata Authoring Tool (MAT)

GIFT/config/tools/authoring/mat/mat.properties

MetadataSchemaFile
File path
Optional (default: config/domain/metadata/metadata.xsd)
This is the XML schema file the MAT uses to build and validate metadata XML file content.
MetadataSchemaFile=config/domain/metadata/metadata.xsd

Pedagogy Configuration Authoring Tool (PCAT)

No properties yet.

Sensor Configuration Authoring Tool (SCAT)

GIFT/config/tools/authoring/scat/scat.properties

SensorConfigSchemaFile
File path
Optional (default: config/sensor/sensorConfig.xsd)
This is the XML schema file the SCAT uses to build and validate Sensor configuration XML file content.
SensorConfigSchemaFile=config/sensor/sensorConfig.xsd

TestSensors {true, false}
Optional (default: false)
Flag used to indicate whether to test the sensors in a sensor configuration file during the user initiated GIFT Validation process. Testing a sensor means calling the test method of the sensor implementation class.
TestSensors=false

Survey Authoring System (SAS)

GIFT/config/tools/sas/sas.properties

File_Server_Path
Directory Path
Required
The directory where the survey images are located; this will be used to service requests for survey images and also is where uploaded survey images will be stored
File_Server_Path=data/surveyimages

File_Server_Excludes
Comma separated list of strings
Optional (default: no files will be excluded)
Excludes files from being listed in the survey image list. If an entry in the list is found in the string to the survey image then the entry will not be listed.
For example,
If ‘.svn’ is being excluded, ‘.svn/myimage.jpg’ would not be listed in the survey image list
File_Server_Excludes=.svn

Survey_Export_path
Directory Path
Required
The directory where surveys are imported from and exported to.

Single Process Launcher (SPL)

Timeout
Integer
Required
How much time, in seconds, to wait for modules to load before GIFT times out. This number should be higher on slower machines. The default is 15 seconds.

Dashboard

GIFT/config/tools/dashboard/dashboard.properties

LandingPageMessage
String
Optional
This message is shown on the login page of the Dashboard. It can be used to notify the user of schedule maintenance or other reasons.
LandingPageMessage=This tutor will be down for some quick maintenance on June 19th 2014 at 1pm EDT

UseCloudLoginPage {true, false}
Optional (default=false)
Variable to control if the cloud version of the login page should be displayed. The cloud version of the
login page is different than the normal GIFT login page in that it forces the user to accept the terms of the GIFT EULA,
and also has different branding and messaging to describe the cloud version of GIFT.
This value should only be set to true for the cloud version of GIFT. Most users should never need to change the value of this setting.
The default is false (which means to use the normal login page).
UseCloudLoginPage=false

CourseValidationCacheExpiration
Integer [not negative]
Required
Number of seconds that the Dashboard Service will cache a course validation result.
A value of zero will effecitively disable the validation cache.
CourseValidationCacheExpiration=120

InvalidCourseValidationCacheExpiration
Integer [not negative]
Required
Number of seconds that the Dashboard Service will use a cached course validation
for a course that has failed validation. This should be set lower or equal to the
above CourseValidationCacheExpiration.
InvalidCourseValidationCacheExpiration=10

TutorCourseStartTimeout
Integer [greater than zero]
Optional (default = 10)
Number of seconds before the dashboard times out when the tutor is starting a course.
This will cause the session to end and returns the learner to the course tile page.
TutorCourseStartTimeout=10

Deployment Modes

There are currently three different types of deployment modes for GIFT in order to support the various ways a user may want to interact with GIFT.

Experiment

In this mode the main user interface for GIFT is a simple login webpage that presents a user id field. A user id consists of an integer and represents the user’s unique id in GIFT. This is the original login webpage for GIFT and is useful for many situations such as experiments where anonymity is needed. This login webpage doesn’t require an internet connection but merely a connection to the UMS module which is required to run a GIFT session in the first place.

After logging in the user is presented with a course list to allow the user to select a course to start.

Desktop

In this mode the main user interface for GIFT is the GIFT Dashboard. The initial page is a login webpage that presents a username and password field. This page will authenticate against user accounts on gifttutoring.org.

  • A note about internet connectivity: If your computer is unable to reach gifttutoring.org GIFT will ask you to go into offline mode. In offline mode, the user is presented with a list of user to choose from that have already been authenticated on the GIFT instance.

Feel free to replace the existing authentication implementation (i.e. GIFT Tutoring authentication protocol) with a different one as you see fit.

After logging in the user is able to interact with various GIFT tools and execute GIFT courses.

Server

In this mode the main user interface for GIFT is the same as in Desktop mode. The main differences in this mode however are:
  • Files are located in GIFT’s content management system (CMS).
  • Users are restricted to what files they can see and what tools are available based on the user management system.
  • A Java Web Start (JWS) Gateway module application may need to be downloaded prior to running a course that needs to communicate with a locally running training application.

Camera Settings (Monitor)

To configure the web cameras being displayed on the monitor you will need to edit:
GIFT\config\tools\monitor\cameras.txt

The entries in this file follow the format:
camera_display_name=ip_address_of_camera

The monitor requires that the web cameras being available on port 8081 at the specified IP address for image capture. More information on how to enable an IP based webcam can be found in the GIFT install instructions under the Yawcam section.

Logging

GIFT source logging (except webpages)

GIFT/config/(module or tool name)/(module or tool name).log4j.properties

Each module creates a log file in the folder ‘GIFT/output/logger/module’ and tools in the folder 'GIFT/output/logger/tools' upon starting. The degree to which packages can write their log statements to the log file is defined by log levels in the specific log4j properties file.

The log4j log files are used primarily for debugging and troubleshooting.

Log4j: More information on log4j can be found here: http://logging.apache.org/log4j/1.2/manual.html.

Log4j: The set of possible log levels are: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.

Examples

1. Let's say I want to increase the default log level of Warn in the domain module to Debug. Furthermore I don't want to increase the log level for all of the code running in the domain module but just the code in the mil.arl.gift.domain package.

In GIFT/config/domain/domain.log4j.properties there is this line:

log4j.logger.mil.arl.gift.domain=warn

changing the 'warn' to 'debug' (in this case) would increase the log level:

log4j.logger.mil.arl.gift.domain=debug

Now the domain module log will have debug and above logging for the domain named package.

2. What if you don't know which source code package you want to increase logging for? Then the easiest log level change to make is the 'root' level. Look for the following, usually at the top of a GIFT log4j property file:

log4j.rootLogger=warn, domain

and change 'warn' to the level you wish. This will change the log level for any package not specifically defined in the property file. If you want to increase logging across all packages than you can simply change all 'warn' (or other values) to the log level you want.

Dynamic log levels

All of the GIFT modules (except Tutor) support changing the log levels while the module is running. After changing the log level and saving the file a new module log file will be created.

GIFT webpage logging

The client side logging from GIFT webpages can be found in the browsers developer console. The log levels are set when the various GWT war files are created during the GIFT build process.

GIFT Java Web Start Gateway module logging

The client side logging of a Java Web Start (JWS) application is managed by Java.

To enable Java logging for debugging purposes:
1) Open "Java Control Panel"

2) Goto "Advanced" tab
3) Check "Enable tracing" and "Enable logging" under "Debugging" section.

optionally you can show the Java console while the JWS application is running by selecting "Show console" under "Java console" section.

Where are the JWS Java log files?

The log files are normally located in C:\Users\<username>\AppData\LocalLow\Sun\Java\Deployment\log\.

If not in that directory check "Location" value for Temporary File Settings for the root path to the "Deployment" directory on your computer.

LMS Module “LMS Connections” Settings

GIFT/config/lms/LMSConnections.xml (default, configured by lms.properties file)

This configures the LMS connections for the LMS module when it starts. The LMS connections file schema can be found at GIFT/config/lms/LMSConnections.xsd. The XML file can contain one or more LMS configurations thereby allowing the LMS module to connect to multiple LMS back-ends simultaneously. Any requests from GIFT for a learner’s record are sent to each of the configured LMS connections. The LMS records provided are then shown to the user in the GIFT Tutor User Interface (TUI) on the LMS course history webpage. Moreover, when GIFT has a record to store in the LMS, each LMS connection is given those records for a chance to store it in their respective LMS storage system. This feature allows GIFT to retrieve a better learner history across multiple systems.

In order to support the Experience API (spec located here: https://github.com/adlnet/xAPI-Spec/blob/master/xAPI.md#stmtapi, a connection can be made to a Learning Record Store(LRS). In order to start publishing and consuming data from a LRS, the LRS must exists somewhere that GIFT can see (on the same network, same machine, or over the internet). There are several options for an LRS. There are open source and cloud based options available for obtaining a LRS. GIFT has been tested with Advance DistributedLearning (ADL)'s open source LRS (availible here: https://github.com/adlnet/ADL_LRS) and with WaxLRS (a cloud based LRS, availible here:https://www.waxlrs.com/). Once the LRS is set up, create new HTTP Basic Auth credentials and add the endpoint and credentials to the connection.

Gateway Module “Interop Connection” Settings

An interop connection is used to configure the connections between the gateway module and third-party systems used as training applications (e.g., Distributed Interactive Simulations (DIS), High Level Architecture (HLA) compatible simulations, game-based simulations such as Virtual Battle Space 2 (VBS), Microsoft PowerPoint)

Interop Connection Settings

GIFT/config/gateway/interopConfig.xml

The interop configuration file is used to instantiate interop interface plugins (i.e., classes in Gateway package) which are used to facilitate communication between GIFT and external applications, in particular, various training applications.

The interop configuration file is handled by the InteropConfigFileHandler.java and validated against interopConfig.xsd (GIFT\config\gateway\). Each interop interface class must have a “config” method with a parameter for configuration argument object.

The following subsections describe the interop interfaces that have been created for GIFT. For more information on the messages theses interfaces can handle, please refer to GIFT Interface Control Document.

Distributed Interactive Simulations (DIS)

More information on DIS standard: http://usl.sis.pitt.edu/trurl/DIS/JdbeHtmlFiles/dis-dd.html.

Description of the various input parameters needed, and validated against using the interopConfig.xsd, by the GIFT DIS interop interface:

  • available - (optional) Whether this interop interface is available for use by this GW module (Default is true). An interface might be unavailable if the training application is not installed.
  • impl – specify the classpath to the DIS interop interface implementation class which handles communication between GIFT and DIS clients.
  • name – display name for this interop interface
  • exerciseID - the DIS network exercise ID, used to filter out traffic from other DIS scenarios.
  • networkPort - The network port to listen and send DIS traffic on. This number needs to match other client’s DIS network port configurations (e.g., dis.sendPort in Bohemia Interactive\VBS\config\DIS\DIS.config)
  • siteID - The unique site Id for this DIS site.
  • applicationID - The unique application id for the simulation application communicating with DIS at a particular site
  • networkAddress - The IP address to send DIS messages too. It can be set to a single host (point to point), a broadcast address or a multicast address.

Virtual Battle Space (VBS)

Description of the various input parameters needed, and validated against using the interopConfig.xsd, by the GIFT VBS interop interface:

  • impl – specify the classpath to the VBS interop interface implementation class which handles communication between GIFT and the GIFT VBS plugin DLL.
  • name – display name for this interop interface
  • networkPort - The network port to communicate on with the VBS Plugin dll. If you change this value, also change the “PortNumber” property of the GIFT VBS Plugin. Refer to the GIFT VBS Plugin section of this document on how to configure it.
  • networkAddress - The network address to communicate on with the VBS Plugin DLL.

PowerPoint (PPT)

Description of the various input parameters needed, and validated against using the interopConfig.xsd, by the GIFT PPT interop interface:

  • available - set to false if a GIFT supported version(s) PowerPoint is not installed on your machine.
  • impl – specify the classpath to the PPT interop interface implementation class which handles communication between GIFT and the PowerPoint application. This is typically ‘gateway.interop.ppt.PPTInterface’.
  • name – display name for this interop interface

TC3 (vMedic)

Description of the various input parameters needed, and validated against using the interopConfig.xsd, by the GIFT TC3 interop interface:

  • impl – specify the classpath to the TC3 interop interface implementation class which handles communication between GIFT and TC3.
  • name – display name for this interop interface
  • networkPort - The network port to communicate on with TC3. If you change this value, also change the “GIFT.server” property of the TC3 cfg.ini file (<path-to-TC3>\bin\config\cfg.ini)
  • networkAddress - The network address to communicate on with TC3.

SCATT

Description of the various input parameters needed, and validated against using the interopConfig.xsd, by the GIFT SCATT interop interface:

  • impl – specify the classpath to the SCATT interop interface implementation class which handles communication between GIFT and the SCATT Bridge application.
  • name – display name for this interop interface
  • networkPort - The network port to communicate on with the SCATT Bridge application.
  • networkAddress - The network address to communicate on with SCATT Bridge application.

Simple Example Training Application (TA) – XML RPC

Description of the various input parameters needed, and validated against using the interopConfig.xsd, by the GIFT Simple Example TA interop interface:

  • impl – specify the classpath to the Simple Example TA interop interface implementation class which handles communication between GIFT and the Simple Example C# Training application. This application is provided in the GIFT release under the top level folder named “Training.Apps”. The application as well as the interop interface is used in the GIFT Developer Guide.
  • name – display name for this interop interface
  • XML-RPC – these are the common inputs needed when setting up an XML-RPC Server/Client relationship.
    • ExternalServerNetworkAddress- The network address of the XML-RPC server external to GIFT. This server contains remote methods for GIFT to call (e.g. loadScenario).
    • ExternalServerNetworkPort- The network port of the XML-RPC server external to GIFT.
    • ServerNetworkPort – the network port of the GIFT XML-RPC server. This GIFT based XML-RPC server contains remote methods for an external system to call (e.g. updateGameState).

Sensor Configuration

Default: none

Sensor Configuration files define what and how sensors are connected and configured to a GIFT sensor module.

All of the configuration files for sensors integrated to date can be found in the downloadable GIFT at GIFT/config/sensor/configurations. A list of sensors integrated include:

  1. BioHarness
  2. Emotiv
  3. Microsoft Kinect
  4. Microsoft Band 2
  5. Temperature/Humidity Mouse (custom made for ARL)
  6. OS3D WOM sensor (both wired and wireless)
  7. Q sensor
  8. Multisense
  9. Software based simple sensors made for GIFT: Sine Wave, Self Assessment

To use a sensor configuration in your GIFT sensor module you will need to set the SensorConfigurationFile property in GIFT/config/sensor/sensor.properties. Currently only a single sensor configuration file can be used for the execution of a sensor module. In the future we hope to associate a sensor configuration to a course as well as support sensors when GIFT is running in server deployment mode.

The Sensor Configuration file can have multiple sensors associated with it. This means that a single sensor module can execute with multiple sensors.

The schema for the sensor configuration flie is GIFT/config/sensor/sensorConfig.xsd.

The sensor configuration file should be authored (i.e., edited, created) using the GIFT Authoring Tool which can be accessed via the GIFT Dashboard.

The following is an explanation, with examples, of how to create and edit the Sensor Configuration.

There are 3 main sections of a sensor configuration file: sensors, filters, and writers.

Sensors

The sensors section specifies the types of sensors the sensor module will be collecting sensor data from. These sensors can be hardware supported (e.g., EmotivSensor) or a complete software implementation (e.g., SelfAssessmentSensor).

Required:
  • id – unique id among all sensors, filters and writers
  • name – display name for the sensor
  • sensorImpl – the sensor implementation class which contains the logic for collecting sensor data. The sensor data will then be provided to the sensor module for further handling. A sensor implementation class needs to be specified with the class path as well (e.g.,sensor.impl.MouseTempHumiditySensor). If the sensor is associated with hardware, the sensor implementation class knows how to read the sensor data from that hardware.
  • distributeExternally – whether the raw sensor data should be sent to the Learner module.

    distributeExternally: If this value is false, the sensor must specify a filter instance to identify that the sensor data will be used somewhere in the sensor module.

Optional:
  • interval – the amount of seconds between sensor readings.

    Sensor Interval: If this value is not provided, then the sensor will be read as fast as sensor data is produced and handled.

  • filterInstance – the unique id of a filter instance which will be responsible for filtering the raw data from this sensor.

    Filter Instance: If this value is not provided, then the sensor must send the raw sensor data to the Learner module by setting the “distributeExternally” input to “true.”

  • writerInstance – the unique id of a writer instance which will be responsible for writing the raw sensor data, e.g., a writer instance can write raw sensor data to a csv file.
  • sensorInput – place to provide sensor specific configurations that will be provided to the constructor of the specified sensor implementation class, e.g., for sensor.impl.SelfAssessmentSensor:
<sensorInput>
   <SelfAssessmentSensor>
               <rateChangeAmount>0.1</rateChangeAmount>
   </SelfAssessmentSensor>
</sensorInput>

Filters

The filters section specifies the available filters in the sensor module that can be used to filter raw sensor data.

Sensor Filters: Multiple sensors in a sensor module can use the same sensor filter.
Required:
  • id – unique id among all sensors, filters and writers
  • name – display name for the filter
  • filterImpl – the filter implementation class contains the logic to filter raw sensor data. A filter implementation class needs to be specified with the class path as well (e.g. sensor.filter.EmotivSensorFilter).
  • distributeExternally – whether the filtered sensor data should be sent to the Learner module.

    distributeExternally: If the filter is referenced by a sensor and that sensor doesn’t distribute sensor data, this value must be true for the filter. Otherwise the validation process will fail because the sensor data will never make it to the Learner module.
    Optional:

  • writerInstance – the unique id of a writer instance which will be responsible for writing the filtered sensor data, e.g., a writer instance can write filtered sensor data to a csv file.

    Distribute Externally: There needs to be at least one externally distribute source (i.e., sensor or filter) in the sensor module’s sensor configuration file.

Writer

The writers section specifies the available writers in the sensor module that can be used to write sensor data or filtered data. The current collection of GIFT writers can write data to disk using the csv format.

Sensor Writers: Multiple sensors and filters in a sensor module can use the same sensor data writer.
Required:
  • id – unique id among all sensors, filters and writers
  • writerImpl – the writer implementation class contains the logic to write the sensor/filter data. A writer implementation class needs to be specified with the class path as well (e.g., sensor.writer.GenericSensorDelimitedWriter).
  • writerInput – place to provide writer implementation class configurations. There must be a writer implementation class constructor with the writer input parameter, e.g., for sensor.writer.GenericSensorDelimitedWriter:
     
<writerInput>
   <GenericSensorDelimitedWriter>
      <directoryToWrite>output/sensor</directoryToWrite>
      <filePrefix>filteredSelfAssessment</filePrefix>
   </GenericSensorDelimitedWriter>
</writerInput>

Learner Configuration

GIFT/config/learner/configurations/Default.learnerconfig.xml

This learner configuration file defines the translators, classifiers and predictors for sensor data of various types. As the sensor data, filtered and/or unfiltered, is received by the Learner module it first passes through a translator followed by a classifier and then finally a predictor. The result is a learner state for the learner state attribute(s) (e.g., arousal, engagement) associated with the various sensor data attributes (e.g., humidity, self-assessment).

The schema for the learner configuration file is GIFT/config/learner/learnerConfig.xsd.

The learner configuration file should be authored (i.e., edited, created) using the GIFT Authoring Tool which can be accessed via the GIFT Dashboard.

The following is an explanation, with examples, of how to create and edit the Learner Configuration.
There are 4 main sections of a learner configuration file: translator, classifier, predictor, producers.

Translator
The translator is responsible for translating the sensor/performance data received from the sensor module, e.g., the MouseTranslator normalizes the mouse sensor data.

Required:
translatorImpl – the implementation class of the translator. A translator implementation class needs to be specified with the class path as well (e.g., learner.clusterer.data.SelfAssessmentTranslator).

Classifier
The classifier is responsible for classifying sensor/performance data into a learner state, more specifically the current learner state.

Required:
classifierImpl – the implementation class of the classifier. A classifier implementation class needs to be specified with the class path as well (e.g., learner.clusterer.EngagementTwoStateClassifier).

Predictor
The predictor is responsible for predicting the next learner state based on sensor/performance data and the current classified state.

Required:
predictorImpl – the implementation class of the predictor. A predictor implementation class needs to be specified with the class path as well (e.g., learner.predictor.EngagementTwoStatePredictor).

Producers
A producer element details which input set of translator/classifier/predictor should be used for a particular sensor’s data.

Required:
(list) producer – the type of sensor (SensorTypeEnum) whose raw/filtered data will use the translator, classifier and predictor.

UMS Database Connection Configuration

GIFT/config/ums/ums.hibernate.cfg.xml

This snippet defines the database connection from the UMS module.
1. <!-- Database connection settings -->
2. <property name="connection.driver_class">org.apache.derby.jdbc.EmbeddedDriver</property>
3. <property name="connection.url">jdbc:derby://localhost:1527/derbyDb/GiftUms</property>
4. <property name="connection.username">root</property>
5. <property name="connection.password">root</property>

i.        &lt;property name="connection.url"&gt; jdbc:derby://localhost:1527/derbyDb/GiftUms/&lt;/property&gt;
The url contains the address of the Derby UMS database.  By default the Derby port is 1527.  The IP address can be localhost.
ii.        &lt;property name="connection.username"&gt;root&lt;/property&gt;
This is the Derby username to use when the UMS connects.
iii.        &lt;property name="connection.password"&gt;root&lt;/property&gt;
This is the password for the user.

LMS Database Connection Configuration

GIFT/config/lms/lms.hibernate.cfg.xml

This snippet defines the database connection from the LMS module.
1. <!-- Database connection settings -->
2. <property name="connection.driver_class">org.apache.derby.jdbc.EmbeddedDriver</property>
3. <property name="connection.url">jdbc:derby://localhost:1527/derbyDb/GiftLms</property>
4. <property name="connection.username">root</property>
5. <property name="connection.password">root</property>

i.        &lt;property name="connection.url"&gt; jdbc:derby://localhost:1527/derbyDb/GiftLms/&lt;/property&gt;
The url contains the address of the Derby LMS database.  By default the Derby port is 1527.  The IP address can be localhost.
ii.        &lt;property name="connection.username"&gt;root&lt;/property&gt;
This is the Derby username to use when the LMS connects.
iii.        &lt;property name="connection.password"&gt;root&lt;/property&gt;
This is the password for the user.

Training Applications

Custom Training Application

In some instances, you may want to control (i.e., automate) a training application that isn’t currently configured with GIFT, such as a Java application. The control may include launching the application, monitoring state of the application and closing the application. Currently the best (and easiest) way to achieve this is to create a Gateway module interop connection. Examples of an interop connection include DIS (gateway.interop.dis.DISInterface) and VBS plugin (gateway.interop.vbsplugin.VBSPluginInterface). Your developed interop connection class should contain the logic to register for SIMAN message types to be notified with, like when a SIMAN.Load message is received, in a similar manner as VBSPluginInterface does. Upon receiving the load message, the interop class would then launch the custom training application. In a similar manner, when a stop message is received, the training application could be terminated. We leave it up to you to develop a way for the states of the training application (or user) to be delivered to the Gateway module which will transmit the appropriate information to GIFT in GIFT messages for assessment. Take note that the assessment logic might need to know, at a minimum, when the training application started and stopped.

GIFT can also control the training application’s window (make the window always on top, give focus, etc) in your custom interop interface class. In order to do so you need the AHK class attribute of your application. You can find this value by downloading and installing AutoHotKey (http://www.autohotkey.com/) and then running the included ‘Window Spy’ application (currently called “AU3_Spy.exe”) and getting the string next to “ahk_class” in the window. You can use this string for the methods in ‘gateway.GatewayModuleUtils’ to control your application’s window. A screenshot of the Spy application is shown below. Notice the “ahk_class” value of “TC3Sim Trainer”.

After you create the interop class, which handles communication between GIFT and the training application, you will need to author the interop configuration in the interopConfig.xml (GIFT/config/gateway/interopConfig.xml). This may involve augmenting the interopConfig.xsd depending on the types of configurations needed. Look at the DIS interop configuration XML elements as an example.

Now that the interopConfig.xml file is authored appropriately, the Gateway module will initialize the interop connections using the files content. The final step is to author the domain’s DKF (specifically the resources/transitions section) to specify the interop connections to use when the lesson is being started via the Training Application transition (Refer to GIFT Domain Knowledge File document for more information on DKF).

We encourage you to discuss implementation details, especially on modifying GIFT, on the GIFT portal to help facilitate development across the GIFT community.

Virtual Battlespace Simulation (VBS)

For install instructions specific to the GIFT integration with VBS refer to GIFT VBS install.

VBS DIS Properties

In previous installs of VBS you could simply open the VBS DIS.config file in a text editor and change various properties so that GIFT could communicate with VBS. With the recent version of VBS the process has been moved to a webpage.

A new step for VBS configuration starting from v3.9.2 is to configure the VBS gateway for use with GIFT.

i. open http://localhost:2310/ui/VBSGateway in a browser

ii. on the Settings page, click DIS, than change the receive port from 3000 to 3005

iii. change the exercise ID to match what is in your GIFT/config/gateway/configurations/default.interopConfig.xml file in GIFT.

iv. Select Apply button on Settings page.

v. on the Mappings page, click Import Mapping File and import the newly created file in GIFT of Domain\resources\external\VBS.common\GIFT_VBS_DIS_Mappings.Export.csv.
You may have to change the file extension type on the file browse dialog to '.csv' in order for the GIFT csv file to show in the file list.
The import can take several minutes. When completed you should see a dialog indicating a successful import.

vi. That's it. You can close the browser window.

VBS Control Properties

GIFT/config/gateway/externalApplications/VBS/vbs.control.properties

This file is used to get the values for various VBS controls when changes in the scenario are needed.

Overcast

Decimal, between 0.0 and 1.0, inclusive
Sets how much overcast is present when requesting overcast.

FogLevel1

Low Density Fog
Decimal, between 0.0 and 1.0, inclusive
Sets how much fog is present when requesting different levels of fog.

FogLevel2

Medium Low Density Fog
Decimal, between 0.0 and 1.0, inclusive
Sets how much fog is present when requesting different levels of fog.

FogLevel3

Medium High Density Fog
Decimal, between 0.0 and 1.0, inclusive
Sets how much fog is present when requesting different levels of fog.

FogLevel4

High Density Fog
Decimal, between 0.0 and 1.0, inclusive
Sets how much fog is present when requesting different levels of fog.

Rain

Decimal, between 0.0 and 1.0, inclusive
Sets how much rain is present when requesting rain.

TimeOfDayDusk

Integer, between 0 and 23, inclusive
Sets what hour to change to for dusk.

TimeOfDayDawn

Integer, between 0 and 23, inclusive
Sets what hour to change to for dawn.

TimeOfDayMidday

Integer, between 0 and 23, inclusive
Sets what hour to change to for midday.

TimeOfDayMidnight

Integer, between 0 and 23, inclusive
Sets what hour to change to for midnight.

GIFT VBS Plugin

A C++ application is used to communicate with VBS. The DLL (.dll) developed by GIFT allows the Gateway module to send commands and receive results from VBS. The plugin is provided as a part of GIFT, located in: Training.Apps/VBS/VBSGIFTPlugin/. Upon installation of GIFT, the plugin is placed in <<VBS Install Directory>/plugins/

The plugin’s configuration files is located here:
<<VBS Install Directory>>/{plugins|plugins64}/gift/config/giftvbsplugin.properties

Refer to GIFT VBS Plugin for more information on how to configure the GIFT VBS plugin.

Scenario Mission Briefing File

Example:
Domain/workspace/Public/Presence Patrol (Sara)/PathToVBS.VBS.mpmissions/PresencePatrol.Sara/briefing.html

This is an example of how to define a mission briefing to be shown to the learner inside of VBS right before the scenario is started. This html page is located in the PresencePatrol.Sara scenario which is associated with the VBS.PresencePatrol.Scenario GIFT domain knowledge. To define a mission briefing for a VBS scenario you can either create an html file or use VBS scenario editor to create the file and place it in the appropriate scenario folder.

PowerPoint

Allow Macros

Some of the GIFT courses use PowerPoint to present PowerPoint show files which contain macros (for more information on Macros refer to http://msdn.microsoft.com/en-us/library/office/ee814734(v=office.14).aspx ). In order to automatically allow those macros to execute in PowerPoint while running a GIFT course, you will need to include the GIFT domain folder as a trusted location in PowerPoint. To do this in PowerPoint 2010:
1. Open PowerPoint application
2. Select File.
3. Select Options.
4. Select Trust Center on the PowerPoint Options dialog.
5. Click on the “Trust Center Settings” button on the PowerPoint Options dialog.
6. Select Trusted Locations on the Trust Center dialog.
7. Select “Add new location” button on the Trust Center dialog.
8. Click on the Browse button and select the GIFT domain folder. Select the OK button on the file browse dialog. Now, the absolute path to the domain folder that you selected will appear in the “Path” field on the Trusted Location dialog.
9. Select the checkbox mentioning subfolders are also trusted on the Trusted Location dialog.
10. Select the OK button on the Trusted Location dialog.
11. You can close the remaining dialogs by pressing OK where appropriate and then close PowerPoint.

Configure Manually

Depending on what version of PowerPoint you have installed on your computer or how PowerPoint is installed, GIFT may or may not be able to automatically configure itself to work with you PowerPoint installation. If you have PowerPoint installed on your computer and you see an error message similar to the one below while installing GIFT or running the GIFT Gateway Application, then it’s likely that GIFT was unable to automatically configure itself to use your PowerPoint installation

A list of PowerPoint versions supported by GIFT can be found in the GIFT release notes. If your PowerPoint version is not already support by GIFT or if GIFT is not able to find your PowerPoint installation for some reason, you will need to manually configure GIFT and your computer in order to to use PowerPoint when running a GIFT course.

To do this in Windows 7:
1. Find the location of your PowerPoint installation.
Your PowerPoint installation is where your PowerPoint .exe file (e.g. “powerpnt.exe”) is located.

2. In your PowerPoint installation folder, find the .olb file corresponding to PowerPoint (e.g. “msppt.olb”)

3. Create a user environment variable on your computer with its variable name set to “POWERPOINT_HOME” and its variable value set to the location of the .olb file (e.g. “C:\Program Files\Microsoft Office 15\root\office15\ msppt.olb”). (For more information on setting environment variables, refer to http://www.computerhope.com/issues/ch000549.htm)

4. Restart your computer to apply the new environment variable (just to be safe).

5. Suggested - Check that the environment variable was set.
a. Open a Windows Command Prompt (search for Command Prompt in the start menu and open the program)
b. Type the following Echo POWERPOINT_HOME

The value printed should be the same as the variable value you set in step 3 above.

6. If you are running GIFT Local (i.e. not cloud.gifttutoring.org) then you need to make sure GIFT hasn’t disabled PowerPoint.
a. Open GIFT\config\gateway\default.interopConfig.xml in a text editor.
b. Set the “<available>” property for the “Powerpoint Adapter” interop configuration to “true” if it is not set to “true” already.
c. If GIFT is currently running, shut it down.

7. Run Gift and a course that uses PowerPoint.

Integrated Development Environments (IDE)

Please refer to the GIFT Developer Guide.

Configure Eclipse IDE

When setting up your IDE to develop GIFT, you need to configure the IDE’s project classpath so that all of GIFT’s dependencies can be used and are loaded in the correct order. Before configuring your IDE, be sure that GIFT’s third-party libraries are extracted to the ‘external’ in GIFT. Provided with the GIFT source release are the classpath and project files needed to configure the Eclipse IDE. The steps detailed below will set the reader’s workstation up for GIFT software development.

1. Install GIFT according to the installation procedures. This includes successfully building GIFT using ant or build.bat script file.
2. Download/Install Eclipse IDE, win32. (http://eclipse.org/).
3. Launch Eclipse
4. Select “File,” then “Import.”
5. Expand “General,” select “Existing Projects into Workspace”
6. Select the “Next>” button.
7. Select the “Browse” button next to “Select root directory:”.
8. Browse for directory where you placed GIFT and select the GIFT named directory and select the “OK” button.
9. Select the Finish button.
10. Build newly created GIFT project in Eclipse – select the “Project” in the Package Explorer pane, then “Project” menu option followed by “Build Project.”
11. Upon successfully build (view the Problems tab for Errors)…
12. Select “File,” then “Import.”
13. Expand “Run/Debug,” select “Launch Configurations.”
14. Browse to and select the folder: <install-directory>/GIFT/config/launchConfigurations.
15. Select checkbox next to launchConfigurations to select all launch configurations to be imported. Select the “Finish” button.

Java Compiler

Eclipse tends to default the Java compiler version to what it can find on your machine and depending on the version of Eclipse you are using, it may choose the wrong Java version. Follow the steps below to ensure your GIFT Eclipse project is configured correctly. Failure to use the appropriate Java version can result in build warnings and errors and/or Java runtime exceptions.

1. Identify the GIFT project Java compiler version by right clicking on the GIFT project in Eclipse and selecting “Properties.” Select “Java Build Path,” then the “Libraries” tab. Scroll to find the “JRE System Library.” It should match the version of Java that was installed using the GIFT provided Java exe. If you don’t remember what that version was, select “JRE System Library” and expand it. Do the paths to the various jars match where you installed the GIFT Java? If not, then click the Edit button and select the GIFT Java folder you provided during the GIFT Java install.
2. Make sure the JDK Compliance version matches your Java version. From the project properties window, select “Java Compiler.” From that window, you can set project specific settings if needed.

Note: as of writing this, GIFT uses Java 1.8 and the latest Eclipse version is called Juno. In order to select 1.8 as the JDK Compliance version, you will need the Eclipse Juno or newer version.

Your Eclipse IDE is now configured with the GIFT baseline and launch configurations for the various modules/applications. Please refer to the IDE Debugging section for more information on what to do with launch configurations for each GIFT module/application.

Debugging

There are two main options for debugging using an IDE. Both involve using the IDE to place breakpoints anywhere in the code, that when hit will pause the appropriate thread.

The first option is to run the module within the IDE. In this option, you can either have the IDE manage the build process or build using ant with the build.bat script or console. A GIFT module/application (e.g., tools or modules) can be launched within an IDE using launch configurations (Eclipse reference, may be called different things in different IDEs). After importing/creating a launch configuration you can access or run it by selecting Run, then Debug Configurations from the menu (this is just one way to find them). If you have imported the launch configurations provided with GIFT (after following the procedures in Detailed Steps to Configure IDE), then they will be listed under Java Applications. Simply select the application you wish to run (e.g., DomainModule) and select the Debug button. Once you successfully launch a module you will be able to set breakpoints in the code that can greatly improve debugging capabilities over simple console out techniques.

The other option is to remotely connect to a running module. Each module/application has a specific port assigned to it for remote debugging. It most instances the port is displayed on the console window for that application but, for reference, all ports numbers are in the GIFT/scripts/launchProcess.bat file. In order to remote connect, the GIFT application needs to be running and you will need to provide the IDE the appropriate port number to connect on.

Increase Java Heap Space

In some circumstances you may find yourself needing to allocated more memory to the Java Virtual Machine (JVM) because of an error/exception found (“java.lang.OutOfMemoryError: Java heap space”) while executing a GIFT application (e.g. ERT). Currently most GIFT applications are allocated up to 1GB of heap space by using the Java command line argument of “-Xmx1024m” in GIFT/scripts/launchProcess.bat.

To allocate more memory to the JVM here are the steps:
1) You must be using a 64bit version of Windows.
2) You must have at least 2GB of “installed memory” (RAM).

3) Download and install a 64bit version of the Java Runtime Environment (JRE). We suggest you use a similar version of Java that GIFT provides (currently v1.7).
http://www.oracle.com/technetwork/java/javase/downloads/index.html

4) Open GIFT\scripts\launchProcess.bat in a text editor
5) Find “GIFT_JAVA_HOME” and change the value to the path to the Java you just installed.
example: set GIFT_JAVA_HOME=D:\Java\jdk1.7.0_45
6) Now edit the “-Xmx” value for the appropriate “set Command=” line.

Note: you can’t allocate more memory than is available on your machine.

Example: the ERT ‘set command’ logic is under the “:LaunchWebServerCommand” batch section, therefore I would change “-Xmx1024m” to “-Xmx8192m” to use 8GB of RAM on my machine.

7) Save launchProcess.bat and then run your GIFT application again. If the application doesn’t start as normal, refer to the GIFT Troubleshooting documentation (search for Prompt Appears than Disappears).

Module Discovery

GIFT can support any number of module instances on the same ActiveMQ message bus (see Approved Module Workstation Configurations. This means that when a learner starts a course all of the modules that are going to handle that course execution need to know about each other in order to communicate as well as determine when a module is no longer working correctly.

Currently only the Sensor and Gateway modules have any logic to restrict the number of concurrent learner's using that module instance. All other modules can support an infinite number of concurrent learners (up to resource limitations of course). In the future we hope to implement logic for load balancing of modules based on their current utilization.

For module discovery to work correctly all GIFT modules must be connected to the same ActiveMQ message bus instance. This means that you can have multiple instances of every module connected to the same ActiveMQ instance. For now, modules are selected first by localhost IP address and then the first one in the list for that module type.

To ensure modules in a domain session use the same instances of each module type for interaction purposes, the following procedure is used:

Learner's starting in the GIFT Dashboard:
1. User logs in using username and password
2. User starts course
3. Tutor modules selects UMS, LMS modules to use

Learner's starting in the GIFT Simple Sign-on webpage
1. User logs in using an integer id only (here the learner is logging into the tutor module directly)
2. Tutor module selects UMS, LMS modules to use for this user's session
3. User wants to view available courses on the GIFT Simple sign-on course selection webpage

4. Tutor selects Domain module (Tutor provides UMS and LMS module information to the domain module)
5. User selects Course
6. Domain selects Pedagogical module (Domain provides UMS and LMS information)
7. Domain selects Learner module (Domain provides UMS, LMS and Pedagogical module information)
8. Domain selects Sensor module (Domain provides UMS, LMS, Pedagogical and Learner module information)
9. Domain selects Gateway module (Domain provides UMS, LMS, Pedagogical, Learner and Sensor module information)

Each module selection step is handled by sending module allocation request and reply messages. This provides the ability for a module to deny the allocation request by another module.

Approved Module Workstation Configurations

This section contains information about the latest approved configurations for using multiple workstations running various GIFT modules. The following configurations must adhere to the items listed in the Caveats section. Furthermore, the configurations listed by no means limits the various GIFT capable networked layouts, it is merely meant as a guide to help you implement specific configurations in their unique environment such as a classroom setting. For more information on what configurations are supported and tested, view the “GIFT Test Procedure Distributed Operation” spreadsheet.

Single Node, Single Learner at a Time

This will be the most used and tested configuration for a while because it is simple in many ways including needing one machine to run. In this configuration, all GIFT modules, learner applications and DB are on the same computer. This configuration forces only a single learner to use GIFT at a time (for each ActiveMQ network).

Single Instance of Every Module on ‘N’ Workstations, Single Learner at a Time

This configuration allows modules to execute on any computer on the network, thereby increasing the overall performance and resource availability of the entire GIFT system by increasing the number of computers being utilized. An example might be that the Domain module is becoming resource intensive and it would make more sense to run that module on its own machine. This configuration forces only a single learner to use GIFT at a time (for each ActiveMQ network).

Single/Multiple Instance(s) of Same Module types, Multiple Learners

This configuration supports multiple users running concurrently. Each learner will use a single workstation to view the Web-TUI and Learner application. All users will use the same LMS and UMS. Each user will need a Sensor and Gateway module, along with a web browser connected to the TUI and learner application instance – all on the same workstation.

Caveats

This section describes some of the GIFT module configuration caveats. Most of these topics relate to running GIFT in ‘power user’ mode in which each GIFT module is a separate Java process/application, each of which can be located on a different computer on the same network.

Message Bus

Modules communicate with each other using a single ActiveMQ instance. Therefore if a module isn’t connected to the appropriate ActiveMQ instance (by IP address), other modules won’t interoperate with it. This may mean that all workstations are on the same network subnet (i.e. LAN).

Gateway Module

A Gateway module instance only supports a single Learner at a time when the interopConfig.xml file is configured with one or more interop plugins/interfaces that require the user’s display.

Here is how you can tell (or setup) a single Gateway module to support multiple users at the same time:

1. Check the GIFT/config/gateway/interopConfig.xml for the interop interfaces that are “available” (i.e. the available value is “true”). Take note of the “impl” value for each of these as it indicates which Java classes to check in the next step.

2. Open each of the associated Java class file(s) (e.g. for the “impl” value of “gateway.interop.ppt.PPTInterface”, open the file “GIFT\src\mil\arl\gift\gateway\interop\ppt\PPTInterface.java”) for the available interop interfaces.

3. Find the class constructor (the method named after the Java file)

Example: in PPTInterface.java the class constructor looks like:

/**
 * Class constructor - set attribute(s)
 *
 * @param name - display name of this interface
     */
    public PPTInterface(String name){
        super(name, true);       
    }

4. The value we are looking for is the 2nd argument in the line of code with the word “super”. In the above snippet the value is true. This value indicates that the PPTInterface will require the user’s display.

If you find one or more available interfaces that require the user’s display you will need to set the available value to “false” in the interopConfig.xml file before attempting to start the Gateway module and have it support more than one concurrent learner at a time.

  • When the Gateway module is configured to support only a single learner at a time, the application must reside on the Learner’s workstation (i.e., the workstation with the GIFT user interface, or TUI, the learner is interacting with) when using training applications (e.g. Microsoft PowerPoint, VBS, TC3). This requirement is due to the fact that GIFT can control third party application’s window presentation on the computer executing the Gateway module. This includes but is not limited to launching PowerPoint shows to the user, changing window properties (e.g. foreground, background, minimize, restore, etc.) using Auto Hot Key (AHK) scripts and loading/pausing VBS and TC3 scenarios.

Note: You can disable this requirement by changing the value of the IgnoreIPAddrAllocation common module property accordingly. Please be aware of the side effects of doing so.

Domain Content

  • Content within the GIFT Domain folder is hosted as web resources by the Domain module and is available by the TUI (i.e. web browser) via a network connection. This means that the Domain module can reside on machine A and the TUI web interface can be used on machine B while still having access to domain content (e.g. training material such as pdf files, flash files, etc.).
  • Currently the Training Material content (as referenced by the TrainingMaterialDirectory domain.properties property) must be on the Domain module’s workstation. In the future “shared” drives will be supported.
  • Any files used by Gateway module interop interfaces (e.g. PowerPoint show file) must reside on the same relative path as available to the Domain and Gateway modules (as well as the training application, e.g. PowerPoint). This is because the file referenced by a course (via relative path) resides in the GIFT Domain folder on the Domain module’s machine. That file path is sent to the Gateway module during course execution, therefore the Gateway module needs to have access to that same relative location. The reader could setup a shared network drive to support having the Domain and Gateway modules on separate machines if desired.

LMS and UMS

  • Currently there is no complex logic to select a single LMS and UMS from a list of those module types found on the same ActiveMQ network. Therefore, for now, only launch a single LMS module and a single UMS module instance.

Sensor Module

  • A Sensor module only supports a single Learner at a time, unless the sensor module is configured with no sensors (i.e. there is no sensor configuration file property value in GIFT\config\sensor\sensor.properties, which is the default setting for GIFT).
  • In most instances a Sensor module should be on the Learner’s workstation. This will guarantee that data collected by any sensor hardware attached to the Learner’s workstation will be used for that Learner and not assigned to another Learner on the same ActiveMQ network. In addition, any software sensor GUIs, such as the “Self-Assessment Sensor will appear on the Learner’s workstation. Currently there is no complex logic to select or link a sensor module to a particular learner, except for having the sensor module run on the Learner’s workstation.

Deployment Services layer

In order to support the various deployment types of GIFT (server, desktop, experiment, offline, online) a deployment services layer was created to abstract various actions away from applications that need them. These actions include file, user and database operations. Before this layer existed the GIFT Authoring Tool (GAT) would directly manipulate the file system (e.g. save a course.xml file in the GIFT folder structure). Those type of operations are acceptable as long as the GIFT folder is accessible to the GAT which is not accessible when running GIFT in server mode and connected to GIFT via a web browser on another machine. Therefore this abstract layer hides the implementation details from the applications allowing the applications to reference a single interface.

Developer’s Note: the services package is located in GIFT/src/mil/arl/gift/tools/services/

As you can see in the figure below there are currently two applications that use the services layer: Dashboard and GAT. Depending on the deployment mode (desktop versus server), operations are performed on different underlying systems (e.g. Windows file system versus Nuxeo Content Management System).

With this abstraction layer in place GIFT is moving closer to seamlessly supporting transitioning the user from online to offline, local desktop instance to server/cloud hosted instance all while maintaining a similar appearance to the user. In addition this architecture will make it easier to change the CMS to something other than Nuxeo as long as the appropriate interface specification is implemented for that new system.