Introduction

The Vortex Student Database is a Mongo database that is used to store student information and their training sessions.

The database contains all users, students and instructors, and their organization in classes. Each training session is recorded, results and metrics, in addition to scoring rules and the results. Some additional tables might be present for optional or prototype features.

In this document, we assume the reader is familiar with Mongo database. The document describes the current state of the Vortex Student Database.

Collections

The basic collections contain information about the users, classes and training sessions

users : contains the information about all users
classes : contains all the classes and the users in each class
sessionsV2 : contains each training session information
metrics : contains all the metrics gathered during the training sessions

Scoring collections are optional and contain the scoring rules for each scenario

scoring_factory : contains the default scoring rules for specific training scenarios, provided by CM Labs.
scoring_custom : contains the instructor-created scoring rules for specific training scenarios

Locales collection contains the translated strings to be used during report generation

locale_xx_YY : contains the translated text for language xx (international language code in lowercase) and for country YY (international country code in uppercase)

Some collections are used only for demo or experimental features and should be ignored.

bestcontainermove
learningpath

There is a deprecated collection (session) that can be present in some database, depending what version of simulators is running.

Users and classes

users collection
Field	Type	Description
_id	oid	Unique ID for a user
name	string	Login name of the user. With this name, the user will be able to log in the Console. Must be a non-empty string with no whitespace.
version	integer	Current version is 620140801. Used for backward compatibility.
type	string	Indicates the type of user. The type can be "STUDENT", "INSTRUCTOR" or "ADMIN". No other values are allowed.
fullname	string	The full name of the user, that will be shown in the reports. It is usually in the form FirstName LastName. It should not be empty, but there is no error if it is.
active	boolean	Indicates if the user is active or not. An inactive user cannot log in, and cannot be added to a training session by the instructor.
company	string	An optional string that can be used for the company for this user.
customid	string	An optional string that can be used if the school has its own id system.
password_hash	string	256 bits cryptographic key
password_salt	string	256 bits cryptographic key
Indexes	Description
_id	Standard Mongo databse index on object ids
company	Index by company
type	Index by user type
name	Index by user name

classes collection
Field	Type	Description
_id	oid	Unique ID for a class
users_id	array of oid	List of users _id that are in this class
version	integer	Current version is 620141210. Used for backward compatibility.
name	string	The name of the class.
Indexes	Description
_id	Standard Mongo database index on object ids
users_id	Index by the users who are in the class

Sessions and Metrics

The sessionV2 collection contains all the informations about the student, the exercise, when, and any event that happened during a single training session.

sessionsV2 collection

Field

Type

Description

_id

oid

Unique ID for a session

name

string

(unused) Name of the session. Usually empty.

description

string

(unused) Description of the session. Usually empty

version

integer

Current version is 620200107. Used for backward compatibility.

start_time

date

The start date and time of the training session

users_id

array of oid

Users involved in this training session. It usually is 1 student and 1 instructor, it can be only 1 student on some simulators. Can be more students for tandem scenario

elapsed_time

double

The duration of the training session (in seconds)

equipment

array of strings

The training equipment as an array of 2 strings : ["Top Equipment", equipment name]

sub_equipment

array of array of strings

The sub-equipment describes a variation on the main equipment.

It is an array of items [ [sub-equipment type, sub-equipment name] ... ]

scene

array of strings

The scene is the name of the training exercise : [exercise list name, exercise name]

bookmarks

array of bookmark documents

Bookmarks are tags that the instructor can enter during the training session.

See bookmark document definition

environmental_conditions

array of environmental_condition documents

Records all the initial weather conditions and any changes.

See environmental_condition document definition

malfunctions

array of malfunction documents

Malfunctions that the instructor has triggered during the simulation session

See malfunction document definition

comments

string

Instructor comment entered at the end of the training session

result

string

Either "Pass", "Fail" or "None"

scoring_rule_set

scoring_rule_set document

Copy of the scoring rules used during the training session.

See the scoring_rule_set document definition

video_recording

string

Path to the video recording of the training session. Not available on all simulators.

report_info

report_info document

Contains only one field

Field	Type	Description
plotter_diameter	double	The maximal distance from the hook when drawing Hook Block positions on certain simulators.

vortex_version

string

The Vortex Toolkit version when the session was run. Used for backward compatibility.

Indexes

Description

_id

Standard Mongo database index on object ids

users_id

Index by users in the session

bookmark document
Field	Type	Description
text	string	Annotation entered by the instructor
type	integer	Instructor coded type : 0 = Blue flag, 1 = Green flag, 2 = Orange flag, 3 = Red flag
id	integer	Sequential id of the bookmark in the session
time	double	Session time the bookmark is entered, in seconds

environmental_condition document
Field	Type	Description
time	double	Session time this environmental condition has been set , in seconds
text	string	Description of the condition that changed
value	string	The new value

malfunction document
Field	Type	Description
time	double	Session time this malfunction been triggered, in seconds
name	string	Malfunction name
action	string	Either of "FAULT_ON", "FAULT_OFF" or "FAULT_VALUE_CHANGED"
value	string	Either of "FAULT_ON", "FAULT_OFF" or the actual value as a string
dimension	string	Either empty, or a string indicating the dimension. See References

scoring_rule_set document
Field	Type	Description
version	integer	Current version is 0. Used for backward compatibility.
scenario_id	string	Id of the scenario used during this simulation session
scoring_rules	array of scoring_rule document	List of rules that defines how the score is calculated See scoring_rule document definition
score	double	Final score of the trainee in this session

scoring_rule document
Field	Type	Description
version	double	Current version is 0. Used for backward compatibility.
minimum	double	Minimum value for this rule. When the metric's value goes below the minimum, the deduction is applied.
maximum	double	Maximum value for this rule. When the metric's value goes above the maximum, the deduction is applied.
deduction	double	Number of points deducted per trigger
metric_unique_name	string	A unique name identifying the metric associated to this Scoring Rule
trigger_count	integer	Number of times this rule was triggered
trigger_timestamp	double	Session time when this rule was triggered the last time

The metrics collection contains all the metrics for all training sessions in the database. Each metric contains the oid of the session it belongs to. Those metrics are used for report generation.

metrics collection
Field	Type	Description
_id	oid	Unique ID for this metric
name	string	Name of the metric
value	double	For non-vector3 type metric : Value of the metric
valueX	double	For vector3 type metric : the value is (valueX, valueY, valueZ)
valueY	double
valueZ	double
session	oid	Unique id of the training session when the metric was recorded
unit	string	(obsolete) Contained the unit symbol for the metric. Replaced by dimension and hint.
dimension	integer	Value indicating the dimension of the value (time, speed, etc..). See the list of Dimension values in the References
hint	integer	Value indicating how the dimension should be displayed See the list of Hint values in the References
version	integer	Current version is 620200107. Used for backward compatibility.
Indexes	Description
_id	Standard Mongo database index on object ids
session	Index by the session from which they come
name	Index by the metric name
session and time	Index by the session and the time, so they are retrieved in the order they were saved

Scoring rules : factory and custom

Scoring_factory collection contains the default scoring rules for each scenario, as designed by CM-Labs. Those are hard coded but will be updated automatically when a new version of the Training product is installed. The scoring_custom collection contains the rules that an instructor has created or modified on their own system. Those are local to a system. Both collections have exactly the same structure and data, they only differ in the way they are used.

The structure of those collections is very similar to the scoring rule set document in the session.

scoring_factory and scoring_custom collections
Field	Type	Description
_id	oid	Unique id for this scoring_factory
version	integer	Current version is 0. Used for backward compatibility.
scenario_id	string	id of the scenario used during this simulation session
scoring_rules	array of scoring_rule document	List of rules that defines how the score is calculated See scoring_rule document definition
asset_version	string	The Vortex Toolkit version when those scoring rules were saved. Used for backward compatibility.
Indexes	Description
_id	Standard Mongo database index on object ids
scenario_id	Index by the scenario for which they are used

scoring_rule document
Field	Type	Description
version	double	Current version is 0. Used for backward compatibility.
minimum	double	Minimum value for this rule. When the metric's value goes below the minimum, the deduction is applied.
maximum	double	Maximum value for this rule. When the metric's value goes above the maximum, the deduction is applied.
deduction	double	Number of points deducted per trigger
metric	string	Base-64 serialization of the metrics information

Locales collections

The various locales collections that may or may not be present contain the translated strings that are used when generating reports. Each locale table has the same structure and contains the strings for one particular language. The specific language can be retrieved in the name of the collection : locale_xx_YY : contains the translated text for language xx (international language code in lowercase) and for country YY (international country code in uppercase).

locale_xx_YY collection
Field	Type	Description
_id	oid	Unique id for this translation
context	string	Context for this string (allows disambiguation between same string in different contexts)
source	string	Source in the original language (usually English), but can also be a translation key.
translation	string	Translated text in the target language
Indexes	Description
_id	Standard Mongo database index on object ids
context and source	Index by the the context and the source string
source and translation	Index by the the source and translation

Obsolete sessions collection

The sessions collection is obsolete and new sessions are always added to the sessionsV2 collection. However, this collection may be present in the database of a client that has older simulators. It may even be active, as older simulators will write their sessions to this collection. All the sessions this this obsolete collection are shown in the Console and reports can be generated from them.

The structure of the sessions collection is very similar to the sessionsV2 collection

References

Dimension : describe the type of value
value	Description
0	None (dimensionless)
1	Length
2	Volume
3	Mass
4	Time
5	Angle
6	Linear speed
7	Linear acceleration
8	Angular speed
9	Angular acceleration
10	Force
11	Torque
12	Energy
13	Work
14	Power
15	Moment inertia
16	Spring constant linear
17	Spring damping linear
18	Unit Length Spring constant linear
19	Unit Length Spring damping linear
20	Kinetic loss
21	Percentage %
22	Normalized
23	Spring constant angular
24	Spring damping angular
25	Unit Length Spring constant angular
26	Unit Length Spring damping angular
27	Damping linear velocity
28	Damping angular velocity
29	Density
30	Linear Density
31	Momentum
32	Count
33	Transformation matrix without scale
34	Transformation matrix
35	Pressure
36	Scale
37	Reciprocal of a linear spring constant
38	Reciprocal of a angular spring constant
39	Frequency
40	Surface density
41	Angular kinetic loss
42	Area
43	Volume flow rate
44	Liquid volume
45	Liquid volume rate
46	Rotation rate
47	Bucket efficiency with respect to fuel consumption
48	Bucket efficiency over time
49	Blade efficiency
50	Temperature

Hint : modify how the dimension will be displayed
Value	Description
0	Standard
1	Speed km/h (instead of m/s)
2	Mass tonne (instead of kg)
3	Power kW (instead of W)
4	Pressure kPa (instead of Pa)
5	Bucket efficiency tonne/L (instead of kg/L)
6	Bucket efficiency tonne/h (instead of kg/s)
7	Speed m/min (instead of m/s)
8	Blade efficiency kgkm/L (instead of kgm/L)
9	Blade efficiency tonnekm/L (instead of kgm/L)
10	Length km (instead of m)
11	Length mm (instead of m)
12	Pressure bar (instead of Pa)

Vortex Studio 2020b Documentation

Vortex Student Database Schema

Introduction

Collections

Users and classes

Sessions and Metrics

Scoring rules : factory and custom

Locales collections

Obsolete sessions collection

References