Canadian Profile of the Common Alerting Protocol (CAP-CP) Introduction and Rule Set Beta 0.3

PDF (431 KB)

Table of Contents

Purpose of this Document

This document outlines for Canadian public alerting stakeholders The Canadian Profile of the Common Alerting Protocol, which is also referred to as the Common Alerting Protocol - Canadian Profile (CAP-CP). This profile defines a set of rules, and managed lists of values, that are recommended for use in Canada within public alerting systems. This document deals with the CAP-CP set of rules.

This profile is compliant with the Common Alerting Protocol, (the “Reference Standard” or CAP) in that valid CAP-CP is also valid CAP. As with the Reference Standard, compliance with the CAP-CP is not limited to any one alerting methodology, nor is it specific to any one alerting method, communications channel, or sub-group of public alerting stakeholders. In fact, significant effort has been made to ensure it does not include bias to any method, channel or sub-group of stakeholders.

Authors

The principal authors of this document are listed below in alphabetic order:

Copyright

Copyright 2009. This document may be reproduced, without charge or request for permission, provided it is reproduced in its entirety and without modification.

Notices

This document and the information contained herein is provided on an "AS IS" basis and the Authors, and their officers, employees or agents DISCLAIM ALL WARRANTIES OR REPRESENTATIONS, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY OR REPRESENTATION THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE RIGHTS OF OTHERS, OR ANY IMPLIED WARRANTIES OR REPRESENTATIONS OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Revisions Summary

This document includes the following major revisions to the Public Draft #2 (May 8, 2008 draft), as published by Industry Canada at www.ic.gc.ca/eic/site/et-tdu.nsf/eng/wj00096.html:

  1. Beta 0.3 maintains the requirement of one event type per alert message, but without the limitation of one info segment per language per alert message.
  2. Beta 0.3 references newly established and/or recognized managed lists, along with a rule set defined below, which are to be used as part of the CAP-CP.

Other CAP-CP Documents

The entire CAP-CP is defined in this document, and the following two additional documents:

To ensure access to CAP-CP by public alerting stakeholders as soon as possible, all three documents are to be available at the following web sites:

CAP-CP may also be available on other websites. Where there is a difference in versions, the version at www.CAPAN.ca/CAP-CP shall take precedence. New versions shall be created only with the express consent of the authors listed in this document.

Associated Documents and Resources

  1. The Common Alerting Protocol (CAP) version 1.1 is a standard administered by the Organization for the Advancement of Structured Information Standards (OASIS). The Standard is available at: http://www.oasis-open.org/committees/download.php/14759/emergency-CAPv1.1.pdf
  2. www.CAPAN.ca/CAP-CP. The CAP-CP website offers CAP-CP related resources and links.

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in IETF RFC 2119, available at http://www.ietf.org/rfc/rfc2119.txt

The CAP-CP also adopts the terminology of the Reference Standard. In addition:

The term “layer” is used in this document to refer to message elements that are not required under the Reference Standard or under the CAP-CP but that may involve a new rule, other managed lists and or information specific to a subset of users in Canada's public alerting community. A layer is typically supported with the use of one or more parameter elements within a CAP or CAP-CP file. Information found in a layer is outside the scope of the CAP-CP; however, CAPAN will maintain a list of known layers to support non-conflicting naming schemes. Authors of layers are encouraged to self identify to CAPAN.

The expression “managed list” is used in this document to refer to a collection of permitted values specific to a given element within a CAP-CP file (for example, the CAP-CP event list).

The term “profile” is used in this document to refer to a collection of rules, managed lists, and other references, which pertain to the Reference Standard. A profile is accepted as necessary to address needs specific to a country or system using the Reference Standard, and to the full community of users identifying with the profile.

The expression “rule set” is used in this document to refer to a collection of rules which are applied to the use of the Reference Standard, which impose usage requirements beyond those of the Reference Standard, but also remain in compliance with the Reference Standard.

Development of CAP-CP as a National Standard of Canada

The authors of CAP-CP Beta Version 0.3 are giving consideration to submitting the profile to a Canadian standards development organization (SDO) for development as a National Standard of Canada. This, they anticipate, will ensure a recognized process in the decision-making regarding elements of the standard on an initial and ongoing basis, and will also ensure clarity and access to the standard for all public alerting stakeholders. With the formal initiation of the standard development process, the SDO would become the custodian and manager of CAP-CP.

Introduction

History of CAP

The need for a public alerting protocol was identified in a year 2000 report by the US National Science and Technology Council titled “Effective Disaster Warnings”. It concluded that, “A standard method should be developed to collect and relay instantaneously and automatically all types of hazard warnings and reports locally, regionally and nationally for input into a wide variety of dissemination systems.”

Mr. Art Botterell, a public communications official from the State of California, proposed what has come to be known as the Common Alerting Protocol (CAP). His efforts, and those of the broad community of stakeholders supporting him, earned CAP an endorsement, and funding support, from the US Partnership for Public WarningFootnote 1 (PPW).

In 2004, CAP became a standard of the Organization for the Advancement of Structured Information Standards (OASIS). A revision was published in October 2005. In December 2006, the International Telecommunication Union (ITU) adopted CAP v1.1 as an ITU-T Recommendation.

