Install Instructions - Windows 7¶
- Install Instructions - Windows 7
- Detailed Instructions
- Amazon Web Services (AWS) install
- GIFT Directory Structure
- Optional Instructions
1. Acquire GIFT¶
A GIFT release includes:
- GIFT Source - contains top level folders such as Domain, GIFT and Training.Apps
- GIFT Third Parties – includes Windows 32bit libraries (needed to build and run GIFT) and applications (some of which are integrated with GIFT).
- Note: 32bit libraries will work on 64bit machines. Furthermore you can configure Java compilation to use 32bit Java for both Windows and the Eclipse IDE.
- Public courses – domain related content such as training application scenarios (e.g., VBS scenario files, PowerPoint files), and GIFT course files.
2. Run the GIFT Installer¶
The GIFT installer named “installGIFT.bat” is located at the root of the GIFT release (i.e. next to the GIFT, Domain and Training.Apps folder). It has the ability to:
- Check for a built/compiled GIFT software
- Check for and extract the Derby Database data
- Copy the Launch GIFT script to the root of the GIFT release.
Now that you know what the GIFT installer does, go ahead and execute it by double clicking on the “installGIFT.bat” file at the root of the GIFT release. Follow the prompts presented to you to install GIFT.
3. Training Application(s)¶
As of now GIFT has been tested using the following training application(s). Of course because GIFT has been designed to be a generic framework it can support other training applications. For more information about configuring to use different Training applications refer to GIFT Configuration Settings document.
Virtual Battle Space (VBS)¶
GIFT has been integrated with Bohemian Interactive Simulations Virtual Battle Space (VBS) simulation training system. There are a set of exemplar GIFT courses with corresponding VBS scenarios that demonstrate the GIFT capability of providing tutoring by attaching to a pre-existing simulation. If don’t plan on using VBS with GIFT, then you can skip this subsection.
As of 10/13/17 GIFT currently supports VBS3 v3.9.2.
Visit the GIFT forums to ask how to obtain VBS.
Configuring VBS for GIFT
1. Verify VBS is installed on your machine by starting VBS and seeing the main menu. It shouldn't matter which configuration you start VBS in to perform this test.
Note: When starting VBS for use with GIFT, there is a special shortcut that will be created later on.
2. Let GIFT know where your VBS install is located by running the GIFT installer. On the training applications part of the GIFT installer make sure to set the path to your VBS installation.
Note: if the GIFT installer is not allowing you to change the VBS location you will need to manually delete the GIFT created mappings by removing the Windows User Environment variable VBS_HOME and the VBS_HOME line in GIFT\temp\GIFTEnvironmentVariables.properties.
3. Install New VBS Terrain
In some instances (e.g. the GIFT VBS Clear Building course), the VBS scenarios used in a GIFT course require a new terrain not provided in the VBS out-of-the-box installation. Therefore you have to place the terrain file(s) in the appropriate VBS directory in order for VBS to find the files during execution.
VBS Terrain files go in <vbs install path>\VBS\mycontent\addons\ (e.g. “jtc_shakarat.pbo”)
If you have any additional VBS terrains used by VBS scenarios referenced by a GIFT course, now is a good time to copy those terrain files into the appropriate VBS directory.
Note: The GIFT “Presence Patrol (Sara)” named course (folder name “VBS.PresencePatrol.Scenario”) uses a terrain provided by VBS, therefore you don’t need to copy any terrain file for the corresponding VBS scenario.
4. Install New VBS Models
In some instances (e.g. the GIFT VBS Clear Building course), the VBS scenarios used in a GIFT course require a new 3D models (e.g. buildings, vehicles, people, animals) not provided in the VBS out-of-the-box installation. Therefore you have to place the model file(s) in the appropriate VBS directory in order for VBS to find the files during execution.
VBS model (e.g. actors, vehicles, buildings, scripts, etc.) file go in <vbs install path>\VBS\mycontent\addons\
If you have any additional VBS models used by VBS scenarios referenced by a GIFT course, now is a good time to copy those model files into the appropriate VBS directory.
Note: The GIFT “Presence Patrol (Sara)” named course (folder name “VBS.PresencePatrol.Scenario”) requires no additional model files, therefore you don’t need to copy any model files for the corresponding VBS scenario.
5. Adding the GIFT scenarios to VBS
A GIFT course folder (located in the Domain folder of GIFT) that utilizes VBS as a training application might have had a VBS scenario created for it to use. In this case the VBS scenario files are located in a folder alongside the GIFT course, dkf, etc. files. This folder needs to be copied to the location where VBS can find it.
The VBS scenarios GIFT has been integrated with can be found in “Domain\<course name>\<vbs scenario folder>\.” The way you can tell if you found a VBS scenario folder is if there are files such as mission.biedi, mission.sqfand mission.sqm.sqf.
Copy and paste each VBS scenario folder you would like to use to “<VBS install path>\VBS\mpmissions\”.
6 Starting VBS
In order to GIFT to control and interact with VBS you must start VBS using the GIFT created shortcut file named 'GIFTVBSGame.bat'. If you used the GIFT installer to configure GIFT to be used with VBS, than GIFT should have copied that file to your VBS installation folder (e.g. C:\Bohemia Interactive\VBS3). Do not move this file out of the VBS installation folder. You can create a shortcut to this file and place that shortcut on your desktop for ease of use.
Manual Installation Option: [OUT OF DATE since 6/7/18]
If security restrictions or other items have complicated the automatic installation of VBS, or VBS extensions, using the installGIFT.bat script, it can be manually installed using the following steps:
1. If VBS is still running, please close it using the appropriate Cancel and Exit buttons offered on the VBS menu system.
2. Double click “installVBSExtensions.bat” in the “GIFT\scripts\install” directory. If the script asks you confirm if a directory should be created or if a file should be overwritten, accept. If no errors are produced, VBS is successfully configured to run GIFT.
3. Open the directory where VBS was installed. You should observe there is a file called “GIFTVBSGame.bat.” This is the file that should be executed to start VBS when being used with GIFT. It is advised that you create a shortcut to that file on your Desktop.
Do not use any other VBS shortcuts to launch VBS when using GIFT.
7 Configure VBS Gateway
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 the DIS switch to turn it ON, then change the 'receive port' from 3000 to 3005
iii. change the exercise ID to match what is in your GIFT/config/gateway/default.interopConfig.xml file in GIFT
iv. 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. If you don't see it in the folder, make sure you have the file filter enabled for .csv files.
- Disable Fatigue setting in VBS*
You may notice that after running around in VBS your character starts to breath heavy. This is often times annoying, especially when giving a demo. To disable fatigue in your VBS instance:
1 From the VBS main menu, select OPTIONS
2 On the OPTIONS page select SIMULATION SETTINGS
3 Click in the large black area with the options are located and start typing 'fat' (for fatigue) and you should see the list of options filtered to show only 1 option, 'Realistic Fatigue'.
4 Change the USER, ADMIN and ENFORCE column settings to match those in the picture below. To change a value simply click on the text such as 'Enabled'. Select OK on the right hand side to save the changes. Everytime your VBS is started these changes will be used.
Microsoft PowerPoint¶PowerPoint is used by several GIFT Domains to present and monitor PowerPoint shows and is one of the easier training applications to create lessons for. Refer to the appropriate section below based on your desired configuration:
- To use PowerPoint:
- Install PowerPoint (at least PowerPoint 2003) on the machine executing GIFT (more specifically the Gateway module).
- Select the GIFT domain folder as a trusted location in PowerPoint as described in the GIFT Configuration Settings.
- The “GIFT/config/gateway/interopConfig.xml” file describes the interface connection named “Powerpoint Adapter” between GIFT and PowerPoint. It uses the type library value to find a specific file in your PowerPoint installation. In some instances the default type library file name maybe incorrect and will be corrected by the Gateway module when it is started for the first time (for more information about interopConfig.xml and configuring PowerPoint, refer to GIFT Configuration Settings).
To NOT use PowerPoint
If you do not wish to use PowerPoint all together or you don’t have the Microsoft PowerPoint application, then refer to the appropriate section below to make the PowerPoint interface unavailable for use in this installation of GIFT:
To automatically mark the interface as unavailable because you don’t have PowerPoint, simply continue with the GIFT installation and the first time the Gateway module is started a prompt will appear asking if you would like to make the change.
To manually mark the interface as unavailable:
1. Open “GIFT/config/gateway/interopConfig.xml”
2. Find the interface named “PowerPoint Adapter”.
3. Change the value of “available” from “true” to “false”.
4. Save and then close the XML file.
TC3 (aka vMedic)¶
If you would like to use the GIFT Domains that execute TC3 scenarios, then you will need to obtain the GIFT compatible version of TC3. The GIFT version of TC3 can be downloaded here: https://gifttutoring.org/projects/gift/files.
One of the modules in the GIFT architecture is the Sensor module that communicates with sensors that are software and/or hardware driven. For sensors that are hardware based, you will need to acquire that hardware and any appropriate licenses before being able to use that sensor with GIFT. In addition, you will need to set the sensor configuration file property appropriately to configure the sensor module. Read the GIFT Configuration Settings document for sensor configuration information. Basically you need to specify the sensors you want to use in a sensor configuration file and reference that file in the sensor module properties file. (If you will be following the Test Procedures soon, this step can be skipped as it will be done then.)If you don’t have sensor hardware to use with GIFT continue to the next section or the next sensor in this list...
The self-assessment sensor is a very simple sensor that has no additional hardware requirements. You can configure the sensor module to use this sensor by setting the sensor configuration file property for the sensor module.
- Read the GIFT Configuration Settings document for sensor configuration information. Basically you need to specify the sensors you want to use in a sensor configuration file and reference that file in the sensor module properties file.
- Temperature/Humidity Mouse
The mouse reference here is a custom sensor device created for the Army Research Laboratory. It contains a temperature/humidity sensor embedded within the case of an oversized mouse. If you don’t have this piece of hardware as part of your GIFT system, then skip the following section.
- Connect both USB cords of the mouse to the computer. Let Windows automatically install the drivers for the mouse functionality of the device.
- Install the Arduino drivers for the Temperature/Humidity Sensors
- Open up the system’s Device Manager by opening the “Start Menu” and right clicking “Computer” and selecting “Properties.”
- In the new window that appears, select “Device Manager” in the top-left corner of the window.
- In the new window that appears, look for “Other devices” in the tree and then “Arduino Uno” within, right click “Arduino Uno” and select “Update Driver Software.”
- In the window that appears, select “Browse my computer for driver software” and then select “Browse” and in the new window, browse to the GIFT checkout directory and then into “GIFT,” then “External.” Press “OK” and then “Next.”
- A popup may open and warn you about installing this driver, install anyway.
- Q Sensor
The Affectiva Q Sensor is a piece of hardware that measures, among other things, Electrodermal Activity. If you don’t have this piece of hardware as part of your GIFT system, then skip the following section.
- Follow the instructions that came with your Q Sensor to install any necessary drivers. Also use the Q Live software to confirm that your system is receiving data from the sensor. Make sure to close Q Live before using the Q Sensor with GIFT as the port may become blocked and unreadable via GIFT Sensor Module logic.
- Read the GIFT Configuration Settings document for sensor configuration information. Basically you need to specify the sensors you want to use in a sensor configuration file and reference that file the sensor module properties file.
- Finally, when you are at the point of launching the Sensor Module pay special attention to any prompts on the command terminal asking you to synch the sensor.
In order to use the Emotiv (www.emotiv.com) EPOC neuroheadset and software, you must purchase the appropriate license. RDECOM purchased the neuroheadsets and Research edition licenses in order to read “Affectiv” and EEG level data. Due to licensing restrictions, we are unable to release the edk.dll and edk_utils.dll, but note that they come with the purchase of the physical device.
Assuming you have the edk dlls, follow the steps below to use Emotiv:
1. Create “emotiv” directory in GIFT/external/.
2. Place “edk.dll” and “edk_utils.dll” into “GIFT/external/emotiv/”
3. Build GIFT (Note: if the sensor module doesn’t build, try a clean build instead)
The build system is already configured to add the DLLs to the library path.
4. Make sure your Sensor Configuration is correct before launching the Sensor module.i. You can either author a new sensor configuration file using the Sensor Configuration Authoring Tool (SCAT) or use the existing GIFT/config/sensor/SensorConfiguration.Emotiv.xml file. Either way in order to use the Emotiv headset you will need to make sure the sensor configuration uses the “EmotivSensor” sensor implantation.
- Note: the default SensorConfiguration.Emotiv.xml is setup to use the Emo Composer application to produce Emotiv data and not the headset. You will need to uncomment one section and comment the other like shown in Figure 1 and 2 below.
ii. Change the “SensorConfigurationFile” property in GIFT/config/sensor/sensor.properties to the sensor configuration file you want to use. Don’t forget to save the file.
5. There are several ways to test if the setup worked:
Figure 1. Screenshot showing a portion of the SensorConfiguration.Emotiv.xml that comes with GIFT.
Figure 2. Screenshot showing a portion of the SensorConfiguration.Emotiv.xml, altered so that the Emotiv headset is used because the sensor implementation is "Emotiv Sensor"
Notice how the Emotiv "Emo Composer" is the default sensor implementation.
- Launch Sensor Module using an Emotiv configured sensor configuration file. If there are no errors and the module starts successfully then that’s a good start. Note: you may have to start ActiveMQ before the sensor module.
- Start all GIFT modules and enter into a domain session, then verify, using the monitor or looking at the sensor module output, that sensor data is being captured.
- The Sensor Configuration Authoring Tool (SCAT) can be used to check for library loading issues by loading an emotiv sensor configuration file and GIFT validating its content.
In order to use Multisense, you must first obtain it as part of the Virtual Human Toolkit. The instructions to get Virtual Human Toolkit can be found here: https://vhtoolkit.ict.usc.edu/download/
When installing Virtual Human Toolkit, follow these instructions to ensure that it will work with GIFT:
- Run the Virtual Human Toolkit installer
- Click "Next" on the first screen
- Click "I Agree" on the following screen
- Click "Next" on the following screen (Default destination folder should be C:\vhtoolkit)
- Click “Install”
- Virtual Human Toolkit will be installed with all of its Third Parties
- Uncheck the "Run Virtual Human Toolkit Launcher" checkbox and click "Finish”
Bioharness 3 is a multi-function sensor produced by Zephyr Technologies (http://www.zephyr-technology.com/). GIFT has been integrated with the Bioharness 3 http://www.zephyranywhere.com/products/bioharness-3/.
This chest-worn sensor communicates with your workstation wirelessly via Bluetooth and is capable of sensing heart rate, breathing wave form, ECG waveform and posture.
To install the sensor follow the instructions provided with your Bioharness 3 unit. Before attempting to run the Bioharness with GIFT, verify the software and drivers have been properly installed. This can be done by running the “BioharnessBlueTooth Test Application V2” provided on the software CD that accompanies the unit. If the software runs successfully, then it everything needed by GIFT should also be installed.
Before running a GIFT session with the Bioharness make sure to do the following:
- Charge the Bioharness unit using the provided USB charger
- Ensure that the Bioharness processor in locked into position on the chest strap.
- Attach the Bioharness strap snugly around the user’s chest.
- Ensure that the workstation where GIFT is installed has Bluetooth capability. (in most cases this will mean to ensure that the Bluetooth USB dongle is in plugged in)
- Power on the Bioharness
- Other Sensors
Depending on the GIFT release, there may be other sensors supported. Refer to the test procedures available in GIFT/docs/testing for more information on configuring and testing other sensors.
5. GIFT Source¶
The GIFT release has already been compiled for you. If you want to edit the GIFT source then proceed, otherwise continue to the next section.
WARNING: If the path to the GIFT installation folder is too long when building GIFT, an error message will be shown indicating how many characters need to be removed from the path before proceeding.
To build GIFT, Go into the ”GIFT” directory and double click ”build.bat,” when the command prompt disappears, GIFT has finished building.
6. Verify that GIFT is running¶
Verify that GIFT is properly installed by following the instructions for starting the Tutor in the GIFT Run Instructions document.
7. Avatar – “Embedded pedagogical agent” (EPA)¶
It is highly recommended that you install the Media Semantics Character server in order to present an embedded pedagogical agent (EPA) in the Web based Tutor User Interface (Web TUI) (example shown below) that can, among other things, convert feedback text into speech. To install please follow the instructions in GIFT Media Semantics Character Server Instructions. It is recommended that you have GIFT working before you proceed.
1. Create an AWS and install the latest Learning Locker AMI.
2. Putty into the new box, you will need access to the private key file.
3. The AMI may not have built the latest learning locker and xAPI repository, so let’s get the latest and build.
a. Become a root user “sudo su –“
b. Navigate to /usr/local/learninglocker
c. Install with cURL:
“curl -o- -L http://lrnloc.kr/installv2 > deployll.sh && bash deployll.sh”
d. Navigate through the prompts, selecting all the defaults, until the process is complete.
4. Navigate to /home/ubuntu/ll_credentials.txt
5. Open the AWS Learning Locker instance by inserting the IP or the URL into the address bar.
6. Enter the email and password found in the ll_credentials.txt file.
7. Right now everything is set to default values, so let's make a few changes. First click "View all users".
8. Expand the default user (e.g. ht2testadmin@ht2labs. com).
a. Leave name blank.
b. Change the email to a more fitting GIFT admin login email (e.g. admin@email. org).
c. Check "change password", type your new password twice and click "Set Password".
9. Click Organisations in the left navigation bar and rename the organization to something more appropriate.
a. Optionally, you can specify more specific password requirements.
10. Go back to the Learning Locker home page by clicking on the “switch organisation” icon in the top right corner.
11. Select your newly renamed organization.
12. In the left navigation bar, go to Settings > Stores > Add New.
a. Enter a title
b. (Optional) Enter a description.
13. In the left navigation bar, go to Settings > Clients > Add New.
a. Add a title.
b. Keep “Enabled?” selected.
c. Select your created Store under “LRS (optional)”
d. Select “All” under “Scopes”
e. Add an authority name (e.g. Admin).
f. Add an authority email (must start with ‘mailto:’ e.g. mailto:admin@email. org).
14. Enable SSL security on your VM.
14. Enable SSL security on your VM.
15. Configure your GIFT LRS connection settings: [[https://gifttutoring.org/projects/gift/wiki/Configuration_Settings_2020-1#LRS-Implementation-Parameters]]
a. Copy the xAPI endpoint as the network address (add an ending slash)
i. This can be found in the LRS at the top of the Settings > Clients page.
b. Copy the Key as the username
i. This can be found in the LRS on the Settings > Clients page.
c. Copy the Secret and the password.
i. This can be found in the LRS on the Settings > Clients page.
If you have one or more webcams that you would like to view using the GIFT monitor application, follow these steps:
1. Install Yawcam (‘GIFT/external/yawcam_install.exe’) on the machine with the webcam.
2. Open the Yawcam application on the machine with the webcam.
3. Confirm that your camera is configured with Yawcam.
a. Select “Window,” then “Preview” to view the current image.
b. If there is an error or an image doesn’t appear, try detecting your webcam by selecting “Settings,” then “Detect Webcam…”, followed by selecting your webcam from the list of devices.
4. Select the “Enable” button next to Stream on the Control Panel tab.
a. In addition, select “Settings,” then “Edit Settings…” on the main dialog, then “Startup” and check ”Start Stream output” and “Hide to traybar at start” on the “Yawcam – Settings” dialog that appears.
b. The GIFT monitor will use the default port of 8081 which can be found by selecting “Stream” under “Output” on the “Yawcam – Settings” dialog that appears.
5. Confirm the webcam is streaming by opening a web-browser on the machine with the webcam and visiting the url “http://localhost:8081/”.
6. The Monitor camera configuration file can be found under ‘GIFT\config\tools\monitor\cameras.txt.’ For more information refer to the GIFT Configuration Settings document.
7. Optionally, you can configure the Yawcam application to:
a. Start as a windows service – run (as administrator) the “Yacam-NTservice-Install.bat” and then “Yawcam-NTservice-START.bat” files, found in the Yawcam install folder. Now when Windows is started the Yawcamapplication will automatically be started as well.
Adobe Acrobat Reader¶
If you intend to use course materials (e.g. PDF files) that require Adobe Acrobat Reader, download and install the latest version of the software. Adobe Acrobat Reader is available here: http://get.adobe.com/reader/otherversions/. Other browser-embedded PDF readers are acceptable, but are not documented within this document.
If you intend to use either the QrsFromEcgFilter (Sensor module) or XmlRpcService (Learner Module) you will need to install python. Currently the only supported python distribution is Python 184.108.40.206. This is a heavy-weight distribution that installs all required libraries in a single installation process. Other python distributions may work and GIFT may move to a lighter weight distribution in future releases.
The software can be downloaded and installed from the GIFT Install Tool. Registered users can also download the WinPython installation program from the GIFT Portal at https://gifttutoring.org/projects/gift/files
To install the software through the GIFT Install Tool:
1. Run the GIFT installer and navigate to the ‘Miscellaneous’ page
2. Click the button to “download and install WinPython”
3. Log into the GIFT Portal and allow the WinPython installation program to download
4. When the download completes, click “Run”
5. The WinPython setup program will prompt you for an “Install Location”. Choose a destination folder for WinPython and click “Install”. You will need to specify this WinPython folder in the GIFT Install Tool when the installation is complete
6. When the WinPython installation is complete, return to the GIFT Install Tool. Click “Browse” and navigate to the WinPython folder created during the installation
7. Click “Next,” then “Finish” to complete the setup
Alternatively, if WinPython has already been installed:
1. Run the GIFT installer and navigate to the ‘Miscellaneous’ page
2. Click the button indicating WinPython has already been installed
3. Click "Browse" and navigate to your WinPython directory
4. Click “Next,” then “Finish” to complete the setup
Amazon Web Services (AWS) install¶
GIFT can be installed and executed on an Amazone Web Services (AWS) by following these instructions.
A GIFT AWS monitoring VM is also available. GIFT monitoring includes Graphite and Grafana among other tools in its suite.
GIFT Directory Structure¶
Domain/ - contains information specific to domains, i.e. VBS Scenarios
GIFT/ - contains the GIFT modules
api-docs/ - created by the build process, contains the Javadocs
bin/ - created by the build process, contains the jar files for each GIFT module
build/ - created by the build process, contains the class files
config/ - contains properties files for each of the GIFT modules and their loggers
data/ - contains the pedagogical models and empty databases for UMS and LMS
docs/ - contains helpful GIFT-related documents such as this one
external/ - contains the external (third-party) dependencies (installers, tools, jar files) needed to run the system
generated/ - created by the build process, this directory gets created during the build and contains jaxb generated java classes. These classes are directly related to GIFT XML schema (.xsd) files.
output/ - where all the log files are stored, i.e. domain session, survey response, module logs
scripts/ - contains the scripts to launch modules and clean up log files
src/ - contains the GIFT source code
src.py/ - is for current and future python source code that is used to augment the core GIFT baseline
test/ - where all the junit tests are located
Training.Apps/ - contains information specific to the training applications, i.e. application plugins
Install and Configure SQuirreL SQL Client¶
The Squirrel application allows you to view and query against the GIFT Derby database.
- Download and install Squirrel SQL Client
- The project site is: http://sourceforge.net/projects/squirrel-sql/. At the time this is being written the latest stable package is http://sourceforge.net/projects/squirrel-sql/files/1-stable/3.5.0/squirrel-sql-3.5.0-install.jar/download locatedhttp://sourceforge.net/projects/squirrel-sql/files/1-stable/3.5.0/.
- Double click on the downloaded jar (e.g. squirrel-sql-3.5.0-install.jar) and an installation dialog will appear.
- Proceed through the installation until you get to the screen where you are supposed to “Select the packs you want to install:”. Make sure to select the following:
- Optional Plugin - Derby
- Optional Plugin – Hibernate
- Finish the installation.
- Launch Squirrel
- You will need the JAVA_HOME Windows environment variable set to an installed JDK on your machine. (we use the JDK provided by GIFT).
- If you selected to have a desktop or start menu icon then execute that, otherwise double click on the “squirrel-sql.bat” file where you installed Squirrel.
- Note: in version 3.5.0 there was a bug in the squirrel-sql.bat file for Windows 7 64x. To fix the problem change the following lines and then save and execute the file again:
- set IZPACK_JAVA="%JAVA_HOME%" to set “IZPACK_JAVA=%JAVA_HOME%"
- set LOCAL_JAVA=%IZPACK_JAVA%\bin\javaw.exe to set "LOCAL_JAVA=%IZPACK_JAVA%\bin\javaw.exe"
Before being able to connect to the GIFT derby database you will need to make sure your Squirrel application has the appropriate Derby Client driver configured.
- Check driver:
- After launching Squirrel, go to the “Drivers” panel and find “Apache Derby Client” in the list of drivers.
- If there is a check mark next to “Apache Derby Client” you can proceed onto “Create a GIFT Derby Alias“ step. Otherwise continue to “Change Driver” step below.
- Change driver:
- After clicking on “Apache Derby Client” in the list of drivers, select the “Modify the selected driver” button right above it (currently the button has a pencil on it).
- Click on the “Extra Class Path” tab.
- Click on the “Add” button.
- Browse to your GIFT installation and then select the derby.jar and derbyclient.jar in the external\derby folder as shown, similarly, in the screenshot below.
- Select the Open button on the file browse folder and then the OK button on the “Add Driver” window.
- There should be a check next to the “Apache Derby Client” in the list of drivers.
- Create a GIFT Derby Alias
- Click the “+” button in the “Aliases” pane in SQuirreL to create a new Alias.
- Create a name for the Alias in the “Name” textfield. (e.g. “UMS Derby Client”)
- Select “Apache Derby Client” as the “Driver”
- Modify the “URL” value to look like the below value but replace the red text with the path to your GIFT folder:
- For UMS database connection:
- For LMS database connection:
- In order to connect to the LMS database in Squirrel, it cannot be running in GIFT.
- Shut down the LMS Module in GIFT if it is running.
- Execute startNetworkServer.bat (located at GIFT/external/db-derby-10.10.1.1-bin/bin)
- Test the Alias by selecting the “Test” button followed by the “Connect” button on the dialog that appears. You should see a popup dialog that states “Connection Successful”. Select the OK button on that popup to close it. Finally select the OKbutton on the Alias dialog to save the alias and close the dialog.
More help can be found in <path-to-squirrel-install>/doc/quick_start.html.
- Double click on the Alias you created in the “Aliases” pane on SQuirreL.
- Select the “Connect” button. Upon successful connection the view should change to show information about the database. By default this is the Metadata tab of the database connection.
- To view values in a table:
- Expand your alias named node under the “Objects” tab.
- Expand the “APP” schema node.
- Expand the “TABLE” node.
- Select a table to view.
- Select the “Content” tab to the right of the panel you have been selecting nodes in. The table’s rows are now visible.
If the Alias fails to connect and an error message is displayed (could be in the stack trace of the error) such as “Check your URL” – trying using another “derbyclient.jar”. This issue was seen on one GIFT developer’s computer. Merely changing which derbyclient.jar was being used from GIFT/external/derby/derbyclient.jar to GIFT/external/db-derby-10.10.1.1-bin/lib/derbyclient.jar solved the problem.