Index: main/waeup.kofa/trunk/docs/source/userdocs/academics.rst
===================================================================
--- main/waeup.kofa/trunk/docs/source/userdocs/academics.rst	(revision 13024)
+++ main/waeup.kofa/trunk/docs/source/userdocs/academics.rst	(revision 13025)
@@ -45,16 +45,15 @@
 .. note::
 
-  In the user handbook we do not describe how to browse the user
-  interface of Kofa. The menu navigation should be
+  In the user handbook we do not describe how to browse the
+  academic section. The menu navigation should be
   self-explanatory and it's quite easy to follow the menu
-  prompts. However, in the beginning of the development of Kofa,
-  we used extensive doc tests which describe the navigation very
-  well. Thus navigating through the academic section and other
-  parts of Kofa with a test browser is perfectly described in
-  :ref:`pages.txt <pages_txt>`.
+  prompts. However, in the beginning of the development of
+  Kofa, we used extensive doc tests which describe the
+  navigation very well. Thus navigating through the academic
+  section and other parts of Kofa with a test browser is
+  perfectly described in :ref:`pages.txt <pages_txt>`.
 
-
-Faculties
-=========
+Faculty
+=======
 
 Faculties are container objects of type `Faculty`. They have a
@@ -74,6 +73,6 @@
 
 
-Departments
-===========
+Department
+==========
 
 Additionally, each department object has the attributes
@@ -94,6 +93,6 @@
      :noindex:
 
-Courses
-=======
+Course
+======
 
 The `Course` class inherits from `grok.Model` which means it is
@@ -130,6 +129,6 @@
 
 
-Certificates
-============
+Certificate
+===========
 
 .. seealso::
@@ -164,6 +163,6 @@
 
 
-Certificate Courses
-===================
+Certificate Course
+==================
 
 `CertificateCourse` objects point to `Course` objects which means
Index: main/waeup.kofa/trunk/docs/source/userdocs/students.rst
===================================================================
--- main/waeup.kofa/trunk/docs/source/userdocs/students.rst	(revision 13024)
+++ main/waeup.kofa/trunk/docs/source/userdocs/students.rst	(revision 13025)
@@ -1,10 +1,17 @@
 .. _student_section:
 
-Student Section :sup:`in progress`
-**********************************
+Student Section
+***************
 
-'Student' is a multi-purpose term in Kofa which may lead to some misconceptions. First of all, 'Student' is a Python/Grok container class and student objects are the instances of this class. Sometimes we are sluggish when talking about 'creating students' and actually mean: 'creating student container objects and storing the objects (persistently) in the ``students`` container'. The latter is the parent container for all students in the portal.
+'Student' is a multi-purpose term in Kofa which may lead to some
+misconceptions. First of all, 'Student' is a Python/Grok container
+class and student objects are the instances of this class. Sometimes
+we are sluggish when talking about 'creating students' and actually
+mean: 'creating student container objects and storing the objects
+(persistently) in the ``students`` container'. The latter is the
+parent container for all students in the portal.
 
-The :ref:`treelike storage of objects <object_database>` in the student section can be figured as follows::
+The :ref:`treelike storage of objects <object_database>` in the
+student section can be figured as follows::
 
 
@@ -30,264 +37,36 @@
 .. note::
 
-  Throughout Kofa we distinguish singular and plural expressions. A students container contains students (or more precisely student containers), a payments container contains payments, a courses container contains courses, a certificates container contains certificates.
+  Throughout Kofa we distinguish singular and plural expressions. A
+  students container contains students (or more precisely student
+  containers), a payments container contains payments, a courses
+  container contains courses, a certificates container contains
+  certificates.
 
-Furthermore, a student is also a user of the portal and the student object is a user account surrogate, see :ref:`Applicants and Students <applicants_and_students>`. In the following we always refer to the student container when talking about a student.
+Furthermore, a student is also a user of the portal and the student
+object is a user account surrogate, see :ref:`Applicants and
+Students <applicants_and_students>`. In the following we always
+refer to the student container when talking about a student.
 
-Students
-========
+Interfaces
+==========
 
-The `Student` class is a container class which means, there are not only attributes describing the student entity but also content. Each student container contains exactly three sub-containers: ``studycourse``  (instance of `StudentStudyCourse`), ``payments`` (instance of `StudentPaymentsContainer`)  and ``accommodation`` (instance of `StudentAccommodation`). The purposes of them are described further below.
+.. toctree::
+   :maxdepth: 3
 
-Let's talk about the attributes and methods belonging to the `Student` class, the so-called 'external behaviour' of student objects specified in Zope 'interfaces'. The data stored with each student object are subdivided into three parts: base data, personal data and clearance data. Each part has its own interface.
+   students/interfaces
 
-.. _kofa_interfaces:
+Workflow & History
+==================
 
-.. note::
+.. toctree::
+   :maxdepth: 3
 