Canada’s Needs

In the fall of 2002, Industry Canada launched a public alerting initiative to study gaps and investigate new technologies for public alerting in Canada. Industry Canada followed the development of CAP in the US and recognized its benefits for Canadian public alerting systems. On March 1, 2005, Industry Canada hosted a Canadian Public Alerting Forum and Workshop and presented a vision for public alerting in Canada. The vision saw the adoption of the CAP as a North American standard, to be used in a proposed Canada-wide public alerting system, then known as CANALERT.

Soon after, New Brunswick Emergency Measures Organization (NBEMO) and the Allport Group noted that Canadian public alerting stakeholders needed a profile specific to Canada’s implementation of the CAP. What they identified was a requirement to support Canadian language and geopolitical considerations.

Industry Canada provided funds towards the development of a Canadian adaptation of the CAP in partnership with NBEMO. Industry Canada also hosted a national multi-stakeholders workshop in 2006 to discuss the proposed Canadian implementation. This spawned an Industry Canada hosted CAP Working Group, which completed a draft Canadian Profile (CAP-CP) dated July 27, 2007 (Draft 1). This document was updated May 8, 2008 (Draft 2).

Early implementers of CAP-CP identified a few issues with the May 8, 2008 draft of the CAP-CP. In the fall of 2008, Environment Canada (EC) chaired a series of meetings with representation from federal and provincial levels of government and a cross section of impacted supporting industry organizations that resulted in changes to Draft 2.

Environment Canada also created a “reference implementation” of CAP-CP with the goal of focussing discussion on the interpretation of both CAP and CAP-CP within Canada. This “reference implementation” consists of a website hosted by Environment Canada that offers live and static examples in the CAP/CAP-CP format, for industry testing purposes. This “reference implementation” serves to help stakeholders understand differences in interpretation, and overall should improve the integrity of each system involved.

CAP-CP Overview

The CAP-CP primarily centers on four main requirements and constraints. They are as follows:

  1. Constraint of one subject event per alert message
  2. Requirements associated with languages
  3. Requirements associated with event identification
  4. Requirements associated with location identification

Additionally, there are other rules intended to help overcome implementation challenges that have been identified by the early adopters of the Reference Standard and Draft 2 of the CAP-CP.

The specifics for all these points are detailed later in this document. What follows is a general discussion for each point.

1. Constraint of one subject event per alert message

The Reference Standard allows for the inclusion of multiple subject events (events) within a single alert message, but specifies only one unique message identifier is required. Therefore, an update to any one of the events would appear as an update to all the other events within the same alert message, even if the other events remain unchanged.

Further, given that event values will be used for the purpose of filtering, routing, validating, and other needs within the community, systems would have difficulty handling a single alert message containing multiple events where all events may appear as updated when that may not be the case.

To avoid any potential confusion, the CAP-CP limits each CAP alert message to one single event reference.

2. Requirements associated with languages

The Reference Standard identifies a language value as an optional element. In the absence of a value, US English is assumed in accordance with the Reference Standard. In Canada, where there are two official languages, use of the language value is very important for message distributors.

The CAP-CP requires the use of the language value. Further, it defines additional practices that address challenges associated with issuing and updating alerts in multiple languages.

3. Requirements associated with event identification

The Reference Standard simply requires that a human readable value describing the subject event for an alert message exists. It does not offer suggestions or a recognized list of events as that is a function of any alerting system that employs the Reference Standard.

However, since the CAP-CP includes rules on issues like languages, providing a coordinated Canadian event list within the CAP-CP, independent of any specific alerting system, will ensure consistency for the Canadian public.

Given that many Canadian alerts will be translated by automated applications, a list of recognized pre-translated events is needed. Further, the use of a master list supports the routing of all levels of public alerts by type. The CAP-CP includes the requirement of an event code that must come from a comprehensive managed list of events. This list is found in the CAP-CP Event References document. As mentioned previously, this document is managed separately from the main body of the CAP-CP, as it is expected to change more frequently than the main section. 

4. Requirements associated with location identification

The Reference Standard supports the use of geo-referenced location codes to describe the area(s) affected by an alert. The CAP-CP, however, requires that at a minimum geo-referenced location codes must be used for locations in Canada, and that the location codes correspond to commonly known geopolitical area(s). Geopolitical areas are easily identified on most maps, and are seen as the best common denominator for associating alerts with recognizable location references for Canadians.

The Canadian Geographical Standard Classification (SGC), maintained by Statistics Canada, is the CAP-CP reference list for geopolitical location codes. The SGC system provides unique numeric codes for three types of geographic areas: provinces and territories; census divisions (CD) such as counties and regional municipalities; and census subdivisions (CSD) such as cities, towns, and townships. Further information on the SGC is available at http://www.statcan.gc.ca/subjects-sujets/standard-norme/sgc-cgt/geography-geographie-eng.htm

The CAP-CP Location References document identifies the version (or versions) of the SGC that are currently recognized for use in Canada, and provides details on the use of SGC in CAP-CP, along with some of the limitations of SGC with regard to place names in more than one language.

