YOUR STORY PLAYS HERE
Home » Categories » Multiple Categories

CAP integrations with Carousel 7

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 didnt 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.

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.

0 (0)
Article Rating (No Votes)
Rate this article
  • Icon PDFExport to PDF
  • Icon MS-WordExport to MS Word
Attachments Attachments
There are no attachments for this article.
Related Articles RSS Feed
Can I have a separate SQL server for FrontDoor/Carousel?
Viewed 2013 times since Thu, Nov 13, 2014
Carousel for Apple TV Media Constraints
Viewed 966 times since Thu, Jun 22, 2017
Changing the Hostname of Carousel server breaks bulletin rendering
Viewed 2242 times since Tue, Feb 17, 2015
Carousel Does Not Load when Logged in with Usernames that Contain Periods
Viewed 550 times since Mon, Sep 18, 2017
Choosing a player
Viewed 1037 times since Fri, Sep 8, 2017
Locating my hardware license key
Viewed 4810 times since Wed, Sep 17, 2014
Carousel for BrightSign version 2.1.1 is Released
Viewed 1475 times since Fri, Nov 18, 2016
How do I backup my Carousel server?
Viewed 3222 times since Mon, Sep 22, 2014