CSC/ECE 517 Spring 2014/oss S1402 jyy: Difference between revisions

From Expertiza_Wiki
Jump to navigation Jump to search
(Created page with "This project is developed as a contribution to Sahana Software Foundation (Eden). right = Background = Sahana Eden is an open source software project that ...")
 
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[File:sahana.jpg|right]]
This project is developed as a contribution to Sahana Software Foundation (Eden).
This project is developed as a contribution to Sahana Software Foundation (Eden).
[[File:sahana.jpg|right]]


= Background =


Sahana Eden is an open source software project that provides effective solutions for critical humanitarian needs management either prior to or during a crisis (mainly disasters). This platform has a rich feature set which can be rapidly customized to adapt to existing process and integrate with existing systems.   
== Background ==
 
Sahana Eden is an open source software project that provides effective solutions for critical humanitarian needs management either prior to or during a crisis (mainly disasters).<ref>http://sahanafoundation.org/products/eden/</ref> This platform has a rich feature set which can be rapidly customized to adapt to existing process and integrate with existing systems.   


Sahana Eden’s features are designed to help emergency management practitioners to better mitigate, prepare for, respond to and recover from disasters more effectively and efficiently. With this logistic software, strategic planning and the deployment of efforts of human resources and supplies to victims is handled in an efficient manner. It coordinates the information of all the components required to relieve in some way the pain of the affected victims.
Sahana Eden’s features are designed to help emergency management practitioners to better mitigate, prepare for, respond to and recover from disasters more effectively and efficiently. With this logistic software, strategic planning and the deployment of efforts of human resources and supplies to victims is handled in an efficient manner. It coordinates the information of all the components required to relieve in some way the pain of the affected victims.


Sahana Eden is supported by Sahana Software Foundation whose mission it to save lives by providing information management solutions that enable organizations and communities to better prepare for and respond to disasters. This is a voluntary community consisted of disaster management practitioners, academics, companies and students.   
Sahana Eden is supported by Sahana Software Foundation<ref>http://sahanafoundation.org/about-us/</ref> whose mission it to save lives by providing information management solutions that enable organizations and communities to better prepare for and respond to disasters. This is a voluntary community consisted of disaster management practitioners, academics, companies and students.   


= Motivation =
== Motivation ==


Sahana Eden provides a wide range of functionalities.  Its main capabilities include organization registry, project tracking, human resources management, inventory&assets tracking, assessments, shelter management, scenario&events planning, gis mapping, messaging, etc.  
Sahana Eden provides a wide range of functionality.  Its main capabilities include organization registry, project tracking, human resources management, inventory&assets tracking, assessments, shelter management, scenario&events planning, GIS mapping, messaging, etc.  


Among all the features, inventory tracking keep records of shipments; supports multiple catalogs of items; and allow organization to manage requests, donations and warehouse. However, we found that the systems does not have place where we can track some “Drop Off Sites” for collection of supplies in minor disasters or during our daily life. These drop off sites can  convenience stores, supermarket, hospitals, etc. People can donate supplies to one of these sites which might be most convenient for them and the organizations then can collect useful goods themselves. After talking with one of the managers from Sahana Software Foundation, we decide to add this new feature to the system.
Among all the features, inventory tracking keep records of shipments; supports multiple catalogs of items; and allow organization to manage requests, donations and warehouse. However, we found that the systems does not have place where we can track some “Drop Off Sites” for collection of supplies in minor disasters or during our daily life. These drop off sites can  convenience stores, supermarket, hospitals, etc. People can donate supplies to one of these sites which might be most convenient for them and the organizations then can collect useful goods themselves. After talking with one of the managers from Sahana Software Foundation, we decide to add this new feature to the system.


= Technique Overview =  
== Technique Overview ==  


