source: main/waeup.kofa/trunk/docs/source/userdocs/students/browser.rst @ 13046

.. _students_browser:

Browsing the Student Section
============================

The reader may ask: How do officers and students browse the portal? Where are the step-by-step operating instructions on how to use Kofa? We are always tempted to answer: The menu navigation should be self-explanatory and it's quite easy to follow the menu prompts or flash messages which appear above page titles in a green, yellow or red box. For the students section this answer seems a bit over the top. We must indeed describe some browser pages and what their clickable actions are doing with the data. The reason is, that a lot of Kofa's functionality is embedded in view and utility methods and not only provided by the functionality of content components as described above.


.. _page_layout:

Page Layout
===========

Kofa makes use of two different `Bootstrap`_ layouts. Anonymous users, students and applicants do see a single-column theme with only a static top navigation bar. Students can navigate to the various display pages of their record by pulling down the 'My Data' in the navigation bar.

Officers see a double-column theme after logging in. The left column contains a box which contains links to the user's preferences (My Preferences) and roles (My Roles). It also contains links to the various sections of Kofa depending on the permissions the officer has has obtained. Possible sections are: 'Portal Configuration', 'Officers', 'Data Center', 'Reports' and 'Access Codes'. A second box shows up in the left column when the officer accesses a student record. This box gives direct access to the display pages of a student record.


.. _manage_edit_pages:

Manage and Edit Pages
=====================

Pages, or more precisely web pages, are browser views which render (produce) HTML or PDF code to be displayed in a web browser or a pdf reader respectively. Views are dealing with request and response objects. In Kofa most pages are form pages which means they are views on data. These pages are either used to display, edit or add persistant data. Thus we can further distinguish display, edit and add form pages. Kofa is using the `Zope Formlib`_ package to auto-generate these forms.

.. note::

  Briefly, Zope Formlib is wedded to `Zope Schema`_, it provides display and input widgets (= views) for the fields defined in the Zope Schema package. Auto-generation is done with `grok.AutoFields` which takes the fields, declared in an interface, and renders display or input widgets, according to the schema declaration, for display or edit forms respectively.

Whereas display and add form pages are usually shared by officers and students, edit form pages are not. Students are not allowed to edit all of their data all the time. Edit access is restricted by workflow states or other conditions. Officers' access is much less restricted and we therefore speak of 'managing' instead of 'editing' data. In most cases, Kofa uses two different form pages which require different permissions: An `EditFormPage` requires the :py:class:`HandleStudent<waeup.kofa.students.permissions.HandleStudent>` permission and a `ManageFormPage` requires the :py:class:`ManageStudent<waeup.kofa.students.permissions.ManageStudent>` permission.


.. _action_buttons:

Action Buttons
==============

There are two kinds of action buttons which appear on pages: 

-  **Link Buttons** appear on top of the page above the page
   title and are decorated with an icon. These
   :py:class:`action
   buttons<waeup.kofa.browser.viewlets.ActionButton>` have a
   link target which means they usually refer to another Kofa
   page and are sending GET requests to open the page.

-  **Form Buttons** are submit buttons which appear below a form.
   They are HTML form actions which submit data by sending a
   POST request back to the form page. A form page method is
   called and processes the data or simply redirects to
   another Kofa page.


.. _logging_in_as_student:

Logging in as Student
=====================

Officers with :py:class:`LoginAsStudent<waeup.kofa.students.permissions.LoginAsStudent>` permission do see a 'Login as student' button on student display pages which redirects to a page, where a temporary student password can be set by clicking a 'Set password now' form button. The temporary password is valid for 10 minutes. During this period the student can't login. The officer is being redirected to a login page which allows to directly login as student with pre-filled temporary credentials. The second page is to avoid that officers must remember the student credentials, have to logout from their own account and manually login as student via the regular login page. After 10 minutes the officer is automatically thrown out and the student is able to login again (if the officer hasn't changed the password). Attention: When logging in as student, the officer really impersonates the student. All actions are logged with the student id and not with the officer's user id. However, start of student impersonation is also logged, so that officers can be identified and fraudulent use can be discovered.


.. _rejecting_clearance:

Rejecting Clearance
===================