At the time of writing, Statistics Canada publishes SGC codes with one location value for each entry, as provided to them by the province or territory to which they pertain. Some are in English, some are in French, and a few include both an English and French value. It is therefore the issuing authority’s responsibility to ensure translation when necessary.

This requirement does not preclude the inclusion of other codes, such as postal codes, or Environment Canada Canadian Location Codes (CLC). More precise means of location identification, such as geospatial polygons, are encouraged to accurately describe the area to which the alert pertains.

CAP-CP Rules

This section identifies specific requirements, constraints, and recommendations associated with the CAP-CP. Reference Standard content is included for reference and illustration only. Differences in Reference Standard interpretations, if any, are unintended and do not mean to override the Reference Standard.

Table Layout Definitions

Element: a CAP-XML element as described in the Reference Standard
Message:the content of the XML itself, and not necessarily any business definition of the word message
Use: a rule outlining the usage specifics of an element. As per the Reference Standard, one of “Required”, or “Optional” and as per CAP-CP one of “Required”, “Recommended” or “Optional”
Type: a categorization of the rule to one of “Technical” (format or structure) or “Policy” (the business of public alerting)
Value: allowable values for an element defined by a rule for the element
Description: a general description of a rule and its purpose
Notes: any special notes regarding implementation of a rule
Example: XML examples or snippets, which illustrate the use of a rule

CAP-CP <valueName> Scheme

The Reference Standard states that, “Values of 'valueName' that are acronyms SHOULD be represented in all capital letters without periods”. The standard does not provide any further recommendations on creating a <valueName> or determining the domain of the code nor its format. The <valueName> should uniquely identify the value list being used, and if the value list is expected to change, should provide a method to accommodate changes by identifying each unique revision.

Subsequent specifications from the OASIS committee that developed CAP use a <valueListUrn> instead of a <valueName> and it is assumed that future versions of CAP will adopt this as well. A Uniform Resource Name (URN) is a Uniform Resource Identifier (URI) and is described in RFC 1737 of the Internet Engineering Task Force (IETF). However at this time there is no official namespace identifier registered for CAP value lists.

CAP-CP has adopted a URN-like scheme for creating valueNames. And while following many of the same principles, it is purposely different than a standard URN to distinguish it from any future standardized format that does incorporate an officially registered namespace identifier. The following format will be used to create CAP-CP valueNames:

<type> ":" <identifier> “:” <specific string>

The character formatting for URNs from the IETF's RFC 2141 will be followed, including case in-sensitivity. <type> will be one of “profile” or “layer”. <identifier> is a unique string identifying this value list. This might be the agency who publishes the list or the type of list, and acronyms should follow the Reference Standard recommendations. <specific string> is further information about this value list such as a further identifying name, sub-segment, or version number. For example:

profile:CAP-CP:Location:0.3

Layer creators should ensure that their valueNames follow this format, do not conflict with established CAP-CP valueNames, and uniquely identify their organization.

1. CAP-CP message must be valid CAP

CAP

Element: N/A

Use:

Type:

Value:

Description: The Reference Standard

Notes:

Example:

CAP-CP

Element: N/A

Use: Required

Type: Policy

Value:

Description: All alert messages must be structured and formatted according to the guidelines set out by the Reference Standard. Messages that do not conform to this standard are also considered invalid CAP-CP messages as well.

Notes: Systems receiving invalid CAP messages will not necessarily be expected to act on them; however, rather than aborting the process, it is recommended that the message be flagged with a “concern” or “error” system element and the originator notified of the reason for the flag. Recipients of a CAP message that may contain one of these elements should contact the originator for details.

Example:

(The following XML namespace declaration indicates that the CAP message should validate to CAP. In this case CAPv1.1 is identified by the given URN. Since all CAP-CP messages are to validate to CAP then the following line is still a valid line in all CAP-CP messages)

(Required)

<alert xmlns="urn:oasis:names:tc:emergency:cap:1.1">

</alert>

2. Constraint of one subject event per alert message

CAP

Element: N/A

Use:

Type:

Value:

Description:

Notes: CAP places no restrictions on the number of different subject event types per alert message

Example:

CAP-CP

Element: N/A

Use: Required

Type: Policy

Value:

Description: To avoid any potential confusion, and consistent with other profiles of CAP, CAP-CP constrains each alert message to one subject event type.

Notes:

Example:

(Acceptable)

<alert …>

<info>

<event>Thunderstorm</event>

<eventCode>
<valueName>profile:CAP-CP:Event:0.3</valueName>
<value>thunderstorm</value>
</eventCode>

<area>
<areaDesc>area 1</areaDesc>
<geocode>…</geocode>
</area>
</info>
<info>

<event>Thunderstorm</event>

<eventCode>
<valueName>profile:CAP-CP:Event:0.3</valueName>
<value>thunderstorm</value>
</eventCode>

<area>
<areaDesc>area 2</areaDesc>
<geocode>…</geocode>
</area>
</info>

(Not Acceptable)

<alert …>

<info>

<event>Thunderstorm</event>

<eventCode>
<valueName>profile:CAP-CP:Event:0.3</valueName>
<value>thunderstorm</value>
</eventCode>

<area>
<areaDesc>area 1</areaDesc>
<geocode>…</geocode>
</area>
</info>
<info>

