Adaptive Learning Service API 2023-1¶

About¶

The Adaptive Learning Service API is a reconfigured GIFT instance that exposes tutoring capabilities to an external system. The external system has the ability to manage sessions, receive learning affect chain events such as learner states and approve scenario adaptation requests.

The separation of different Topics has not yet been implemented

How to use this API¶

In order to use the API your application will need to communicate with the same external message bus that the GIFT Gateway module is connecting too and send Protobuf defined messages on that message bus. Essentially there are five main parts of using the API:

your application
Protobuf defined messages
message bus (currently ActiveMQ)
GIFT
training application (e.g. VR Forces/Engage, VBS, Unity)

Read through each section to understand how to setup your configuration and run your first real time assessment using the Adaptive Learning Service API.

Quick Start Guide¶

The quick start guide is meant for those that just want to get running quickly. If you want to know more about the API then please read the other sections in this document.

Currently the delivery of this API is packaged with several things:

GIFT configured, compiled, ready to install and run.
- In the folder ITS
- Also contains an example GIFT Course called Clear Building.
A simple Test Harness desktop application that can be used to test the API in lieu of your own external system that would make use of the API on its own.
- In the folder RTA Test Harness
- You can obtain this folder on the Downloads tab ("COMING SOON":)
The Clear Building VBS scenario, models and terrain files that accompany the GIFT Clear Building course assessments.
- In the folder Clear Building Test Case- VBS files
- VBS requires a Distribution Agreement (DA). These files can be shared but you will need to request them directly.
A slightly modified ActiveMQ Message broker instance
- In the folder AdaptiveLearningServiceBus
- You can obtain this folder on the Downloads tab (current link)

Steps to start core components¶

To have your external system use the API all you need is GIFT and the message broker running.

Start Adaptive Learning Service Bus
- Double left click on AdaptiveLearningServiceBus\launchServiceBus.bat
- A command prompt window should appear and the message broker should be running. (screenshot)
Install GIFT (if not already installed)
- To install GIFT double left click on ITS\installGIFT.bat and run the GIFT installer.
Start GIFT
- After a successful install of GIFT, double left click on ITS\launchGIFT.bat
- The GIFT Dashboard login webpage should appear in a web browser. (screenshot)
Login to GIFT
- Now that GIFT is running, if you don't want to author or manage real time assessments you can close your browser. You can always get back to the Dashboard login page through the GIFT system tray icon (when GIFT is running).
- Until a more sophisticated user identity management system is selected and integrated, user credentials are managed in ITS\GIFT\config\tools\dashboard\LocalAccounts.txt. Current default is username/password.

If you want to use the Test Harness Application to test the API, continue to the next section.

Steps to run Test Harness Application¶

The Test Harness Application is a simple program that can be used to test the API over the message broker.

Start the test harness application
- First follow Steps to start core components
- Double left click on RTA Test Harness\launch.bat
- A window should appear and the status indicator light(s) in the top right should be green.

If you want to run a test of the API, continue to the next section.

Steps to run the VBS Clear Building assessment¶

The Clear Building assessment involves a Virtual Battlespace (VBS) scenario and a GIFT course that assesses actions taken in that VBS scenario in real time. You will need to have VBS to continue (see VBS configuration for GIFT). Currently GIFT is integrated with VBS 3.9.2.

Place VBS files into VBS install
- Follow the instructions in Clear Building Test Case- VBS files\VBS Resources\README.txt to place the VBS scenario, models and terrain files into their appropriate locations.
Start VBS
Follow Steps to start core components
Follow Steps to run Test Harness Application
Select the TSB 07-GFT-0137 ClearBldg (jtc_shakarat) real time assessment on the "RTA" tab of the Test Harness Application. Click start session button to begin the session.
In VBS, host a networked Clear Building scenario.
1. Left click Networking
2. Double left click 'Host session'
3. Select 'Shakarat'. as the terrain
4. Select 'TSP07-GFT-0137 ClearBldg.jtc_shakarat'. as the scenario name, then 'START'.
5. Select '1-1-A-2 RTO_1_B' as the character you will be playing, then 'OK'.
6. Select 'OK' button when map is shown.

To test a full loop of the API:

Now that the VBS scenario and GIFT course (RTA) is running you should see more than one learner state in the new session tab that appeared when you started the session in the test harness application. If not, something is not configured appropriately. Most like your VBS and GIFT DIS settings don't match (e.g. network port, DIS exercise Id). Don't continue until this is resolved.
Move your character in VBS a little and then fire your weapon once.
In the session tab of the test harness you should see an authorize strategy request event. Click on each and then click the 'Approve Strategies Request' button that appears.
If you quickly go to the VBS window again you should see text appear that relates to weapon control ("Target missed! Remember..."). This is feedback triggered by GIFT and approved by you through the test harness application over the message bus.

