Integrating CAP and Carousel
So you want to integrate your alerting software with Carousel. Carousel has had the ability to respond to properly formed CAP messages since Carousel 6. Now, with Carousel 7, you have the added benefit of a much easier to use CAP configuration and testing interface. To get started, lets go over some of the basics.
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 HTTP POST to a URL like
http://your_carousel_server/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 token is used for security purposes and must match the token set in the Carousel UI. The setup page can be found at: http://your_carousel_server/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.
Lets 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.
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 are 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 set the global CAP token, see what CAP messages have been received and when, do some testing, and get the URL you should use for CAP POSTs.
Configure your CAP Token
The CAP token is a security token to ensure that incoming CAP messages are authenticated in some way. The value is used in the URL that CAP messages are POSTed to. This setting is global, so if you have already configured CAP services outside of Carousel, do not change it or those integrations will stop working.
Choose Tags to Target
Choose what bulletin tags you wish to target. These should match the tags we tagged our bulletin with. Once you've chosen a tag, the URL For This Test will contain the URL that you should use to POST CAP messages at.
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.