<event>Tornado</event>

<eventCode>
<valueName>profile:CAP-CP:Event:1.0</valueName>
<value>tornado</value>
</eventCode>

<area>
<areaDesc>area 2</areaDesc>
<geocode>…</geocode>
</area>
</info>

3. The CAP-CP version for an alert message must be identified

CAP

Element: <code>

Use: Optional

Type: Technical

Value: User defined

Description: Any user-defined value, flag or special code used to identify the alert message for special handling.

Notes:

Example:

CAP-CP

Element: <code>

Use: Required

Type: Technical

Value: profile:CAP-CP:0.3

Description: A value used to identify which version(s) of the CAP-CP that the alert message is intended to be compliant with.

Notes: <code> is a multi-use element and this required use for noting the CAP-CP version does not preclude the option of using <code> for other purposes, such as version referencing, layer identification, system specific functions, etc..

Example:

(Multiple version reference)
<alert>

<scope>Public</scope>
<code>profile:CAP-CP:0.3</code>
<code>profile:CAP-CP:1.X</code>
<note></note>

</alert>

(Multiple profile reference)
</alert>

<scope>Public</scope>
<code>profile:CAP-CP:0.3</code>
<code>IPAWS v1.0</code>
<note></note>

(Additional Layer reference)

</alert>

<scope>Public</scope>
<code>profile:CAP-CP:0.3</code>
<code>layer:EnvironmentCanada:1.0</code>
<note></note>

4. Time zone field must be included in all time values

CAP

Element: <sent>, <expires>, <onset>, <effective>

Use:

Type: Technical

Value: dateTime format

Description: Alphabetic time zone indicators such as Z must not be used. The time zone for UTC must be represented as -00:00 or +00:00

Notes: CAP states a format requirement for the time zone field but does not state a requirement for it to be present.

Example:

<sent>2008-07-16T20:00:00-00:00</sent>
...or...
<sent>2008-07-16T20:00:00</sent>
is equally valid as per the Reference Standard.

CAP-CP

Element: <sent>, <expires>, <onset>, <effective>

Use: Required

Type: Technical

Value: dateTime format

Description: The time zone field is required to eliminate misinterpretation of implied times with time zones.

Notes:

Example:

(Acceptable)

<alert …>

<sent>2008-07-16T20:00:00-00:00</sent>
<status>Actual</status>

<info>

<effective>2008-07-16T20:00:00-00:00</effective>
<onset>2008-07-16T20:30:00-00:00</onset>
<expires>2008-07-17T06:00:00-00:00</expires>

</info>

</alert>

(System specific policy - in this case -02 :30 represents Newfoundland and Labrador during Daylight Savings)

<alert …>

<sent>2008-07-16T20:00:00-00:00</sent>
<status>Actual</status>

<info>

<effective>2008-07-16T17:30:00-02:30</effective>
<onset>2008-07-16T18:00:00-02:30</onset>
<expires>2008-07-17T03:30:00-02:30</expires>

<area>
<areaDesc>Newfoundland and Labrador</areaDesc>

</area>
</info>

</alert>

5. Alert messages intended for public distribution must include an <info> block

CAP

Element: <msgType>

Use: Required

Type: Policy

Value: “Alert”, “Update”, “Cancel”, “Ack”, “Error”

Description: A value denoting the state of the alert message

Notes:

Example:

CAP-CP

Element: <msgType>

Use: Required

Type: Policy

Value:

Description:
Message states, and the transition from one state to another, are implied with the use of the <msgType> and <references> elements.

  1. For alert messages intended for public distribution, a <msgType> of “Alert”, “Update” or “Cancel” does affect the message state, and an <info> block is required.
  2. For alert messages with a <msgType> of “Ack” or “Error”, an info block is not required, as these messages are primarily intended for system level purposes and not for distribution to the public.

Notes: Processing of “Ack” or “Error” messages is optional, and systems may impose their own associated rules.

Example:

(for public distribution)

<alert .. >

<status>Actual</status>
<msgType>Alert</msgType>
<source>Environment Canada</source>
<scope>Public</scope>
<code>profile:CAP-CP:0.3</code>
<note />
<references />
<incidents />
<info>
….
</info>
</alert>

(not for public distribution)

<alert .. >

<status>Actual</status>
<msgType>Error</msgType>
<source>Environment Canada</source>
<scope>Public</scope>
<code>profile:CAP-CP :0.3</code>
<note >Invalid eventCode</note>
<references >test@ec.gc.ca,TEST-1,2009-01-01T12:00:00-00:00</references>
<incidents />
</alert>

6. <info> blocks must specify the content language

CAP

Element: <language>

Use: Optional

Type: Policy

Value: Defined by RFC 3066

Description: The code denoting the language of the <info> blocks sub-elements within the alert message.

Notes: If not present or null, an implicit default value of "en-US" SHALL be assumed.

Example:

CAP-CP

Element: <language>

Use: Required

Type: Technical

Value:

Description:

  1. All messages with an <info> block must include the <language> element in order to denote the language of the content of the <info> block.
  2. Multilingual messages must use separate <info> blocks for each language, with all non free-form text elements repeated verbatim in each block.
  3. Mixing public display content or text from different languages within the same <info> block is not allowed, except for inherently multilingual content (people, places, things) that may or may not include accented characters.

