Lesson 1: Anatomy of a CAP Alert Message

Introduction

Let us take a look at the components of a CAP alert message. Here is an example of an alert as it may look when posted to a web page or sent via email:

Recall from the CAP Basics course that CAP messages are prescribed through XML, a machine and human readable markup language easily distributed via the Internet. The information that is displayed in this sample alert is parsed from the XML source. In addition to the displayed information, there is other critical data in the source file that can be used to evaluate the urgency of the alert and to disseminate it through the appropriate channels.  

Document Object Model

In technical terms, XML files are described through a “document object model” which details the  underlying structure and elements of a message. The details of this are more important to someone that needs to develop a program to author or process CAP messages than it is for someone that is issuing alerts. However, being familiar with the technical aspects of CAP will help assure that alert authors are providing appropriate information for their alerting system and target audience.

Here are the structure and elements, the document object model, of a CAP alert message:

In descriptive terms, an alert message contains information about an event (or multiple events) which can contain multiple supporting resources and area descriptions. The elements that describe each of these are made up of XML tags containing values.  

XML Elements

As shown in the document object model on the previous page, a CAP alert message is constructed using XML element tags. Here is an example of the XML that makes up a CAP flood alert. The colors indicate the various groupings of the elements as shown in the document object model.

Recall that in XML each element has two parts:

1. Opening and closing tags with a name (e.g., <cap:sender></cap:sender>)

2. A value: the information contained within the tag (e.g., "meteo.rwanda@gmail.com")

Athough it is possible to author CAP alert messages using a simple text editor, that is not a practical approach. Writing XML manually is tedious and it is easy to introduce errors into its very structured format. This is especially true when dealing with the time constraints of getting an alert authored and published. Most likely, you will author alerts within a forecast monitoring system, a hazard alerting tool, or a web-based application. The tool will take care of creating the properly structured XML and make it available to the end user through a news feed or other means.

Processing XML

Here is another example of the previous message processed for display on a web page showing all the element values:

How the message is displayed or processed will depend on the warning system and the target audience. Through the use of server applications, certain elements of the message can be used to trigger dissemination and processing of the message. Depending on the type of alert, it may be sent via email or text, it might be a pop-up on a web page, it may get processed by a machine reading application on a radio or TV station, or it might take some other form. For instance, an application can be programmed to trigger a siren if certain values are present in a message:

Note that those three elements — urgency, severity, certainty — are key elements used to emphasize the importance of an alert. Their values indicate when to take protective action, what impacts the event will have on life and property, and how certain it is that the event will happen.

Mandatory Elements and Codified Values

CAP alert messages contain certain mandatory elements. And some of those elements must contain particular, prescribed values. 

The mandatory elementals are highlighted in bold here:

The details of these elements and values are described in the OASIS (Organization for the Advancement of Structured Information Standards) document defining CAP version 1.2 (available on the OASIS website). As mentioned previously, those technical details are more of value to someone that needs to develop a program to author or process CAP messages than for someone issuing alerts. However, for your particular situation, it is important to know if any of the elements will trigger an alerting event and how the message is going to be processed (i.e., for triggering a siren).

Values for Codified Elements

The following lists the codified elements and their prescribed values.  Unless you are authoring CAP alert messages in a text editor, your authoring tool will provide the available values for the codified elements.

Knowing what each of these values represents is important to assure that the alert targets the proper audience, triggers the appropriate response, provides valuable and appropriate information. Download this list as a reference when authoring alerts or refer to the OASIS document.

Message Status <status>

• “Actual” - Actionable by all targeted recipients
• “Exercise” - Actionable only by designated exercise participants; exercise identifier SHOULD appear in <note>
• “System” - For messages that support alert network internal functions
• “Test” - Technical testing only, all recipients disregard
• “Draft” – A preliminary template or draft, not actionable in its current form

Message Type <msgType>

• “Alert” - Initial information requiring attention by targeted recipients
• “Update” - Updates and supercedes the earlier message(s) identified in <references>
• “Cancel” - Cancels the earlier message(s) identified in <references>
• “Ack” - Acknowledges receipt and acceptance of the message(s) identified in <references>
• “Error” - Indicates rejection of the message(s) identified in <references>; explanation SHOULD appear in <note>