Real time assessment authoring¶

To manage the available Real Time Assessments contained within this GIFT instance you will need to use the GIFT Dashboard and Course Creator.

Quick Start¶

1. Start GIFT using ITS\launchGIFT.bat
2. Login
3. Create new using the 'Create' button or edit existing by clicking the pencil (edit) button on one of the GIFT real time assessment tiles.
4. Choose training application type by either clicking to add from the right panel or drag a training application type from the left panel onto the course tree.

Real-Time Assessment Authoring for VBS¶

In this example, we will be going through the Virtual Battle Space (VBS) training application.

1. Follow Quick Start steps above.
2. Choose Virtual Battle Space (VBS).
3. Click the button "No Real-time Assessment Selected".
4. Window pops up asking to "Create New" or "Select Existing". In this case, we will click on "Create New".

Adding a Concept¶

In this walk-through, we will go over how to add a concept that the task should cover.

1. When hovering over "Application Completed Task", a '+' icon and a 'trash can' icon should appear.
2. Click the '+' icon.
3. A new concept should now be added, initially giving you the option to re-name it from "New Concept 1" that is already provided.

Adding a Strategy¶

In this walk-through, we will go over how to add a strategy.

1. From the panel on the left, there will be a 'lightning bolt' icon implying the strategies tab.
2. Click the green '+' icon on the right side of the icons from the left panel. When hovering over, it should say "Add New Strategy".
3. A new concept should now be added, initially giving you the option to re-name it from "New Strategy 1" that is already provided.

Adding a State Transition¶

In this walk-through, we will go over how to add a state transition.

1. Under "State Transition", click the button "Create State Transition".
2. A new state transition should now be added, initially giving you the option to re-name it from "New State Transition 1" that is already provided.
3. Under "Tutor Behavior", click on the criteria to edit the concept's performance level changes.
4. After "changes from", select the first box and choose "Below Expectation" and click "Set".
5. Click the button stating "Click here to add a new strategy reference".
6. Select the strategy we made previously.
7. Click "Set".

Adding a Condition¶

In this walk-through, we will go over how to add a condition.

1. When hovering over the concept that was just made, a '+' icon and a 'trash can' icon should appear.
2. Click the '+' icon.
3. Click "Add condition".
4. A condition type must be selected. In this case, we will select "Application Completed".

Creating a task¶

In this walk-through, we will go over how to create a task.

1. Under "Tutor Behavior", click the button "Create task".
2. A new task should now be added to the panel on the left, initially giving you the option to re-name it from "New Task 1" that is already provided.
3. A task must have a stopping event. Scroll down and click on the button that says "Click here to add a new stop event".
4. Click the "Set" button.

Afterwards, click the "Save and Close" button.¶

GIFT modifications¶

In a standard GIFT configuration prior to this API existing, the learner controlled course/session execution by interacting with the GIFT Tutor User Interface (TUI) which was served by the Tutor Module. For this configuration an external system is in control of the session. This means that the Tutor module is not even started. To facilitate this a new Gateway module interop plugin was created called the Adaptive Learning Service Interface (mil.arl.gift.gateway.interop.adaptivelearningbus.AdaptiveLearningServiceInterface.java). This interop plugin connects to an external messages bus to open bi-directional communication. The external system can then manage sessions and receive events such as learner state updates from GIFT.

The course creator is still needed to author real time assessments in GIFT but other features are currently not desired (e.g. publish courses, numerous other course objects like surveys, lesson material). Therefore a stream-lined Dashboard user experience was developed to allow easier management of real time assessments.

Since there is no Tutor module to host the TUI, the GIFT team session lobby will not be shown. It is up to the external system to provide the team member assignments for the learners involved in the session.

How to enable Real Time Assessment mode¶

This new configuration was built into the existing GIFT architecture and user interfaces so that future changes could be easily integrated.

To switch between the standard configuration and the real time assessment configuration:
1. Open GIFT\config\common.properties for editing
2. Find and change the LessonLevel property to 'Course' for the standard configuration and 'RTA' for this Adaptive Learning Service API configuration.
3. Save common.properties
4. Restart GIFT.

Protobuf messages¶

The proto files located in GIFT at GIFT\config\gateway\externalApplications\AdaptiveLearningServiceBus\ define the structure of the messages that the GIFT Gateway module can send and receive via the mil.arl.gift.gateway.interop.adaptivelearningbus.AdaptiveLearningServiceInterface.java connection to the external message bus. These proto files are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages. Protocol buffers currently support generated code in Java, Python, Objective-C, and C++. With our new proto3 language version, you can also work with Dart, Go, Ruby, and C#, with more languages to come.