Notes:

  1. The corresponding RFC 3066 values for Canadian English and French are “en-CA” and “fr-CA”. A message may support other languages spoken in Canada and the appropriate values should be used.
  2. UTF-8 is the recommended encoding for XML documents in order to support a wide range of languages and accented characters.
  3. Fixed CAP values, which often appear as a word from a specific language, are used for software processing purposes only and not for display, and are not translated between <info> blocks (ie. <category>, <urgency>, <severity>, <certainty>, <responseType>, etc…)

Example:

(The values for <event> and <areaDesc> are translated across <info> blocks below as they are values for public display. Other public display elements not exampled below requiring translation include…<senderName>, <headline>, <description>, <instruction>, <web>, <contact>, <audience> )

<info>
<language>en-CA</language>
<category>Met</category>
<event>Hurricane</event>
<responseType>Monitor</responseType>
<urgency>Expected</urgency>
<severity>Severe</severity>
<certainty>Likely</certainty>

<area>
<areaDesc>Avalon Peninsula</areaDesc>

</area>
</info>

<info>
<language>fr-CA</language>
<category>Met</category>
<event>Ouragan</event>
<responseType>Monitor</responseType>
<urgency>Expected</urgency>
<severity>Severe</severity>
<certainty>Likely</certainty>

<area>
<areaDesc>péninsule d'Avalon</areaDesc>

</area>
</info>

7. Use established <event> values

CAP

Element: <event>

Use: Required

Type: Technical

Value: user-defined

Description: The text denoting the subject event of the alert message

Notes:

Example:

CAP-CP

Element: <event>

Use: Required

Type: Policy

Value: an event from the CAP-CP Event References document

Description: It is recommended that the <event> value come from the CAP-CP event list when dealing with public alerts. Using these pre-defined and pre-translated values ensures that all public alert messages are using common terminology to describe events.