Scope <scope>

• “Public” - For general dissemination to unrestricted audiences
• “Restricted” - For dissemination only to users with a known operational requirement (calls for including <restriction>)
• “Private” - For dissemination only to specified addresses (calls for including  <addresses>)

Event Category <catagory>

• “Geo” - Geophysical (including landslides)
• “Met” - Meteorological (including floods)
• “Safety” - General emergency and public safety
• “Security” - Law enforcement, military, homeland and local/private security
• “Rescue” - Rescue and recovery
• “Fire” - Fire suppression and rescue
• “Health” - Medical and public health
• “Env” - Pollution and other environmental
• “Transport” - Public and private transportation
• “Infra” - Utility, telecommunication, other non-transport infrastructure
• “CBRNE” – Chemical, Biological, Radiological, Nuclear or High-Yield Explosive threat or attack
• “Other” - Other events

Response Type <responseType> - optional element

• “Shelter” – Take shelter in place or per <instruction>
• “Evacuate” – Relocate as instructed in the <instruction>
• “Prepare” – Make preparations per the <instruction>
• “Execute” – Execute a pre-planned activity identified in <instruction>
• “Avoid” – Avoid the subject event as per the <instruction>
• “Monitor” – Attend to information sources as described in <instruction>
• “Assess” – Evaluate the information in this message.  (This value SHOULD NOT be used in public warning applications.)
• “AllClear” – The subject event no longer poses a threat or concern and any follow on action is described in <instruction>
• “None” – No action recommended

Urgency <urgency>

• “Immediate” - Responsive action should be taken immediately
• “Expected” - Responsive action should be taken soon (within next hour)
• “Future” - Responsive action should be taken in the near future
• “Past” - Responsive action is no longer required
• “Unknown” - Urgency not known

Severity <severity>

• “Extreme” - Extraordinary threat to life or property
• “Severe” - Significant threat to life or property
• “Moderate” - Possible threat to life or property
• “Minor” – Minimal to no known threat to life or property
• “Unknown” - Severity unknown

Certainty <certainty>

• “Observed” – Determined to have occurred or to be ongoing
• “Likely” - Probability is greater than or equal to 50%
• “Possible” - Probability is less than 50%
• “Unlikely” - Not expected to occur
• “Unknown” - Certainty unknown

Text Entry Elements

Aside from the codified elements, there are elements for entering information as text or as date and time values. The OASIS document describes the appropriate information to enter in these elements. Important ones are highlighted here:

Headline <headline>

A brief human-readable headline.  Note that some displays (for example, short messaging service devices) may only present this headline; it should be made as direct and actionable as possible while remaining short. 160 characters may be a useful target limit for headline length.

Description <description>

An extended human readable description of the hazard or event that occasioned this message. This is where you describe the important information (who, what, when, and where) about the hazardous situation.

Instructions <instruction>

An extended human readable instruction to targeted recipients.  This is where you place the important information (how and why) of your protective behavior instruction.

Area Description <areaDesc>

A text description of the affected area for human readers. Be as specific as possible. There are several elements related to Area Description that can be populated through mapping programs and can be machine interpreted (polygon, circle, geocode). Some warning systems use this information to provide a highlighted map of the area of concern or to send text messages to people within the area of concern.

Three Important Trigger Elements

As mentioned previously, urgency, severity, and certainty, are key elements used to emphasize the importance of an alert. Their values indicate:

In many systems, if the top two values are selected for all three elements, alerts are issued.

Listen to Eliot Christian speak to the importance of these elements:

Video segment of interest: 07:13 to 08:32

Summary

The technical details of the structure and content of a CAP alert message are critical to know when developing CAP tools and for alerting. Those details are also valuable for CAP alert issuers to understand in order to issue effective and appropriate alerts. It is important to know which elements and values are mandatory, which are used for triggering alerting events, and how those alerts will be disseminated.