recodex-wiki/User-documentation.md

# User documentation

## Student

### From registration to solution submit

- Registration can be made on separate page, _Create acount_ link from left menu. There are two forms, one for ReCodEx authentication and one for CAS (Charles University Authentication System) authentication. During the process instance has to be chosen. After successful registration you will be automatically logged in.
- Login forms are located on page accessible through _Sign in_ link from menu. The same type of form as the registration must be used. After login occurs redirection to _Dashboard_ -- page with overview of achievements for each group user is member of.
- New page with details about used instance is accessible from menu, specificaly containing list public groups. From group detail page is possible to join (or leave) the group. Private groups are hidden and only supervisor can add students to that group.
- Pages of joined groups are accessible from menu. There is a list of assigned exercises. Detail of each assignment contains description of problem, deadlines, already submitted solution and other information.
- Solution is submitted from assignment detail page through _Submit new solution_ button. After uploading source files the evaluation will start showing current progress. When finished, button _See results_ redirects to page with results summary.

### Password reset

- Password reset could by done only for ReCodEx authentication, CAS has its own system.
- Under login form there is a link leading to forgotten password page. After providing an email address a message with short term link to password change page is sent.
- On that page the new password can be set. Please note that password change link is time limited and is functional only for few minutes.


## Group supervisor

### Create and update exercise

- For management of exercises there is whole page which can be visited from _Exercises_ link in main menu.
- In there you can list all public exercises and the ones you created.
- If you choose to create new exercise, there is a button _Add exercise_ for that purpose.
- After clicking on it you will be redirected to exercise editation page.
- In here there are three forms, in the first one you can add localized descriptions of exercise, change difficulty, name and some description which can be seen by supervisors.
- Second form serves for the purpose of uploading supplementary files to exercise. These files are handed over directly to fileserver and afterwards can be used in job configuration with their hashed names. Note that these files are not additional files for exercise and are not visible to outside world!
- The most important thing on exercise editation page is runtime configurations, in here you can select environment which will be used for processing of this exercise and most notably you should provide textual job configuration.
- Job configuration is instruction set for workers which is used for detailed description of execution flow. It should be provided in right format which can be found in separate [article](https://github.com/ReCodEx/wiki/wiki/Assignments#job-configuration).

### Assign exercise to group

- On group detail page is search box for exercises. Every match has a button _Assign_ which redirects to configuration page. Assignment text, visibility to students, time and memoty limits for tests, deadlines and other informations can be set there.
- Assigned exercises are shown in separate box in group detail page, where is also button for editing each assignment.

### Add student to group

- Groups can be public or private. Public groups are visible to all instance users and students can join them. Private ones are hidden and students can be only added to them.
- Supervisor of group can add students to it by hand on group detail page through _Add student_ search box.

### View students results

- Agregate results for each assignment are accessible through _View student results_ button on assignment detail page. There is a list of submissions for every group member.
- Each submission can be viewed in detail including submitted files on special page.


## Group administrator

### Create sub-group

- Group administrator can create sub-groups of his own groups.
- On group detail page there is a form for creating new subgroup, including fields for brief description in Markdown and other basic information.
- Newly created group is shown in refreshed group hierarchy.

### Add and delete supervisor

- On group detail page is list of supervisors and search form for adding new ones.
- Supervisors are searched by their names and surnames. Adding supervisor immediately changes supervisor list from where the removal is possible.


## Superadministrator

Superadmin is user with the most priviledges.

### Users management

There are only few roles to which users can belong in ReCodEx. Basically there are only three: _student_, _supervisor_, and _superadmin_. Base role is student which is assigned to every registered user. Roles are stored in database alongside other information about user. One user always has only one role at the time. At first startup of ReCodEx administrator should create his/hers account and then change role in database by hand. After that manual intervention into database should never be needed.

There is a little catch in groups and instances management. Groups can have admins and supervisors. This setting is valid only per one particular group and has to be separated from basic role system. This implies that supervisor in one group can be student in another and simultaneously have global supervisor role. Changing role from student to supervisor and back is done automatically by application and should not be managed by hand in database! Previously stated information can be applied to instances as well, but instances can only have admins.

Roles description:

- Student -- Default role which is used for newly created accounts. Student can join or leave public groups and submit solutions of assigned exercises.
- Supervisor -- Inherits all permissions from student role. Can manage groups to which he/she belongs to. Supervisor can also view and change groups details, manage assigned exercises, view students in group and their solutions for assigned exercises. On top of that supervisor can create/delete groups too, but only as subgroup of groups he/she belongs to.
- Superadmin -- Inherits all permissions from supervisor role. Most powerful user in ReCodEx who should be able to do everything which is provided by application.