Example Practices: CAP Elements Version 1.0

This document was last revised or approved by the OASIS Emergency Management Adoption TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document.

Technical Committee members should send comments on this document to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the “Send A Comment” button on the Technical Committee’s web page at http://www.oasis-open.org/committees/emergency-adopt/.

Citation format:

When referencing this document the following citation format should be used:

[CAP-Elements-v1.0]

Example Practices: CAP Elements Version 1.0. 12 August 2013. OASIS Committee Note 01. http://docs.oasis-open.org/emergency-adopt/cap-elements/v1.0/cn01/cap-elements-v1.0-cn01.html.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

1 Introduction. 5

1.1 References (non-normative). 5

2 CAP Element Usage. 6

2.1 Optimize alert areas (CAP XML Path: alert/info/area). 6

2.2 Include useful descriptions and instructions (CAP XML Paths: alert/info/description and alert/info/instruction) 7

2.3 Take care with XML encoding. 7

2.4 Customize urgency, severity, certainty to event (CAP XML Paths: alert/info/urgency, alert/info/severity, and alert/info/certainty). 8

2.5 Provide rich content by linking to resources (CAP XML Path: alert/info/resource). 8

2.6 Prepare CAP Usage Documentation. 9

2.7 Public Alert Aggregators Should Ignore CAP Messages with a Restriction Element (CAP XML Path: alert/restriction) 9

3 Alerting Challenges that Impact CAP Alerts. 10

3.1 Alerts that span jurisdiction boundaries. 10

3.2 Alert updates. 10

3.3 Alert information expiration. 11

Appendix A. Acknowledgments. 12

Appendix B. Revision History. 13

1 Introduction

This note provides example practices related to certain elements contained in CAP alerts. The need for this note came from Comment 6, Comments & Questions, Emergency Alerting Policy Workshop, made at the Emergency Alerting Policy Workshop, Montreal, Canada, 1-3 May, 2012. The comment expressed a “Need for international good/example practices used for alert generation.”

This note covers:

· CAP Element Usage

· Alerting Challenges that Impact CAP Alerts

1.1 References (non-normative)

[CAP-1.2] Common Alerting Protocol Version 1.2. 01 July 2010. OASIS Standard. http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.htm l

[Environment Canada] Environment Canada is an agency that has adopted the CAP Canadian Profile, and which has also established its own CAP practices.

[Canadian Community] Canadian Community practices are used by NAADS (National Alert Aggregation & Dissemination System), and by many Canadian federal, provincial, and private agencies that have adopted the CAP Canadian Profile.

2 CAP Element Usage

The Common Alerting Protocol provides flexibility in how most of the CAP data elements are completed. As a result, various implementations of CAP alert messages can look quite different. This section summarizes some example implementation practices pertaining to the use of certain CAP elements. (Note that an instance of a CAP message may be serialized in either XML or ASN.1 form; these principles apply equally in either case as well as in the case of internal data structures representing CAP messages within software applications.)

2.1 Optimize alert areas (CAP XML Path: alert/info/area)

· Watch for false precision of coordinates in geometric shapes. Regardless of the alert area shape, the precision of any one coordinate value (number of decimal places) should reflect its true accuracy (distance accurate to meters, kilometers, etc.). For CAP alert areas, the precision, generally, should not be greater than one meter and, therefore, coordinates should have no more than five decimal places.

· If possible, simplify overly-complex polygons. Having too many coordinates in a polygon may interfere with the efficient processing of a CAP alert, and can result in an alert being dropped. This can happen when an alert area is defined by a reference source that gives an official boundary with hundreds of sides (for example, a polygon is automatically derived from mapping data for an irregular boundary such as a shoreline). To avoid an unreasonable number of points for a polygon alert area, it may be necessary to use a simplify function on the polygon. In most cases a polygon of less than 20 vertices can provide acceptable precision.

· Close polygons. For any polygon in CAP, the first point must be identical to the last point. This is a requirement of the CAP specification even though some mapping tools may not enforce this rule.

· A zero-radius circle implies a geometric point. In general, the radius should be comparable in scale to the precision implied by the circle's center coordinates. For instance, given a center point latitude with three decimal places (about 100 meters), the radius ought to be .1 kilometer rather than zero.

Note that zero-radius circles may reflect an intentional policy decision. For example, a zero-radius circle may be the only option for earthquakes, which usually are defined by a point and, since they occur quickly, may not have a warning area. Similarly, a zero-radius circle may be appropriate at the beginning phase of an emergency when the actual affected area may not be yet be determined but the location is at least known.

· When the alerting area is the whole Earth (e.g., certain space weather hazards), a "bounding box" polygon (SW SE NE NW SW) should be used in the CAP area element:
<polygon>-90,-180 -90,180 90,180 90,-180, -90,-180</polygon>

