Dolphin Documentation, Version 1.0 (Beta)

What follows is a minimal technical documentation of Dolphin system, which will greatly help in using and understanding Dolphin system.
This document is meanly meant for programmers or advanced technical people wanting to know how it works internally. This document is heavily stressing the "data" concept, since to be able to be fully inter-operable with other systems it needs to define clear

0. Concepts and glossary

0.1 Dolphin - Why the name?

The entire dolphin project comes from the idea that we must need to have a flexible and simple system, able to be federated within multiple systems if needed. Also allowing local copies running without the need of Internet being active.
Also a well defined system for defining requirements and new implementations has been put in practice guaranteeing a quality of service and of maintainance.

0.2 Branches - The federated model (different policies for different branches/chapters)

Current Dolphin is based on the assumption that each country can define entirely the policies for entering, modifying, accessing and printing their data, defining special internal roles and also external applicable roles.
Database can be unique, but with specific usage policies, or even separated if needed.
A country can do for example the following different choices:
- Have special local fields which are not used by other countries (for instance Kitchen Use, have Pets etc),
- Have special protection on local fields which are extra-protected
- Be not accessible by other countries, or accessible only in limited way

All these kind of control can be performed by a specific "branch panel"

0.3 Open Door - The basic block

Dolphin deals with Open Doors which are essentially "addresses" or "hostlist" records. Open Doors are structured in a hierarchy of 3 levels: city - district - region/state. This should accommodate most of the normal host lists.
For each open door we keep track of the full address, and of a series of flags defining characteristics like:
year-ins, not confirmed, num hosts, children, sleep. bag, disabled welcoming, notice, type of opendoor, smoking and eating habits, youth, etc. Open Doors are essentially distinguished in HOSTS, Day Hosts, EX-
Each Open Door can be constituted by many people (see below).

0.4 People - The "living" entity

While Dolphin records Open Doors, main entities accessing and constituting dolphin are People, that are able to login to the system, and make advantage of its functionalities. Each person in a branch is given a login, a password, and is allocated to one or more "open door" entry. For each person we track information like age, contacts, role in the country and in servas, profession and interest. Some shared information can as well be put in the Open Door record. If authorized, people can modify their own data.

0.5 Administrators - The key people

Some people in servas are involved in direct managing of Open Doors in their country. According to local policies, key people (NATBOARD members, local coordinators, and helpers), they are able to do various tasks, like update members data and profiles, setting securities, managing moves, and storing administrative data.

0.6 Browsing - The main activity

Dolphin main usage will be in browsing the hostlist for each country, according to local security policies. Browsing can be done using a "search" looking for interesting people or using a hierarchical geographical tool.
Geo-tagging software (Google Maps) is used to help people in finding their way and visiting people in each country.

0.7 Standard Formats - Talking with other systems

Although not yet developed, a way for exporting-importing data into/from Dolphin is vital. To have this done we need to have at least the following flows to be defined:

- People flow (one record for each person with login/password information), and personal information
- Addresses flow (one record for each person with a field to be crossed with people).

This also will lead to have a standard for keeping a minimal and inter-operable listing of information.

1. Environment

Preference is given to Open Source languages and systems, avoiding proprietary systems like Microsoft's, but well spread web2.0 choices are taken in serious consideration, like Google Maps, Flickr, etc..

1.1 The database: MySQL

Dolphin is developed basing on an effective MySQL database, containing all the relevant tables needed for dealing with the data.

1.2 The language - Ruby on Rails (but also PHP, Java, Visual Basic)

Database is accessed via Ruby on Rails, but every other language able to access the database can be OK, namely PHP, Java or even local applications written in Visual Basic.

NB: A tiny version of Dolphin has been developed with visual basic and is using an MSAccess database. Data can be then exported/imported using Standard Formats.

1.3 The Hostlist Printing Process - pdflatex

Due to the power of this printing language, hostlists are "printed" directly from the website in pdf, using an intermediate latex layer.

2. Database (as of 1.0.5 version)

Following tables are used: alphabetical order, and only currently relevant tables are documented. Most important tables are in bold.



Currently we don't document fully each table (this will be done with more detailed documentation).

3. Functionalities and main roles

Depending on the local policies we can have the following main people roles:

