How to Implement the CAP Broker

Overview

• Alerts -- The qualifiers of the alert message. Includes alert identifier, sender, message type, scope (audience), references to other cap alerts and other fields.
  • 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.
    • Resource -- One or more files attached to the information (could be things like a map of the affected area, documents containing instructions etc.)
    • 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.

Work Flows

User Management

Some of the user management resembles core Sahana User Management, which can be found here. The management specific to SAMBRO are described below:

Self Subscriptions

After you login, the dropdown on the your_email on the top right side shows the sub menu for subscription.

The table lists your subscriptions. To add, click on "Create Subscription" button on the right side above the table list.

The subscription form list the drop down for the Event Type, Priority and the Language which you want to receive the alert. It also list the medium through which you want to receive the alert (Email, SMS, Mobile App, FTP).

If you do not choose any of the filters, then you will receive the alert for all kind of event type, priority as well as in all language.

Admin Forced Subscriptions

The admin forced subscriptions is mostly for personnel who are bound to receive the alerts. This may be the policy or the standard operating procedures. Note this is accessible only for admin.
Logged in as admin, you will see 'Recipients' menu at the top.

Click on there and you will be redirected to the table list of recipient. Recipients could be individuals or the group of people. Click on 'Add Recipient to List' in order to add new person/group of people to the list.

Select the people, group of people and then filter the event type, priority and language and the medium through which you want them to receive the alerts. Remember that if you don't select any of event type, priority and language, the people and the group of people will receive all the alerts. That is no filter is applied. If you want the people or group of people only to recieve the earthquake alert, you can select the Earthquake Event Type from the drop down.

Creating Predefined Alert Area

In order to create template area (or predefined area), in your browser go to: domain-name/eden/cap/area/create (domain-name/application-name/cap/area/create), fill in the necessary information:

1. Area description - A text description of the affected area.
2. Began to draw the location by selecting the country and then following the hierarchy to go to other administrative level.
3. Geocode Name and value - Any geographically-based code to describe a message target area
4. Altitude - The altitude measure is in feet above mean sea level per the [WGS 84] datum
5. Ceiling - The ceiling measure is in feet above mean sea level per the [WGS 84] datum
6. Event Type - The event to which this area is targeted for.
7. Priority - The priority of the area in response to the event.

Every event have priority associated with it. So the selection of event triggers the priority.

Request for Account

By default we do not allow to register. However if you belong to some Disaster Response organisation and feels like having account, you can request to admin to setup the account for you. Go to /eden/default/user/register or from menu Login -> Request for Account. Fill out the form and wait for your account to be approved.

Changing the Social Media Icon Links

In order to change the social media icon link in the footer of the index and the alert hub page, under /eden/modules/templates/SAMBRO/ and then go to your country instance folder eg. Myanmar admin go to MM, and then /views/footer.html.

Change ​this and ​this line and equivalent in other country instances to change the link for the twitter and facebook respectively.

Managing the Register of Alerting Authorities and OIDs

1. Login as an 'Admin' and go to the 'Organizations' menu to see your organisation and manage it.
   
   

2. Create the organisation if not present or click on "Open" to begin editing it.
   
   

3. Begin entering the details and the CAP OID.
   
   

4. Click on "Branches" tab. You can add Branches to your organisation by clicking on 'Add Branch'.

Remember to have different CAP OID for the branch.

The tree hierarchy of the organisation with all the associated branches can be viewed by clicking on 'Show Branch Hierarchy'.

If you are using the Hierarchy structure, then if you right click it gives you different options, namely "Open", "Edit", "Delete" and "Add". The name implies what they do. Now you can begin adding the branches to the organisation.After you add you can the tree hierarchy structure.

5. Now you can relate a person to any organisation(or its branch). Go to /cap/admin/user. You can now see all your staff. Create on "Open" to open the staff record.
   
   

6. Under "Organisation", you can see your organisation and its branches. Now you can assign a particular branch to the staff.
   
   

