Changes between Initial Version and Version 1 of UserGuidelines/SAMBRO


Ignore:
Timestamp:
06/08/15 15:25:15 (7 years ago)
Author:
Nuwan Waidyanatha
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UserGuidelines/SAMBRO

    v1 v1  
     1= SAMBRO User Guide =
     2[[TOC]]
     3
     4[http://eden.sahanafoundation.org/wiki/Deployments/SAMBRO An Introduction to SAMBRO] (Sahana Alerting and Messaging Broker)
     5== Purpose ==
     6The user guide is comprehensive with instructions from setting up SAMBRO software to issuing 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.
     7== Data ==
     8Note: the alert data model and its children are more or less identical to those in the [http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html#_Toc454352650 CAP 1.2 Specification]. The help text next to each field in the UI describes the purpose of these as in the specification document.
     9* '''Alerts''' -- The qualifiers of the alert message. Includes alert identifier, sender, message type, scope (audience), references to other cap alerts and other fields.
     10  * '''Alert information''' -- An alert can contain more than one information element, the primary purpose of this is to annotate the alert message in multiple languages. An information part of the alert contains fields that are pertinent to the actual subject and characters of the alert. Fields include: language, category of the alert, a short description of the event, expected response type, priority, urgency, severity, certainty, target audience, auxiliary codes and parameters as metadata to the event, time of effectiveness, onset and expiry, name of the sender, headline of the event, a url, contact information etc.
     11    * '''Resource''' -- One or more files attached to the information (could be things like a map of the affected area, documents containing instructions etc.)
     12    * '''Area''' -- Each alert information item may contain one or more area fields which describe the affected geographical area and optionally provide data to place it on a map.
     13* '''Alert templates''' -- these are a subset of alert and alert information fields which can be filled in before hand and kept ready for use during a time of emergency. This will be part of the pre-planning process for the particular Eden instance. A default empty template is provided on a fresh installation. As a first step of the alert creation procedure you will need to select a template to apply to the alert message.
     14* '''CAP Profile''' -- These are site-wide configuration settings that can be used for configuring the cap module for a specific region's (usually a country) requirements for disaster preparedness. For an example look at [http://capan.ca/index.php/en/cap-cp/ Canadian CAP Profile].
     15
     16== Workflow ==
     17
     18Before creating a CAP template and a message, you should have [wiki:UserGuidelines/Alerts#ConfiguringaCAPProfile created a CAP Profile] first.
     19
     20=== Create a Template ===
     21
     22'''[[https://www.youtube.com/watch?v=J03xcVOOPOI&feature=youtu.be | Watch the Video]]'''
     23
     24An '''alert template''' is a pre-populated CAP message that is created to speed-up with the message creation as well as preserving the consistency of a message. Wherever the event specific information such as the DATE or LOCATION or other information you may create place holders for those values within the text. You should mark up places in the text that need to be changed within a pair of square brackets with capitalized text inside as shown below.
     25
     26''Example'' the ''headline'' text in a CAP message template for a flood event could be something like this: '''''[YYYY] [MMM]''' heavy rains have caused flash floods in the '''[LOCATION]''' area''. If the floods was in Varnasi area on 2012-09-25, then the message creator would replace the MMM YYYY and LOCATION to create the headline to be specific as such: '''''2012 September''' heavy rains have caused flash floods in the '''Varnasi''' area''.
     27
     28* '''template name''' - the template name should be a generic name such as earthquake, cyclone, epidemic, et; one that a message creator can easily identify.
     29* '''Locked''' - If you mark a field as locked, it cannot be edited in the actual alert message that inherits the template and extends it.
     30* '''Status''' - Make sure the set the message ''status'' to '''''Draft'''''. At the time of issuing the message, the message creator will change that to ''Actual, Exercise, System, Test'',
     31* '''All the values''' - enter all other values as you deem essential, then apply the syntax mentioned earlier in creating place holders for words or sentences that should be replaces at the time of creating the actual message with hazard event specific information.
     32
     33[[Image(http://i.imgur.com/K98gj.png)]]
     34
     35=== Create a CAP Message ===
     36
     37'''[[http://www.youtube.com/watch?v=WvObh2BTABc&feature=youtu.be | Watch the Video]]'''
     38
     39The workflow for creation of a CAP alert is as below.
     40
     41As the first step of the process, you will need to select a template.
     42
     43[[Image(http://i.imgur.com/nIhQh.png)]]
     44
     45----
     46
     47A form is displayed to you after the template has been applied on it. You can edit the alert qualifiers now.
     48
     49[[Image(http://i.imgur.com/K98gj.png)]]
     50
     51----
     52
     53After you are done and submitted the above form you will be redirected to a page where you can add information about the alert. Fill in the details as it applies
     54
     55[[Image(http://i.imgur.com/IZjFy.png)]]
     56
     57----
     58After saving the alert information you can click on the "Open" button against the information row to edit it further or to add its components such as Area or Resource.
     59
     60[[Image(http://i.imgur.com/0LzB4.png)]]
     61
     62The next image is slightly obsolete.  It shows an embedded "Location" widget (a subform with pick lists, map, and "Draw on Map" button).  That's gone now.  Instead, alongside the Area tab is a "Location" tab.  From that tab, there is an "Add Location" button -- clicking that exposes the location widget.  This change allows adding multiple location records to an Area, as the CAP specification allows.
     63
     64
     65[[Image(http://i.imgur.com/GSTIz.png)]]
     66
     67Click on the "Draw on Map" button to open a map to mark the boundary of the affected area.
     68
     69[[Image(http://i.imgur.com/V4J92.png)]]
     70
     71Some Sahana versions have a toolbar on the map, as shown: its polygon tool will be active by default when you open the map (or select it as needed later).
     72
     73In any event, successively click then move the mouse, drawing a polygon with vertices at each click.  Double-clicking ends the polygon.
     74
     75[[Image(http://i.imgur.com/6Fqzj.png)]]
     76
     77Close the map and click on save to commit the area to the alert information.
     78
     79----
     80
     81You can now also attach files to the Alert information by going to the "Resources" tab.
     82
     83[[Image(http://i.imgur.com/jfIyr.png)]]
     84
     85----
     86
     87
     88
     89
     90== Configuring a CAP Profile ==
     91
     92[[http://www.youtube.com/watch?v=nfW4vs7j5Kw | Watch the Video]]
     93
     94CAP profiles can be configured using the deployment settings.
     95
     96The following settings can be set as follows
     97
     98{{{
     99    settings.cap.identifier_prefix = "prefix"  # string
     100    settings.cap.identifier_suffix = "suffix"  # string
     101    settings.cap.codes = [...]           # key-value pairs
     102    settings.cap.parameters = [...]      # key-value pairs
     103    settings.cap.geocodes = [...]        # key-value pairs
     104    settings.cap.base64 = False          # boolean
     105    settings.cap.languages = OrderedDict([
     106                                 ("en-US", "English"),
     107                                 ("fr", "Français")
     108                                 ...])
     109    settings.cap.priorities = OrderedDict([
     110                                  ("<value>, "<Translated title>", <urgency>, <severity>, <certainty>, <color>),
     111                                  ...
     112                              ])
     113
     114}}}
     115
     116Key-value pairs above are python lists containing many dictionaries detailing the behavior and parameters for the key-value pair.
     117It should take the following form
     118
     119{{{
     120    kvpairs = [
     121        dict(key="<key>", value="<value>", comment="<help text>", immutable=<immutable>, options=[("<value>", "<Value title>"), ...]),
     122        ...
     123    ]
     124
     125}}}
     126
     127* Here the comment and options dictionary values are optional.
     128* The options argument is a list of ("<value>", "<value title>") pairs and provides a drop-down to pick the value for the key from.
     129* The mutable argument is a bit-map saying whether to lock the key field or the value field or both in the key-value user interface. (by locking we mean disabling.) You can use it like so:
     130{{{
     131    KEY_MUTABLE = 1
     132    VALUE_MUTABLE = 2
     133
     134    immutable = KEY_IMMUTABLE # only key is immutable
     135    immutable = VALUE_IMMUTABLE # only value is immutable
     136    immutable = KEY_IMMUTABLE | VALUE_MUTABLE # both immutable
     137    immutable = 0 # both immutable
     138}}}
     139
     140== Future Plans ==
     141
     142See the [wiki:BluePrint/CAPBroker BluePrint/CAPBroker]