• Global administrators (technicians involved in setting up and maintaining the system)
• Country administrators and helpers (people from the country or from buddy countries)
• Hosts in specific country
• Travellers in specific country
• Other viewers

3.1 Branch Creation and general permission policies (global admin)

Need to create a new country, and at least one country administrator with proper rights.

3.2 Branch Profiling and Geographical structure (Branch admin)

Need to have an at least drafted hierarchical geographical structure (cities, districts, regions/states). This will greatly help the further insertion of members. A specific panel is set up to control specific branch structure:
- special fields
- read policies
- write policies
- printing policies
- geographical naming

3.3 Inserting new People and Addresses (Branch admin)

This will be done by country admin, which will certify that each person and open door is authorized to access the system. Also specific roles should be given (Host, Traveller, Key person).

3.4 Modifying people data (Branch admin or even person)

If security policies allow this, than each person might modify their data.
Otherwise the task is to be done by country admins.

3.5 Browsing the hostlist (people)

According to local security policies, hostlist for each specified country can be browsed in a hierarchical way or with direct search, looking for people interests, addresses, names, etc..

3.6 Obtain hostlist (people or country admin)

A pdf partial hostlist can be easily obtained by the dolphin website, using branch profiling panel.

4. Minimal Example for setting up a country

4.0 Database prerequisite (see also installation)

If you are not correctly setting up these steps new country WON'T WORK.
Note you must have the following data already in tables:

- roles
INSERT INTO `roles` (`id`, `name`, `description`, `area_id`, `rolegroup_id`, `abbreviation`, `ordering`, `international`, `keylist`, `role_id`, `email`) VALUES (1, 'HOST', 'HOST', NULL, 0, 'HOST', '', '', '', NULL, ''),
(2, 'DH', 'DH', NULL, 0, 'DH', '', '', '', NULL, ''),
(3, 'TR', 'TR', NULL, 0, 'TR', '', '', '', NULL, ''),
(4, 'COORD', 'COORD', NULL, 0, 'COORD', '', '', '', NULL, ''),
(5, 'NATBOARD', 'NATBOARD', NULL, 0, 'NATBOARD', '', '', '', NULL, ''),
(6, 'EX', 'EX', NULL, 0, 'EX', '', '', '', NULL, ''),
(7, 'MS', 'Membership suspended', NULL, 0, 'MS', '', '', '', NULL, '');

- permissions
INSERT INTO `permissions` (`id`, `name`, `description`, `abbreviation`, `created_on`, `updated_on`) VALUES (1, 'RD', 'Read&Print', 'RD', '2006-11-10 15:25:16', '2006-12-01 11:19:33'),
(2, 'RDSAFE', 'Read&Print only permitted fields', 'RDSAFE', '2006-11-10 15:25:33', '2007-01-04 20:15:57'),
(3, 'MODOWN', 'Modify only own data', 'MODOWN', '2006-11-10 15:26:09', '2007-01-04 20:15:42'),
(4, 'MODREG', 'Modify regional', 'MODREG', '2006-11-10 15:26:23', '2006-12-01 11:21:38'),
(5, 'MODCOUNTRY', 'Modify country', 'MODCOUNTRY', '2006-11-10 15:26:35', '2006-12-01 11:21:11'),
(6, 'NORD', 'Only statistical data', 'NORD', '2006-11-10 15:26:49', '2006-12-01 11:15:48');

4.1 As admin, create the country

Click on "countries" on the leftbar and insert the country with proper area.

4.2 Specify policies for the new country

Go to Country Permissions and specify the following:
Country, SAME, NATBOARD, Modify Country
Country, OTHER, HOST, RD&PRINT

4.2 Create a New person in the country and give her NATBOARD rights

Go to New Member, enter address, enter Person data and give NATBOARD rights.

5. Current problems and trouble-shooting

Please refer to Dolphin people at ICT for any problems you might encounter

6. Exchange data format

Official import format recognized for importing data into Dolphin.
Import Data should be produced in YAML using a set of files or a unified file:

- addresses.txt
- people.txt


A yaml file must be generated with the following simple structure per each record (respect the initial spaces).

--- 
- !ruby/object:Opendoor 
  attributes: 

    fieldname: "value"


For the listing of fields refer to the following table: