Integrating CAP and Carousel
So you want to integrate your alerting software with Carousel. Carousel has the ability to respond to properly formed CAP messages using an easy to use CAP configuration and testing interface. To get started, let's go over some of the basics. CAP is a standard used by many notification systems like Alertus and Syn-Apps Revolution
How CAP messages are turned into Carousel Bulletins
The tldr; (too long didn't read) version of this is that incoming CAP messages sent via HTTPS POST to a CAP POST URL like:
https://***.carouselsignage.net/CarouselAPI/v1/CAP?token=my_token&tags=my_tag,your_tag
will activate bulletins that are tagged with tags that match the tag list in the URL and populate any text blocks with the data from XML nodes in the CAP message info node who's node name matches the text blocks name. The setup page can be found at: http://***.carouselsignage.net/Carousel/settings/system/CAP.
Bulletins triggered by CAP can be disabled manually in the UI, or they can be disabled by sending a CAP message to the same URL with the text CLEAR in either the event or description XML nodes inside the info node.
Let's go through that information in more detail.
What is CAP?
Common Alerting Protocol is an international standard for exchanging emergency alert information. CAP messages are transmitted in XML format. The XML message contains XML nodes that define the message. A node is defined by an opening and closing tag surrounding node data like this: <nodeName>Node Data</nodeName>
CAP message nodes consist of the following: identifiers, a timestamp, message status, message type, message scope, and an info block containing other data nodes. An example message is shown below.
<?xml version = "1.0" encoding = "UTF-8"?>
<alert xmlns = "urn:oasis:names:tc:emergency:cap:1.2">
<identifier>KSTO1055887203</identifier>
<sender>KSTO@NWS.NOAA.GOV</sender>
<sent>2003-06-17T14:57:00-07:00</sent>
<status>Actual</status>
<msgType>Alert</msgType>
<scope>Public</scope>
<info>
<category>Met</category>
<event>SEVERE THUNDERSTORM</event>
<responseType>Shelter</responseType>
<urgency>Immediate</urgency>
<severity>Severe</severity>
<certainty>Observed</certainty>
<expires>2003-06-17T16:00:00-07:00</expires>
<senderName>NATIONAL WEATHER SERVICE SACRAMENTO CA</senderName>
<headline>SEVERE THUNDERSTORM WARNING</headline>
<description> AT 254 PM PDT...NATIONAL WEATHER SERVICE DOPPLER RADAR INDICATED A SEVERE THUNDERSTORM OVER SOUTH CENTRAL ALPINE COUNTY...OR ABOUT 18 MILES SOUTHEAST OF KIRKWOOD...MOVING SOUTHWEST AT 5 MPH. HAIL...INTENSE RAIN AND STRONG DAMAGING WINDS ARE LIKELY WITH THIS STORM. </description>
<instruction>TAKE COVER IN A SUBSTANTIAL SHELTER UNTIL THE STORM PASSES.</instruction>
</info>
</alert>
For our purposes, we only need to be concerned with the data in the msgType and any of the nodes inside of the info node. The msgType node cannot be Test if you're going to actually trigger content. The info node contains all of the data that could populate our bulletin's text blocks.
Important note!
When sending CAP alerts, the content header must be included for the request to be recognized by Carousel. Use Content-Type: application/xml header
How Do I Set Up a Bulletin for CAP?
We need to have these bulletins pre-created for our various incoming CAP messages. For our purposes, we will assume that we only want to create a general purpose bulletin to be triggered in the event that an incoming CAP message is received. If your scenario is more complex, then repeat these steps for each variety of incoming CAP message.
**Please note - Due to the nature of CAP, Only Standard Template/Text based bulletins can be triggered using CAP.**
Create a New Bulletin from a Template
Choose a template or create a new one that matches the layout and design of the kind of bulletin you want to use to display the incoming CAP message.
Customize the Bulletin Layout
We are going to need the bulletin to have a text block for each node of the CAP message that we want data from. CAP follows a standard so all compliant messages will have an EVENT and a DESCRIPTION node. Let's start there.
We will make sure that our bulletin has a text block named 'event' and one named 'description'. It isn't important the actual text that is contained within them at the moment as that text will be replaced with the text in our CAP message.
The rest of the bulletins look and feel are completely up to your creative impulses. The only thing that is imperative is that we name the appropriate text blocks correctly.
Schedule the Bulletin
Since we don't want this bulletin to display immediately, we are going to leave the schedule as Always Active but uncheck all of the Daily Availability days.
Settings and Tags
Now go to the Settings tab and make this bulletin an Alert if its not being created in a Full Alert zone. After all, we want to ensure that this bulletin is displayed immediately when its created.
The last thing we want to do before publishing is to Tag the bulletin with a semi-unique tag. You'll notice in the initial example the URL contained a list of tags. These tags are how the system knows which bulletins to target, so you shouldn't have any bulletins that you don't want triggered to share the tag or tags you apply.
Publish the Bulletin
Since we de-selected all of the availability days, this bulletin will remain in upcoming bulletins and will not display until we trigger it with a CAP message.
Configure and Test CAP in Carousel
Navigate to the CAP settings page in the Carousel UI at Configure > System > CAP. Here you can enable CAP, see what CAP messages have been received and when, do some testing, and get the CAP POST URL to use in your notification system.
Choose Tags to Target
Choose what bulletin tags you wish to target to generate your CAP POST URL. This will direct the CAP commands at the bulletin tags you've selected above. Once you have added your desired tags, use the CAP POST URL in your notification system.
Test Your CAP Message
You can trigger a CAP message from your external system or paste the XML from your system into the text box on screen and test using the UI. Either way you should see the newly sent CAP message appear in the list of received CAP messages and get some indication of if bulletins were triggered, or if there were errors.
Disabling Triggered CAP Bulletins
Bulletins triggered by CAP can be disabled manually in the UI or, they can be disabled by sending a CAP message to the same URL with the text CLEAR in either the event or description XML nodes inside the info node.