How to Set Up Emergency Alerting with a CAP Feed
Emergency alerting affects what every matching screen shows. Test the whole setup on a few test devices before you connect it to a production feed.
This guide shows you how to make devices switch to emergency content automatically when an alert arrives in a CAP (Common Alerting Protocol) feed, and switch back when the alert is no longer active. It also covers turning emergency state on and off by hand and by webhook.
How emergency state works
Every device has an emergency state, which is either on or off.
- Off: the device plays its normally assigned Content.
- On: the device plays its emergency content instead. If the device has no emergency content assigned, it shows the default emergency screen.
You can turn emergency state on in three ways:
| Method | Best for |
|---|---|
| By hand, on the device | Drills, or one-off incidents |
| A Device Action (webhook) with Enable emergency / Disable emergency | Another system, such as a fire panel or building management system, decides when to switch |
| A CAP datasource with Automatically show alerts on devices turned on | Public alert feeds or alerting platforms that publish CAP |
Step 1: Prepare the emergency content
- Create the Content, Slide or Playlist you want to show during an emergency.
- Assign it to the devices as emergency content. Learn more: Assign Emergency Content
Emergency content only appears while the device's emergency state is on. Assigning it changes nothing on screen by itself.
Step 2: Tag your devices
Tags decide which devices react to which alerts. Add tags that the alert feed can refer to, for example a tag per building or area (building-a, north-campus).
Learn more: Tags
Step 3: Create the CAP datasource
- Go to Datasources and add a new External datasource of the CAP type.
- Choose how the system checks for alerts:
- Scheduled checking (Poll): the server fetches the feed URL on a schedule.
- Real-time alerts (Callback): your alerting system pushes alerts to Wallboard through a Datasource Action.
- For Scheduled checking (Poll), enter the Emergency alert feed URL, and set how often to check.
- Set Fallback alert duration (minutes) (in callback mode: How long to show alerts (minutes)). This is used only for alerts that have no expiry time of their own; after it passes, the alert is removed.
Learn more: CAP datasource for Alert details path (advanced), Advanced caching and callback setup.
Step 4: Decide which devices an alert affects
Option A: every device reacts to every alert
Leave Match devices by tags off. When Automatically show alerts on devices is on (Step 5), any active alert in the feed turns emergency state on for every device in scope, and an empty feed turns it off.
Option B: alerts name the devices they affect
Use this when the feed is built for your installation and its alerts carry your device tags.
- Turn on Match devices by tags in the Device identification section.
- Set Tag attribute: the CAP field that holds the tags. Options: Addresses, Audience, Area desc, Note, Code.
- Set Tag separator: the character between tags in that field. Leave it empty to split on spaces.
- Set the matching rule:
- Any match: a device switches on if it has at least one of the alert's tags.
- All match: a device switches on only if it has every tag in the alert.
Tag matching ignores upper and lower case.
Standard public feeds do not contain your device tags. Option B needs a feed, or a feed generator, made for your installation. ❓ Confirm with John Macan which customer feeds are known to work.
Step 5: Turn on automatic emergency state
- In the Emergency state management section, turn on Automatically show alerts on devices.
- Optional: in Only affect devices with this tag, enter one tag to limit which devices the feed can switch. Leave it empty to include every device of the customer.
- Save the datasource.
On every refresh, the system sets emergency state on each device in scope to match the feed: on where an active alert matches, off everywhere else. A device you switched on by hand will be switched off again at the next refresh if no active alert matches it.
Use Only affect devices with this tag to keep devices you control by hand, or by webhook, out of the feed's reach.
How alerts are timed
- An alert with an effective time in the future does not switch devices on until that time.
- An alert is removed once its expires time has passed. Alerts without one use the fallback duration from Step 3.
- When the last matching alert is gone, the next update switches the devices back to their normal Content. ❓ Confirm how soon after expiry this happens in poll mode (the service schedules a one-time refresh at the expiry time, but this has not been tested end to end).
Taking alerts down by hand
The Clear CAP Datasource Action removes one alert or all alerts from a CAP datasource, for example when an emergency is over. Learn more: CAP datasource
Switching by webhook instead of a feed
If your building system cannot publish CAP but can call a URL, create two Device Actions:
- Enable emergency and Disable emergency.
- Choose the target: all devices, one device, a device group (folder), or a device tag.
- Have the external system call the action's URL with an API key.
Learn more: Device Actions
Showing the alert text on screen
The CAP datasource holds the alerts it has fetched, so your emergency content can bind to it and show, for example, the alert headline. ❓ The data structure exposed to Widgets (field names such as headline, description, area) has not been verified; check it in the datasource preview before writing this section.
Checklist before going live
- Every device in scope has emergency content assigned, or you accept the default emergency screen.
- Device tags match what the feed sends.
- Only affect devices with this tag is set if some devices must stay under manual control.
- You tested with a test alert, and the devices switched back afterward.
Related articles
- Learn more: CAP datasource
- Learn more: Assign Emergency Content
- Learn more: Device Actions