· Example: NOAA (National Oceanic and Atmospheric Administration)

§ Alerts are targeted both to a custom polygon and to a one or more UGC and FIPS6 geocodes.

§ UGC geocodes and shapes are defined and updated on the NOAA website http://www.nws.noaa.gov/geodata/

§ Area descriptions vary from being a list of towns, to a name of a region, to a short phrase that describes an area (e.g., “Central Beaufort Sea Coast,” “Sierra Nevada from Yosemite to Kings Canyon,” “Columbia; Hempstead; Howard; Lafayette; Little River; Miller; Nevada; Sevier”).

· Example: Canadian Community

§ Polygons for the threat area are simplified (reduced number of vertices) and have exaggerated boundaries that extend beyond complicated boundaries

2.2 Include useful descriptions and instructions (CAP XML Paths: alert/info/description and alert/info/instruction)

· The <description> and <instruction> elements allow for free-form text. The text should be relevant and useful for the audience in the alert area. Instruction text should be actionable and should focus on appropriate protective action to be taken by the public or the specified target audience of the alert. To enhance understanding and simplify processing by recipients, text in CAP alerts should use common phrases, drawn from a published source, if possible. Note for U.S. originators. Hazard-alerting guidance is available from the World Meteorological Organization/Public Weather Services.

· Example: NOAA (National Oceanic and Atmospheric Administration) descriptions are consistently high quality, and usually include information on the current weather event, predictions about the event, and its impact. Excellent alert creation guidance provided in WFO SEVERE WEATHER PRODUCTS SPECIFICATION.

· Example: Environment Canada practices provide alert information in multiple languages (English and French) to serve both official languages of Canada

· Separate alert <info> block for each language.

· Content is professionally translated.

· Different landing pages in <web> for each language.

2.3 Take care with XML encoding

· For maximum interoperability, a CAP alert message that is serialized as XML should be UTF-8 encoded. The source code of any programs that modify such XML files must be UTF-8 encoded as well. Care should be taken when inserting text by “cutting and pasting” from web pages or word-processors, as such insertions often include hidden and/or non-UTF-8 characters. CAP editing software that permits keyboard entry should, whenever possible, check for such characters.

2.4 Customize urgency, severity, certainty to event (CAP XML Paths: alert/info/urgency, alert/info/severity, and alert/info/certainty)

Many alert events can elicit a range of urgency, severity, and certainty values. For example, NOAA’s “Special Weather Statement” alert has been used for events such as light snow, thunderstorms, and strong winds. The Urgency, Severity, and Certainty values of each alert instance should correspond to the characteristics of the specific event and the desired level of response to that event.
It's best to use an "unknown" Urgency, Severity, and Certainty value only when the value is unavailable. Further, the value “unknown” should not be treated as equivalent to “minimal.” This helps avoid underplaying an event, such as when an event with "immediate urgency" (responsive action should be taken immediately) or “extreme severity” (extraordinary threat to life or property) is underplayed because it has an "unknown certainty"). Note the OASIS Emergency Management Reference Information Model (RIM) Subcommittee provides the following guidance: "... practitioners should only utilize this value [unknown] when the element value is truly unknown."

