source: main/waeup.ikoba/trunk/README.txt @ 17341

What is WAeUP.Ikoba ?
*********************

Ikoba, which means 'bucket' in Bini language, is a multifunctional Application and Registration Web Portal to provide transparent and comprehensive information about application and registration processes.

Ikoba is the second flagships of the West African eUniversity Project (WAeUP) Group. See http://www.waeup.org to learn more about WAeUP.

Installation instructions can be found in the User Documentation (docs folder in the file system).


Ikoba and Kofa - Similarities and differences
---------------------------------------------

Ikoba could be described as a customer registration, document verification and contract conclusion portal. Customers are being registered (customer registration workflow), documents are being verified (document verification workflow) and contracts are being applied for and concluded (contract workflow).

Ikoba's user interface and its usability is very similar to WAeUP's Student Management System Kofa. This comprises:

- Responsive webdesign (by Bootstrap)
- User management
- Permissions and roles
- Authentication
- Portal configuration
- Data import (batch processing)
- Data export
- Logging
- Reporting
- Localization
- Mandates
- Notification and mailing
- Data tables
- etc.

But in Ikoba there are completely new content components (models), views (including pdf slips) and controlling components.


Company
-------

The main web application and container class is called 'Company' which corresponds to the university container in Kofa. The company container contains sub-containers for products, public documents, customers and officers (regular users).


Products
--------

A company offers products usually for sale. A product could be a license, a visa or any purchasable merchandise/article. In the base package a product has eight attributes, unique product id, title, contract title, contract_category, options (set of product options), valid from, valid to, terms and conditions

Products don't have a workflow.


Public Documents
----------------

Public documents are meant for publishing content on the portal. There are three types of public documents:

- PDF documents
- HTML documents
- REST documents

The first can be used to provide pdf files for download. The second and third can be used to create multilingual static html pages on the portal. HTML documents expect html coded text as input, REST documents expect reStructuredText which is transformed into html. Public documents have a publication workflow with two states: created and published. Only published documents can be seen by anonymous users.


Officers
--------

Officers are regular users or principals of the system with a set of global and local roles which allows them to view or manage the various sections in Ikoba. In contrast to classical content management systems, officers do not manage their own space where they can add and edit own content. Ikoba officers can just access those parts of the portal which their roles or sets of permissions allow them to access.

An officer has eight attributes: unique login name, title (fullname), public name, description, email address, phone number, set of roles, encrypted password

Officers can't register themselves. They have to be added by the initial system administrator or by officers who have the permission to manage user data.

Officers don't have a workflow.


Customers
---------

The term 'customer' has two different meanings in Ikoba. On the one hand a customer is a container object which contains all the documents and contracts owned by a prospective or registered client or contractor of the company. On the other hand a customer is an authenticated users or principal of the system with a user account adapted to each customer container object.

The attributes of a customer in the base package are: customer id, firstname, middlename, lastname, sex, email, phone, an encrypted password and a unique registration number which can be set by the company.

Customers have a registration workflow with four states: created, started, requested and approved. An email notification is sent after after approval or rejection of the registration.

Customer accounts can be temporarily suspended. Although suspension is not part of the workflow it does appear in the customer's workflow history.

Only approved customers can conclude contracts (see below).

Customers can register themselves. They need a valid email address for self-registration.


Customer Documents
------------------

Customers are requested to upload scanned documents and images required e.g. for the conclusion of contracts. Each uploaded file is connected with a document object which carries the metadata of the scanned document. In the base package a customer document has only a title, a unique document id and an md5 attribute. The latter contains the md5 checksum of the connected (binary) file after verification.

Documents have a verification workflow with five states: created, submitted, verified, rejected and expired.

Various document classes can be implemented and selected by the customer to make customization as flexible as possible.

Once a document has been submitted, it can no longer be edited by customers. Verified documents can neither be edited by customers nor by officers.

The md5 checksum proves the genuineness of the uploaded file.

A pdf document slip can be downloaded. The slip is composed of a covering page and the scanned document badged by a watermark.


Contracts
---------

Contracts are being concluded between the company and the customer. The customer applies for a contract by

1. selecting a proper form (= contract class),
2. selecting one of the products which belong to the contract class,
3. filling the contract form,
4. uploading required documents,
5. submitting the documents for verification,
6. linking the submitted documents on the contract form,
7. paying the contract fees,
8. submitting the contract form for approval.

A customer has to register first but must not wait for approval before s/he can add contracts. Only after registration the customer can proceed to the contracts section and add, pay and submit contracts. If documents have to be uploaded and attached to the contract, these documents must be at least submitted for verification. Otherwise they cannot be attached. This ensures that documents can't be modified after application (= submission of contracts). Thus, a new customer can register, add and submit documents and then add, pay and submit contracts in just one single session.

Company officers approve the customer registration request first, then verify the customer's documents and finally approve the contracts submitted by the customer. Approving a contract means that the contract is concluded. Contracts can also be rejected or expire.

Each contract class belongs to a contract category. The contract category defines the subset of products which can be selected when configuring the contract (see Products section above).

A contract in the base package has a title, a unique contract id, one document reference, one product reference and list of product options.  A customized contract can have several document references, but it can only refer to a single product offered by the company. The product options determine the fees to be paid before a contract can be concluded.

A contract can only be submitted if all documents attached to the contract have been at least submitted for verification. Contracts can only be approved if the customer registration request has been approved and then all attached documents have been verified by an officer.

The contract workflow has the following states: created, submitted, approved, rejected and expired. An email notification is sent after after approval or rejection of the contract conclusion request.

A pdf contract slip can be downloaded.