BluePrint: CAP Broker

Sahana Alerting and Messaging Broker (SAMBRO) uses the the CAP Broker.

User Guide (SAMBRO Manual)

Introduction

​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. ​GDACS common operating picture with message filtering). The tools are mainly for National Disaster Management Organizations for managing ​Multi-agency Situational-awareness with capabilities for all-hazard all-media warning/alerting.
.

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 ​National Oceanic and Atmospheric Administration's National Tsunami Warning Centre CAPXML feeds ​International Tsunami Warning System in Indonesia with their CAP-Atom feeds, or the ​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.
.

SAMBRO subscribers could be human or other systems (e.g ​Google's Alerthub or ​IFRC's hazard app). 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:

Filtered Alert Hub

Making use of the Global CAP Data feeds to find trends and other probabilistic events of interest in the data streams for informing climate change and disaster planning.

1. ​Wireframe fore Homepage

CAP Profile

A Country develops their Country CAP Profile and intend to implement the profile along with the rules

1. Authorized super-user (or implementer) starts to edit the profile
2. define the format of the message "identifier"
3. define the hazard event specific areaDescription template and geographic boundaries
4. define the mandatory set of languages that all messages should be in
5. define the hazard and areaDescription template specific roles and permissions

CAP Message Template

A warning agency authorized to issue alerts for a specific hazard event wants to create CAP message templates

1. Authorized user will create a new template
2. The CAP Profile will determine the rules for validating the template such as forcing the implementer to generate a "info" segment for each language
3. 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
4. Implementer would provide the required text with placeholders set for message issuers to complete with actual event specific values
5. The template is saved and assigned permissions, for which only authorized users with those permissions can select the specific template when issuing a message

Issue CAP message

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:

1. Authorized user chooses to create a new message
2. If presented to select a template (e.g. Cyclone template)
3. Completes the missing information specific to the event such as event, headline, onset, description, instructions, effective, areaDesc, etc
4. Repeat the "info" segment of the message for each language, as specified by the profile
5. Attach a "resource" file
6. Saves the message as an "actual" alert with a scope set to "Public"
7. Chooses to broadcast the message through the cellular networks, share with all TV/Radio stations

Approve and Reject CAP Alert

1. Authenticated User creates the CAP Alert
2. This CAP Alert needs approval from people assigned with alert_approval role
3. The alert_approval people are emailed and SMS about the approval with the link
4. alert_approval people open the link, login and are presented with "Approve Alert" and "Reject Alert" button at the top (rheader) along with the data that needs to be approved
5. CAP Alert are approved or rejected via approve/reject method
6. The approval alert provides the audit of who approved the message and when it was approved, while the reject deletes the CAP Alert
7. If approve/reject has not been performed within the required time, then the email/SMS should go out again, repeating until it is resolved

SOP Check List

First-responders (special group of subscribers or message recipients) entrusted with carrying our various Standard Operating Procedures (SOPs) would have a guide in the form of a check-list. The SOP check-list is for the Central Authority to receive feedback from the ground troops (first-responders) on the status of the alert/warning instigated activities

1. The implementers would generate an Event Type specific SOP check-lists and save then in the database
2. Those check-lists are then assigned to various administrator generated subscriber groups
3. When a message is issued and the subscriber group is selected, the URL to the check-list is sent as a <resource> to the recipients
4. The recipients, then execute their SOPs and frequently update the status of the check-list
5. The Central Authority would generate reports that would monitor the progress of the check-list

Turn on Siren Towers

A warning agency learns of a tsunami warning and wants to activate a system with a CAP message (e.g. siren towers)

1. Similar to the previous instance, the authorized user would create a message
2. Set the "parameter" values to trigger the sirens
3. Select the areaDescription to determine the targeted siren towers
4. Choose the delivery method as "siren system" and send the message

View common operating picture

A emergency management agency wants to view the current situation or get an overall picture of all the current alerts for situational-awareness

1. Authorized user enters SAMBRO
2. Typically, upon entry, they are presented with the "common operating picture" or they navigate to it
3. The user may choose to filter the map of alerts by various CAP elements such as "category", "priority", or "areaDescription"
4. The user may choose to filter the map of alert for a specific time interval
5. 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"
6. The user may choose to further investigate the alert message by clicking more to view the full message
7. Authorized user may choose to update that message and save it with the most current information

Area descriptions

There are three ways a use may define the alerting or warning area