Note that the terms "Advisory,” “Watch,” and “Warning" are not used consistently across hazard types with respect to the separate CAP aspects of Urgency, Severity, and Certainty. (The National Weather Service is considering simplifying these terms–see http://products.weather.gov/PDD/hazsimp_pdd.pdf).
Example: Canadian Community

· Distinct notion of an event (e.g., severe thunderstorm, freezing rain) versus an alert (e.g., severe thunderstorm advisory, freezing rain warning)

2.5 Provide rich content by linking to resources (CAP XML Path: alert/info/resource)

Use the <resource> element to embed links to content, such as images or audio files. This helps a message receiver to better understand the context of the event (a web feed client can access and display the linked resource).

· Example: For large tsunamis, WCATWC provides links to their Tsunami Energy Map. USGS has ShakeMaps on their website that can be linked.

The <resource> element generally invokes a secondary delivery mechanism, such as retrieval of a URL over HTTP. Therefore, CAP messages should NOT use the <resource> element to include essential warning information. The basic CAP payload should be complete and actionable by itself; information in a <resource> should only provide supplemental information.

2.6 Prepare CAP Usage Documentation

· Publicly accessible and regularly updated documentation of CAP element usage and maintenance is sometimes necessary.

· Example: Good Canadian CAP profile (CAP-CP) documentation available at http://capan.ca/index.php/en/cap-cp/.

2.7 Public Alert Aggregators Should Ignore CAP Messages with a Restriction Element (CAP XML Path: alert/restriction)

Aggregators of CAP messages intended for public distribution (i.e., where the <scope> value is “Public”) cannot be relied on to evaluate the <restriction> element.

In a message validated against the CAP 1.2 schema the restriction element should only occur in a CAP message that also has a <scope> of “Restricted”. In prior CAP schemas, the <restriction> element can occur with any of the enumerated values of <scope> (“Public”, “Private” or “Restricted”), but only a "Restricted"<scope> is defined for such messages.

3 Alerting Challenges that Impact CAP Alerts

3.1 Alerts that span jurisdiction boundaries

Hazards such as meteorological and geological events often cross city, town, province, state, and national boundaries. Poor coordination among alerting agencies can result in each agency issuing its own alert. Multiple alerts are generally acceptable to avoid gaps and provide corroboration. However, inconsistent alerts can cause confusion, and a large number of duplicative alerts can clog delivery channels and desensitize recipients.

· Agencies and alert issuing bodies in the same region should, where possible, leverage existing inter-jurisdictional processes and agreements to coordinate their warning efforts. If such existing frameworks are not considered adequate, the establishment of policies, procedures or regional warning centers should be considered.

· The CAP <area> element should be used to describe the area at risk from the subject threat or event. The area should not be constrained (“clipped”) to political or administrative boundaries unless the originator is certain that people in adjoining jurisdictions are receiving comparable alert information from other sources.

· If there are overlapping or duplicate alerts issued by different authorities, one way to help identify the duplication is through the use of a common identifier, such as the <incidents> sub-element, in the alerts.

3.2 Alert updates

Alert updating can be complex. The content of an alert needs to be updated to reflect changing and moving conditions, and the CAP element need to be structurally valid. The following process and technical tips can help improve the quality and accuracy of alert updates.

· Regularly update alerts. Alert creators/maintainers should establish protocols for obtaining current alert information for use in timely alert updates. At a minimum alerts should be updated before the previous version expires, unless it is the intention to allow the alert to expire.

· Issue CAP updates instead of new alerts to reflect changing circumstances or protection action recommendations. This helps ensure that CAP feed clients do not miss changes.

· Use <references> to point to earlier alerts. The alerting system needs to record the IDs of all previous alerts referring to the same event that haven't expired.

· Example: Environment Canada practices model the subject event for each alert as it moves across areas

· Expired area contains <responseType>AllClear</responseType>.

· Alert update contains a still active area and an expired area.

· Separate <info> blocks for each area.

· Still active area contains updated <effective> and <expires> time.

3.3 Alert information expiration

The <alert><info><expires> time is optional, and is defined in the CAP specification as "The expiry time of the information of the alert message." Determining the <expires> time of an alert information block during alert issuance can be challenging, yet having an <expires> time is extremely helpful for CAP feed clients and other downstream alert recipients. Unless an explicit <expires> time is specified, it will be up to the various disseminators, feeds and delivery systems to determine how long the alert information will remain visible to the public.

· One possibility is to set alert information expiration to a time slightly after the next expected update of the alert information. This helps avoids gaps for clients that poll more slowly.

o For example, if an agency issues measures flood gauges and issues updates every 30 minutes, the <expires> time can be 45 minutes or more after the <sent> time.

Appendix A. Acknowledgments

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Participants:

Doug Allport Canada Multi-Agency Situational Awareness Systems-
National Information Exchanges (MASAS-x)

Art Botterell Individual

Rex Brooks Network Centric Operations Industry
Consortium

Elliot Christian Individual

Phil Coakley Google

Steve Hakusa Google

Gary Ham Individual

Elysa Jones Individual

Camille Osterloh Individual

Norm Paulsen Environment Canada

Greg Trott CAP-AU Custodian for the Australian Government standard
for Common Alerting Protocol

Jacob Westfall Individual

Appendix B. Revision History

Revision	Date	Editor	Changes Made
1.0 wd 01	01/11/13 01/14/13	Tony Mancuso	Initial Draft (copied CAP element content from prior CAP feed and element doc developed by EMA-Collateral and Docs SC). Added text and edits from Elliot Christian.
1.0 wd 02 - 11	03/26/13 -04/04/13	Tony Mancuso	Updated draft with additional content. Incorporated content and responded to comments from Art Botterell and Elliot Christian, Norm Paulsen.
v. 1.0-cnprd02.doc	06/10/13	Tony Mancuso	Edited and added Jacob Westfall comments and responses for post-public review EMA-TC discussion.
v. 1.0-cnprd02.doc	06/25/13	OASIS EMA C&D SC	Resolved remaining comments received from Jacob Westfall