-  **Interfaces** are one of the pillars of Zope's Component Architecture (ZCA, see also :ref:`prerequisites`). They document the 'external behaviour' of objects. In Kofa interfaces are used to specify the attributes, methods and schema fields of objects. The first two are well-known Python concepts. A Zope schema field is a bit more complicated. It's a detailed description of a field to be submitted via forms to the server, or which is processed by a batch processor. In both cases the input data are being validated against the schema field requirements. In Kofa, schema fields (see also note below) in interfaces are also used to automtically add `FieldProperty` attributes of the same name to most content classes. This is done by a function :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>` which is called once during startup of Kofa. These class attributes ensure that corresponding attributes of instances of this class - when being added or changed - always meet the requirements of the schema field. Another big advantage of such class attributes is, that attributes with a `FieldProperty` do not need to be set in `__init__` methods.
+   students/workflow
 
-The `Student` class implements several interfaces which we will quote to unveil the student's 'external behaviour'.
+Browser Pages  :sup:`in progress`
+=================================
 
-`IStudentBase`
---------------
+.. toctree::
+   :maxdepth: 3
 
-`waeup.kofa.students.interfaces.IStudentBase` defines a fundamental set of attributes, schema fields and methods which are being used throughout the portal. This set is immutable. No class statement must be removed or added in customized versions of Kofa.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IStudentBase
-
-The **first part** of the interface lists attributes. Except for the last two attributes (`password` and `temp_password`) they are all read-only property attributes, i.e. attributes with a getter method only. These properties are computed dynamically and can't be set. Most of them return data derived from the ``studycourse`` subobject.
-
-The **second part** of the interface specifies the schema fields
-
-.. _kofa_schemas:
-
-.. note::
-
-  **Schema fields** are instances of schema field classes with `title`, `description`, `default`, `required`, `readonly` attributes. Class names and class attributes are self-explanatory and described in the `Zope Schema`_ documentation.
-
-  A very powerful Zope Schema field is `Choice`. Choice fields 'are constrained to values drawn from a specified set, which can be static or dynamic'. This set can be a simple list of choices (= `values`), or a `vocabulary` or `source` which produce dynamic choices.
-
-  **Vocabularies and sources** are very similar. The latter is a newer concept of producing choices and considered to replace vocabularies. In Kofa we are using both. Common to both is that a set of values is accompanied by a user-friendly title, which is displayed on pages (e.g. in select boxes) instead of a less informative value token or even a cryptic representation of a persistent value object. In most cases we have a token-title pair which perfectly describes the values of a source or a vocabulary. The tokens are being sent in forms or imported by batch processors.
-
-  See `token-title pairs <http://kofa-demo.waeup.org/sources>`_ of most (non-database-dependent) sources and vocabularies in the Kofa base package.
-
-The **third part** of the interface lists the methods which can be applied to student objects.
-
-`IUGStudentClearance`
----------------------
-
-Much like all the following student interfaces, `waeup.kofa.students.interfaces.IUGStudentClearance` describes an additional set of schema fields which are exclusively used on form pages. They do not play any role beyond that purpose. Any kind of schema field can be safely added in customized versions of these interfaces to meet the conditions of the university's matriculation process. Also `date_of_birth` and `nationality` are not used in the base package for further data processing which means, there is no dependency on these two parameters. Attention: This might be different in customized versions of Kofa. Some views might use these parameters to restrict access or make actions (e.g. payment of items) conditional on the student's nationality or current age.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IUGStudentClearance
-
-`clearance_locked` controls the access to the edit form page of clearance data. The corresponding attribute is automatically set by workflow transitions to lock or unlock the edit form page respectively. The attribute can also be set by officers via the manage form page to lock or unlock the page manually.
-
-`officer_comment` is usually edited by clearance officers when rejecting clearance previously requested by the student. The attribute contains the message which informs the student about the reasons of rejection. The attribute is cleared after final clearance. The message can be also found in ``students.log``.
-
-Both `clearance_locked` and `officer_comment` are controlled by workflow transitions not by states, see below.
-
-`IPGStudentClearance`
----------------------
-
-Most universities acquire different data from undergraduate (UG) and postgraduate (PG) students. The forms vary widely. Therefore Kofa offers a second interface for acquiring PG clearance data. In the base package `IPGStudentClearance` inherits from the `IUGStudentClearance` interface. The additional `employer` field in the base package only serves as an example.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IPGStudentClearance
-
-`IStudentPersonal`
-------------------
-
-`waeup.kofa.students.interfaces.IUGStudentPersonal` defines an additional set of personal student data which are permantly editable by students. The set usually contains further contact data and information about the student's relatives.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IStudentPersonal
-
-Kofa provides a mechanism which ensures that personal data are being kept up to date. Students are regularly requested to update the personal data directly after login. The personal data expire 180 days after saving the data for the last time which is stored in the `personal_updated` attribute. Then the `personal_data_expired` property returns ``True`` and the student is redirected to the personal data edit page when logging in.
-
-`IStudentNavigation`
---------------------
-
-See docstring.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IStudentNavigation
-
-Student Study Courses
-=====================
-
-All data related to an individual course of study are stored with the ``studycourse`` object. This container object is an instance of the `StudentStudyCourse` class which implements `waeup.kofa.students.interfaces.IStudentStudyCourse`, `waeup.kofa.students.interfaces.IStudentNavigation` and `waeup.kofa.students.interfaces.IStudentStudyCourseTranscript`. The latter does not add further behaviour to our classes but is needed for transcript pages only. It is not described in the user handbook.
-
-`IStudentStudyCourse`
----------------------
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IStudentStudyCourse
-
-All attributes are read-only property attributes which are computed dynamically.
-
-The first schema field is a `Choice` field which allows values from the `CertificateSource`. The source provides all certificates stored in the portal. This way, `StudentStudyCourse` objects point to exactly one `Certificate` object in the portal. If the certificate is removed, an event handler takes care of clearing also all referring `certificate` attribute. The tokens of the `CertificateSource` are the certicate codes which means, that in forms and import files the unique code must be given and the desired `Certificate` object will be stored.
-
-The interface has two entry parameter fields. `entry_mode` stores the study mode of the programme and `entry_session` the academic year when the study course was started. Usually these parameters are fixed and must not be changed during course of study.
-
-Very import - or even most important - are the parameters which describe the current state of the student's study course. `current_session`, `current_level`, `current_verdict`, `previous_verdict` and the student's workflow state (see below) declare precisely in which academic session and how successfully the student has reached the current study level and state in the portal. All these attributes are set automatically by the portal und must (normally) not be changed via manage form pages.
-
-What is a verdict? A verdict is the individual judgement of a jury (senate in Nigeria) at the end of each academic session. The jury's verdict tells the portal, if the student has successfully completed an academic session or not. Depending on the verdict, the student will be either allowed to proceed to the next study level or forced to repeat the current level. Without a verdict, the student gets stuck and cannot even pay school fees for the next academic year. This will be further exlplained in the workflow section below.
-
-`StudentStudyCourse` is a container class. Study courses contain `StudentStudyLevel` instances which implement `waeup.kofa.students.interfaces.IStudentStudyLevel` and also `waeup.kofa.students.interfaces.IStudentNavigation`, see above.
-
-`IStudentStudyLevel`
---------------------
-
-`StudentStudyLevel` instances contain information about the study progress achieved at that level. In Kofa study levels range from 100 to 900. There are two additional levels: a pre-studies level (10) and a special postgraduate level (999). There are also two probation levels per regular study level. Level 120, for instance, means level 100 on second probation. See `complete numbering of study levels <https://kofa-demo.waeup.org/sources#collapseStudyLevels>`_ in the base package.
-
-`StudentStudyLevel` instances are container objects which contain course tickets. We therefore sometimes speak of a level course list instead of a study level. The study level stores and provides the information when (`validation_date`) and by whom (`validated_by`) the course list was validated, in which session the level was taken (`level_session`) and which verdict the student finally obtained.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IStudentStudyLevel
-
-`StudentStudyLevel` instances also compute some statistics on the fly to give an overview of the courses taken. These read-only property attributes are: `number_of_tickets`, `passed_params`, `gpa_params`, `gpa_params_rectified`, `cumulative_params`, `total_credits` and `gpa`. The attentive reader may wonder why the latter two are not listed in the attributes section of the interface, but as read-only schema fields further below. This is a trick which we used to properly display these fields on some display pages and pdf slips. However, the `attrs_to_fields` function explicitly excludes them when starting the portal, so that these fields are not used for persistent storage of same-named attributes in the database.
-
-`ICourseTicket`
----------------
-
-Course tickets allow students to attend a course. Lecturers can enter scores at the end of the term. A `CourseTicket` instance contains a copy of the original `Course` and `CertificateCourse` data. If the courses and/or the referring certificate courses are removed, the corresponding tickets remain unchanged. So we do not need any event triggered actions on course tickets.
-
-The `CourseTicket`  implements `waeup.kofa.students.interfaces.ICourseTicket` and also `waeup.kofa.students.interfaces.IStudentNavigation`, see above.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: ICourseTicket
-
-The quite long list of schema fields pretends that form pages may provide these fields for editing. This is not the case. Except for `score`, all these fields are 'for display' only. They can neither be changed through the UI nor by batch processing (import). They are solely meant for backing up the orginal course data. See also :ref:`course_ticket_processor`.
-
-.. note::
-
-  It may happen that a course has been accidentally misconfigured, for example the number of credits was set too high. The course object can be corrected, but, course tickets, which refer to this course, can not. They are neither adjusted automatically nor changeable by the batch processor. The only solution to 'adjust' course tickets is to replace them by new tickets.
-
-Student Payments
-================
-
-`IStudentOnlinePayment`
------------------------
-
-`waeup.kofa.students.interfaces.IStudentOnlinePayment` inherits from `waeup.kofa.payments.interfaces.IOnlinePayment` and has only two additional schema fields: `p_current` and `p_level` which are student-specific. It also promises three additional methods which process student data after successful or approved payment.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IStudentOnlinePayment
-
-Student Accommodation
-=====================
-
-`IBedTicket`
-------------
-
-A bed ticket confirms that a bed space in a hostel has been allocated to the student for the period of an academic session (`booking_session`). The `bed_coordinates` specify which bed space has been booked. Sometimes this value is too cryptic and inappropriate to guide the student to the bed space. The `display_coordinates` property can be used to 'translate' the coordinates and display a customary description of the bed space. Much like some study level attributes, also `display_coordinates` is defined as a read-only schema field in order to automatically display the field on form pages. It is excluded by the `attrs_to_fields` function and thus not stored in the database.
-
-.. literalinclude:: ../../../src/waeup/kofa/students/interfaces.py
-   :pyobject: IBedTicket
-
-Registration Workflow
-=====================
-
-Studying at a higher education institution means following orchestrated and repeatable patterns of activities or, in other words, following a workflow prescribed by the school regulations. This process starts with application for studying a programme offered by the school, and may end with de-registration of a student. But even after de-registration, former students can be kept in the system as alumni so that they can still access their records or can apply for official transcripts.
-
-Kofa divides these 'repeatable patterns of activities' into two different and strictly seperated workflows: an application and a student registration workflow. The latter, which presupposes the admission of the student, will be described here.
-
-A worflow defines states and transitions between the states. The following diagram shows the entire student registration workflow. Workflow states are connected with dashed lines which symbolize workflow transitions. There are no arrows at the end of each line because in most cases, Kofa provides transitions in both directions. Transitions are denoted by lower-case characters, reverse transitions additionally by a preceded dash. A few transitions do not make sense and are thus not available (N/A)::
-
-              a
-   created ------- admitted
-              b       |
-     +----------------+
-     |                         e
-     +------------------------------------------------------+
-     |                  c                            d      |
-   clearance started ------- clearance requested  ------- cleared
-                                                            |
-                                f                           |
-     +--------+---------------------------------------------+
-     |        |
-     | h    school fee paid -------- returning -------------+
-     |        |             \   l        |                  |
-     +--------+ g            \ _ _ _ m   | k                |
-              |                      \   |                  |
-           courses registered ------ courses validated      |
-                          |      i       |                  |
-                          |              | n                |
-                          | j            |                  |
-                          |          graduated              |
-                          |              |                  |
-                          |              | o                |
-                          |              |                  |
-                          |          transcript requested   |
-     a: admit             |                                 |
-    -a: reset1            +---------------------------------+
-     b: start_clearance
-    -b: reset2
-     c: request_clearance
-    -c: reset3 (= reject request)
-     d: clear
-    -d: N/A
-     e: N/A
-    -e: reset4 (= annul clearance)
-     f: pay_first_school_fee, approve_first_school_fee
-    -f: reset5 (= annul payment)
-     g: register_courses
-    -g: reset7 (= reject request)
-     h: pay_pg_fee, approve_pg_fee
-    -h: N/A
-     i: validate_courses
-    -i: N/A
-     j: bypass_validation
-    -j: N/A
-     k: return
-    -k: reset9
-     l: pay_school_fee, approve_school_fee
-    -l: reset6 (= annul payment)
-     m: N/A
-    -m: reset8 (= annul validation)
-     n: N/A
-    -n: N/A
-     o: request_transcript
-    -o: process_transcript
-
-
-Student registration starts with the first login of the student into state ``admitted``. After filling the email adress and phone number field, and also uploading a passport picture, the student immediately proceeds with the clearance sub-workflow. S/he starts clearance **(b)** either directly or by using a clearance activation code, depending on the configuration of the portal. After filling the clearance form and uploading all necessary documents, the student requests clearance **(c)** which can be either accepted **(d)** or rejected **(-c)** by a clearance officer. A cleared student can enter the 'cyclical' part of the workflow which starts after first school fee payment **(f)**.
-
-A properly registering undergraduate student creates a new study level (course list) at the beginning of each academic session, adds the necessary course tickets and finally registers the list **(g)**. The student's course adviser subsequently validates the list **(i)**, or rejects the course registration request **(-g)** so that the student has to register again. Even after validation there is an option to annul the already validated course list **(-m)** so that the student can revise the list. At the end of the session, when all exams have been taken, course results (scores) are either entered by lecturers or imported by an import officer, a verdict is announced and the student is finally enabled to return **(k)**. In Kofa the last two steps are automatically performed by the Verdict Batch Processor. In some cases, course validators are not available or course validation is not necessary. Then validation can be skipped **(j)** by setting `bypass_validation` in the processor's import file to ``True``. In both cases the student arrives in state ``returning`` but is still in the same session. Also the current level has not changed. The new session starts only if the student pays school fee for the subsequent session **(l)**. Then `current_session` increases by one, `current_level` is set according to the verdict obtained, the old verdict is copied into `previous_verdict` and `current_verdict` is cleared. The student has arrived in the new academic session in state ``school_fee_paid``. The **gikl** cycle is repeatedly passed through till the student is ready for graduation.
-
-So far we have spoken about undergraduate students. The same sequence of transitions also applies to postgraduate students if they have to pass several levels (e.g. 700 and 800). Very often the level model does not apply to postgraduates. The students remain in the same (999) level but pay for each year of studying. In this case the gikl cycle collapses to the **h** cycle. Students may add course tickets whenever they like, but cannot register their course list.
-
-.. _workflow_batch_processing:
-
-Workflow Batch Processing
-=========================
-
-The :py:class:`StudentProcessor <waeup.kofa.students.batching.StudentProcessor>` allows to import either workflow states or transitions. As already emphasized in the description of the processor class, we refer to them as unsafe and safe respectively. Transitions are only possible between allowed workflow states. Only transitions ensure that the registration workflow is maintained. Setting the workflow state by import is considered brute and must be avoided.
-
-.. _student_history:
-
-Student History
-===============
-
-All transitions are automatically logged in ``students.log``. And also the import of workflow states is recorded in the logfile. However, these logfiles can only be accessed by some officers and are hidden from students. Since Kofa takes up the cause of transparancy, we were of the opinion, that also students must know, when and by whom the state of their record was changed. Therefore we store all workflow-relevant changes additionally in the student history which is attached to the student object. The history is a list of messages. Each message contains the local time, the workflow transition message and the public name of the user who triggered the transition, either online or by import::
-
-  2015-05-16 05:11:34 UTC - Record created by System Admin
-  2015-05-30 07:34:09 UTC - Admitted by System Admin
-  2015-05-30 08:34:11 UTC - Clearance started by John Doe
-  2015-05-30 09:34:15 UTC - Clearance requested by John Doe
-  2015-05-30 10:37:27 UTC - Cleared by Clearance Officer
-
-If the workflow state is set by import, the following message would have been added instead::
-
-  2015-05-30 10:37:27 UTC - State 'cleared' set by Import Officer
-
-Student histories are exportable but cannot be imported.
-
-
-Browser Pages
-=============
-
-
-.. _zope schema: http://docs.zope.org/zope.schema
+   students/browser
Index: main/waeup.kofa/trunk/docs/source/userdocs/students/browser.rst
===================================================================
--- main/waeup.kofa/trunk/docs/source/userdocs/students/browser.rst	(revision 13025)
+++ main/waeup.kofa/trunk/docs/source/userdocs/students/browser.rst	(revision 13025)
@@ -0,0 +1,49 @@
+.. _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. 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 classes as described above.
+
+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 pages of their record by pulling down the 'My Data' in the navigation bar.
+
+Action Buttons
+==============
+
+Managing or Editing Student Pages
+=================================
+
+Loging in as Student
+====================
+
+Rejecting Clearance
+===================
+
+Transferring Students
+=====================
+
+Adding Payment Tickets
+======================
+
+Adding Bed Tickets
+==================
+
+Bed Relocation
+==============
+
+Adding Course Tickets
+=====================
+
+Using Activation Codes
+======================
+
+Requesting a Password
+=====================
+
+Editing Scores by Lecturers
+===========================
+
+.. _bootstrap: http://getbootstrap.com/
Index: main/waeup.kofa/trunk/docs/source/userdocs/students/interfaces.rst
===================================================================
--- main/waeup.kofa/trunk/docs/source/userdocs/students/interfaces.rst	(revision 13025)
+++ main/waeup.kofa/trunk/docs/source/userdocs/students/interfaces.rst	(revision 13025)
@@ -0,0 +1,334 @@
+.. _interfaces:
+
+Student
+=======
+
+The `Student` class is a container class which means, there are not
+only attributes describing the student entity but also content. Each
+student container contains exactly three sub-containers:
+``studycourse`` (instance of `StudentStudyCourse`), ``payments``
+(instance of `StudentPaymentsContainer`) and ``accommodation``
+(instance of `StudentAccommodation`). The purposes of them are
+described further below.
+
+Let's talk about the attributes and methods belonging to the
+`Student` class, the so-called 'external behaviour' of student
+objects specified in Zope 'interfaces'. The data stored with each
+student object are subdivided into three parts: base data, personal
+data and clearance data. Each part has its own interface.
+
+.. _kofa_interfaces:
+
+.. note::
+
+  **Interfaces** are one of the pillars of Zope's Component
+  Architecture (ZCA, see also :ref:`prerequisites`). They document the
+  'external behaviour' of objects. In Kofa interfaces are used to
+  specify the attributes, methods and schema fields of objects. The
+  first two are well-known Python concepts. A Zope schema field is a
+  bit more complicated. It's a detailed description of a field to be
+  submitted via forms to the server, or which is processed by a batch
+  processor. In both cases the input data are being validated against
+  the schema field requirements. In Kofa, schema fields (see also note
+  below) in interfaces are also used to automtically add
+  `FieldProperty` attributes of the same name to most content classes.
+  This is done by a function
+  :py:func:`attrs_to_fields<waeup.kofa.utils.helpers.attrs_to_fields>`
+  which is called once during startup of Kofa. These class attributes
+  ensure that corresponding attributes of instances of this class -
+  when being added or changed - always meet the requirements of the
+  schema field. Another big advantage of such class attributes is,
+  that attributes with a `FieldProperty` do not need to be set in
+  `__init__` methods.
+
+The `Student` class implements several interfaces which we will
+quote to unveil the student's 'external behaviour'.
+
+`IStudentBase`
+--------------
+
+`waeup.kofa.students.interfaces.IStudentBase` defines a fundamental
+set of attributes, schema fields and methods which are being used
+throughout the portal. This set is immutable. No class statement
+must be removed or added in customized versions of Kofa.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentBase
+
+The **first part** of the interface lists attributes. Except for the
+last two attributes (`password` and `temp_password`) they are all
+read-only property attributes, i.e. attributes with a getter method
+only. These properties are computed dynamically and can't be set.
+Most of them return data derived from the ``studycourse`` subobject.
+
+The **second part** of the interface specifies the schema fields.
+
+.. _kofa_schemas:
+
+.. note::
+
+  **Schema fields** are instances of schema field classes with `title`,
+  `description`, `default`, `required`, `readonly` attributes. Class
+  names and class attributes are self-explanatory and described in the
+  `Zope Schema`_ documentation.
+
+  A very powerful Zope Schema field is `Choice`. Choice fields 'are
+  constrained to values drawn from a specified set, which can be
+  static or dynamic'. This set can be a simple list of choices (=
+  `values`), or a `vocabulary` or `source` which produce dynamic
+  choices.
+
+  **Vocabularies and sources** are very similar. The latter is a newer
+  concept of producing choices and considered to replace vocabularies.
+  In Kofa we are using both. Common to both is that a set of values is
+  accompanied by a user-friendly title, which is displayed on pages
+  (e.g. in select boxes) instead of a less informative value token or
+  even a cryptic representation of a persistent value object. In most
+  cases we have a token-title pair which perfectly describes the
+  values of a source or a vocabulary. The tokens are being sent in
+  forms or imported by batch processors.
+
+  See `token-title pairs <http://kofa-demo.waeup.org/sources>`_ of
+  most (non-database-dependent) sources and vocabularies in the Kofa
+  base package.
+
+The **third part** of the interface lists the methods which can be
+applied to student objects.
+
+`IUGStudentClearance`
+---------------------
+
+Much like all the following student interfaces,
+`waeup.kofa.students.interfaces.IUGStudentClearance` describes an
+additional set of schema fields which are exclusively used on form
+pages. They do not play any role beyond that purpose. Any kind of
+schema field can be safely added in customized versions of these
+interfaces to meet the conditions of the university's matriculation
+process. Also `date_of_birth` and `nationality` are not used in the
+base package for further data processing which means, there is no
+dependency on these two parameters. Attention: This might be
+different in customized versions of Kofa. Some views might use these
+parameters to restrict access or make actions (e.g. payment of items)
+conditional on the student's nationality or current age.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IUGStudentClearance
+
+`clearance_locked` controls the access to the edit form page of
+clearance data. The corresponding attribute is automatically set by
+workflow transitions to lock or unlock the edit form page
+respectively. The attribute can also be set by officers via the
+manage form page to lock or unlock the page manually.
+
+`officer_comment` is usually edited by clearance officers when
+rejecting clearance previously requested by the student. The
+attribute contains the message which informs the student about the
+reasons of rejection. The attribute is cleared after final
+clearance. The message can be also found in ``students.log``.
+
+Both `clearance_locked` and `officer_comment` are controlled by
+workflow transitions not by states, see below.
+
+`IPGStudentClearance`
+---------------------
+
+Most universities acquire different data from undergraduate (UG) and
+postgraduate (PG) students. The forms vary widely. Therefore Kofa
+offers a second interface for acquiring PG clearance data. In the
+base package `IPGStudentClearance` inherits from the
+`IUGStudentClearance` interface. The additional `employer` field in
+the base package only serves as an example.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IPGStudentClearance
+
+`IStudentPersonal`
+------------------
+
+`waeup.kofa.students.interfaces.IUGStudentPersonal` defines an
+additional set of personal student data which are permantly editable
+by students. The set usually contains further contact data and
+information about the student's relatives.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentPersonal
+
+Kofa provides a mechanism which ensures that personal data are being
+kept up to date. Students are regularly requested to update the
+personal data directly after login. The personal data expire 180
+days after saving the data for the last time which is stored in the
+`personal_updated` attribute. Then the `personal_data_expired`
+property returns ``True`` and the student is redirected to the
+personal data edit page when logging in.
+
+`IStudentNavigation`
+--------------------
+
+See docstring.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentNavigation
+
+Student Study Course
+====================
+
+All data related to an individual course of study are stored with
+the ``studycourse`` object. This container object is an instance of
+the `StudentStudyCourse` class which implements
+`waeup.kofa.students.interfaces.IStudentStudyCourse`,
+`waeup.kofa.students.interfaces.IStudentNavigation` and
+`waeup.kofa.students.interfaces.IStudentStudyCourseTranscript`. The
+latter does not add further behaviour to our classes but is needed
+for transcript pages only. It is not described in the user handbook.
+
+`IStudentStudyCourse`
+---------------------
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentStudyCourse
+
+All attributes are read-only property attributes which are computed
+dynamically.
+
+The first schema field is a `Choice` field which allows values from
+the `CertificateSource`. The source provides all certificates stored
+in the portal. This way, `StudentStudyCourse` objects point to
+exactly one `Certificate` object in the portal. If the certificate
+is removed, an event handler takes care of clearing also all
+referring `certificate` attribute. The tokens of the
+`CertificateSource` are the certicate codes which means, that in
+forms and import files the unique code must be given and the desired
+`Certificate` object will be stored.
+
+The interface has two entry parameter fields. `entry_mode` stores
+the study mode of the programme and `entry_session` the academic
+year when the study course was started. Usually these parameters are
+fixed and must not be changed during course of study.
+
+Very import - or even most important - are the parameters which
+describe the current state of the student's study course.
+`current_session`, `current_level`, `current_verdict`,
+`previous_verdict` and the student's workflow state (see below)
+declare precisely in which academic session and how successfully the
+student has reached the current study level and state in the portal.
+All these attributes are set automatically by the portal und must
+(normally) not be changed via manage form pages.
+
+What is a verdict? A verdict is the individual judgement of a jury
+(senate in Nigeria) at the end of each academic session. The jury's
+verdict tells the portal, if the student has successfully completed
+an academic session or not. Depending on the verdict, the student
+will be either allowed to proceed to the next study level or forced
+to repeat the current level. Without a verdict, the student gets
+stuck and cannot even pay school fees for the next academic year.
+This will be further exlplained in the workflow section below.
+
+`StudentStudyCourse` is a container class. Study courses contain
+`StudentStudyLevel` instances which implement
+`waeup.kofa.students.interfaces.IStudentStudyLevel` and also
+`waeup.kofa.students.interfaces.IStudentNavigation`, see above.
+
+`IStudentStudyLevel`
+--------------------
+
+`StudentStudyLevel` instances contain information about the study
+progress achieved at that level. In Kofa study levels range from 100
+to 900. There are two additional levels: a pre-studies level (10)
+and a special postgraduate level (999). There are also two probation
+levels per regular study level. Level 120, for instance, means level
+100 on second probation. See `complete numbering of study levels
+<https://kofa-demo.waeup.org/sources#collapseStudyLevels>`_ in the
+base package.
+
+`StudentStudyLevel` instances are container objects which contain
+course tickets. We therefore sometimes speak of a level course list
+instead of a study level. The study level stores and provides the
+information when (`validation_date`) and by whom (`validated_by`)
+the course list was validated, in which session the level was taken
+(`level_session`) and which verdict the student finally obtained.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentStudyLevel
+
+`StudentStudyLevel` instances also compute some statistics on the
+fly to give an overview of the courses taken. These read-only
+property attributes are: `number_of_tickets`, `passed_params`,
+`gpa_params`, `gpa_params_rectified`, `cumulative_params`,
+`total_credits` and `gpa`. The attentive reader may wonder why the
+latter two are not listed in the attributes section of the interface,
+but as read-only schema fields further below. This is a trick which
+we used to properly display these fields on some display pages and
+pdf slips. However, the `attrs_to_fields` function explicitly
+excludes them when starting the portal, so that these fields are not
+used for persistent storage of same-named attributes in the database.
+
+`ICourseTicket`
+---------------
+
+Course tickets allow students to attend a course. Lecturers can
+enter scores at the end of the term. A `CourseTicket` instance
+contains a copy of the original `Course` and `CertificateCourse`
+data. If the courses and/or the referring certificate courses are
+removed, the corresponding tickets remain unchanged. So we do not
+need any event triggered actions on course tickets.
+
+The `CourseTicket` implements
+`waeup.kofa.students.interfaces.ICourseTicket` and also
+`waeup.kofa.students.interfaces.IStudentNavigation`, see above.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: ICourseTicket
+
+The quite long list of schema fields pretends that form pages may
+provide these fields for editing. This is not the case. Except for
+`score`, all these fields are 'for display' only. They can neither
+be changed through the UI nor by batch processing (import). They are
+solely meant for backing up the orginal course data. See also
+:ref:`course_ticket_processor`.
+
+.. note::
+
+  It may happen that a course has been accidentally misconfigured, for
+  example the number of credits was set too high. The course object
+  can be corrected, but, course tickets, which refer to this course,
+  can not. They are neither adjusted automatically nor changeable by
+  the batch processor. The only solution to 'adjust' course tickets is
+  to replace them by new tickets.
+
+Student Payment
+===============
+
+`IStudentOnlinePayment`
+-----------------------
+
+`waeup.kofa.students.interfaces.IStudentOnlinePayment` inherits from
+`waeup.kofa.payments.interfaces.IOnlinePayment` and has only two
+additional schema fields: `p_current` and `p_level` which are
+student-specific. It also promises three additional methods which
+process student data after successful or approved payment.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IStudentOnlinePayment
+
+Student Accommodation
+=====================
+
+`IBedTicket`
+------------
+
+A bed ticket confirms that a bed space in a hostel has been
+allocated to the student for the period of an academic session
+(`booking_session`). The `bed_coordinates` specify which bed space
+has been booked. Sometimes this value is too cryptic and
+inappropriate to guide the student to the bed space. The
+`display_coordinates` property can be used to 'translate' the
+coordinates and display a customary description of the bed space.
+Much like some study level attributes, also `display_coordinates` is
+defined as a read-only schema field in order to automatically
+display the field on form pages. It is excluded by the
+`attrs_to_fields` function and thus not stored in the database.
+
+.. literalinclude:: ../../../../src/waeup/kofa/students/interfaces.py
+   :pyobject: IBedTicket
+
+.. _zope schema: http://docs.zope.org/zope.schema
Index: main/waeup.kofa/trunk/docs/source/userdocs/students/workflow.rst
===================================================================
--- main/waeup.kofa/trunk/docs/source/userdocs/students/workflow.rst	(revision 13025)
+++ main/waeup.kofa/trunk/docs/source/userdocs/students/workflow.rst	(revision 13025)
@@ -0,0 +1,177 @@
+.. _registration_workflow:
+
+Registration Workflow
+=====================
+
+Studying at a higher education institution means following
+orchestrated and repeatable patterns of activities or, in other
+words, following a workflow prescribed by the school regulations.
+This process starts with application for studying a programme
+offered by the school, and may end with de-registration of a
+student. But even after de-registration, former students can be kept
+in the system as alumni so that they can still access their records
+or can apply for official transcripts.
+
+Kofa divides these 'repeatable patterns of activities' into two
+different and strictly seperated workflows: an application and a
+student registration workflow. The latter, which presupposes the
+admission of the student, will be described here.
+
+A worflow defines states and transitions between the states. The
+following diagram shows the entire student registration workflow.
+Workflow states are connected with dashed lines which symbolize
+workflow transitions. There are no arrows at the end of each line
+because in most cases, Kofa provides transitions in both directions.
+Transitions are denoted by lower-case characters, reverse
+transitions additionally by a preceded dash. A few transitions do
+not make sense and are thus not available (N/A)::
+
+              a
+   created ------- admitted
+              b       |
+     +----------------+
+     |                         e
+     +------------------------------------------------------+
+     |                  c                            d      |
+   clearance started ------- clearance requested  ------- cleared
+                                                            |
+                                f                           |
+     +--------+---------------------------------------------+
+     |        |
+     | h    school fee paid -------- returning -------------+
+     |        |             \   l        |                  |
+     +--------+ g            \ _ _ _ m   | k                |
+              |                      \   |                  |
+           courses registered ------ courses validated      |
+                          |      i       |                  |
+                          |              | n                |
+                          | j            |                  |
+                          |          graduated              |
+                          |              |                  |
+                          |              | o                |
+                          |              |                  |
+                          |          transcript requested   |
+     a: admit             |                                 |
+    -a: reset1            +---------------------------------+
+     b: start_clearance
+    -b: reset2
+     c: request_clearance
+    -c: reset3 (= reject request)
+     d: clear
+    -d: N/A
+     e: N/A
+    -e: reset4 (= annul clearance)
+     f: pay_first_school_fee, approve_first_school_fee
+    -f: reset5 (= annul payment)
+     g: register_courses
+    -g: reset7 (= reject request)
+     h: pay_pg_fee, approve_pg_fee
+    -h: N/A
+     i: validate_courses
+    -i: N/A
+     j: bypass_validation
+    -j: N/A
+     k: return
+    -k: reset9
+     l: pay_school_fee, approve_school_fee
+    -l: reset6 (= annul payment)
+     m: N/A
+    -m: reset8 (= annul validation)
+     n: N/A
+    -n: N/A
+     o: request_transcript
+    -o: process_transcript
+
+
+Student registration starts with the first login of the student into
+state ``admitted``. After filling the email adress and phone number
+field, and also uploading a passport picture, the student
+immediately proceeds with the clearance sub-workflow. S/he starts
+clearance **(b)** either directly or by using a clearance activation
+code, depending on the configuration of the portal. After filling
+the clearance form and uploading all necessary documents, the
+student requests clearance **(c)** which can be either accepted **(d)
+** or rejected **(-c)** by a clearance officer. A cleared student
+can enter the 'cyclical' part of the workflow which starts after
+first school fee payment **(f)**.
+
+A properly registering undergraduate student creates a new study
+level (course list) at the beginning of each academic session, adds
+the necessary course tickets and finally registers the list **(g)**.
+The student's course adviser subsequently validates the list **(i)**,
+ or rejects the course registration request **(-g)** so that the
+student has to register again. Even after validation there is an
+option to annul the already validated course list **(-m)** so that
+the student can revise the list. At the end of the session, when all
+exams have been taken, course results (scores) are either entered by
+lecturers or imported by an import officer, a verdict is announced
+and the student is finally enabled to return **(k)**. In Kofa the
+last two steps are automatically performed by the Verdict Batch
+Processor. In some cases, course validators are not available or
+course validation is not necessary. Then validation can be skipped
+**(j)** by setting `bypass_validation` in the processor's import
+file to ``True``. In both cases the student arrives in state
+``returning`` but is still in the same session. Also the current
+level has not changed. The new session starts only if the student
+pays school fee for the subsequent session **(l)**. Then
+`current_session` increases by one, `current_level` is set according
+to the verdict obtained, the old verdict is copied into
+`previous_verdict` and `current_verdict` is cleared. The student has
+arrived in the new academic session in state ``school_fee_paid``.
+The **gikl** cycle is repeatedly passed through till the student is
+ready for graduation.
+
+So far we have spoken about undergraduate students. The same
+sequence of transitions also applies to postgraduate students if
+they have to pass several levels (e.g. 700 and 800). Very often the
+level model does not apply to postgraduates. The students remain in
+the same (999) level but pay for each year of studying. In this case
+the **gikl** cycle collapses to the **h** cycle. Students may add
+course tickets whenever they like, but cannot register their course
+list.
+
+
+.. _workflow_batch_processing:
+
+Workflow Batch Processing
+=========================
+
+The :py:class:`StudentProcessor
+<waeup.kofa.students.batching.StudentProcessor>` allows to import
+either workflow states or transitions. As already emphasized in the
+description of the processor class, we refer to them as unsafe and
+safe respectively. Transitions are only possible between allowed
+workflow states. Only transitions ensure that the registration
+workflow is maintained. Setting the workflow state by import is
+considered brute and must be avoided.
+
+
+.. _student_history:
+
+Student History
+===============
+
+All transitions are automatically logged in ``students.log``. And
+also the import of workflow states is recorded in the logfile.
+However, these logfiles can only be accessed by some officers and
+are hidden from students. Since Kofa takes up the cause of
+transparancy, we were of the opinion, that also students must know,
+when and by whom the state of their record was changed. Therefore we
+store all workflow-relevant changes additionally in the student
+history which is attached to the student object. The history is a
+list of messages. Each message contains the local time, the workflow
+transition message and the public name of the user who triggered the
+transition, either online or by import::
+
+  2015-05-16 05:11:34 UTC - Record created by System Admin
+  2015-05-30 07:34:09 UTC - Admitted by System Admin
+  2015-05-30 08:34:11 UTC - Clearance started by John Doe
+  2015-05-30 09:34:15 UTC - Clearance requested by John Doe
+  2015-05-30 10:37:27 UTC - Cleared by Clearance Officer
+
+If the workflow state is set by import, the following message would
+have been added instead::
+
+  2015-05-30 10:37:27 UTC - State 'cleared' set by Import Officer
+
+Student histories are exportable but cannot be imported.