The basic Sahana Eden architecture is as follows:
The basic Sahana Eden architecture is as follows:
{| border="1" class="wikitable"
|-
! Web Server
|  Apache || Other web servers can also be used, such as Cherokee.
|-
! Application
| Sahana Eden ||
|-
! Web Framework
| Web2py ||
|-
! Programming Language
| Python & Java Script ||
|-
! Database
| MySQL, PostgreSQL, or SQLite || MySQL, PostgreSQL, and SQLite are supported. Other databases should be usable without major additional work since Web2Py supplies many connectors.
|-
! Operating System
| Linux (Debian recommended) || Windows and Mac OS X are possible, but only recommended for single-user environments.
|}
=== Web2py ===
Web2py<ref>http://www.infoworld.com/d/application-development/pillars-python-six-python-web-frameworks-compared-169442</ref> is an open source framework, licensed under the LGPL version 3 License,  developed and interpreted with the Python language and agile concept development that follows good software engineering practices.  It is based on the [http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller Model View Controller(MVC)]  pattern.  It also includes a Database Abstraction Layer (DAL) that writes SQL dynamically so the communication between the application and any database will be transparent.  Since this framework includes various options in security, data access control, input validation on forms, it is been said that is built for security, because the framework addresses many of these issues.
Because Sahana Eden needs to be accessible to users at remote locations, including the public, a browser-based solution was essential. The system also needs to be able to be used on offline laptops, so it needs to run on a lightweight stack.
Python<ref>https://www.python.org/</ref> was selected as a suitable high level language allowing the rapid customization of code required for each individual circumstance yet has a large number of powerful libraries available including for Geo-spatial Information Systems (GIS).<ref>http://www.gis.usu.edu/~chrisg/python/2009/</ref>
=== S3 Framework ===
The Sahana Eden Software Platform(S3) has been built around a Rapid Application Development (RAD) Framework.<ref>http://en.flossmanuals.net/sahana-eden/technical-overview/</ref> This provides a high level of automation to ensure that new solutions can be quickly and effectively developed. Once a database table is defined, the Sahana Eden Framework automatically generates HTML pages to handle CRUD (Create, Read, Update, Delete) as well as Search, Map and Pivot Reports. Web Services are available to import and export in XML, CSV, JSON and EXtensible Stylesheet Language (XSL) transforms are supported to produce other data standards.
The Sahana Eden Framework has flexible authorization policies which can be configured to grant permissions for different modules, tables as well as the ability to have multiple Organizations control their own data on a single Sahana Eden installation.
== Design ==
=== Database ===
This is a basic relation established on the system between the place and the contact for the drop off site. An organization to each drop off sites, and one organization can have different representative for each site. Both of them are many-to-one relationship<ref>http://en.wikipedia.org/wiki/Relational_database</ref>. A dropOffSite table has six attributes: name, flyer, comments, startTime and endTime which indicates the time period the site will be open for donation, and personId as a foreign key to person table.
[[File:SahanaER.png]]
=== Framework ===
In order to add the capability to manage drop off sites information from within the Sahana Eden instance, we have two options: installing a separate package, or integrating this into the Sahana Eden instance. We have decided to use the latter so that :
* We don’t need to define data, like users, locations, organizations, in multiple systems.
* We can use Sahana Eden’s messaging and mapping capabilities for the drop off sites in the future.
* The organization module can use drop off sites records of personnel.
=== Design Pattern ===
We have taken two design patterns into consider during our development.
* '''Factory Methods'''
In the controller, we return an s3_rest_controller() method, this  function provides all the Sahana Eden framework support needed to access the resource, including automatic loading of the respective model definitions. With this method, we can have a working module and be able to see the CRUD (Create, Read, Update, Delete) user interface. We could define our own methods to do CRUD of drop off site module. In that case, the code will violate DRY principle. If all contributors to Sahana have done the CRUD themselves, there will be a lot of duplication and the readability of the system will decrease. However, we can replace the deault strings within the CRUD user interface with custom strings. To be specific, we use crud_strings() method in S3 framework to do customizations.
<pre>
def course():
    return s3_rest_controller()