If your programming in Java, copy the protobuf_generated.jar from GIFT\bin\ of a built GIFT instance to your application. For other, Protobuf supported programming languages, use the Protobuf compiler on the GIFT provided proto files at GIFT\config\gateway\externalApplications\AdaptiveLearningServiceBus\ to generated the appropriate code for your application.

Real Time Assessment (RTA) Test Harness Application¶

This open-source, Real-time assessment test harness application is meant to be a simple application that can be used to test the API and provide an example of how to use the API. The user interface code has been purposefully separated from the message bus communication logic for an easier understanding of the recommended logic that your external system should implement. Feel free to copy this code for use in your Java application or recreate it in your systems native programming language.

How to use the application¶

The application is structured so that it is easy to start and use. After starting the message bus and GIFT in RTA lesson level mode, simply double-left click on RTA Test Harness/launch.bat to begin.

If the 'Status' indicator in the top right is green than the connection to the message bus has been established.

There are two tabs that are shown when you first launch the application, Sessions and RTAs. The Sessions tab shows all of the currently running sessions. To attach to a session, click on that session and then click the 'Attach' button which will show a new tab with the events occurring in that session. The RTAs tab lists the available authored courses that exist in the connected GIFT instance. To start a new session, click on a Real Time Assessment and then click 'Start New Session' button which will show a new tab with the events occurring in that session.

Message sequences¶

Request Available courses¶

The external system (to GIFT) can request a list of available courses that reside in GIFT and can be loaded into a new session.

Sender	Message Sent	Received by	Replies with
External System	DomainOptionsRequestProto	GIFT	ACK (hasProcessed=false) then DomainOptionsReplyProto

Request Active Domain sessions¶

The external system (to GIFT) can request a list of the currently running sessions in GIFT. This is useful for attaching a monitor for a session and closing existing sessions for cleanup.

Sender	Message Sent	Received by	Replies with
External System	ActiveDomainSessionsRequestProto	GIFT	ACK (hasProcessed=false) then ActiveDomainSessionsReplyProto

Start a new session¶

The external system (to GIFT) can request that a session be started with an available course in GIFT.

Sender	Message Sent	Received by	Replies with
External System	DomainSelectionRequestProto	GIFT	ACK (hasProcessed=false) then DomainSelectionReplyProto

If the started session has multiple playable team roles, GIFT will request team role assignments from the external system.

Sender	Message Sent	Received by	Replies with
GIFT	TeamMemberRoleAssignmentRequestProto	External System	TeamMemberRoleAssignmentReplyProto

Close Session¶

The external system (to GIFT) can request that a currently running session in GIFT be closed.

Sender	Message Sent	Received by	Replies with
External System	CloseDomainSessionRequestProto	GIFT	ACKProto or NACKProto

Evaluator Update Request¶

The external system (to GIFT) can send an evaluator update request during a session. This request can have observed information such as assessment and bookmark.

Sender	Message Sent	Received by	Replies with
External System	EvaluatorUpdateRequestProto	GIFT	ACKProto or NACKProto

Real Time Assessment events¶

During a real time assessment GIFT can send any of the following messages to the external system.

Type	Message Sent	Description
Lesson Started	LessonStartedProto	notification that a real time assessment has started. Happens once per real time assessment (DKF) instance.
Learner State	LearnerStateProto	contains the learner state information such as performance assessment across the entire team organization.
Authorize Strategies Request	AuthorizeStrategiesRequestProto	GIFT is recommending one or more scenario adaptations be applied and needs authorization before doing so. See section on how to reply to this message.
Filtered Sensor data	FilteredSensorDataProto	future implementation - contains a data stream from a sensor such as a physiological sensor like a Zephyr Bioharness with breathing waveform and heart-rate
Pedagogical Request	PedagogicalRequestProto	contains one or more instructional strategy requests. This is also sent to the GIFT Domain module to determine which scenario adaptations (Tactics) should be applied based on current domain knowledge of the situation. If there are any scenario adaptations to apply a resulting AuthorizeStrategiesRequestProto will be sent by the Domain module to the External System via the Gateway module for approval.
Lesson Completed	LessonCompletedProto	notification that a real time assessment has finished. Will happen once per real time assessment (DKF) instance and only after a lesson started event.

Authorize Strategies Request¶

During a real time assessment GIFT may want to apply certain scenario adaptations. The External System is responsible for approving which adaptations GIFT can apply (and when).

Sender	Message Sent	Received by	Replies with
GIFT	AuthorizeStrategiesRequestProto	External System	ApplyStrategiesProto

Project

General

Profile

GIFT

Wiki