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. 11 April 2013. OASIS Committee Note Draft 01 / Public Review Draft 01. http://docs.oasis-open.org/emergency-adopt/cap-elements/v1.0/cnprd01/cap-elements-v1.0-cnprd01.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). 7

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

2.6 Prepare CAP Usage Documentation. 8

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 expiration. 10

3.4 Alert Expiration vs. Alert Update. 11

Appendix A. Cap Alert Practices. 12

A.1 NOAA (National Oceanic and Atmospheric Administration). 12

A.2 CAP Canadian Community. 12

A.2.1 Canadian Community. 12

A.2.2 Environment Canada. 13

Appendix B. Acknowledgments. 15

Appendix C. Revision History. 16

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

[CAP-1.1]

Common Alerting Protocol Verison 1.1. 01 October 2005. OASIS Standard https://www.oasis-open.org/committees/download.php/15135/emergency-CAPv1.1-Corrected_DOM.pdf

[CAP-1.0]

Common Alerting Protocol Verison 1.0. March 2004. OASIS Standard https://www.oasis-open.org/committees/download.php/6334/oasis-200402-cap-core-1.0.pdf

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.

· Examine the use of a zero-radius circle, as it implies a geometric point (which may not be what you intend). 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, while technically incorrect, 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.

· 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

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.

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://nws.weather.gov/haz_simp/).

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 may also be used as a means to extend a CAP message with highly specific data structures that cannot be adequately handled by the <parameter> extension. In such cases, an appropriate MIME type should be specified to enable recipients to distinguish such extensions from rich media content.
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/.

· Locally-specified usage of <parameter> elements in alerts with a "Public" scope should be clearly documented. A reference to the URL or other location of the documentation should be provided in a <parameter>: the parameter's ValueName should include the term “Usage,” and the parameter's Value should contain the URL to the documentation.

Example:

<cap:parameter>

<cap:valueName>myParameterUsage</cap:valueName>

<cap:value>url-to-parameter-usage-doc</cap:value>

</cap:parameter>

· If possible, designers of new CAP origination tools or procedures should refer to usages.

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.

3.3 Alert expiration

Determining the alert’s <expires> time 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 will remain visible to the public. The following steps, though not perfect, have proven useful for giving people a general idea of the duration of the alert

· If the issuer is not certain when the event will expire, it may be desirable to fill in a default <expires> time for the alert, so that the alert won’t be effective indefinitely. A default time can be set several ways:

· The <expires> time can be several hours ahead of the <sent> time, and this active duration can be fixed.

· The <expires> time can be dependent on the event type. For example, a Tornado Warning can be active for 2 hours by default, while a Hurricane Warning can be active for 2 days by default.

· The <expires> time can be set after the next expected update time for the alert (setting it slightly after the next update time helps avoid gaps for clients that poll more slowly). For example if the agency issues measures flood gauges and issues updates every 30 minutes, the <expires> time can be 45 minutes or more after the <sent> time

· Note - if the alert expiration time is certain, the issuer can send the update early, so that the <sent> time is 30 min to 2 hrs before the <expires> time, and not exactly the same as the <expires> time. This ensures that the CAP feed clients and other recipients have time to pull in the update.

3.4 Alert Expiration vs. Alert Update

Typically, an originator uses the <expires> sub-element to express the next time the alert will be updated (if it is known). If the originator can predict the expiration of the event, it may wish to consider adding an additional <parameter> that explicitly states that the event expiration time. Here is an example:

<parameter>
<valueName>EventEndTime</valueName>
<value>2012-02-28T16:45:00-06:00</value>
</parameter>

Appendix A. Cap Alert Practices

The appendix describes features of specific CAP alert implementations that may provide useful guidance to other CAP alert originators and distributors.

A.1 NOAA (National Oceanic and Atmospheric Administration)

https://alerts.weather.gov/cap/us.php?x=0

· Clear alert <area>

· 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/

· Succinct and understandable <areaDesc>

· The area description varies from being a list of towns, to a name of a region, to a short phrase that describes an area.

· Example: “Central Beaufort Sea Coast,” “Sierra Nevada from Yosemite to Kings Canyon,” “Columbia; Hempstead; Howard; Lafayette; Little River; Miller; Nevada; Sevier”

A.2 CAP Canadian Community

NAADS (National Alert Aggregation &Dissemination System) is a primarily a feed service that aggregates and redistributes CAP alert messages, but also can originate Canadian CAP alerts on behalf of other authorities.

http://rss.naad-adna.pelmorex.com/

A.2.1 Canadian Community

The Canadian Community practices listed below are used by NAADS. They also are used by many Canadian federal, provincial, and private agencies that have adopted the CAP Canadian Profile (see Common Alerting Protocol - Canadian Profile (CAP-CP).

Alert vs. event

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

· Compatibility with multiple clients

· Ability to Embed multiple defined practices (by entity) in a single CAP alert message (through the use of Profiles and Layers – see Common Alerting Protocol - Canadian Profile (CAP-CP)

· Declares the usage of a profile within a CAP message through the<code> element.

· Implements profile and layer specific CAP parameters through a consistent use of <valueName> in the <parameter> element… <valueName>profile:profile_name:version:valueName</valueName>

· Secure CAP content

· Although not defined in the Canadian Profile, Digital signatures in each CAP alert have found common usage.

· Simplified and exaggerated polygons

· Polygons for the threat area are simplified in the number of vertices and have exaggerated boundaries beyond complicated boundaries

A.2.2 Environment Canada

Environment Canada is an agency that has also adopted the CAP Canadian Profile, and which has also established its own CAP practices. Several Environment Canada practices are listed below.

· Multiple languages (English and French) are always present to serve both official languages of Canada

· Separate <info> block for each language.

· Content is professionally translated.

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

· Modeling 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.

· Secure CAP content

· Public key published at http://dd.meteo.gc.ca/public-keyring/

· 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/

· 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/

· 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/

Appendix B. 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 C. 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.