7. If that staff logins now, he/she can see the CAP OID as the one that we assigned while we created the branch.
   
   

Priority

Warning Priority can be created and updated only by Admin . Some basic understanding of terms is required for Warning Priority as:

'Priority Rank' : It is used to enumerate the priority for the event, for example (1, Signal 1), (2, Signal 2)..., (5, Signal 5) to enumerate the priority for cyclone.
'Event Code' : This is the code(key) for the particular event.
The 'Name' here refers to the name of the priority. for example, Typhoons in Philippines have five priority name (PSWS# 1, PSWS# 2, PSWS# 3, PSWS# 4 and PSWS# 5)

The 'Event Type' is the name of the standard Eden Event Type . These are available at /eden/event/event_type (The 'Event Type' should be exactly same as in /eden/event/event_type - case sensitive). For those events which are not in /eden/event/event_type but having the warning priority, you can create the event type using /eden/event/event_type/create. For those events that does not have warning priority, you can use Event Type as 'others' and this will use the default options for priority (Urgent, High and Low) - value for Urgency, Severity and Certainty can be viewed at /eden/cap/warning_priority. You can change them.

The 'Urgency' value can be one of:

• "Immediate" - (meaning) Responsive action SHOULD be taken immediately
• "Expected" - (meaning) Responsive action SHOULD be taken soon (within next hour)
• "Future" - (meaning) Responsive action SHOULD be taken in the near future
• "Past" - (meaning) Responsive action is no longer required
• "Unknown" - (meaning) Urgency not known

The 'Severity' value can be one of:

• "Extreme" - (meaning) Extraordinary threat to life or property
• "Severe" - (meaning) Significant threat to life or property
• "Moderate" - (meaning) Possible threat to life or property
• "Minor" – (meaning) Minimal to no known threat to life or property
• "Unknown" - (meaning) Severity unknown

The 'Certainty' value can be one of:

• "Observed" – (meaning) Determined to have occurred or to be ongoing
• "Likely" - (meaning) Likely (p > ~50%)
• "Possible" - (meaning) Possible but not likely (p <= ~50%)
• "Unlikely" - (meaning) Not expected to occur (p ~ 0)
• "Unknown" - (meaning) Certainty unknown

The 'Color Code' is the color for the priority, for eg. for priority 1, the color code could be 'red'.
'Name' along with 'Urgency', 'Severity' and 'Certainty' are compulsory field.

There are two ways to create the Warning Priority for a particular Event Type

a) The first way is through CSV file. In the browser address bar, go to /eden/cap/warning_priority/import (or /sambro/cap/warning_priority/import [a/c to the app name]). There you can see Download Template link. Click on that, and it will be downloaded. If you open up that csv, you will see different columns. The meaning is explained above. Now fill in the csv file. Click Choose File. Go to the csv file that you filled and click Submit.

If everything, goes right you will see something like image below (i.e. without any warning/ error in the error column). Click on Import and its done.

If the value does not match the referred value above on any column or the type does not match or any other mistake can cause some error in the data import (may look as image below). You may want to go to csv file to check or just click Import, that will import the records without error and ignore those records with error.

b) The next way to create Warning Priority is to go to /eden/cap/warning_priority/create. Fill the information as explained above and click Save button at the end.

Onset

In your Eden directory, go to models/ and open 000_config.py. Below the Identifier setting (as explained above), you will see

# Change this for the offset period in days that the alert will be effective for
# Expire Date = Effective Date + expire_offset
# Default is 2 days
#settings.cap.expire_offset = 2

This parameter is maintained to assign the default period to offset the expiry date; i.e. effective + expire_offset. The default is 2 days. You can change the number of the period. With the offset, we trying to help speed up the data entry.

Map Area Display Options

The default elements used while importing from CAP XML are "polygon" and "geocode". If you want to change the default behavior, go to the config file of your country implementation and change the list for the setting settings.cap.area_default = ["your_choice"]
for example, the default settings for the Philippines implementation is importing by "geocode" which can be found at /SAMBRO/PH/config.py as

    # Default location from geocode
    settings.cap.area_default = ["geocode"]