Notes:

  1. When creating public alert messages in languages other than English or French, a translation of the list to the appropriate language should be conducted in advance for inclusion in alerts.
  2. When creating public alerts using the <eventCode> “other”, a short and descriptive <event> value should be used. The originator would be expected to provide any necessary translations of these other events. The Tier I event names in the Event References document are helpful should this situation occur.
  3. The CAP-CP event list does not include articles as part of the name of the event (i.e... the 'd' and apostrophe in the reference… d'orages). Automated phrase construction using <event> needs to accommodate the article separately. A lookup table listing the articles for each event in the Event References document will be made available.

Example:

<info>

<event>Thunderstorm</event>

<eventCode>
<valueName>profile:CAP-CP:Event:0.3</valueName>
<value>thunderstorm</value>
</eventCode>

</info>

8. A recognized <eventCode> must be used

CAP

Element: <eventCode>

Use: Optional

Type: Technical

Value: user-defined

Description: A system specific code identifying the event type of the alert message

Notes:

Example:

CAP-CP

Element: <eventCode>

Use: Required

Type: Technical

Value: the <valueName>,<value> pair for the event code associated with an event from the CAP-CP Event References document.

Description:

Notes: Additional event codes from other lists may be included for other purposes.

Example:

(The following example uses an <eventCode> from two Event References lists. The user is to identify the appropriate reference list from the <valueName> entry for their purposes.)

<info>

<event>Thunderstorm</event>

<eventCode>
<valueName>profile:CAP-CP:Event:0.3</valueName>
<value>thunderstorm</value>
</eventCode>
<eventCode>
<valueName>SAME</valueName>
<value>SVR</value>
</eventCode>


</info>

9. A recognized <geocode> must be used

CAP

Element: <geocode>

Use: Optional

Type: Technical

Value: user defined.

Description: A geographically-based code describing the alert message target area

Notes: <geocode> is deprecated in CAPv1.1. Use of <polygon> and <circle> are recommended and preferred.

Example:

CAP-CP

Element: <geocode>

Use: Required

Type: Technical

Value: the <valueName>,< value> pair for an associated code from the CAP-CP Location References document

Description:

  1. The Profile requires the use of at least one <geocode> value from the CAP-CP Location References document for messages that describe areas within Canada. Other <geocode> values from other code systems may optionally be used in concert with the required CAP-CP Location References document.
  2.  As many <geocode> elements as necessary to fully cover the alert message target area may be used.
  3. The Statistics Canada Standard Geographical Classification (SGC) codes are the basis for the CAP-CP Location References.
  4. The <valueName> version suffix will change as new versions of the Location References document are published. Messages may include <geocode>s from different versions of the Location References document in order to provide backward compatibility and to ease transition between list updates.

Notes:

Example:

(In the example, the first <geocode> uses a Census Division while the second <geocode> uses a Census Sub-Division all within the same <info> block)

<info>

<area>

<geocode>
<valueName>profile:CAP-CP:Location:0.3</valueName>
<value>3506</value>
</geocode>
<geocode>
<valueName>profile:CAP-CP:Location:0.3</valueName>
<value>3507004</value>
</geocode>

</area>

</info>

(The following example uses an <geocode> from two location reference lists. The user is to identify the appropriate reference list from the <valueName> entry for their purposes.)

<info>

<area>

<geocode>
<valueName>profile:CAP-CP:Location:0.3</valueName>
<value>3506</value>
</geocode>
<geocode>
<valueName>PostalCode</valueName>
<value>M4R2S8</value>
</geocode>

</area>

</info>

10. <area> blocks are required

CAP

Element: <area>

Use: Optional

Type: Technical

Value:

Description: Area sub-element container

Notes:

Example:

CAP-CP

Element: <area>

Use: Required

Type: Technical

Value:

Description:

  1. An <area> block is required for each <info> block.
  2. It is recommended that an associated geospatial value for the <polygon> or <circle> elements be included in the <area> block as well.
  3. <areaDesc> is a textual description of the area defined by the combination of area elements, and like <event> may not necessarily be a name found in the Location Reference document.
  4. CAP-CP requires that the <area> block contain one or more <geocode> values.

Notes:
Area descriptions (like events) will need to be translated by the originator of the message in cases where the name doesn't come from the recognized reference list.

Example:

<info>

<area>
<areaDesc>Shawinigan Area</areaDesc>
<polygon>-73.2174,46.7498 -72.5497,46.7665 -72.5497,46.7665
-72.4830,46.6498 -72.4830,46.6498 -72.4330,46.5832 -72.433,46.5832
-72.8832,46.3998 -72.8832,46.3998 -72.8833,46.4000 -72.8833,46.4000
-72.9666,46.5333 -73.1389,46.5201 -73.1389,46.5201 -73.1858,46.5139
-73.1858,46.5139 -73.2174,46.7498 </polygon>
<geocode>
<valueName>profile:CAP-CP:Location:0.3</valueName>
<value>2435040</value>
</geocode>
<geocode>
<valueName>profile:CAP-CP:Location:0.3</valueName>
<value>2435027</value>
</geocode>

</area>
</info>

11. <sender> should be descriptive

CAP

Element: <sender>

Use: Required

Type: Technical

Value: user-defined

Description: Identifies the originator of the alert message

Notes:

Example:

CAP-CP

Element: <sender>

Use: Required

Type: Policy

Value:

Description:

  1. Must be human readable.
  2. Must identify the agency that assembled the message, which may have been done on behalf of another agency that originated the message. Ex. When a municipality originates an alert that is published by a provincial agency, the <sender> is the provincial agency, and the <senderName> is the municipality.
  3. Must be as unique as possible. Ex. An internet domain name as part of <sender> is one way to create uniqueness

Notes: If an alert message created by another agency is being passed through a system, such as an aggregator, with no alterations, then the <sender> can remain as is. However, if any changes are made to the message, or if the aggregator is the authority to its clients, the <sender> value should change to reflect the aggregator. Preferably, the original message <identifier> will be added to the <incidents> element, and a <note> added identifying what was changed.

Example:

(The Toronto office of Environment Canada (EC) received alerting information from another EC office in non CAP format and subsequently reformatted the data into a CAP format and redistributed the message. In this case “Toronto” is human readable and “@ec.gc.ca” settles uniqueness).

<sender>toronto@ec.gc.ca</sender>

(The following is a two tiered example of a human readable name with a uniqueness quality. The “operations-center” of the New Brunswick Emergency Measures Organization as part of the Government of New Brunswick)

<sender>operations-center@EMO@gnb.ca</sender>

12. An Update or Cancel message should minimally include references to all active messages

CAP

Element: <references>

Use: Optional

Type: Technical

Value:

Description: An element that lists earlier message(s) referenced by the alert message.

Notes: The normative copy in CAP requires <references> for “Update” and “Cancel” values, however, it is not enforced in the schema.

Example:

CAP-CP

Element: <references>

Use: Required

Type: Policy

Value:

Description:

  1. Consistent with the normative copy of the Reference Standard, <references> are required with <msgType> values of “Update” or “Cancel”.
  2. Further, CAP-CP requires references to all active messages (ones with at least one active <info> block) whose status is impacted by the new message. An “active” <info> block is one that has not yet reached its <expires> time.
  3. In the case of an <info> block that does not have an <expires> time, all further messages in the chain should include a reference to that message since it does not expire on its own.

Notes: Referencing all alert messages with <info> blocks that still have an <expires> time in the future ensures that any messages that may still be playing incorrectly are properly superseded by the most recent Update or Cancel. This resolves issues caused by transmission delays and/or lost messages that may result in message chains being broken. If only a single reference were used, a missed message could result in an alert playing beyond its intended time.

Example:

(The first Alert message with a 3 hour expires time)

<alert … >
<identifier>ABC-7</identifier>
<sender>A@ca</sender>
<sent>2008-01-01T01:00:00-00:00</sent>
<status>Actual</status>
<msgType>Alert</msgType>

<references></references>
<info>

<expires>2008-01-01T04:00:00-00:00</expires>

</info>

</alert>

(The subsequent “Update” with a 3 hour expires time referencing the first)

<alert … >
<identifier>ABC-8</identifier>
<sender>A@ca</sender>
<sent>2008-01-01T02:00:00-00:00</sent>
<status>Actual</status>
<msgType>Update</msgType>

<references>A@ca,ABC-7,2008-01-01T01:00:00-00:00</references>
<info>

<expires>2008-01-01T05:00:00-00:00</expires>

</info>

</alert>

(Another subsequent Update with a 3 hours expires time referencing the first two)

<alert … >
<identifier>ABC-9</identifier>
<sender>A@ca</sender>
<sent>2008-01-01T03:00:00-00:00</sent>
<status>Actual</status>
<msgType>Update</msgType>

<references>A@ca,ABC-7,2008-01-01T01:00:00-00:00 A@ca,ABC-8,2008-01-01T02:00:00-00:00</references>
<info>

<expires>2008-01-01T06:00:00-00:00</expires>

</info>

</alert>

(A further subsequent Update with a 3 hours expires time referencing the most recent two as the earliest one has expired and should not be playing anymore for two reasons…1) it has been superseded, or 2) it has expired)

