Index: main/waeup.kofa/trunk/docs/source/userdocs/datacenter/logging.rst
===================================================================
--- main/waeup.kofa/trunk/docs/source/userdocs/datacenter/logging.rst	(revision 12893)
+++ main/waeup.kofa/trunk/docs/source/userdocs/datacenter/logging.rst	(revision 12894)
@@ -4,5 +4,7 @@
 ********
 
-Kofa is logging actions, which cause changes to the database or the filesystem, in separate human-redable event logfiles. Nearly all actions are being logged, except those committed by applicants and students during registration periods. During these data initialization periods, applicants and students are requested to edit many fields and upload heaps of scanned documents. Logging all these changes would mean filling the logfiles with more or less useless or redundant information. The main purpose of Kofa's logging facilities is to trace changes effected by portal officers. Applicants and students can only access their own data. They don't have the permission to change anything else. Whereas portal officers bear responsibility for the integrity of the whole database. Depending on the roles they have, officers can add, edit or remove application and study data without leaving a trace in the object database itself. Kofa closes this security gap by recording nearly all actions of portal officers into various event logfiles.
+Kofa is logging actions, which cause changes to the database or the filesystem, in separate human-redable event logfiles. Nearly all actions are being logged, except some actions committed by applicants and students during registration periods. During these data initialization periods, applicants and students are requested to edit many fields. Usually they press the 'Save' button quite often to backup the data entered so far. Logging all these changes would mean filling the logfiles with more or less useless or redundant information.
+
+The main purpose of Kofa's logging facilities is to trace changes effected by portal officers. Applicants and students can only access their own data. They don't have the permission to change anything else. Whereas portal officers bear responsibility for the integrity of the whole database. Depending on the roles they have, officers can add, edit or remove application and study data without leaving a trace in the object database itself. Kofa closes this security gap by recording nearly all actions of portal officers into various event logfiles.
 
 .. note::
@@ -117,12 +119,94 @@
 ============
 