</pre>
* '''Oberserver'''
Observer pattern is widely used in GUI systems. By the nature of Model-View-Controller(MVC) architecture, the observer pattern is used to decouple the model from the view. View represents the Observer and the model is the Observable object. This kind of framework can be enhanced in future with new observers with minimal changes.
=== Component ===
As shown above, we'd like to be able to record information relating to staff in each drop off site, such as how long they will be there and contact number etc. To do this, we need to build a 'link' table between the person and the drop off site. The natural way to do this within Sahana Eden is to make the link table a 'component' of the drop off site table. The drop off site is the 'primary resource', and contact person are a 'component' of the course.
To realize the 'component' feature. First, we add a 'represent' function to allow a record in the drop off site table to be represented by its name.
<pre>
def place_represent(id):
    table = db.dosite_place
    query = (table.id == id)
    record = db(query).select().first()
    if record:
        return record.name
    else:
        return "-"
</pre>
This code involves using Web2Py's Database Abstraction Layer (DAL) to do a SQL query.The variable db is an instance of the DAL class, which represents a database. Queries are written in a syntax that is much like a Python expression.
Then, we define a 'reusable field' which can be added to other table definitions to provide a foreign key reference to the drop off site table.
<pre>
place_id = S3ReusableField("place_id", db.dosite_place,
                    requires = IS_ONE_OF(db,
                                    "dosite_place.id",
                                    "%(name)s"),
                    represent = place_represent,
                    label = T("Place"),
                    ondelete = "RESTRICT")
</pre>
Note that this uses the represent function which we just defined. It also adds a 'requires' validator function. This provides both server-side validation and a client-side widget (in this case a dropdown of records in the drop off site table).
As to the controller, we don't need to create a separate REST controller to manage the component, since it will always be accessed via the existing drop off site controller, however we must then extend the controller with 2 new elements to allow the Sahana Eden framework to display the component: 'tabs' and an 'rheader'. Tabs are how the framework provides access to the different components in a web page for the primary resource. The 'resource header' is a section of HTML that provides a summary of the primary resource record, in this case the drop off site. This is displayed above the tabs so that when each component record is being viewed, its parent record is also visible at the same time.
We can simply add the following code into the controller model. Here, rheader is simply a variable passed through the REST controller unaltered & then serialized as rheader.xml() in the views.
<pre>
def place_rheader(r, tabs=[]):
    if r.representation != "html":
        # RHeader is a UI facility & so skip for other formats
        return None
    if r.record is None:
        # List or Create form: rheader makes no sense here
        return None
    rheader_tabs = s3_rheader_tabs(r, tabs)
    place = r.record
    rheader = DIV(TABLE(
        TR(
            TH("%s: " % T("Name")),
            place.name,
            TH("%s: " % T("Start Date")),
            place.start_date,
            )
        ), rheader_tabs)
    return rheader
</pre>
== Implementation ==
* Define dropOtffSite table in our new models and its relationship with person table and organization table.
<pre>
tablename = "dosite_place"
table = db.define_table(tablename,
            Field("name", notnull=True, length=64, label=T("Place Name")),
            s3db.pr_person_id(label=T("Place Contact")),
            Field("flyer", "upload",label=T("Flyer Propaganda")),
            s3_comments(),
            s3base.s3_date("start_date",label="Collection Start Date"),
            s3base.s3_date("end_date",label="Collection End Date"),
            *s3_meta_fields()
        )
</pre>
* Add editable features to the the Drop Off Site list.
<pre>
LIST_PLACE =  T("List Drop-Off Sites")
s3.crud_strings[tablename] = Storage(
  title_create = T("Add New Place"),
  title_display = T("Place Details"),
  title_list = LIST_PLACE,
  title_update = T("Edit Place"),
  title_search = T("Search Place"),
  title_upload = T("Import Place"),
  subtitle_create = T("Add New Place"),
  subtitle_list = T("Place"),
  label_list_button = LIST_PLACE,
  label_create_button = T("Add New Place"),
  label_delete_button = T("Delete Place"),
  msg_record_created = T("Place added"),
  msg_record_modified = T("Place updated"),
  msg_record_deleted = T("Place deleted"),
  msg_list_empty = T("No Place currently registered"))
</pre>
* Customized the view in controller so that it fits Sahana Eden's standard.
<pre>
def place():
    return s3_rest_controller(rheader=place_rheader)
