Triggers: Common Alerting Protocol (CAP) – Omnilert

Omnilert Scenarios can be triggered by the receipt of a Common Alerting Protocol (CAP) message via HTTPS POST.

This trigger will provide a simple URL that will listen for incoming CAP messages and trigger a scenario launch when/if a qualifying CAP message is posted.

An Omnilert CAP trigger can accept CAP-formatted XML as the content of HTTPS post and then use the content of that XML to launch (or not launch) a scenario. Scenario Actions can also use that content within their messages as variables. (see below)

Create a new CAP Trigger

To create a new CAP trigger, open the Scenarios Manager > Triggers and then click Add new trigger.

Then select the trigger type as "CAP".

Assign your new trigger a name and give it a description.

Then click Add trigger or Add trigger and make active to make the new trigger active immediately.

Configure the CAP trigger

Your new trigger will need some basic configuration to properly filter incoming CAP messages and launch an assigned Scenario.

Basic trigger info

You can set a Trigger name and Trigger description which should help you know what this trigger is for and be named accordingly.

The Trigger URL is the web address (URL) of the CAP listener for your trigger. This is the address that your external CAP message source will need to use for its HTTP POST operations.

CAP filtering

One of the key features is the ability to filter CAP messages to restrict what will and will not cause Omnilert to launch a scenario.

You can add multiple layers of filtering to restrict launch based on the incoming CAP messages' XML content.

Note: Many of the Common Alerting Protocol fields have standardized values that can be found in the Common Alerting Protocol (CAP) standard, found online at http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html

Using filters will make the trigger more selective over which messages will cause the linked scenario to send.

Linking to a Scenario

Of course, in order to function, your trigger must be linked to a Scenario. Visit the Scenarios tab within the trigger's screen and choose the appropriate scenario.

Be sure to click Update trigger to save any changes.

CAP Variables

CAP messages often contain useful content that you may wish to relay as part of your Scenario Actions.

Omnilert provides access to that content through the use of text variables. The incoming CAP message's XML can be passed along using the following variables:

CAP field	Text Variable
addresses	{{cap_addresses}}
altitude	{{cap_altitude}}
areadesc	{{cap_areadesc}}
audience	{{cap_audience}}
category	{{cap_category}}
ceiling	{{cap_ceiling}}
certainty	{{cap_certainty}}
circle	{{cap_circle}}
code	{{cap_code}}
contact	{{cap_contact}}
derefuri	{{cap_derefuri}}
description	{{cap_description}}
digest	{{cap_digest}}
effective	{{cap_effective}}
event	{{cap_event}}
eventcode	{{cap_eventcode}}
expires	{{cap_expires}}
geocode	{{cap_geocode}}
headline	{{cap_headline}}
identifier	{{cap_identifier}}
incidents	{{cap_incidents}}
instruction	{{cap_instruction}}
language	{{cap_language}}
mimetype	{{cap_mimetype}}
msgtype	{{cap_msgtype}}
note	{{cap_note}}
onset	{{cap_onset}}
parameter	{{cap_parameter}}
polygon	{{cap_polygon}}
references	{{cap_references}}
resourcedesc	{{cap_resourcedesc}}
responsetype	{{cap_responsetype}}
restriction	{{cap_restriction}}
scope	{{cap_scope}}
sender	{{cap_sender}}
sendername	{{cap_sendername}}
sent	{{cap_sent}}
severity	{{cap_severity}}
size	{{cap_size}}
source	{{cap_source}}
status	{{cap_status}}
urgency	{{cap_urgency}}
uri	{{cap_uri}}
web	{{cap_web}}

For more information about the fields provided with Common Alerting Protocol (CAP) v1.2, please see the CAP standard at http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html

For your convenience, these fields are also listed within the CAP trigger editor in your Omnilert admin portal.

How to add a text variable to an action

If you're new to creating and using Scenarios and Actions, please see the following articles and videos within this help center:

When composing a message in your Scenario actions, you can access fields passed by the CAP alert by inserting variables into your message.

Important notes to keep in mind:

Hide special scenarios from other admins: If your scenario is designed to be only triggered via CAP and includes CAP content, you won't want your admins launching it by hand or via the app. Set the scenario permissions accordingly.
Message length matters! When it come to SMS, messages should never exceed 160 characters or they will be truncated. Be sure to keep this in mind when inserting variables into your message content. If the variable content includes more characters than the variable's name, you need to account for this in your action's content.
Filtering is important! Be sure to test your CAP filters to make sure that only the desired messages will trigger a launch!
Beware of cascading triggers and infinite loops! If you are working with another site's admins to automate messaging between two accounts or services, be sure that you are not causing a feedback loop with your partner, causing your scenario to force a launch which in turn re-launches the original scenario! Omnilert will attempt to prevent such a loop, but such an issue could cause multiple deliveries or no message to send at all!

Cannot trigger from your own CAP/EAS feed. The CAP/EAS messages from your own account cannot be used to trigger scenarios within your own account. (This safeguard is designed to help prevent infinite looping issues.)
Expired CAP messages will be ignored. If the incoming CAP message's XML content has an expired date in the <expires> CAP field, the trigger will not launch.
Spam control: Each POST message must be unique. If the incoming CAP POST's content is identical to a previous CAP post, the trigger will not launch.