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">
    <event>SEVERE THUNDERSTORM</event>
    <headline>SEVERE THUNDERSTORM WARNING</headline>

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
Dynamic Instagram via third-party API Intergration
Viewed 1578 times since Thu, Apr 20, 2017
What features of Carousel require a Multicast enabled network?
Viewed 2314 times since Tue, Oct 4, 2016
Disabling RDA
Viewed 401 times since Thu, Mar 22, 2018
Changing the Hostname of Carousel server breaks bulletin rendering
Viewed 2548 times since Tue, Feb 17, 2015
I get an error that "There is insufficient memory in resource pool "internal" to run this query."
Viewed 1945 times since Fri, Sep 11, 2015
Carousel Access Rights in 7.3: what you need to know
Viewed 640 times since Tue, May 1, 2018
Unable to locate Stored Procedures
Viewed 276 times since Tue, Sep 13, 2016
About Tightrope’s software version numbers
Viewed 4230 times since Wed, Dec 17, 2014