Setting up SMS gateway

Go to Administration -> Settings. On the left panel, you will see a number of Settings including the SMS Settings. We would be using WebAPI channels as it is easier to setup and use. If you are planning to use other such as hardware-based, etc. then refer to this wiki.

• Click on the SMS WebAPI Channels
• Click to create a new channel or edit the existing one.
• There are many providers like ​Clickatell, ​Cardboardfish, ​TextMagic etc. that can be used.
• Put in the appropriate values for the URL, Parameters, Message variable, To variable, etc.

For example, for Clickatell the values are

URL: https://api.clickatell.com/http/sendmsg
Parameters: user=yourusername&password=yourpassword&api_id=yourapiid
Message variable: text
To variable: 480

• After saving, Click on SMS OUTBOUNDS GATEWAYS. There could be a number of channels for the SMS but the Gateway define which one to use. Click to create a new gateway and select the appropriate Channel that you want to use along with the Default Country Code for the SMS. Click Save.
• Add your phone number and test by using url /eden/msg/compose.

Setting up Twitter Account

SAMBRO lets you post your alerts on twitter automatically without having to copy-paste again.

• Get the authentication details for Twitter by signing in to ​https://apps.twitter.com
  • Create New App
  • Create an Access Token in the Keys and Access Tokens tab
• Go to Administration -> Settings. On the left panel, you will see a number of Settings including the Twitter Channels. Click on it.
• Click on Add Twitter Channel. Fill out the details along with the Twitter Account, Consumer Key, Consumer Secret, Access Token, Access Token Secret. You have to check the Use for Login? to be able to be post on the twitter. Click Save.

Setting up Facebook Account

SAMBRO lets you post your alerts on facebook automatically without having to copy-paste again. But remember the setting for Facebook might change with time. So keep an eye on the official documentation.

• Get the app id and app secret for facebook app by signing in to ​https://developers.facebook.com/apps
  • Create New App
  • Get the APP ID and APP SECRET on the app page.
  • We will use Facebook's official Graph API to get the access token for the page and its id.
  • Go to ​https://developers.facebook.com/tools/explorer/, and from the drop-down on the right side, choose the page that you would like to use. Use me?fields=id,name in the GET field to get the ID of the page. The Access token is displayed there.

• Go to Administration -> Settings. On the left panel, you will see a number of Settings including the Facebook Channels. Click on it.
• Click on Add Facebook Account. Fill out the details along with the App Id, App Secret, Page ID, Page Access Token. Click Save.
• However, this token is only valid for 2 hours. Use the info available ​here and ​here to get the token that lasts for 60 days. You cannot get the everlasting token.
• For page permission, give it at least the following permission.

• In exchange for short-lived tokens you can get the long-lived token (60 days) by using the URL as:

    GET /oauth/access_token?  
        grant_type=fb_exchange_token&           
        client_id={app-id}&
        client_secret={app-secret}&
        fb_exchange_token={short-lived-token}

More info is available here: ​https://developers.facebook.com/docs/facebook-login/access-tokens/expiration-and-extension

• You can check your access token expiry date here: ​https://developers.facebook.com/tools/debug/accesstoken/

• Finally it should look something like this

Subscribe to External CAP Feed

You can subscribe to External CAP Feed through SAMBRO.

• Log in as administrator.
• From menu, go to Administration -> Settings.
• On the left side, you can see several menu items including RSS CHANNELS.
• Click on Create RSS Feed for CAP.
• Grab the External CAP Feed URL. eg. You can use this Myanmar Public Feed URL ​http://www.dmhwarning.gov.mm/eden/cap/public.rss
• Give a name and paste the URL into the URL/Link button.
• Wait for sometime for SAMBRO to grab the link.
• These alerts are the external alerts and can be viewed through the menu Alert Hub or go to /eden/cap/alert?~.external=True to view the datalist.

Other