1. Free text areaDesc only - the user simply writes the a description for an area (e.g. Cox's Bazar Coastal area Bangladesh), which is not precise and contains a level of ambiguity as to how far from the sea, is it 30m, 50m, or 100m but gives a general sense.
2. Predefined areaDesc text only - we may create a database for country with names of all administrative jurisdictions, like towns, cities, villages, districts, provinces, states, etc. These names would also be related to an administrative category (e.g. District={Colombo, Kalutara, Kandy}, City = {Colombo 01, Colombo 02, Kandy, Kalutara}, ...). We would first give the option for the user to filter the categories; e.g. they may chose District. Thereafter, they are presented with an autofill ajax type text box to start typing the name of the District, as in this example, and to select the name from the suggested list. Multiple names are separated by a comma.
3. Polygon or Circe only - the user may chose to either define a polygon or a circle. In either case they would provide lat/lon pairs to define the shape.
4. areaDesc and Polygon/Circle - the user may decide to provide an are description as in (a) and a series of lat/lon pairs to define the geographical shape of the area mentioned in the areaDesc
5. Predefined areaDesc - Similar to (b) but combining with (c), a feature introduced for the ease-of-use. Based on a risk assessment exercise, the users will develop predefined alert area polygons. These polygons will be categorized by the eventType, Incident, Administrative jurisdictions and associated with an area description. During the time of creating a message, when a user defines the eventType, that would trigger for filtering the relevant list of predefine polygons. Additionally, the user may continue to filter by selecting the District and a provide a District name to further filter the predefined polygons. Thereafter, they would select the relevant areaDesc from the present list. Upon selection the polygon or circle shape lat/lon pairs would be automatically populated.

Sahana Agasti has a CAP broker implementation but is currently deprecated

Requirements

TODO - redo this subsystem diagram in tune with Eden

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.(see this ticket on templates)
• CAP subscriber: data model and GUIs to manage intended users and groups when disseminating alerts via the available delivery methods
  • SMS - Short Message Service - restricted to 140 characters per page; possibly restrict it to 1 SMS page with link to the full CAP message (e.g. URL); using s3msg module
  • Email ; using s3msg module
  • Cell-broadcast
  • TV
  • Radio (audio)
  • FTP - File Transfer Protocol - to transfer CAP files or text extracted from a CAP file to a specified/authorized FTP site and folder
  • ​HF radio data platform: uses Pactor modems and HF radios for exchanging data and images

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

We have summarized the use case in this section and provided an abstract level diagram. Developers are encourage to follow the links given in the column: Use-case in the table below to find a more detailed use-case discussion.

Actors and Use-case

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
	Acknowledge message receipt	A subset of the subscribers known as administrator generated subscriber list comprises first-responder groups. They are required to acknowledge the receipt of a alert message
	Report SOP Status	The same set of first-responders might be required to follow a SOP and report to the central authority of the outcomes

Roles

SAMBRO module would have the following roles:

	Actor
Role	Implementer	Author & Issuer	Authorizer	Subscriber	Description
Anonymous					Can view only scope=public Alert
Authenticated	X			X	Authenticated user who can subscribe to RSS/SMS/Email
Map Admin	X				Allowed access to edit the Map Service Catalogue
Alert Editor	X	X			Can create CAP Message and disseminate the Message after authorization from CAP Authorizer
Alert Approver	X	X	X		Besides Authorizing Message to disseminate, they can also act as CAP Editor
Admin	X				CAP module Admin and Key role for implementing. Implementing includes Administering Organizations, Setting Incident/ Event lookup values, defining Warning Priorities, Generating Message Templates, Editing the Register of Alerting Authorities, Manage users both Authors and Subscribers, test the system from a alerting/warning/situational-awareness context

Publisher-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 design page
  
  • 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

• Security Requirements:
  • Registration
    • Disable self registration; only authorized administrator should create an account and grant permissions to access.
    • Registration request form should be made available and the request should be emailed to the administrator upon submission.

Process Flow

Process/Entity	Description
Alert publisher	authorized to author alerts
Create or Edit alert

Eden Modules

SAMBRO SCHEMA

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)

SAMRBO SPECIFIC MODULES

Module Name	Module Key	Description (more)
CAP	cap	essential for enabling CAP-enabled messaging (more)
Messaging	msg	to send and receive SMS, Email, Twitter related CAP messages (more)
Events	event	required for defining CAP events; (more)

INSERT DATA MODEL IMAGE

Implementations

• [GSoC 2012 project wiki:Event/2012/GSoC/CAPBroker]
• SAMBRO deployments:
  • Maldives Blueprint
  • Myanmar Blueprint
  • Philippines Blueprint

References

CAP

1. SAMBRO CAP-enabled Mobile App Blueprint
   
2. ​CAP 1.2 Specification
   
3. ​Example Practices: CAP Feeds Version 1.0
   
4. ​Google Alerthub
   
5. SAMBRO User Guidelines
   
6. ​Pacific Disaster Center
   1. ​Inaware for DRR project in Indonesia
7. UniversalApp dissemination specification logic developed for the IFRC Preparecenter.
8. ​Red Cross Preparecenter - WhatNow App
9. ​NOAA Tsunami Warning Center

GIS

1. GIS data manipulation ​Doc 1 and ​Doc 2
   

Eden

1. S3 Subscriptions and Notifications
   
2. Message Template
   

Other

1. ​Flood warning and mapping mobile app - FloodReadyQ Smartphone App Prototype Development for Community Dissemination of Flood Warning and Flood Mapping Information
   

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.​ The code is here. Anyone can use this as the basis to continue the CAP Broker developments.
• This ticket contains some of the screen shots and initial GUI layouts with some descriptions.

---

-CAP Broker GUI Design

Current Status

​Fit-Gap analysis spreadsheet

Available features:

1. built on the Emergency Data Exchange Language (EDXL) Common Alerting Protocol (CAP) version 1.2 [1]
2. manage templates, manage messages
   
3. manage CAP cutomizations (multiple languages, identifier format, etc) in ../cap/000_config.py file
4. support multiple language CAP message publication
5. receive CAP feeds [2] to serve as an aggregator and a pubhub
6. approve or reject a CAP message prior to dissemination
7. delivery options: HTTP, RSS/Atom, SMS, Email, FTP (dynamic labels)
8. visualize CAP feeds on a map ("common operating picture")
9. Use GIS-based risk assessment techniques to develop predefined (hazard, event, and severity specific) CAP alert area templates\1. delivery options: HTTP, RSS/Atom, SMS, Email, Voice-text (audio)
10. subscription management (who, what, when, and where) serve as a subhub
11. Mobile application to server as a publisher and a subscriber

Missing features:

1. Feed in to Google Alerthub [3] and ​IFRC Universal Hazard App
2. digitally sign the messages
3. Pictographs for Alerting
4. Event specific SOP check list