= !BluePrint: CAP Broker =
[[TOC]]

== Current Status == 

==== Available features: ====
* built on the Emergency Data Exchange Language (EDXL) Common Alerting Protocol (CAP) version 1.2 '''[1]'''
* manage templates, manage messages [[BR]]

==== Missing features: ==== 
1. manage CAP Profiles (multiple languages, identifier format, etc)
1. receive CAP feeds '''[2]'''
1. delivery options: HTTP, RSS/Atom, SMS, Email, Cell-broadcast, Twitter, HF data, Voice-text (audio), FTP (dynamic labels)
1. visualize CAP feeds on a map ("common operating picture")
1. subscription management (who, what, when, and where)
1. integrate with Google Alerthub '''[3]'''
1. enable multi language "info" segments
1. digitally sign the messages

UserGuidelines/Alerts
== Introduction ==
[http://en.wikipedia.org/wiki/Common_Alerting_Protocol Common Alerting Protocol] defines a data format for sharing alerts (and re-relaying) over various media channels. This project aims to implement core CAP features into Eden and provide usable UI elements for managing CAP alerts.The module will facilitate the publishing and relaying of alerts and warning as well as offer subscribers means to receive warnings and alerts of their choice. Moreover, the module will provide a common operating picture of the published alerts for improving situational-awareness (e.g. [http://gdacs.org/alerts/ GDACS common operating picture with message filtering]). The tools are mainly for National Disaster Management Organizations for managing [http://lirneasia.net/2012/05/masas-iscram-2012/ Multi-agency Situational-awareness] with capabilities for all-hazard all-media warning/alerting.[[BR]]


The self-contained product, coming out of the developments, will be coined as the CAP-enabled Sahana Alerting and Messaging Broker (abbreviated as "SAMBRO"). One aspect of SAMBRO is give implementers the option to subscribe to available CAP feeds such as the [http://wcatwc.arh.noaa.gov/ National Oceanic and Atmospheric Administration's National Tsunami Warning Centre] CAPXML feeds [https://inatews.bmkg.go.id/rss/capatomlast40event.xml International Tsunami Warning System in Indonesia] with their CAP-Atom feeds, or the [http://gdacs.org/resources.aspx?eventid=122640&episodeid=122656&eventtype=EQ Global Disaster Alert and Coordination System] (GDACS) individual alert CAP files. Thereby, serving in capacity of an aggregator to present those CAP messages in the common operating picture based on spatial and temporal dimensions. Authorized SAMBRO user can choose to amend those CAP messages, received through the feeds, to relay them to the subscribers registered in the SAMBRO. [[BR]]


SAMBRO subscribers could be human or other systems (e.g [http://alert-hub.appspot.com Google's Alerthub]). SAMRBO message publishers would be provided with functionality to manage reusable CAP message template and issue CAP messages over multiple channels such as HTTP posts, RSS/Atom feeds, SMS, Email, Twitter, Facebook, so on and so forth. The CAP standard also requires that implementers define a CAP-Profile. These are typically considered as CAP Country Profiles. Therefore, the module will feature those components for managing those implementation specific profiles.
== Description ==
'''User stories:'''
1. A Country develops their Country '''CAP Profile''' and intend to implement the profile along with the rules
     a. Authorized super-user (or implementer) starts to edit the profile
     a. define the format of the message "identifier"
     a. define the hazard event specific areaDescription template and geographic boundaries
     a. define the mandatory set of languages that all messages should be in
     a. define the hazard and areaDescription template specific roles and permissions
1. A warning agency authorized to issue alerts for a specific hazard event wants to '''create CAP message templates'''
     a. Authorized user will create a new template
     a. The CAP Profile will determine the rules for validating the template such as forcing the implementer to generate a "info" segment for each language
     a. Implementer can choose to either allow the message issuer to change the template value for a certain attribute or lock that field with a fixed value
     a. Implementer would provide the required text with placeholders set for message issuers to complete with actual event specific values
     a. The template is saved and assigned permissions, for which only authorized users with those permissions can select the specific template when issuing a message
1. A warning agency learns of an imminent hazard event (e.g. cyclone) and wants to '''issue a CAP message''' to warn the targeted public at risk:
     a. Authorized user chooses to create a new message
     a. If presented to select a template (e.g. Cyclone template)
     a. Completes the missing information specific to the event such as event, headline, onset, description, instructions, effective, areaDesc, etc
     a. Repeat the "info" segment of the message for each language, as specified by the profile
     a. Attach a "resource" file
     a. Saves the message as an "actual" alert with a scope set to "Public"
     a. Chooses to broadcast the message through the cellular networks, share with all TV/Radio stations
1. A warning agency learns of a tsunami warning and wants to '''activate a system with a CAP message''' (e.g. siren towers)
     a. Similar to the previous instance, the authorized user would create a message
     a. Set the "parameter" values to trigger the sirens
     a. Select the areaDescription to determine the targeted siren towers
     a. Choose the delivery method as "siren system" and send the message
1. A emergency management agency wants to view the current situation or get an overall picture of all the current alerts for '''situational-awareness'''
     a. Authorized user enters SAMBRO
     a. Typically, upon entry, they are presented with the "common operating picture" or they navigate to it
     a. The user may choose to filter the map of alerts by various CAP elements such as "category", "priority", or "areaDescription"
     a. The user may choose to filter the map of alert for a specific time interval
     a. The user would click on a alert icon on the map to view the short description with essential information such as the "headline" and "priority"
     a. The user may choose to further investigate the alert message by clicking more to view the full message
     a. Authorized user may choose to update that message and save it with the most current information 

Sahana Agasti has a CAP broker implementation but is currently deprecated

== Requirements ==
==== Functional: ====
  * CAP Profiles and CAP Templates: Data model and user interface assisting easy and correct implementation of CAP profiles and create/edit of CAP templates
  * CAP Editing:  Data model and user interface for creation of CAP alerts compliant with the EDXL-CAP 1.2 standard.([http://eden.sahanafoundation.org/ticket/1423 see this ticket on templates])
  * CAP subscriber: data model and GUIs to manage intended users and groups when disseminating alerts via SMS and Email. (we can use s3msg module here)
==== Interoperability: ====
  * CAP Broadcasting: Use XSL and XSLT to generate text suitable for distribution. Generate broadcast events, broadcast media can be added by hooking up to these events generated in the system: tap in to s3msg module
  * CAP Reception: Expose a PuSH end point and allow Eden instances to subscribe to each other. Handling cancellation and update alerts gracefully.
  * Import and Export facility for CAP and CAP Profiles: Enable importing of CAP Alerts from XML files with CAP Alert elements. Allow Exporting. Use the Survey module as a reference here. Also these should be implemented inside the s3export module.
==== Visualization ====
  * Basic requirement is displaying CAP messages on a Map
  * The effective area of the CAP message is typically bounded and shaded by a polygon
  * Offer search and filter functions to drill in to the maps
    * time-series widgets for viewing time-series activities in a given time window
    * map zoom and filter widgets for animating activities over time
  * Built in parser to strip a CAP message to unbundle the elements
  * Preferred CAP RSS/Atom feeds for receiving he CAP XML file
== Use-Cases ==
||=Actor                     =||=       Use-case   ||=         Description       =||
||CAP profile implementer     || Implement CAP profile || CAP Profile defines a class of CAP alerts which may provide a structure to the CAP alert and speed up the creation of CAP Alerts and templates, for example a Profile may specify a region, a set of languages and generic templates in each language. This can be used during CAP alert creation for centering the map for example and for fast creation of alert messages ||
||CAP template implementer || Implements CAP templates || CAP templates are Abstract CAP alerts with blanks that need to can be filled really fast in case of an imminent disaster to produce a CAP alert, for example a Tsunami CAP template might be of help in a coastal area, hence an implementer will create the same ||
||CAP message editor       || Send a CAP alert || a message editor can pick a CAP template and fill the blanks in it to send out a CAP alert (user story in description) ||
||CAP alert subscriber     || Subscribes to CAP Alerts || when a CAP alert is created and the subscriber is in the audience, a notification will be issued via modes prescribed by the subscriber ||
== Design ==
* The Models: The table definitions go are in modules/s3db/cap.py. Place some functions which will help in the creation, sending and receiving of CAP XML files in s3msg module where it might best fit.
  * A detailed description of the data model is here: https://docs.google.com/spreadsheet/ccc?key=0AiLVG3CYfknsdGljMXNQejNWSURnVHZYYnMySERzdHc
  * The Eden modules and their dependencies are explained here: ['''Tharindu - insert URL to doc''']
* The GUI
  * index: A map and a table of alerts sortable by the various fields of an alert. Clicking on a row on the table centers the map to the <Area> associated with the alert.
  * profiles:
    * index: View a listing of templates (We should ship some country-specific profiles by default in Eden since this is recommended)
    * edit & create: Editing / creating a profile. This should allow for specification of constraints for each field of the cap message.
  * templates:
    * index: View a listing of all templates grouped by their pertinent profiles.
    * edit & create: Allow users to create templates: This will allow for creating multiple <info> elements with placeholders for canned inputs such as [AREA] [SEVERITY] etc.which will then be substituted to produce text consumable via various media like SMS and IVR
  * create alert: A map with ability for easy input of polygons and circles, A drop-down for picking profiles and templates to use. A way to specify recipients for restricted alerts.
  * Reference and mockups: http://eden.sahanafoundation.org/ticket/1026

==== MANDATORY MODULE ====
|| '''Module Name''' || '''Module Key''' || '''Description''' ||
|| Home || default || Root page with the index.html that is initially called by the application and display the home page to the user with login controls (more) ||
|| Administrator || admin || When login as administrator the home page presents all administrative functions for the administrator to carry out the respective functions (more) ||
||  || appAdmin || Similar to the Admin module but provides additional features relevant to the specific application such as with handling database related administrative functions (more) ||
|| Ticket viewer || errors || required during development cycle; errors are shown only when login as administrator (more) ||
|| Translation Functionality || translate || core module for application localization (more) ||
|| Synchronization || sync || To manage the synchronization of multiple users working on the same features (more) ||
|| Support || support || Help page, can be disabled but essential for providing help features (more) ||
|| Map || gis || definitely required for spatially presenting information (more) ||
|| Person Registry || pr || mainly used for managing users with privileges and roles with respect to accessing and operating CAP functions (more) ||
|| Organization || org || required for managing all organizations/institutions (more) ||

== Implementations ==
* [GSoC 2012 project wiki:Event/2012/GSoC/CAPBroker]
* [# Maldives CAP on a Map project]
* [# Philippines CAP on a Map project]

== References ==
'''[1]''' [http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.pdf CAP 1.2 Specification][[BR]]
'''[2]''' [http://docs.oasis-open.org/emergency-adopt/cap-feeds/v1.0/cn02/cap-feeds-v1.0-cn02.html Example Practices: CAP Feeds Version 1.0] [[BR]]
'''[3]''' [http://alert-hub.appspot.com/ Google Alerthub] [[BR]]
'''[4]''' [http://eden.sahanafoundation.org/wiki/UserGuidelines/Alerts SAMBRO User Guidelines] [[BR]]
== Notes ==
Common Alerting Protocol:

''Originating CAP alerts is one need, receiving them and using them to actuate alerting systems, be they SMS drivers or sirens or whatever is another.  Another is a message broker that can interoperate with the commercial boxes.  Authentication systems are also a factor, especially where cross-jurisdictional reciprocity is required''

''Ideally the CAP XML should be signed end-to-end, especially in a federated system where there's more than one authority running servers/aggregators.  Our current implementations sign the alerts at the originating server, so they're at least traceable to the source server but not necessarily the individual operator.  Current servers check integrity when they get a message from another server, but there isn't a regional PKI.''

 * http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2.html
  * Use an XSLT
 * Subset of EDXL-DE: http://docs.oasis-open.org/emergency/edxl-de/v1.0/EDXL-DE_Spec_v1.0.pdf
  * Use another XSLT
  * http://code.google.com/p/pyedxl/source/browse/trunk/edxl/edxl.py
  * http://edxlsharp.codeplex.com
  * SQL schema: http://wiki.sahanafoundation.org/doku.php/wiki:user:edxl_discussion#proposed_sahana_edxl-de_database_implementation
 * http://talksahana.com/2009/03/04/firefox-browser-cap-alerting-plugin-sahana-idea-for-gsoc2009/
 * Sahana CAP/EDXL Broker specification - http://lirneasia.net/wp-content/uploads/2009/05/Sahana-CAP-Msg-Mod-v0.2.pdf

==== Wireframe (ported to eden) ====
* The wireframe built using Python and Eden frameworks.[[https://github.com/Nostraa/eden/tree/CAPBroker | The code is here]]. Anyone can use this as the basis to continue the CAP Broker developments.
* [[http://eden.sahanafoundation.org/ticket/1026 | This ticket]] contains some of the screen shots and initial GUI layouts with some descriptions.

----
BluePrints