</pre>
== Deliverables ==
The application can be accessed with the following link: [http://152.46.16.162/eden Sahana Eden Site]
We go through one use case to see how the system handles a drop off site information collection.
*Accessing "DropOff Site" from the main menu
[[File:Ss1.png]]
* After click on the menu, we will see a welcome page first. This page gives users a brief introduction of what is drop off site and how does it works.
[[File:Ss2.png]]
* Click on "list of drop off site" link, we'll see a list of drop off sites with their detail information. Then we can add a new record by clicking the button "Adding a Record".
[[File:Ss3.png]]
* Fill in the table with detail. Notice that here when you fill in the person name, you can look up their name by enter part of their name.
[[File:Ss4.png]]]
* After successfully add a new record, we can go back to see the new drop off site information.
[[File:Ss5.png]]
== Future Work ==
Based on the information we have now for Drop Off Site. We plan to add a location attribute to this table so that we can map this location information to mapping feature of Sahana.
Sahana has a fully integrated mapping functionality which allows any location-based data to be visualized on a map. What we can do is to add a layer on the map. When user want to view drop off site information, one can select "Drop off sites" label besides the map, then he will see some marked location on map which indicates available sites. When we click on these marked places, information about the sites, including detailed address and contact number will be available for users in a small text field.
== Further Reading ==
* [http://web2py.com/init/default/documentation Web2py]
* [http://diveintopython.org/ Python]
* [http://docs.jquery.com/ Jquery]
* [http://docs.sencha.com/ext-js/3-4/ Ext_JS 3.4.0]
= Reference =
<references/>
---

Latest revision as of 04:31, 7 April 2014

This project is developed as a contribution to Sahana Software Foundation (Eden).


Background

Sahana Eden is an open source software project that provides effective solutions for critical humanitarian needs management either prior to or during a crisis (mainly disasters).<ref>http://sahanafoundation.org/products/eden/</ref> This platform has a rich feature set which can be rapidly customized to adapt to existing process and integrate with existing systems.

Sahana Eden’s features are designed to help emergency management practitioners to better mitigate, prepare for, respond to and recover from disasters more effectively and efficiently. With this logistic software, strategic planning and the deployment of efforts of human resources and supplies to victims is handled in an efficient manner. It coordinates the information of all the components required to relieve in some way the pain of the affected victims.

Sahana Eden is supported by Sahana Software Foundation<ref>http://sahanafoundation.org/about-us/</ref> whose mission it to save lives by providing information management solutions that enable organizations and communities to better prepare for and respond to disasters. This is a voluntary community consisted of disaster management practitioners, academics, companies and students.

Motivation

Sahana Eden provides a wide range of functionality. Its main capabilities include organization registry, project tracking, human resources management, inventory&assets tracking, assessments, shelter management, scenario&events planning, GIS mapping, messaging, etc.

Among all the features, inventory tracking keep records of shipments; supports multiple catalogs of items; and allow organization to manage requests, donations and warehouse. However, we found that the systems does not have place where we can track some “Drop Off Sites” for collection of supplies in minor disasters or during our daily life. These drop off sites can convenience stores, supermarket, hospitals, etc. People can donate supplies to one of these sites which might be most convenient for them and the organizations then can collect useful goods themselves. After talking with one of the managers from Sahana Software Foundation, we decide to add this new feature to the system.

Technique Overview

The basic Sahana Eden architecture is as follows:

Web Server Apache Other web servers can also be used, such as Cherokee.
Application Sahana Eden
Web Framework Web2py
Programming Language Python & Java Script
Database MySQL, PostgreSQL, or SQLite MySQL, PostgreSQL, and SQLite are supported. Other databases should be usable without major additional work since Web2Py supplies many connectors.
Operating System Linux (Debian recommended) Windows and Mac OS X are possible, but only recommended for single-user environments.

Web2py

Web2py<ref>http://www.infoworld.com/d/application-development/pillars-python-six-python-web-frameworks-compared-169442</ref> is an open source framework, licensed under the LGPL version 3 License, developed and interpreted with the Python language and agile concept development that follows good software engineering practices. It is based on the Model View Controller(MVC) pattern. It also includes a Database Abstraction Layer (DAL) that writes SQL dynamically so the communication between the application and any database will be transparent. Since this framework includes various options in security, data access control, input validation on forms, it is been said that is built for security, because the framework addresses many of these issues.

Because Sahana Eden needs to be accessible to users at remote locations, including the public, a browser-based solution was essential. The system also needs to be able to be used on offline laptops, so it needs to run on a lightweight stack.

Python<ref>https://www.python.org/</ref> was selected as a suitable high level language allowing the rapid customization of code required for each individual circumstance yet has a large number of powerful libraries available including for Geo-spatial Information Systems (GIS).<ref>http://www.gis.usu.edu/~chrisg/python/2009/</ref>

S3 Framework

The Sahana Eden Software Platform(S3) has been built around a Rapid Application Development (RAD) Framework.<ref>http://en.flossmanuals.net/sahana-eden/technical-overview/</ref> This provides a high level of automation to ensure that new solutions can be quickly and effectively developed. Once a database table is defined, the Sahana Eden Framework automatically generates HTML pages to handle CRUD (Create, Read, Update, Delete) as well as Search, Map and Pivot Reports. Web Services are available to import and export in XML, CSV, JSON and EXtensible Stylesheet Language (XSL) transforms are supported to produce other data standards.

The Sahana Eden Framework has flexible authorization policies which can be configured to grant permissions for different modules, tables as well as the ability to have multiple Organizations control their own data on a single Sahana Eden installation.

Design

Database

This is a basic relation established on the system between the place and the contact for the drop off site. An organization to each drop off sites, and one organization can have different representative for each site. Both of them are many-to-one relationship<ref>http://en.wikipedia.org/wiki/Relational_database</ref>. A dropOffSite table has six attributes: name, flyer, comments, startTime and endTime which indicates the time period the site will be open for donation, and personId as a foreign key to person table.

Framework

In order to add the capability to manage drop off sites information from within the Sahana Eden instance, we have two options: installing a separate package, or integrating this into the Sahana Eden instance. We have decided to use the latter so that :

  • We don’t need to define data, like users, locations, organizations, in multiple systems.
  • We can use Sahana Eden’s messaging and mapping capabilities for the drop off sites in the future.
  • The organization module can use drop off sites records of personnel.

Design Pattern

We have taken two design patterns into consider during our development.

  • Factory Methods

In the controller, we return an s3_rest_controller() method, this function provides all the Sahana Eden framework support needed to access the resource, including automatic loading of the respective model definitions. With this method, we can have a working module and be able to see the CRUD (Create, Read, Update, Delete) user interface. We could define our own methods to do CRUD of drop off site module. In that case, the code will violate DRY principle. If all contributors to Sahana have done the CRUD themselves, there will be a lot of duplication and the readability of the system will decrease. However, we can replace the deault strings within the CRUD user interface with custom strings. To be specific, we use crud_strings() method in S3 framework to do customizations.

def course():
    return s3_rest_controller()
  • Oberserver

Observer pattern is widely used in GUI systems. By the nature of Model-View-Controller(MVC) architecture, the observer pattern is used to decouple the model from the view. View represents the Observer and the model is the Observable object. This kind of framework can be enhanced in future with new observers with minimal changes.

Component

As shown above, we'd like to be able to record information relating to staff in each drop off site, such as how long they will be there and contact number etc. To do this, we need to build a 'link' table between the person and the drop off site. The natural way to do this within Sahana Eden is to make the link table a 'component' of the drop off site table. The drop off site is the 'primary resource', and contact person are a 'component' of the course.

To realize the 'component' feature. First, we add a 'represent' function to allow a record in the drop off site table to be represented by its name.

def place_represent(id):
    table = db.dosite_place
    query = (table.id == id)
    record = db(query).select().first()
    if record:
        return record.name
    else:
        return "-"

This code involves using Web2Py's Database Abstraction Layer (DAL) to do a SQL query.The variable db is an instance of the DAL class, which represents a database. Queries are written in a syntax that is much like a Python expression.

Then, we define a 'reusable field' which can be added to other table definitions to provide a foreign key reference to the drop off site table.

place_id = S3ReusableField("place_id", db.dosite_place,
                    requires = IS_ONE_OF(db,
                                     "dosite_place.id",
                                     "%(name)s"),
                    represent = place_represent,
                    label = T("Place"),
                    ondelete = "RESTRICT")

Note that this uses the represent function which we just defined. It also adds a 'requires' validator function. This provides both server-side validation and a client-side widget (in this case a dropdown of records in the drop off site table).

As to the controller, we don't need to create a separate REST controller to manage the component, since it will always be accessed via the existing drop off site controller, however we must then extend the controller with 2 new elements to allow the Sahana Eden framework to display the component: 'tabs' and an 'rheader'. Tabs are how the framework provides access to the different components in a web page for the primary resource. The 'resource header' is a section of HTML that provides a summary of the primary resource record, in this case the drop off site. This is displayed above the tabs so that when each component record is being viewed, its parent record is also visible at the same time.

We can simply add the following code into the controller model. Here, rheader is simply a variable passed through the REST controller unaltered & then serialized as rheader.xml() in the views.

def place_rheader(r, tabs=[]):
    if r.representation != "html":
        # RHeader is a UI facility & so skip for other formats
        return None
    if r.record is None:
        # List or Create form: rheader makes no sense here
        return None

    rheader_tabs = s3_rheader_tabs(r, tabs)

    place = r.record

    rheader = DIV(TABLE(
        TR(
            TH("%s: " % T("Name")),
            place.name,
            TH("%s: " % T("Start Date")),
            place.start_date,
            )
        ), rheader_tabs)

    return rheader

Implementation

  • Define dropOtffSite table in our new models and its relationship with person table and organization table.
tablename = "dosite_place"
table = db.define_table(tablename,
            Field("name", notnull=True, length=64, label=T("Place Name")),
            s3db.pr_person_id(label=T("Place Contact")),
            Field("flyer", "upload",label=T("Flyer Propaganda")),
            s3_comments(),
            s3base.s3_date("start_date",label="Collection Start Date"),
            s3base.s3_date("end_date",label="Collection End Date"),
            *s3_meta_fields()
        )
  • Add editable features to the the Drop Off Site list.
LIST_PLACE =  T("List Drop-Off Sites")
s3.crud_strings[tablename] = Storage(
   title_create = T("Add New Place"),
   title_display = T("Place Details"),
   title_list = LIST_PLACE,
   title_update = T("Edit Place"),
   title_search = T("Search Place"),
   title_upload = T("Import Place"),
   subtitle_create = T("Add New Place"),
   subtitle_list = T("Place"),
   label_list_button = LIST_PLACE,
   label_create_button = T("Add New Place"),
   label_delete_button = T("Delete Place"),
   msg_record_created = T("Place added"),
   msg_record_modified = T("Place updated"),
   msg_record_deleted = T("Place deleted"),
   msg_list_empty = T("No Place currently registered"))
  • Customized the view in controller so that it fits Sahana Eden's standard.
def place():
    return s3_rest_controller(rheader=place_rheader)

Deliverables

The application can be accessed with the following link: Sahana Eden Site

We go through one use case to see how the system handles a drop off site information collection.


  • Accessing "DropOff Site" from the main menu


  • After click on the menu, we will see a welcome page first. This page gives users a brief introduction of what is drop off site and how does it works.


  • Click on "list of drop off site" link, we'll see a list of drop off sites with their detail information. Then we can add a new record by clicking the button "Adding a Record".


  • Fill in the table with detail. Notice that here when you fill in the person name, you can look up their name by enter part of their name.

]


  • After successfully add a new record, we can go back to see the new drop off site information.

Future Work

Based on the information we have now for Drop Off Site. We plan to add a location attribute to this table so that we can map this location information to mapping feature of Sahana.

Sahana has a fully integrated mapping functionality which allows any location-based data to be visualized on a map. What we can do is to add a layer on the map. When user want to view drop off site information, one can select "Drop off sites" label besides the map, then he will see some marked location on map which indicates available sites. When we click on these marked places, information about the sites, including detailed address and contact number will be available for users in a small text field.

Further Reading

Reference

<references/> ---