Carousel Cloud and CAP (Common Alerting Protocol)

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.

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 section, we will assume that you want to create a templated bulletin, that can be populated with custom text, to be triggered by CAP. If you need to include more CAP usage scenarios, 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

   1. If you’re looking for ready-to-go pre-created templates for CAP usage, visit our Creator Library, and then download and import any of the provided templates

2. A templated bulletin (that can be populated with custom text) will need to have a text block for each node of the CAP message that you want to display. 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

      

3. 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 tab, and it will not activate or display until you trigger it with a CAP message

      

4. In the Extras tab, 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

      

5. Click the orange Publish button in the upper right to save your changes and put the bulletin in the Upcoming tab

6. Now that you have a bulletin ready to activate using CAP, navigate to the CAP settings page in Carousel Cloud > 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

Testing CAP within Carousel Cloud

1. Verify the Enable CAP? toggle is set to Yes

2. In the Target Bulletin Tags dropdown, choose the bulletin tag/s you want to target

   1. This will direct the CAP commands to the bulletin tag/s you've selected

      

3. Click the orange Test CAP Message button to tell Carousel Cloud to activate your targeted bulletin/s using CAP

   

4. If working correctly, you will see a log entry created under the Received CAP Messages heading indicating that at least 1 bulletin was targeted, and at least 1 bulletin was changed, with no errors

   

5. If there are reported errors, please review the information in this section, and also in the section above called How Do I Set Up a Bulletin for CAP? to ensure you have a working configuration

Testing CAP with a Third-Party System

1. Verify the Enable CAP? toggle is set to Yes

2. In the Target Bulletin Tags dropdown, choose the bulletin tag/s you want to target

   1. This will direct the CAP commands to the bulletin tag/s you've selected

      

3. Copy the CAP POST URL

   

4. Use the CAP POST URL in your third-party system to trigger CAP in Carousel Cloud.

   1. The example shown below is using the InformaCast Outbound CAP Endpoint Details settings page

      

   2. If CAP XML is available from your third-party system, you can also copy and paste the CAP XML from your third-party system into the text box on screen (screenshot) and test using the Carousel Cloud CAP page

      

5. If working correctly, you will see a log entry created under the Received CAP Messages heading indicating that at least 1 bulletin was targeted, and at least 1 bulletin was changed, with no errors

   

6. If there are reported errors or there are no logged entries for CAP messages when using a third-party CAP system, please review the information in this section, in the section above called How Do I Set Up a Bulletin for CAP?, and review the notes posted below to ensure you have a working configuration across all of the defined processes and systems

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 (such as CrisisGo, InformaCast, Raptor, Everbridge, Alertus, etc.):

  • 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