source: main/waeup.kofa/trunk/docs/source/userdocs/applicants/browser.rst @ 13107

.. _applicant_registration:

Registration
============

The `ApplicantRegistrationPage` allows to register in create or in
update mode, depending on the
:ref:`mode of its context<application_mode>`, i.e. the applicants
container.

In create mode, `firstname`, `middlename`, `lastname`, `email` and
`phone` are requested. A new record is being created.

In update mode, only `reg_number`, `lastname` and `email` have to be
entered. Kofa searches for an applicant record with matching
registration number and lowercased lastname. If the search does not
yield a result, the flash message: 'No application record found' is
returned. The anonymous user will not know, if the registration
number does not exist or the provided lastname does not match.
Another ``if`` statement checks whether the password has already
been set and used, i.e. the the application has already been
started. If so, the anonymous user can't register again and is being
requested to proceed to the login page.

In both registration modes a randomly generated password is set and
the email address is saved. An email with login credentials is sent
to this address. Finally, the browser is redirected to a landing
page. Depending on the portals configuration, the landing page tells
the user that an email has been send to her/his mailbox, or even
discloses additionally the login credentials. The disclosure of
credentials has two substantial drawbacks: (1) The login credentials
can be misused by web crawlers for bulk account creation, which may
cause the system to crash. (2) The email address provided by the
user is not being verified and there is no guarantee that the
address belongs to the user or that a mailbox with such an address
exists. Therefore, we strongly recommend to only send credentials to
email addresses.


.. _application_form_locking:

Form Locking
============

We mentioned regular :ref:`page_locking` mechanisms. The
`ApplicantEditFormPage` has two additional locks. One is the same
named applicant attribute `locked`. Applicants can only enter the
edit page if their record is 'unlocked'. Locking and unlocking is
automatically done by workflow event handlers. By default, the
record is unlocked. Only when the applicant submits the record, it
is being locked, which means the attribute is set ``True`` and the
data can no longer be edited.

The reader may wonder why Kofa is not using the workflow state
instead. The additional locking mechanism allows officers to unlock
and lock forms without triggering workflow transitions. A transition
is always a major, and sometimes inappropriate intervention which is
also recorded in the application history.

Use case: An applicant has made a mistake and requests a change of
submitted data. An officer accepts the change, temporarily unlocks
the form to allow editing the data. Unlocking and re-locking is
logged in ``applicants.log`` but not shown on pages or the
application slip.

The second lock is induced by the application deadline. If the
application period has expired and the applicants container's
`strict_deadline` attribute is set, the applicant is also not
allowed to edit or even submit the form.

.. note::

  A locked-out applicant can still login and access the display pages
  of the recod and also download payment and application slips. To
  expell an applicant from the portal, the account has to be suspended
  by setting the same-named attribute.


.. _applicant_payment_tickets:

Payment
=======

In contrast to the students section, there is no
`PaymentsManageFormPage` to handle payment tickets separately.
Payment tickets can be viewed, added and removed directly on the
applicant manage and edit form pages. Officers can remove all
payment tickets, applicants only those without a response code
(`r_code`) and, if the form is unlocked, so that they are allowed to
edit their data.

As already mentioned in the workflow chapter, making a payment and
redeeming a payment is done in one step. When the payment was
successful or has been approved, also the applicant is automatically
set to state ``paid``. There is no need to redeem the ticket
manually.


.. _creating_students:

Creating Student Records
========================

As brought up in the :ref:`application_workflow` chapter, the final
step of the application process is the creation of the student
record on the basis of the application data. Only applicants in
state ``admitted`` can be turned into students. This is possible at
various application section levels:

1. Officers can create student records from single applicant
   records. A link button appears on the display page of each admitted
   applicants which directly triggers the creation process:

  |create_student_button|

2. The `ApplicantsContainerManageFormPage` provides a form button
   which allows to create student records from above selected
   applicants:

  |create_selected_students_button|

  Only admitted applicants will be processed. Other selected
  applicants will be skipped without further notice

3. Last but not least, the portal manager with user id ``admin``
   does see a link buttons:

  |create_students_button|

  on the `ApplicantsContainerPage` and on the `ApplicantsRootPage`
  which creates student records from applicants inside a single
  applicants container or even portal-wide respectively.

  The reader may wonder: Why only user ``admin``?

  Batch creation of thousands or even tenthousands of student records
  is very computation intensive and takes quite a long time, even with
  powerful computers. Experience has shown that the portal must be
  disconnected from the Internet in order to avoid database write
  conflict errors, which cannot be resolved if also students access
  the portal. Usually conflict errrors are not serious. Unresolved
  conflicts just lead to an error message and the database remains
  unchanged. Unfortunataly, student creation does not only alter the
  object database. As we will see below, also folders and files in the
  filesystem are added. These filesystem changes are not being
  reverted after unresolved conflicts, a fact which can cause serious
  problems.

  So the answer to the question is trivial: We expect that the admin
  user knows what s/he is doing and is careful enough to start the
  creation process in maintenance mode, which means when the portal is
  disconnected from a public network.



.. |create_student_button| image:: create_student_button.png
   :scale: 50 %

.. |create_students_button| image:: create_students_button.png
   :scale: 50 %

.. |create_selected_students_button| image:: create_selected_students_button.png
   :scale: 50 %

`Applicant.createStudent`
-------------------------

The `createStudent` method is called for each admitted applicant.
The method performs a series of checks before it creates a new
student record:

1. Is the applicant really in the correct state?

2. Has the registration number not been assigned to another student?

3. Is a certificate (`course_admitted`) provided?

4. Can all required student attributes be copied and set? The
   following attributes are copied:

   .. autoattribute:: waeup.kofa.applicants.applicant.Applicant.applicant_student_mapping
      :noindex:

5. Can the application slip can be created? Defective images may
   cause the adapter method to raise an exception (``IOError``).

If all these checks are passed, a new student record is created, a
password is set, the transitions ``create`` and ``admit`` are fired
and all student study course attributes are set. These are the
changes which affect the database.

Furthermore, `createStudent` also produces an application slip pdf
file, creates a new folder for the student in the filesystem and
copies the pdf file together with the passport jpeg image file into
the newly created folder. The copied application slip ensures, that
the original application data do not get lost, when the application
section is being purged.

As mentioned above, folder creation and file copying are not being
rolled back if the database transactions fails, e.g. due to write
conflict errors. Therefore, batch student creation should only be
performed if the portal is offline.