When a clearance officer clicks the 'Save comment and reject clearance now' button, the `reject` action method of the :py:class:`StudentRejectClearancePage<waeup.kofa.students.browser.StudentRejectClearancePage>` is called. This method first checks, in which workflow state the student is, and fires a transition accordingly. Then the comment, which should explain why the request was requested, is saved twice in the `officer_comment` attribute of the student and in ``students.log``. As soon as the `clear` transition (d) is effected, an event handler clears the attribute again. The logfile message is permanent and ensures that the original cause of rejection can always be reconstructed.

Finally, the method redirects to the ContactStudentForm and prefills the HTML form with the comment previously saved. The clearance officer can leave the comment as it is, or can modify the text to give more information about the reason of rejection. This comment will then be sent to the student by email. This comment is not saved, neither in the student object nor in the logfile.

.. important::

  All messages sent via Kofa contact forms are private. They are neither stored in the database nor in any logfile. The emails are also not forwarded to any other email address. Thus senders and recipients can be sure that nobody else is eavesdropping and the correspondence is kept secret.

.. seealso::

  :ref:`Clearance Handling Doctests <test_handle_clearance>`


.. _transferring_students:

Student Transfer
================

Transferring a student means enabling the student to study another programme.

The simple but dirty way is to select another certificate and adjust study course attributes accordingly. Existing study levels can be either removed or, in case registered courses can be credited, left as they are. This simple way is tedious and also dangerous, because changes are not tracable. Only the logfile can tell us, that an officer has edited the student's data. The data of the previous study course are not backed up. They are lost.

Kofa provides a more adequate, cleaner and tracable way of transferring students. It can make a backup of the entire study course container and create a new and empty container for the new study programme with only one click or even by batch processing.

After clicking the 'Transfer student' button the `StudentTransferFormPage` opens and asks for the new certificate, current session, current level and current verdict. After submitting this form, the student transfer method checks if the old study course is complete and ready for transfer. It also checks if the number of possible transfers is not exceeded. Kofa allows two (2) transfers! Finally the copying process is started and history and logfile messages are added.

The old study course container(s) can still be accessed via links on the current study course display page. But, they can neither be edited, removed, exported or reimported.


Batch Transferring Students
---------------------------

Sometimes students of an entire study programme have to be transferred to another programme. This can be done with the :py:class:`StudentStudyCourseProcessor<waeup.kofa.students.batching.StudentStudyCourseProcessor>`. The import file must contain the following columns: `student_id` (or any other locator), `certificate`, `current_session`, `current_level` and `entry_mode`. Do not import `entry_session`. A transfer is automatically initialized if the `entry_mode` value is ``transfer``.


Reverting Previous Transfers
----------------------------

Previous transfers can be reverted by opening the previous study course and clicking the 'Reactivate this study course (revert previous transfer)' button. This is a complete rollback of the last transfer. The current study mode will be irrevocably deleted and replaced by the previous study course. The second last study course will become the previous study course.


.. _payment_tickets:

Payments
========

The `PaymentsManageFormPage` is used by both students and students officers. The page tabulates existing payment tickets and allows to add or remove tickets. Officers can remove all payment tickets, students only those without a response code (`r_code`). Attention: Students can remove tickets without response code even if they have been marked paid.

There are three different add form pages to add `StudentOnlinePayment` instances (= payment tickets). They all create objects of the same type, only their attributes are set differently.


Current Session Payment Tickets
-------------------------------

Current session payments are the regular payments which have to be made in each session to proceed to the next registration step. The add form provides a select box of available payment categories (`p_category`). After submitting the form, Kofa determines the total amount and sets attributes like payment item (`p_item`), payment session (`p_session`) and payment level (`p_level`) automatically. The Boolean `p_current` attribute is set ``True``. The creation datetime is stored in the `creation_date` attribute and is also used to construct the unique payment id (`p_id`).

.. note::

  Kofa always determines the total amount, including any fees charged by the school and its service providers. This is the amount which is authorized by students and finally submitted to one of the payment gateways. No fees can be added once the payment ticket is created. Payment tickets do not store any information about charged fees.


Ticket Redemption
-----------------

Directly after a student payment ticket has been paid - either by approval by an officer or by receiving a positive response from a payment gateway - the
:py:meth:`redeemTicket<waeup.kofa.students.payments.StudentOnlinePayment.redeemTicket>` method is called. Depending on the category of the payment, an appropriate access or activation code is beeing created for the owner of the ticket. This code must be entered on certain form pages to activate the paid service or to access the next stage of the registration process. In other words, making a payment and redeeming a payment are two different steps. Successful payments do not automatically trigger any action in the portal but create a specifc access code which can be used to trigger access-code-related actions (see :ref:`accesscodes`).

