Carousel Academy

Articles in this section

Carousel Cloud and CAP (Common Alerting Protocol)

  • Updated

Please Note:

  • The CAP setup menu in Carousel Cloud is located in the Configure>System>CAP Configuration menu

  • Due to the nature of CAP, only standard template/text-based bulletins can be triggered using CAP

  • We recommend using full screen alert zones for emergency messaging. While CAP can also trigger bulletins in other zones, full screen alerts are our primary focus and are treated as a critical development priority. Please refer to this article for general information regarding alerts and also how to attach a full screen alert zone to a channel in Carousel Cloud

  • If you’re looking for additional pre-created templates for CAP usage, visit our Creator Library, and then download and import any of the provided templates

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>‍

As shown below, CAP message nodes can consist of the following: identifiers, timestamp, message status, message type, message scope, and an info block, containing other data nodes.

<?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>

How CAP Messages are Used in Carousel Cloud

CAP messages incoming to Carousel Cloud are received via HTTPS POST from a CAP POST URL such as:

‍https://***.carouselsignage.net/CarouselAPI/v1/CAP?token=my_token&tags=my_tag,your_tag

This CAP message activates bulletins that have matching tags from the list at the end of the URL, as noted above, and the message will populate any text blocks with the data from XML nodes included in the CAP message ‘info’ node.

For the purposes of implementing CAP in Carousel Cloud, you only need to be concerned with the data in the ‘msgType’ and any of the nodes contained inside the 'info' node.  The info node contains all of the data that could populate our bulletin's text blocks.

Please note:

  • When sending CAP alerts, the content header must be included for the request to be recognized by Carousel Cloud. Use Content-Type: application/xml header

  • The ‘msgType’ node cannot be “Test” if you're going to actually trigger content in Carousel Cloud

How Do I Set Up a Bulletin for CAP?

You need to have bulletins pre-created in Carousel Cloud for your various incoming CAP messages. For the purpose of this article, we will assume that you only want to create a general-purpose bulletin, to be triggered in the event that an incoming CAP message is received. If you need to include more scenarios, then repeat these steps for each version of incoming CAP messages you intend to use or need on standby.

  1. In a full screen alert zone, choose an existing 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

  2. A templated bulletin will need to have a text block for each node of the CAP message that you want data from. The CAP standard requires all compliant messages to have an ‘EVENT’ and a ‘DESCRIPTION’ node.

    1. To align with this requirement, make sure that your bulletin has a text block named 'Event' and one named 'Description'

    2. The actual text that is contained within these text blocks will be replaced with the text from your CAP message

  1. As shown below, leave the schedule as ‘Always Active' but uncheck all of the 'Daily Availability’ days

    1. When deselecting all of the availability days, this will put the bulletin in the ‘Upcoming’ bulletins category and will not activate or display until you trigger it with a CAP message

  1. Next, you will need to add a ‘tag’ to the bulletin

    1. Tags are how the system knows which bulletins to target. You should use a unique tag for your CAP messages so there isn’t any overlap with other tagged bulletins

  1. Navigate to the CAP settings page in the Carousel Cloud UI at Configure>System>CAP Configuration

    1. Here you can enable CAP, see logs of CAP messages, do internal CAP testing, and find the CAP POST URL to use in your third-party notification system

  2. Choose what bulletin tags you want to target to generate the CAP POST URL

    1. This will direct the CAP commands at the bulletin tags you've selected

  3. Once you have added your desired tags, use the CAP POST URL in your third-party notification system

  1. For testing, you can trigger a CAP message from your third-party system or paste the XML from your system into the text box on screen and test using the Carousel Cloud CAP page

  2. If working correctly as shown below, you should see a newly sent CAP message appear in the list of received CAP messages, and also receive indication that bulletin/s in Carousel Cloud were changed as well

Additional Notes

  • Bulletins triggered by CAP can be disabled manually in their respective zones in Carousel Cloud, or they can be disabled by sending a CAP message to the CAP POST URL with the text ‘CLEAR' in either the 'event' or ‘description’ XML nodes inside the 'info’ node

  • When using a third-party notification system:

    • If you’re having issues triggering CAP messages when using a third-party notification system, please ensure the XML nodes in that system are formatted correctly for use in Carousel Cloud

    • To help isolate an issue when content isn’t changing as expected when using a third-party CAP system, test CAP directly within Carousel Cloud first, and confirm content is changing as expected. If the content is changing as expected within Carousel Cloud, but there are no logged attempts from your third-party system to trigger CAP alerts, please direct support requests in this stage of the process to your CAP vendor for initial troubleshooting

Related articles