<alert … >
<identifier>ABC-10</identifier>
<sender>A@ca</sender>
<sent>2008-01-01T04:00:00-00:00</sent>
<status>Actual</status>
<msgType>Update</msgType>

<references>A@ca,ABC-8,2008-01-01T02:00:00-00:00 A@ca,ABC-9,2008-01-01T03:00:00-00:00</references>
<info>

<expires>2008-01-01T07:00:00-00:00</expires>

</info>

</alert>

13. An <expires> value is strongly recommended

CAP

Element: <expires>

Use: Optional

Type: Technical

Value:

Description: The expiry time of the information of the <info> block within the alert message.

Notes: If this time is not provided, each recipient is free to set its own policy as to when a message is no longer in effect.

Example:

CAP-CP

Element: <expires>

Use: Recommended

Type: Policy

Value:

Description: It is strongly recommended that this element be completed by alert message originators so that distributors can know how long the information within an <info> block of an alert message should remain in effect.

Notes:

Example:

(A message with a properly formatted expires time)

<alert … >

<info>

<expires>2008-01-01T07:00:00-00:00</expires>

</info>

</alert>

(Invalid formats)

     <expires></expires>
<expires>NULL</expires>
<expires>0</expires>
<expires>0000-00-00T00:00:00-00:00</expires>
<expires>2008-01-01T07:00:00</expires>  (missing time zone)
<expires>""</expires>

14. A <senderName> is strongly recommended

CAP

Element: <senderName>

Use: Optional

Type: Technical

Value:

Description: The human-readable name of the agency or authority issuing the alert message <info> block.

Notes:

Example:

CAP-CP

Element: <senderName>

Use: Recommended

Type: Policy

Value:

Description: It is strongly recommended that this element be populated by alert message originators as this value is expected to be used for public presentation purposes.

Notes: The appropriately translated value for the name should be used in each <info> block of a multilingual alert message.

Example:

<info>

<language>en-CA</language>
<senderName>Environment Canada</senderName>
..
</info>
<info>
..
<language>fr-CA</language>
<senderName>Environnement Canada</senderName>
..
</info>

15. <responseType> is strongly recommended, when applicable

CAP

Element: <responseType>

Use: Optional

Type: Policy

Value: Shelter | Evacuate | Prepare | Execute | Monitor | Assess | None

Description: The code denoting the type of action recommended for the target audience.

Notes: Multiple instances MAY occur within a single <info> block.

Example:

CAP-CP

Element: <responseType>

Use: Recommended

Type: Policy

Value:

Description: It is recommended that alert message issuers include response types when applicable, along with a corresponding <instruction> value. Using <responseType> allows for automated dissemination in all included languages of the actions the end user is expected to take when instructions may not be available, or not available in all languages.

Notes:

Example:

<info>

<responseType>Shelter</responseType>
<responseType>Monitor</responseType>
<instruction>Take cover as threatening conditions approach and monitor local media broadcasts for further updates</instruction>

</info>

 

16. Indicate when an update message contains non-substantive content changes.

CAP

Element: <parameter>

Use:

Type:

Value:

Description: A system specific additional parameter associated with the alert message.

Notes: A <msgType> value of “Update” updates and supercedes the earlier message(s) identified in <references>. Therefore the update message must reflect the entire state of the event and is by default always a substantive change.

Example:

CAP-CP

Element: <parameter>

Use: Recommended

Type: Policy

Value: A <valueName> of “profile:CAP-CP:0.3:MinorChange” and a <value> of “none”, “text”, “correction”, “resource”, “layer”, or “other”.

