capeditor 0.4.2

Wagtail based CAP Editor

CAP Editor

A Wagtail Commmon Alerting Protocol (CAP) Editor python package installable as an app on any wagtail project ( version>=4.1).

The Common Alerting Protocol (CAP) provides an open, non-proprietary digital message format for all types of alerts and notifications. It does not address any particular application or telecommunications method. The CAP format is compatible with emerging techniques, such as Web services, as well as existing formats including the Specific Area Message Encoding (SAME) used for the United States' National Oceanic and Atmospheric Administration (NOAA) Weather Radio and the Emergency Alert System (EAS)

The CAP xml response follows the structure of the schema provided at http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html

Contents

• CAP Editor
  • Features
  • Quick start
  • Usage
    • Creating a CAP Alert
    • Sections in the Alert Page and corresponding XML
      • A. Alert Identification
      • B. Alert Info
      • C. Alert Area
      • D. Alert Resource
  • Integrations

🌟 Features

• Modern user-friendly editor that follows CAP 1.2 standard. Built on top of the awesome Wagtail CMS
• Preview your CAP alert page as you edit. Save drafts for sharing with colleagues and collaborating
• Inbuilt CAP validation. The page will not save if you have not input the required data according to CAP standard
• User-friendly alert area map editor that allows multiple ways of constructing alert geographic areas, while keeping the interface simple
  • Select country official administrative boundaries for different levels (Admin 1, Admin 2, Admin 3), with in-built simplification of complex boundaries
  • Draw a polygon
  • Draw a circle
  • Use Geocode key values
• Inbuilt publishing workflow using Wagtail's powerful page model, with automated emails to composers and approvers
• Collaborate with team members using inbuilt comments (similar to how you could do in Word) with automated notifications. Request for changes and approvals
• Publish realtime notifications/messages to third party integrations using MQTT messaging protocol
• Predefine a list of hazards types monitored by your institution, with intuitive icons from OCHA humanitarian icons
• Extendable to add your custom logic and functionality. The package provides an abstract django model that can be inherited for customizations. It is all python code.
• It is all open-source 🥳!

Quick start

1. Install in virualenvironment using pip

pip install capeditor

2. Configure settings

In your settings.py or settings/base.py, within the installed apps, include the rest_framework, rest_framework_xml and capeditor as below:

INSTALLED_APPS = [
    # ...
    'rest_framework',
    'rest_framework_xml',
    'capeditor'
]

Set up restframeworkxml renderers

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework.renderers.JSONRenderer',
        'rest_framework_xml.renderers.XMLRenderer',  # add XMLRenderer
    ),
    'DEFAULT_PARSER_CLASSES': (
        'rest_framework_xml.parsers.XMLParser',
    ),
}

3. Run model migrations

python manage.py migrate

Usage

Creating a CAP Alert

With capeditor successfully installed, both the Alert Listing page and Alert Detail page will be available on wagtail admin interface.

- AlertList
   |_ Alert 1
   |_ Alert 2

Create an Alert Listing Page by adding it as a child page and specifying the title of the page. This page will host a list of all alerts created.

Create one or more Alert Page by adding it as a child to the Alert Listing Page

---

Sections in the Alert Page and corresponding XML

The overall Document Object Model of an alert is as below:

A. Alert Identification

This is the root section of CAP corresponds to:

<alert>
    <!-- ... -->
</alert>

It contains the Message ID (identifier), Sender ID(sender), Sent Dat/Time (sent), Message Status (status), Message Type (msgType), Scope (scope), Restriction (restriction), Addresses (addresses), Note (note), Reference IDs (references) and Incident ids ( incidents).

NOTE: Some fields are visible based on selection of different parameters.

B. Alert Info

This is an optional child section of the Alert Identification Section i.e

<alert>
    <!-- ... -->
    <info></info>
    <info></info>
</alert>

Multiple instances of this section are allowed. It contains the Langauge (langauge), Event Category/Categories (category), Event Type (event), Response Type/Types (responseType), Urgency (urgency), Severity (severity), Certainty (certainty), Audience (audience), Event Code/Codes (eventCode), Effective Date/Time (effective), Onset Date/Time (onset), Expiration Date/Time (expires), Sender Name ( senderName), Headline (headline), Event description (description), Instructions (instruction), Information URL (web), Contact Info (contact) and Parameter/Parameters (parameter).

C. Alert Area

This is an optional child section of the Alert Info Section i.e

<alert>
    <!-- ... -->
    <info>
        <area></area>
        <area></area>
    </info>
    <info>
        <area></area>
    </info>
</alert>

Multiple instances of this section are allowed. It contains the Area Description (areaDesc), Area Polygon/Polygons ( polygon), Area Circle/Circles (circle), Area Geocode/Geocodes (geocode), Altitude (altitude), Ceiling (ceiling).

D. Alert Resource

This is an optional child section of the Alert Info Section i.e

<alert>
    <!-- ... -->
    <info>
        <resource><resource>
        <resource><resource>
        <area></area>
        <area></area>
    </info>
    <info>
        <resource><resource>
        <area></area>
    </info>
</alert>

Multiple instances of this section are allowed. It contains the Description (resourceDesc), MIME Type (mimeType), File Size (size), URI (uri), Dereferenced URI (derefUri) and Digest (digest)

Integrations

To integrate the alerts to another wagtail page and include in templates, for example in the home page refer to sandbox folder for sample standalone.

MQTT Integration

You can publish a mqtt message immediately after a CAP alert has been published. This allows connected clients to receive the CAP message using the MQTT protocol.

You will need to setup a MQTT broker. We have included the docker configuration to setup a local broker instance using Eclipse Mosquitto

You need to add a CAP_BROKER_URI setting to your settings.py which should be the URI to a MQTT broker with permissions to publish messages.

Then using Wagtail page_published signal or Wagtail after_publish_page hook, you can attach a function to publish the MQTT message.

Below is a sample snippet to achieve this in your models.py

# models.py
from wagtail.signals import page_published

from capeditor.models import AbstractCapAlertPage
from capeditor.pubsub.publish import publish_cap_mqtt_message


class CapAlertPage(AbstractCapAlertPage):
    ....


def on_publish_cap_alert(sender, **kwargs):
    instance = kwargs['instance']

    topic = "cap/alerts/all"

    publish_cap_mqtt_message(instance, topic)


page_published.connect(on_publish_cap_alert, sender=CapAlertPage)

Using the sample above, once a CAP Alert Page has published, a corresponding mqtt message will also be published immediately.

You will need to decide how to structure your MQTT alert topics.

You can have a complete look at the code under sandbox/home/models.py