Connecting the CAP Composer with a wis2box

Overview

The Common Alerting Protocol (CAP) is a simple but general format for exchanging all-hazard emergency alerts and public warnings over all kinds of networks, see the full specification here.

This section provides guidance one how one can use the CAP Composer to automate the publishing of CAP alerts to a wis2box.

Requirements

In addition to a running wis2box, you will need to install, configure, and run the CAP Composer.

Note

For information on how to do this, please consult the CAP Composer documentation.

Process Outline

For automated publishing of CAP alerts created by the CAP Composer to a wis2box, we will need to perform the following steps:

  1. Dataset Creation: Configure the dataset in wis2box to store the CAP alerts.

  2. MQTT Configuration: Configure your wis2box broker details in the CAP Composer.

Dataset Creation

Firstly, there must be a dataset in wis2box for the CAP alerts to be stored. To create a dataset, simply navigate to the ‘Dataset Editor’ page in wis2box-webapp, available on your host at http://<your-public-ip>/wis2box-webapp.

Note

For more information on how to create a dataset, please see the Adding datasets section of the wis2box setup guide.

When creating a new dataset for CAP alerts, ensure that the weather/advisories-warnings template is selected:

Select Template

This template will use the ‘CAPMessageData’ data plugin, see more information on this plugin in the wis2box.data.cap_message.CAPMessageData section of the data pipeline plugins documentation.

Enter the relevant missing information and create the dataset using your processes/wis2box token.

Submit Dataset

Now the dataset is created, note down the dataset ID, as it will be required in the next step.

MQTT Configuration

Begin by logging in to the CAP Composer.

Note

We will assume that you have the necessary admin rights to configure the CAP Composer. If you do not, please contact your CAP focal point.

Navigate to ‘CAP Alerts’, then ‘MQTT Brokers’ in the left-hand menu.

MQTT Brokers Menu

Click on the ‘Add MQTT Broker’ button in the top-right corner to add a new broker. You should see the following form:

MQTT Broker Configuration

Here, we should fill the following fields:

  • Name: A name for the broker.

  • Host: The WIS2BOX_BROKER_HOST environment variable from the wis2box configuration.

  • Port: The WIS2BOX_BROKER_PORT environment variable from the wis2box configuration.

  • Username: The WIS2BOX_BROKER_USERNAME environment variable from the wis2box configuration.

  • Password: The WIS2BOX_BROKER_PASSWORD environment variable from the wis2box configuration.

  • WIS2 Node: Confirmation that the MQTT broker is a WIS2 node (defaults to True).

  • Dataset ID: The dataset ID of the dataset created in the previous step.

Once you have filled in the form, click the Save button to save the broker configuration.

You will be redirected back to the ‘MQTT Brokers’ page, where you should see the newly added broker.

MQTT Broker List

Publishing an Alert

Let’s begin by creating a CAP alert. This can be done by navigating to ‘CAP Alerts’, then ‘Alerts’ in the left-hand menu, and clicking the Add Alert button in the top-right corner.

Alerts Menu

Note

For more information on how to create a CAP alert, please see the CAP Composer documentation on creating alerts.

Once the alert is finished, if you are a CAP approver you should see a Publish button at the bottom:

Publish Alert

On clicking the Publish button, the alert XML file will automatically be created, signed, and published to your wis2box.

Note

If you are a CAP composer, you will only be able to submit the alert for moderation. It is then the responsibility of the CAP approver to approve and publish the alert.

You can view the status of the published alert in the ‘CAP Alerts’, then ‘MQTT Broker Events’ section of the CAP Composer.

MQTT Event List

Additional diagnostic information can be found by clicking the Inspect button.

Verifying Receipt of a Published Alert and Viewing the Alert

We can verify that the alert has been successfully published to wis2box by monitoring the dataset in wis2box-webapp.

Navigate to the ‘Monitoring’ page in wis2box-webapp, and select the dataset that you created in the previous steps.

Note

If you do not see the dataset, ensure that the datetime range selected includes the time of the alert publication.

Monitoring Dashboard

Provided the publication was successful, you will see a bar in the ‘Notifications’ section. If you scroll down to the ‘Published Data’ section, the signed and verified CAP alert should appear in the table to download and view.

Published Data

On clicking the View Alert button, you should see a visualization of the CAP alert you created earlier.

View Alert

Congratulations! You have successfully published a CAP alert to a wis2box using the CAP Composer.