Description: The purpose of this parameter is to support advanced distribution decisions associated with reducing the number of cases of over alerting.

  1. This parameter may only be used when the <msgType> is “Update” and the <references> element is correctly populated.
  2. This parameter may only be used when all <info> blocks in a message contain non-substantive content changes or no change. Adding or removing an <info> block relative to the previous message is a substantive change.
  3. The addition, removal, or change of the following elements may be considered non-substantive:  <audience>, <headline>, <description>, <instruction>, <web>, <contact>, <parameter>, <areaDesc>, and <resource> blocks. Both sending and receiving systems are free to impose additional constraints on what they consider to be non-substantive changes.
  4. When an alert message is considered a minor update, all <info> blocks must contain a “MinorChange” parameter value(s) with an appropriate value setting reflecting the minor change.
  5. A <note> element may be used to further explain the reason for the minor changes in this update.
  6. When no change has occurred in an <info> block relative to the previous message, the value of “none” should be used.
  7. When a change has occurred between <info> blocks where some free form text content may have been added or modified, the value of “text” should be used in the <info> block(s) where applicable.
  8. When a correction is made to some of the free form content, perhaps because of an error, spelling mistake or omission, the value of “correction” should be used in the <info> block(s) where applicable.
  9. When the addition, modification, or removal of a <resource> block and its associated content takes place relative to the previous message, the value of “resource” should be used in the <info> block(s) where applicable.
  10. When the addition, modification, or removal of layer based values takes place relative to the previous message, the value of “layer” should be used in the <info> block(s) where applicable.
  11. When the content change doesn't meet the criteria of the other parameter values, the value of “other” should be used in the <info> block(s) where applicable. A <note> element should always be used with “other” changes.
  12. The values “none”, “text”, “correction”, “resource”, “layer”, and “other” are not case sensitive, and shall not be translated.

Notes:

  1. Electing to process and the subsequent presentation of non-substantive content is left up to the sender or receiver.
  2. If a receiver chooses to ignore this parameter and value, all update messages should be considered substantive as per the intent of the Reference Standard.
  3. If a transmission error occurs and the receiver does not receive the referenced previous message to which the non-substantive change applies, the current message should be considered substantive.

Example:

(Initial Update)

<alert … >
<identifier>CA-EC-CWTO-2008-13</identifier>

<references>cwto@ec.gc.ca,CA-EC-CWTO-2008-11,2008-07-16T16:00:00-00:00</references>

<info>

<language>en-CA</language>

<area>
<areaDesc>Sainte-Anne-de-la-Perade</areaDesc>
</area>  
</info>
</alert>

(Subsequent Minor Update)

(The following message corrected the spelling of the name. In this case the original did not have an accent on the name segment Pérade so a minor update was initiated. No other elements from the referenced CAP message were altered so the original message, if it was left to continue playing as it was, would still be correct except for the spelling of the place name. Some distributors may choose not to resend the alert based on this change, opting to keep over-alerting cases to a minimum while others with passive display systems would likely act on this update).

 

<alert … >
<identifier>CA-EC-CWTO-2008-14</identifier>

<references>cwto@ec.gc.ca,CA-EC-CWTO-2008-11,2008-07-16T16:00:00-00:00 cwto@ec.gc.ca,CA-EC-CWTO-2008-13,2008-07-16T16:00:00-00:00</references>

<info>

<language>en-CA</language>

<parameter>
<valueName>profile:CAP-CP:0.3:MinorChange</valueName>
<value>correction</value>
</parameter>

<area>
<areaDesc>Sainte-Anne-de-la-Pérade</areaDesc>
</area>  
</info>
</alert>

17. Indicate automated translation of free form text

CAP

Element: <parameter>

Use:

Type:

Value:

Description: A system specific additional parameter associated with the alert message.

Notes:

Example:

CAP-CP

Element: <parameter>

Use: Optional

Type: Policy

Value: a <valueName> of “profile:CAP-CP:0.3:AutoTranslated” and a <value> of “yes” or “no”

Description: Automated translation is any kind of machine based translation of free form text or the assembly of phrases based on pre-set values where a human translator has not been involved. The purpose of this rule is to support advanced distribution decisions associated with multilingual messages.

  1. When automated language translation of free form text content in an <info> block has taken place, a single instance of this parameter should be used with a value of “yes”.
  2. For alert messages with multiple <info> blocks, only the <info> block(s) where this automated translation has taken place should use the parameter.
  3. When issuing an update message for an <info> block that contains free form text content that has been subsequently reviewed by a human for correct translation, replacing automated translated content, this parameter should be used with a value of “no”.
  4. The values “yes” and “no” are not case sensitive and shall not be translated.

Notes:

  1. Electing to process and the subsequent presentation of automatically translated content is left up to the receiver.
  2. Considerations related to translation and multilingual requirements are numerous, and are to be addressed in supporting documents.
  3. Issuers who intend to use <autoTranslated> should supply supporting documentation indicating which elements are/were auto translated.

Example:

(In the following alert, the instruction was auto generated in English by software interpreting a responseType rather than the free form sentence generated by a person in French. In situations where the first language text is not so simple as exampled, interpretations can be problematic. Therefore, a simple parameter element is used to flag the auto translation activity of the originator)

<alert … >

<info>
<language>en-CA</language>

<instruction>Take shelter as threatening or hazardous conditions arrive.
</instruction>
<parameter>
<valueName>profile:CAP-CP:0.3:AutoTranslated</valueName>
<value>Yes</value>
</parameter>

</info>
<info>
<language>fr-CA</language>

<responseType>Shelter</responseType>
<instruction>En menaçant des approches de temps, prenez l'abri à l'intérieur et surveillez la radio locale pour d'autres mises à jour
</instruction>

</info>
</alert>

Footnotes

  1. 1

    The website for the US Partnership for Public Warning (PPW) can be found at: http://tides2000.mitre.org/ppw/index.html

Date modified: