You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

463 lines
19 KiB
Markdown

# Database
Used database schema is generated by ORM framework Doctrine from ReCodEx API
source code. Tables are directly mapped to _entities_, which are PHP classes
annotated with data provided by ORM framework. In the following text there is a
brief description of each such entity. There may be some additional database
tables for many-to-many relations between entities, but these tables are not
discussed in detail because there are only two columns with keys of both
related tables in each one. Graphical database schema is added as attachement
to this documentation.
8 years ago
## Assignment
Assignment table represents exercise assignment in a group. It holds keys of
the exercise (_exerciseId_) and group (_groupId_) where is the exercise
assigned. Other columns are:
- _name_ -- visible assignment identifier
- _isPublic_ -- assignment can be public (visible to students) or private
(visible only to supervisor of the group)
- _submissionCountLimit_ -- number of attempts student can make to solve the
exercise
- _scoreConfig_ -- configuration for calculating point score; actual syntax
depends on used score calculator
8 years ago
- _firstDeadline_ -- date and time after that no new submissions are received
- _allowSecondDeadline_, _secondDeadline_ -- flag if another deadline is
allowed, date and time of that deadline
- _maxPointsBeforeFirstDeadline_, _maxPointsBeforeSecondDeadline_ -- maximal
amount of points for correct solutions for first (respectively second)
deadline
- _scoreCalculator_ -- name of used score score calculator or NULL for API's
default one
- _canViewLimitRatios_ -- flag if student can view percentage of used time and
memory limits for each test
- _deletedAt_ -- assignment cannot be deleted due to possible numerous
dependencies, but can be hidden from the users; published assignments have
NULL value, deleted ones have time of deletion
- _version_ -- @todo
- _isBonus_ -- @todo
- _pointsPercentualThreshold_ -- @todo
8 years ago
## Comment
Comment entity holds one message published in a comment thread (standalone
comments are not permitted).
8 years ago
- _commentThread_, _user_ -- keys of thread where this comment belongs and
author of the comment
8 years ago
- _isPrivate_ -- flag if the comment is for author only or public
- _postedAt_ -- date and time of comment post
- _text_ -- content of the comment
8 years ago
## CommentThread
CommentThread entity contains all comments in one thread by one-to-many
relation. From database perspective, this table has only one column with
primary key and the relation is made by foreign key column in Comment table.
8 years ago
## Exercise
Exercise is a structure that describes a programming problem. Exercises can
have a tree structure (_exerciseId_ of parent) that can be used to implement an
inheritance mechanism, but it's currently not being used.
8 years ago
- _author_ -- key for user entity of the author
- _name_ -- name of the exercise
- _version_ -- version of the exercise; each edit increases this counter
8 years ago
- _createdAt_ -- date and time of creation
- _updatedAt_ -- date and time of last modification
- _difficulty_ -- description of difficulty, curretly used ones are easy,
medium and hard
- _isPublic_ -- flag if the exercise is publicly visible to all supervisors or
only to author
- _description_ -- @todo
8 years ago
## ExerciseFile
ExerciseFile entity is extension of UploadedFile entity, so they share one
database table. Exercise file has some additional data:
8 years ago
- _hashName_ -- `sha1sum` of file content, used as name in job configurations
- _fileServerPath_ -- URL where the file is stored on file server
- _exerciseId_ -- key of exercise this supplementary file belongs to
## ExternalLogin
ExternalLogin entity provides mapping between username in external login
service and local user account.
8 years ago
- _user_ -- key to local user entity
- _authService_ -- identifier which extrnal service is the user using
- _externalId_ -- username in that particular external instance
## ForgottenPassword
8 years ago
This entity is used for logging requests about password resets.
- _user_ -- key to user who requested the password change (or NULL if not
known)
8 years ago
- _requestedAt_ -- date and time of password reset request
- _sentTo_ -- email address where the reset token was sent to
- _redirectUrl_ -- URL where the user is supposed to change his password
- _IPaddress_ -- IP address from where the request came from (parsed from HTTP
request header)
8 years ago
## Group
Group entity contains data about a group. They can be hierarchical, reference
to the parent is obtained by _parentGroup_ key. Top level groups has this field
set to NULL. Each group belongs to one instance referenced by _instance_ key.
Also, each group has its administrator user referenced by _admin_ key. Other
data:
8 years ago
- _name_ -- name of the group
- _description_ -- Markdown styled text description of the group
- _threshold_ -- percentage of maximal points required to complete the course
in float between 0 and 1 (or NULL)
- _publicStats_ -- flag if user can view total number of points for other users
in the group
- _isPublic_ -- flag if the group is visible for all students in instance or it
is hidden (only for members)
- _externalId_ -- external identifier of the group (or NULL), for example
course code like NPRG042
- _deletedAt_ -- @todo
8 years ago
## GroupMembership
GroupMembership represents relation between group and its members. Also it
contains additional data, so this entity is not autogenerated by Doctrine.
Essential parts are keys to user and group entities (_user_ and _group_ keys).
Additional data:
8 years ago
- _status_ -- user status in the group, one of _requested_, _accepted_ and
_rejected_
- _type_ -- type of user access, one of _student_, _supervisor_ and * for all
8 years ago
- _requestedAt_ -- date and time the join request was received (or NULL)
- _joindedAt_ -- date and time the request for joining was accepted (or NULL)
- _rejectedAt_ -- date and time the request for joining was rejected (or NULL)
- _studentSince_ -- date and time when the user became a student, usually time
of registration (or NULL)
- _supervisorSince_ -- date and time when the user became a supervisor (or
NULL)
8 years ago
## HardwareGroup
HardwareGroup entity represents used hardware groups by the backend. Currently
this table has to be changed manually when a new hardware group is added, but
it is possible to automate this in the future. The hardware group has only one
column with data, the textual _description_.
8 years ago
## HardwareGroupAvailabilityLog
This entity provides information about hardware group changes during time.
System administrator should keep the data up-to-date with backend state.
8 years ago
- _hardwareGroup_ -- key to HardwareGroup entity
- _isAvailable_ -- flag if the hardware group becomes available or disabled
- _loggedAt_ -- date and time of the change
- _description_ -- reason for the change
## Instance
Instance entity represents separation of multiple organisations using the same
API server. Each group or user belong to exactly one instance. User permissions
are only valid in his instance.
8 years ago
- _admin_ -- key referencing administrator user entity
- _name_ -- @todo
8 years ago
- _description_ -- Markdown styled textual description
- _isOpen_ -- flag if new user can register themselves in this instance
- _isAllowed_ -- flag if the instance cen be used or is disabled for all users
- _createdAt_ -- date and time of instance creation
- _updatedAt_ -- date and time of last modification
- _needsLicence_ -- flag if this instance needs a velid license
- _deletedAt_ -- instance cannot be directly deleted due to possibility of many
dependencies, but instead it can be hidden from users by setting this field
to date and time of deletion (active instances have NULL value)
8 years ago
## Licence
Licence entity gives validity to instance. For normal usage an instance needs
valid licence for proper functionality.
8 years ago
- _instance_ -- instance key the licence is bound to
- _isValid_ -- flag if this licence is valid or blocked by administrator
- _validUntil_ -- date and time until the licence is valid (expiration time)
- _note_ -- optional note about the licence
## LocalizedText
LocalizedText entity represent text or description of the problem in one
language mutation. Exercises and assignments uses these text to display problem
description to users. The text can be Markdown styled.
8 years ago
- _locale_ -- language code of locale this text is written in (for example
_en_)
- _text_ -- text content
- _createdFrom_ -- key refering to parent localized text; when editing, new
version is created as a child of the original one
8 years ago
- _createdAt_ -- date and time of creation
## Login
Login entity holds credentials for logging into ReCodEx system using internal
authentication.
8 years ago
- _user_ -- key refering to user entity
- _username_ -- mail of the user
- _passwordHash_ -- hashed password, generated by Nette
[Passwords::hash()](https://api.nette.org/2.3/source-Security.Passwords.php.html#27)
method
8 years ago
## Permission
Permission entity holds permissions for user roles. API endpoints can have a
permission restriction assigned by annotation
_@UserIsAllowed(exercises="view-all")_ which are checked before endpoint
invocation. These permission are gained to user roles in this entity.
8 years ago
- _role_ -- key of the role this permission is assigned to
- _resource_ -- resource name, usually same for all endpoints in one presenter;
from the example above resource is _exercises_ string
- _action_ -- action, usually different for each endpoint, wildcard can be
specified as *; in the example above, _view-all_ is the action
8 years ago
- _isAllowed_ -- flag if the rule is allowed of denied
## ReferenceExerciseSolution
ReferenceExerciseSolution contains additional data for reference solution than
normal solution created by student submit.
8 years ago
- _exercise_, _solution_ -- keys refering to exercise this entity is bound to
and solution entity used for submitting
8 years ago
- _uploadedAt_ -- date and time of creation
- _description_ -- textual description of used algorithm or other note about
the particular solution
8 years ago
## ReferenceSolutionEvaluation
ReferenceSolutionEvaluation contains additional data for reference solution
evalution than normal evaluation created on student solution evaluation.
8 years ago
- _referenceSolution_ -- key to solution which this evaluation belongs to
8 years ago
- _hwGroup_ -- hardware group which was used during execution on worker
- _resultsUrl_ -- filserver address from where results of reference evaluation
can be internally accessed
8 years ago
- _evaluation_ -- associated general evaluation key
8 years ago
## ReportedErrors
All errors which were reported to API from backend are sent as emails to
administrator of system and also stored in this entity.
8 years ago
8 years ago
- _type_ -- textual description of error type
- _recipients_ -- list of comma separated email addresses to which error was
sent
8 years ago
- _subject_ -- subject as it was sent in email
8 years ago
- _sentAt_ -- date and time when email with error report was sent
8 years ago
- _description_ -- message as it was sent in email
## Resource
Resource entity represent different resources used in ReCodEx system. These
resources can be used in presenter actions for access restrictions. Resource
contain list of permissions in one-to-many relation, but from database
perspective this table has only one column with the resource name.
8 years ago
## Role
Each ReCodEx user has exactly one role. A role is associated with multiple
permissions that determine what actions can a user with that role perform on a
resource.
8 years ago
8 years ago
- _id_ -- textual identification of the role
8 years ago
- _parentRole_ -- reference to parent role
- _childRoles_ -- array of roles which have this one as parent; not actual
database column, relation stored using _parentRole_ column
- _permissions_ -- permissions which are connected to this role; not actual
database column, many-to-one relation stored in Permission entity
## RuntimeConfig
RuntimeConfig entity connects job configuration to runtime environment. This
entity is backed up on every update, old version is set as _createdFrom_ key in
the new version. On student submission one runtime config is chosen based on
files extensions and corresponding job configuration is used for evaluation in
the backend.
- _name_ -- human readable identificator of runtime configuration
- _runtimeEnvironment_ -- corresponding runtime environment
- _jobConfigFilePath_ -- path to job configuration which is stored at API
server
- _createdAt_ -- date and time of entity creation
8 years ago
## RuntimeEnvironment
Stores information about supported environments which can be used for
evaluation on workers. On student submit the correct environment is determined
by extensions of uploaded files.
8 years ago
8 years ago
- _name_ -- human readable name of runtime environment
- _language_ -- language which can be used in this environment
- _extensions_ -- list of extensions in yaml format
- _platform_ -- textual description of platform
- _description_ -- some further description concerning this environment
8 years ago
## Solution
Solution is a general entity which is used for all types of evaluations,
including students and reference solutions. This entity can be shared between
multiple submissions (for example resubmit by supervisor in case of backend
failure).
8 years ago
- _user_ -- user key to whom this solution belongs to
- _files_ -- exercise solution files which user uploaded and are associated
with solution; not actual database column, one-to-many relation is stored by
each file
- _runtimeConfig_ -- runtime configuration key which was used during execution
on worker
8 years ago
- _evaluated_ -- true if solution was evaluated and results were processed
8 years ago
## SolutionEvaluation
SolutionEvaluation entity represents evaluation of student or reference
solution. It contains parsed and processed data received from backend.
8 years ago
- _evaluatedAt_ -- date and time of evaluation creation
- _initFailed_ -- if true then one of the initiation tasks failed thus solution
cannot be even compiled
- _score_ -- overall score of user solution (percentual correctness from 0 to
1)
8 years ago
- _points_ -- points which were assigned to user for this solution
8 years ago
- _bonusPoints_ -- bonus points assigned by one of the supervisors
- _isValid_ -- can be used to ban user solution of exercise due to various
reasons
8 years ago
- _evaluationFailed_ -- true if whole evaluation failed on worker
8 years ago
- _resultYml_ -- whole yaml file with evaluation results acquired from backend
- _testResults_ -- results of all tests associated with user solution; not
actual database table, one-to-many relation is stored by TestResult entities
8 years ago
## SolutionFile
SolutionFile entity is extension of UploadedFile entity, so they share one
database table. Solution file has one additional column of associated solution
key.
## Submission
Submission entity corresponds to student submit of assignment. It stores both
information about submission and about subsequent evaluation.
8 years ago
- _submittedAt_ -- date and time of submission creation
- _note_ -- user can provide note to exercise solution
- _resultsUrl_ -- URL pointed to fileserver from which results of submission
can be internally downloaded
8 years ago
- _assignment_ -- corresponding assignment key to which submission belongs to
- _user_ -- key of user to whom submission belongs to
- _submittedBy_ -- user who submitted solution of exercise, can be supervisor
for instance
8 years ago
- _solution_ -- corresponding solution
- _asynchronous_ -- exercise solution was submitted asynchronously, this
happens when supervisor or superadmin submit solution for particular user
8 years ago
- _evaluation_ -- evaluation of this submission
## SubmissionFailure
A queue of failed submissions which need further attention from the
administrator. Administrator can then resolve this issue and information about
that will be stored too.
8 years ago
- _type_ -- type of failure, can be for example _broker_reject_ or
_evaluation_failure_
8 years ago
- _description_ -- description of failure which was provided by backend
- _submission_ -- associated submission which failed
8 years ago
- _createdAt_ -- date and time of entity creation
- _resolvedAt_ -- date and time when failure was resolved
8 years ago
- _resolutionNote_ -- user can provide description when failure is resolved
## TaskResult
@todo
- _taskName_ -- @todo
- _usedTime_ -- @todo
- _usedMemory_ -- @todo
## TestResult
8 years ago
TestResult entity represents result of one logical test from job configuration.
- _testName_ -- name of test which was stated in job configuration
- _status_ -- overall status of test
- _solutionEvaluation_ -- evaluation to which test result belongs
- _score_ -- score which was assigned to test evaluation by judge
- _memoryExceeded_ -- true if memory limit was exceeded
- _usedMemoryRatio_ -- float number from 0 to 1 which represents percentage of
user solution memory usage against memory limit from configuration
- _timeExceeded_ -- true if time limit was exceeded
- _usedTimeRatio_ -- float number from 0 to 1 which represents percentage of
user solution time usage against time limit from configuration
- _exitCode_ -- exit code which whole test returns
- _message_ -- provided only on non-zero exit code
- _stats_ -- textual representation of whole information about evaluation of
test which arrived from worker
- _judgeOutput_ -- output textual message from judge
## UploadedFile
Entity which represents one file which was uploaded to API server. This entity
uses _Single Table Inheritance_ and its children are ExerciseFile and
SolutionFile entities.
8 years ago
- _name_ -- original name of file uploaded to API
- _localFilePath_ -- destination where file is stored on API server
8 years ago
- _uploadedAt_ -- date and time of file upload
- _fileSize_ -- size of uploaded file in bytes
- _user_ -- user which uploaded particular file
## User
Keeps information about all users registered in ReCodEx.
- _degreesBeforeName_ -- degrees before name which user acquired
- _firstName_ -- first name
- _lastName_ -- surname
- _degreesAfterName_ -- degrees after name
- _email_ -- email address which is used for sending email notifications
- _avatarUrl_ -- url of profile picture
8 years ago
- _isVerified_ -- user verified his email address (not used at the moment)
- _isAllowed_ -- if this field is set to false user cannot sign in to
application
8 years ago
- _createdAt_ -- date and time of user registration
- _instance_ -- instance to which user belongs to
- _settings_ -- settings which are connected to this user
- _memberships_ -- array of groups in which is user assigned
- _exercises_ -- exercises which user created and is their author
- _role_ -- role of the user which is used to determine privileges
## UserAction
Stores information about what routes on API user visited and some additional
information about it. This data is collected only from logged users.
8 years ago
- _user_ -- which user performed API request
8 years ago
- _loggedAt_ -- date and time when action was performed
- _action_ -- action which was requested on API
8 years ago
- _params_ -- GET or POST parameters given by user
- _code_ -- return code which was sent back by API
- _data_ -- if call ended up with an exception, description of thrown exception
should be there
## UserSettings
User settings belong to some user and contains settings mostly for web
application.
8 years ago
- _darkTheme_ -- dark mode will be used in text editor in web application
- _vimMode_ -- turn vim mode keybinding on in text editor used by web
application
8 years ago
- _defaultLanguage_ -- default language which will be used in web application
- _openedSidebar_ -- @todo