+The following example shows a typical Nigerian logfile excerpt for a student from the very beginning (student record creation from application data) till the first registration of courses at level 100. Such an excerpt can be produced simply by searching for ``B1234567`` on the ``students.log`` search page::
+
+  2014-12-11 10:21:21,930 - INFO - admin - B1234567 - Record created
+  2014-12-11 10:21:21,935 - INFO - admin - B1234567 - Admitted
+  2014-12-19 05:53:02,760 - INFO - admin - Student Processor - physical_clearance_date_adm - B1234567 - updated: reg_number=12345678AB, physical_clearance_date=FRIDAY 9TH JANUARY 2015
+  2014-12-22 14:16:50,494 - INFO - B1234567 - waeup.kofa.students.browser.OnlinePaymentAddFormPage - B1234567 - added: p4192542104720
+  2014-12-22 14:51:36,959 - INFO - B1234567 - waeup.kofa.interswitch.browser.InterswitchPaymentRequestWebservicePageStudent - B1234567 - valid callback for clearance payment p4192542104720: 00:Approved Successful:4500000:5964:p4192542104720:FBN|WEB|UNIBEN|22-12-2014|02345:000382768769
+  2014-12-22 14:51:36,985 - INFO - B1234567 - waeup.kofa.interswitch.browser.InterswitchPaymentRequestWebservicePageStudent - B1234567 - successful clearance payment: p4192542104720
+  2014-12-22 14:53:09,148 - INFO - B1234567 - B1234567 - Clearance started
+  2014-12-22 14:53:39,983 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: birth_certificate.jpg (birth.JPG)
+  2014-12-22 14:53:54,482 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: acc_let.jpg (acceptance.JPG)
+  2014-12-22 14:54:08,943 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: lga_ident.jpg (LGA.JPG)
+  2014-12-22 14:54:23,541 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: fst_sit_scan.jpg (waec.JPG)
+  2014-12-22 14:54:56,663 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: ref_let.jpg (guarantor.JPG)
+  2014-12-22 14:56:16,039 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: stat_dec.jpg (good.JPG)
+  2014-12-22 14:56:37,895 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: jamb_letter.jpg (JAMB.JPG)
+  2014-12-22 14:56:54,696 - INFO - B1234567 - waeup.kofa.students.browser.StudentClearanceEditFormPage - B1234567 - uploaded: secr_cults.jpg (cult.JPG)
+  2014-12-22 15:02:42,550 - INFO - B1234567 - B1234567 - Clearance requested
+  2015-01-17 11:58:12,643 - INFO - clearanceofficer - B1234567 - Cleared
+  2015-03-10 10:58:46,217 - INFO - B1234567 - waeup.kofa.students.browser.OnlinePaymentAddFormPage - B1234567 - added: p4259815262042
+  2015-03-13 11:38:21,658 - INFO - B1234567 - waeup.kofa.interswitch.browser.InterswitchPaymentRequestWebservicePageStudent - B1234567 - valid callback for schoolfee payment p4259815262042: 00:Approved Successful:4950000:2022:p4259815262042:GTB|WEB|UNIBEN|13-03-2015|001234:0001234566
+  2015-03-13 11:38:22,016 - INFO - B1234567 - waeup.kofa.interswitch.browser.InterswitchPaymentRequestWebservicePageStudent - B1234567 - successful schoolfee payment: p4259815262042
+  2015-03-16 13:01:09,989 - INFO - B1234567 - B1234567 - First school fee payment made
+  2015-03-16 13:03:50,977 - INFO - B1234567 - waeup.kofa.students.browser.StudyLevelEditFormPage - B1234567 - added: PHY124|100|2014
+  2015-03-16 13:05:04,504 - INFO - B1234567 - B1234567 - Courses registered
+  2015-03-28 07:18:21,846 - INFO - admin - Student Processor - Matno_for_upload_25_03_2015-1_admin - B1234567 - updated: student_id=B1234567, matric_number=LSC123456
+
+The log entry format of transactions due to imports is slightly different::
+
+  2015-04-30 08:40:51,088 - INFO - admin - Student Processor - studentcreate_admin - B3333333 - updated: state=returning, reg_number=BIA12326, firstname=FRIDAY, middlename=None, lastname=Olonko, sex=m, nationality=NG, matric_number=SSC4444444
+  2015-04-30 08:41:27,179 - INFO - admin - StudentStudyCourse Processor (update only) - studycourseaupdate_admin - B3333333 - updated: entry_mode=ug_pt, certificate=BIA, current_session=2002, entry_session=2002, current_level=100, current_verdict=Z
+
+Two files had been uploaded by admin (``studentcreate.csv`` and ``studycourseaupdate.csv``, see entries in ``datacenter.log``) and subsequently imported with the Student Processor and Student Study Course Processor respectively.
+
+As already stated above, not all actions committed by students are beeing logged. The student did not only upload a lot of files but also edited dozens of fields on the clearance form page and probably pressed the 'Save' button very often to backup the data entered so far. These backup transactions were skipped. All other transactions are being recorded. Some examples of further logfile records are listed below.
+
+Setting a temporary password::
+
+  2012-10-20 20:59:28,392 - INFO - admin - students.browser.LoginAsStudentStep1 - W4444444 - temp_password generated: Paa3ZVrV
+
+Deactivating and re-activating students::
+
+  2014-11-15 14:28:49,859 - INFO - admin - students.browser.StudentDeactivatePage - W1111111 - account deactivated
+  2014-11-17 10:19:05,735 - INFO - admin - students.browser.StudentActivatePage - W1111111 - account activated
+
+Rejection of clearance requests (an email is sent and the body of the email is stored as comment in the logfile)::
+
+  2014-10-27 12:39:34,499 - INFO - clearanceofficer - students.browser.StudentRejectClearancePage - W2222222 - comment: no credit in english
+
+Approval of payment tickets (which does not automatically goes along with a student workflow transition)::
+
+  2012-11-02 12:01:03,022 - INFO - admin - students.browser.OnlinePaymentApprovePage - W1000000 - schoolfee payment approved: p3517158705027
+
+Bed allocation and re-allocation::
+
+  2012-11-07 12:56:26,745 - INFO - W1000000 - waeup.kwarapoly.students.browser.BedTicketAddPage - W1000000 - booked: white-house_W_106_B
+  2013-10-29 11:49:55,048 - INFO - hostelofficer - students.browser.BedTicketRelocationPage - W1000000 - relocated: block-a-upper-hostel_A_118_E
+
+Password changes by students::
+
+  2013-02-19 08:54:50,177 - INFO - K9999999 - students.browser.StudentChangePasswordPage - K9999999 - saved: password
+
 
 payments.log
 ============
 