Until May 2015 also school fee payments had produced access codes, which enabled students to start the next session. Since software revision 12889, Kofa bypasses SFE access code creation and starts the next session automatically.


Previous Session Payment Tickets
--------------------------------

Previous session payments are additional payments which do not induce further actions in Kofa. Their sole purpose is to enable students to pay for services in previous sessions which they missed to pay. The add form for previous session payments allows the student to select the payment category, session and level by him/herself.


Balance Payment Tickets
-----------------------

Balance payments have been introduced to correct previously made payments. In some cases, students select the wrong payment category, or other things may have happened which led students pay less than expected. This can be balanced by paying a differential amount. Therefore, the add form for balance payments allows to freely choose the total amount to be paid. It also asks for the category, the session and the level the payment is meant for. Like previous session payments, balance payments do not induce further actions in Kofa. Both can be omitted in customized versions of Kofa if these features are not needed.

.. _course_registration:

Course Registration
===================

Study levels are pre-filled with course tickets. When adding a study level, :py:meth:`StudentStudyCourse.addStudentStudyLevel<waeup.kofa.students.studycourse.StudentStudyCourse.addStudentStudyLevel>` automatically adds course tickets in two steps:

1. :py:meth:`StudentStudyLevel.addCertCourseTickets<waeup.kofa.students.studylevel.StudentStudyLevel.addCertCourseTickets>` is called which iterates over the certificate courses of the certificate container object in the academic section and creates course tickets if the `level` attribute matches. `title`, `fcode`, `dcode`, `credits`, `passmark` and `semester` are copied from the course object which is attached to the certificate course; `mandatory` is taken from the certificate course itself. Finally, `automatic` is set to ``True`` and `carry_over` to ``False.``

2. The portal can be configured (`IConfigurationContainer.carry_over`) such that failed courses are automatically carried over from one session to the next. Failed course tickets from the previous level, i.e. tickets with a score below the passmark, are collected and 'copied' into the current study level container. The attributes `automatic` and `carry_over` are set to ``True``.

In most cases such an automatically created course list is not perfect or even ready for submission to the course adviser. The list must be edited according to the student's needs. Students can select further courses, which they desire to attend, and can create additional course tickets, as long as total credits do not exceed 50 (value customizable). Course tickets can also be removed. Whereas officers can remove any ticket from the list, students can remove only optional (non-mandatory) course tickets (condition customizable).

The edit form page provides a 'Register course list' button which submits the course list to the course adviser for validation. Course advisers can't edit the registered/submitted course list, but they can validate or reject it by pressing the same-named link buttons. After pressing the 'Reject courses' button, Kofa redirects to the ContactStudentForm which can be used to inform the student about the reason of rejection. In contrast to clearance rejection, the message, which is being sent to the student by email, is neither stored in the database nor in the logfiles.

.. seealso::

  :ref:`Course List Validation Doctests <test_handle_courses>`


.. _batch_editing_scores:

Batch Editing Scores by Lecturers
=================================

Lecturer cannot access student data directly. They don't have access to the student section. Instead, lecturers go to their course in the academic section and view or export lists of students who attended the course, either in a previous or in the current session. They do also see an 'Update scores' link button which opens the `EditScoresPage` if score editing is enabled for that department (`IDepartment.score_editing_disabled`) and `IConfigurationContainer.current_academic_session` has been set on the portal's configuration page. The page lists all students, who are attending the course in the current academic session. If score editing is allowed, the score can be entered at the end of the student line. Score editing is allowed if the student's current session corresponds with the current academic session and the student is in state 'courses validated', see method :py:meth:`CourseTicket.editable_by_lecturer<waeup.kofa.students.studylevel.CourseTicket.editable_by_lecturer>`

.. seealso::

  :ref:`Batch Editing Scores Doctests <test_batch_editing_scores>`


.. _requesting_new_password:

Requesting New Password
=======================


.. bed_tickets:

Bed Tickets
===========

Bed Relocation
--------------



.. _bootstrap: http://getbootstrap.com/

.. _zope schema: http://docs.zope.org/zope.schema

.. _zope formlib: http://bluebream.zope.org/doc/1.0/manual/schema.html#auto-generated-forms-using-the-forms-package