= SAMBRO Guide =
[[TOC]]
* [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Mobile SAMBRO MOBILE APP] 
* [http://eden.sahanafoundation.org/wiki/Deployments/SAMBRO An Introduction to SAMBRO] (Sahana Alerting and Messaging Broker)
* [http://eden.sahanafoundation.org/wiki/Deployments/SAMBRO/FAQs Frequently Asked Question - SAMBRO]
== Purpose ==
The user guide provides a set of step-by-step instructions from installing, customizing, and operationaizing SAMBRO software to issue and manage alerts. It is intended for all user levels: novices to experts. The guide is structured to take you through an actual implementation with real world examples and data. [[br]]

=== How to use the Guide ===
The user guide is designed to quickly access relevant information for performing a user's role specific task. The topics are ordered such as that the most frequently used activities are listed first, like subscribing to alerts, and the seldom used, one time Admin type activities, are listed at the bottom. We have segmented the '''role specific work flow topics'''. If you are a particular user searching for a topic, '''first navigate to the type of user you are and then select the work flow activity''':
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO#SubscribersAlertRecipients How to receive alerts?] Steps for first registering in SAMBRO as a Subscriber (Closed User Group; e.g. first-responder) to receive location, event type, and warning priority specific messages as well as public alerts
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO#PublishersAlertIssuers How to create, authorize, and disseminate alerts?] Instructions for Alerting Authorities for managing the process of  issuing alerts to Closed User Groups (CUGs) and the Public
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO#ImplementersSuperUsers How to implement SAMBRO for your alerting needs?] For Super Users to define the user roles/responsibilities, message qualifiers, message templates, first-responder groups, and standard operating procedures.
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO#SystemAdministrators How to install and operationalize SAMBRO software?] Guides a Systems Administrator through installation and customization process to get SAMBRO up and running.
== Role Specific Topics ==
=== User Roles and Permissions ===
While Sahana allows for defining various user roles and permissions to the customer's liking, SAMBRO has identified five major roles. The roles and their functions are defined in the table below
||= '''Role''' =||='''Responsibilities''' =||= '''Permitted Functions''' =||
||Authenticated / Subscriber ||Receiving alerts through defined communication modes ||Edit own contact details (email, phone, name, ...) -> pr_contact, pr_person ||
||Alert Editor ||Can create the CAP Message and submit that for approval ||cap_alert (Create, Read, Update),[[br]]cap_template (Read),[[br]]cap_area (Read),[[br]]pr_group [person' group](CRUD),[[br]]Admin Based Subscription pr_subscription (CRUD) ||
||Alert Approver ||Besides Authorizing Message to disseminate, they can also act as CAP Editor ||cap_alert (Create, Read, Update, Review, Approve),[[br]]cap_template (Read),[[br]]cap_area (Read),[[br]]pr_group [person' group](CRUD),[[br]]Admin Based Subscription pr_subscription (CRUD)||
||Implementer/ Administrator ||Normally one time implementation||superuser, has access to all the functions ||
=== Subscribers (Alert Recipients) ===
'''CAUTION'''! SAMBRO has the option of [wiki:UserGuidelines/SAMBRO#ImplementersSuperUsers subscribing to external feeds] (both CAP Feed and RSS Feed) that can be rendered in the SAMBRO News Feeds column in the home page. That Implementation specific process should not be mistaken with the subscription work flows discussed in this section, which is specific to subscribing to SAMBRO feeds[[br]][[br]]
There are two types of alert recipients: Public and CUGs. Public can subscribe to RRS/Atom and Social Media feeds. CUGs have all the privileges the pubic has plus other options to receive email and SMS alerts filtered by location, event type, and warning priority.
1. [wiki:UserGuidelines/SAMBRO/Implement#RequestforAccount Request for an account]; if you don't have one already
1. [wiki:UserGuidelines/SAMBRO/Subscribe#RSSAtomFeeds RSS/Atom Feeds] for your alert hub or RSS/Atom Reader for all alerts
1. [wiki:UserGuidelines/SAMBRO/Implement#SelfSubscriptions Email, SMS, FTP and GCM] subscription to receive and filter alerts
1. [wiki:UserGuidelines/SAMBRO/Subscribe#SocialMediaFeeds Social Media] - link to Twitter, FaceBook news feeds applying the instructions given by the Administrator
1. [wiki:UserGuidelines/SAMBRO/Subscribe#Viewpublishedalerts View Alerts] and interpret them on a map and complete
1. [wiki:UserGuidelines/SAMBRO/Subscribe#FilterAlerts Filter Alerts]
1. [wiki:UserGuidelines/SAMBRO/Subscribe#TesttheSubscription Testing the subscription to alerts]

=== Publishers (Alert Issuers) ===
The section discusses ways and means for creating a CAP message, having it authorized, and then issuing (or disseminating) to the subscribers

1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Publish#CreateaCAPMessage Create] a message for the first time and as a message originator
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Publish#UpdateCancelorClearaCAPMessage Update] a message using an existing message
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Publish#UpdateCancelorClearaCAPMessage Cancel] a message that has been wrongly issued or the event is cancelled
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Publish#UpdateCancelorClearaCAPMessage Error] a message that has error (in information or data)
1. [# Clear] a message when the event has subsided to inform the subscribers with an 'All Clear' message
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Publish#ImportParticularAlertfromtheURLforRelay Import particular alert from the alert URL] to relay the alert
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Publish#AuthorizingandApprovingaCAPMessage Authorizing and Approving Alerts]
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Publish#RelayingAlerts Relaying of alerts]
1. [# Testing the publishing of alerts]

=== Implementers (Super Users) ===
The section is for CAP Implementers for orienting the CAP Broker in the country or implementation specific context.
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/Admin/UserManagement Manage Users] by associating them with the relevant [http://eden.sahanafoundation.org/wiki/BluePrint/CAPBroker#Use-Cases roles] and alerting authority
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#AdminForcedSubscriptions Edit First-Responder compulsory messaging lists] to force messages (i.e. Admin/Implementer defined subscriber lists)
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#CreateMessageTemplate Create Message Templates] for categories of events and user groups
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#CreatingPredefinedAlertArea Predefined Alert Area] polygon and area description developments
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#ManagingtheRegisterofAlertingAuthoritiesandOIDs Update Register of Alerting Authorities]; i.e. setup your organizational structure and alerting jurisdictions
1. [wiki:UserGuidelines/SAMBRO/Profile Define CAP implementation specific information] such as Waring priorities, Event types, Incident tables, ...
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#Configure Configure Broker] with identifier, warning priorities, and other relevant implementation or country context information
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#SubscribetoExternalCAPFeed Subscribe to external feeds]
1. [# Testing the implementation] after setup, configuration, and adding users
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#RequestforAccount Requesting for an account in SAMBRO]
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#ChangingtheSocialMediaIconLinks Changing the social media link in the footer of the index and the alert hub page]
1. [http://eden.sahanafoundation.org/wiki/GIS/Data Download and install the GIS Data needed for the Lx of your country]
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#MapAreaDisplayOptions Map area display while importing alert (geocode or polygon)]
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#SettingupSMSgateway Setting up SMS gateway]
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#SettingupTwitterAccount Setting up the twitter account]
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Implement#SettingupFacebookAccount Setting up the facebook account]
=== System Administrators ===
==== Quick installation ====
1. run script: 
   a. https://github.com/sahana/eden_deploy/blob/master/configure-eden-cherokee-postgis.sh
   a. when asked - "What template should we use?" type "SAMBRO" (without the quotes)
1. ALTERNATIVELY - if you have already installed the default EDEN template and want to change it to the 'SAMBRO' template, do this ...
      i. using your preferred text editor (e.g. [https:/wiki.gnome.org/Apps/Gedit gedit], [https://help.ubuntu.com/community/Nano nano], so on):
      i. edit the file ../web2py/applications/eden/models/000_config.py  
      i. change settings.base.template = ("SAMBRO")
{{{
sudo nano ~/web2py/applications/eden/models/000_config.py
}}}

1. change directory to ../web2py/applications/eden/ and run the command "clean" (without quotes) in your terminal command line
{{{
cd ~/web2py/applications/eden/
clean
}}}


1. change the director to web2py/ and, in your terminal command line, run the command "python web2py.py -a eden" (without the quotes) to start
{{{
cd ~/web2py/applications/eden/
python web2py.py -a eden
}}}
1. Use the browser to check if it all works!

==== Installation with own Git branch ====

Steps for '''INSTALLING''' your SAMBRO instance
1. ''[OPTIONAL]'' [http://eden.sahanafoundation.org/wiki/ConfigurationGuidelines#SwitchtoanalternateGitHubrepo Branch] an instance of the Sahana Eden code to a new github repository of your own. This would allow you to manage your own customized implementation such as with changing the theme. Ohterwise, ignore this step and pull the code from the main github repository; explained in the subsequent step.
1. Activate the [# script to automatically pull the latest version] of the code from your github repository.
1. [http://eden.sahanafoundation.org/wiki/InstallationGuidelines Install] the Sahana Eden software with web2py framework and other dependencies.
     a. Recommend that you [http://eden.sahanafoundation.org/wiki/InstallationGuidelines/Linux/Server install on a Linux server]
     a. Open your terminal and go to your web2py path, by default it will be saved on your home directory
        This is useful if you want to run the EDEN with in your organisation (network) without having the public IP (but remember you cannot access it outside, so recommend you get the public IP) (see http://web2py.com/books/default/chapter/29/04/the-core#Command-line-options for more detail)
 {{{
 cd ~web2py
 python web2py.py -i your.ip.address -p port.number -a 'your password'
 }}}
     a. [# Setup the server with a Public IP] to be visible over the Internet
     a. [# Configure the installation] to send receive SMS, Email.
     a. [http://eden.sahanafoundation.org/wiki/ConfigurationGuidelines#ChangingtheTemplate Activate the SAMBRO template] by changing the default template. Follow 
[[br]]
Steps for CUSTOMIZING your SAMBRO instance
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/SAMBRO/Customize Customize relevant settings] to configure the instance to the Implementer's liking
1. [http://eden.sahanafoundation.org/wiki/ConfigurationGuidelines Customize] the CAP Broker for the implementation context (e.g Admin contact details, banner or logo changes
1. [http://eden.sahanafoundation.org/wiki/UserGuidelines/Admin Basic Administration] tasks for activating an instance for the users
1. [# Testing the installation] to ensure all SAMBRO specific features are functional
1. The Email Generating Function is called ''get_html_email_content'' and is available [https://github.com/sahana/eden/blob/master/modules/templates/SAMBRO/config.py#L996 here]
1. The SMS Generating function is called ''get_sms_content'' and is available [https://github.com/sahana/eden/blob/master/modules/templates/SAMBRO/config.py#L1156 here]
1. The email heading generating function is called ''get_email_subject'' and is available in /templates/SAMBRO/config.py at [https://github.com/sahana/eden/blob/master/modules/templates/SAMBRO/config.py#L1179 here]

== System Menu ==

Depending upon your role and responsibility, you might see all, some or none of the menu item. I will describe the meaning and purpose of each of them here. The purpose will be same no matter what role you are assigned with.[[BR]][[BR]]

[[Image(http://i.imgur.com/uiOOQP9.png)]][[BR]][[BR]]

1. The '''Home Page''' for the system. In case of Philippines, the home page is the alert hub page.
1. The '''Alerts''' has Option Menus for creating, approving alerts. As well as preparing the templates, predefined alerting areas, warning classifications for the event as well as managing events, and viewing the approved and incomplete alert.
1. '''Alert Hub''' menu shows the map and tabular form of the CAP compiled alerts coming from the external system.The external alerts can be relayed through the system.
1. '''Organizations''' menu lets you manage your organization, assign the CAP OID, create branches and label CAP OID in branches as well.
1. '''Persons''' menu allows you to create the person, edit their contact details, manage address, education, map settings etc. Also, you can create a group of person from the Options Menu in the Persons Menu.[[BR]]NB: The person may not be authenticated user, ie. you can create a person, send them alerts etc without allowing them to login to the system, assigning any roles etc. Of course, you can allow them too.
1. '''Recipients''' allows the administrator to manage the list of people as well as the group of person who are forced to receive the alerts.
1. '''Map''' menu allows you to perform various GIS related tasks in the system like managing layers, maintaining the hierarchy of the administrative division, defining styles, projection system, layers for WMS, and many others.[[BR]][[BR]]
Click on '''Alerts''' and you will get the Options Menu.[[BR]]

[[Image(http://i.imgur.com/qZ11vuI.png)]][[BR]][[BR]]

=== Alert Hub ===

[[Image(http://i.imgur.com/BNdIvHA.png)]][[BR]][[BR]]

[[Image(http://i.imgur.com/zJcnMak.png)]] [[BR]][[BR]]






== Design and Specifications ==

For advance users or developers interested in  the SAMBRO software design requirements and specifications are discussed in the[[br]]
[wiki:BluePrint/CAPBroker CAP Broker BluePrint]