+This file is hidden and can only be accessed directly in the filesystem. The payment logger is not needed in the Kofa base package. Only `OnlinePaymentApprovePage.update()` writes into the ``payments.log`` file. The logger is primarily intended for storing information about successfull financial transactions via external payment gateways (e.g. PayPal, Interswitch, eTranzact). No external payment gateway module is configured in the base package.
+
 
 hostels.log
 ===========
 
+Whereas the reservation/allocation of bed spaces is being logged in ``students.log`` (see above), the management of hostels and beds is recorded in ``hostels.log``::
+
+  2015-04-30 11:44:29,145 - INFO - admin - hostels.browser.HostelAddFormPage - hostels - added: Hall 1
+  2015-04-30 11:45:29,283 - INFO - admin - hostels.browser.HostelManageFormPage - hall-1 - saved: rooms_per_floor + blocks_for_female
+  2015-04-30 11:46:29,330 - INFO - admin - hostels.browser.HostelManageFormPage - hall-1 - 0 empty beds removed, 10 beds added, 0 occupied beds modified ()
+  2015-04-30 11:47:29,433 - INFO - admin - hostels.browser.HostelManageFormPage - hall-1 - switched: hall-1_A_101_A (reserved), hall-1_A_101_B (reserved), hall-1_A_101_C (reserved), hall-1_A_101_D (reserved)
+  2015-04-30 11:47:59,283 - INFO - admin - hostels.browser.HostelManageFormPage - hall-1 - saved: beds_for_fresh + beds_for_all
+  2015-04-30 11:48:29,498 - INFO - admin - hostels.browser.HostelManageFormPage - hall-1 - 9 empty beds removed, 9 beds added, 1 occupied beds modified (hall-1_A_101_E, )
+  2015-04-30 11:49:29,560 - INFO - admin - hostels.browser.HostelManageFormPage - hall-1 - switched: hall-1_A_101_A (unreserved), hall-1_A_101_B (unreserved), hall-1_A_101_C (unreserved), hall-1_A_101_D (unreserved)
+  2015-04-30 11:50:29,689 - INFO - admin - hostels.browser.HostelManageFormPage - hall-1 - released: hall-1_A_101_D (K1000000)
+  2015-04-30 11:51:29,898 - INFO - admin - hostels.browser.BedManageFormPage - hall-1_A_101_A - saved: owner
+  2015-04-30 11:54:30,163 - INFO - admin - hostels.browser.HostelsContainerManagePage - hostels - deleted: hall-1
+
+In this example, the hostel ``Hall 1`` was added and configured, beds were updated, beds were reserved (switched), the hostel configuration was changed, beds were updated again, beds were unreserved, a single bed was released, a new student was allocated and, finally, the entire hostel was removed.
+
+Also all transactions of the Hostel Processor are being logged::
+
+  2015-04-30 11:51:12,840 - INFO - system - Hostel Processor - sample_hostel_data - hall-b - updated: beds_for_pre=['F'], floors_per_block=1, beds_for_final=['A', 'B'], rooms_per_floor=44, blocks_for_male=['C', 'D'], hostel_id=hall-b, sort_id=100, beds_for_returning=['C'], hostel_name=Hall B, beds_for_fresh=['D', 'E'], blocks_for_female=[], beds_for_all=[], beds_reserved=[]
 
 
