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

PDF (326 KB)

Reference Standard: OASIS - Emergency Data Exchange Language - Common Alerting Protocol (EDXL-CAP) version 1.2.

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. 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 version are listed below in alphabetic order:

• Doug Allport, Canadian Association for Public Alerting and Notification / Allport Group Inc.
• Jeff Boyczuk, Public Safety Canada
• April Diver, Alberta Emergency Management Agency
• Khalil Hayek, Natural Resources Canada
• Norm Paulsen, Environment Canada
• Jacob Westfall, Net Alerts
• Wendy Wu, Industry Canada

Copyright

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

Additionally, contents of this document may be used in the creation of other documents, providing attribution is given to CAP-CP, and providing the new document is identified in such a way that it will not be interpreted as an official CAP-CP document.

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 no major revisions to Beta Version 0.4 Draft. Revisions include the following:

1. Change to Copyright statement.
2. Addition of references to www.CAP-CP.ca
3. Comments associated with Rule #1 Valid CAP
4. Wording improvements in Rule #3 CAP-CP Version
5. Comments associated with Rule #4 Timezone
6. Wording improvements in Rule #5 Required <info> block
7. Comments associated with Rule #13 Expiry
8. Comments associated with Rule #17 AutoTranslate

Other CAP-CP Documents

The entire CAP-CP is defined in this document, and the following two additional documents, all of which can be found at www.CAP-CP.ca:

• CAP-CP Event References. This document details a comprehensive list of recognized events associated with Public Alerting in Canada. It is versioned independently of this document.
• CAP-CP Location References. This document details the current versions of the Standard Geographic Classification (SGC) location references supported by CAP-CP. It is versioned independently of this document.

Be sure to check www.CAP-CP.ca for updates to this document.

Associated Documents and Resources

1. The Reference Standard, the Emergency Data Exchange Language Common Alerting Protocol (EDXL-CAP or CAP) version 1.2 is a Standard administered by OASIS (Organization for the Advancement of Structured Information Standards). The current and past versions of the Reference Standard are available at: http://docs.oasis-open.org/emergency/cap/
2. www.CAP-CP.ca. This CAP-CP website offers CAP-CP related resources and links.

Please note that CAP-CP version 0.4 was introduced to align with CAP version 1.2. A CAP-CP version change was required because Rule #4 was removed from CAP-CP 0.3. Had the introduction of CAP 1.2 not required this substantive change, an erratum would have been published to refer to the new CAP version as the current Reference Standard.  

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:

Layer: 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 hazard alerting community. A layer is typically supported with the use of one or more <parameter> elements within a CAP or CAP-CP file.^{Footnote 1}

Managed List: 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 message (for example, the CAP-CP event list). The collective list of values is managed through ongoing versions, as the list is susceptible to change to reflect the needs of the community of users.

Profile: 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 target the needs specific to a country or system using the Reference Standard, and to the full community of users identifying with the profile. A profile provides context to the business of alerting within the country or system.

Rule set: 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, that impose usage requirements beyond those of the Reference Standard, but also remain in compliance with the Reference Standard.

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 Warning^{Footnote 2} (PPW).

In 2004, CAP became a standard of the Organization for the Advancement of Structured Information Standards (OASIS), and subsequently adopted by the International Telecommunications Union (ITU).

Canada’s Needs

In 2004, CAP became a standard of the Organization for the Advancement of Structured Information Standards (OASIS), and subsequently adopted by the International Telecommunications Union (ITU).

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 Management

CAP-CP has been managed by a small group of stakeholders known as the CAP-CP Working Group. The group’s website is hosted by the Canadian Association for Public Alerting and Notification (CAPAN).

In 2010 CAPAN secured funding to support a CAP-CP governance and change management study that all members of the CAP-CP Working Group supported. The project team concluded that CAP-CP needed national governance and a formal change management process that included a period of public review. They also reaffirmed their position that CAP-CP would be managed as Beta until the proper governance and change management process was put in place.

In January 2011 the Communications Interoperability Strategy for Canada defined a national governance structure that included a coordinating role for Public Safety Canada’s new Interoperability Development Office (PS-IDO). The associated Communications Interoperability Action Plan for Canada identified CAP-CP as a national priority and identified priorities associated for how it is managed.

In 2012 the PS-IDO will complete a formal change management process for emergency communications specifications that will be overseen by the Senior Officials Responsible for Emergency Management (SOREM). A version 1.0 CAP-CP is to follow this process under its new governance.  

About Layers

As defined above, the term layer used in this document refers to extended message elements that are not known to the Reference Standard or to 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 alert.^{Footnote 3}

Layers are simply a structured way of accommodating extensions in CAP and CAP-CP. Extensions are fundamental to the design of XML and the structured use of the <parameter> element formalizes the application of this basic principle for the community at large. The integrity of the Reference Standard and Canadian Profile is maintained while at the same time allowing CAP-CP to be managed and used without limiting the service potential of CAP-CP to any one use, user or system.

CAP-CP Overview

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

1. Constraint of one subject event type 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 and recommendations intended to help overcome implementation challenges that have been identified by the early adopters of the Reference Standard and 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 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 type value.

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 users.

Given that Canadian alerts may 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 event 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 rules.

4. Requirements associated with location identification

The Reference Standard supports the use of geo-referenced location codes to identify the alert area. 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.

Note that this requirement does not preclude the inclusion of geocodes from alternate code lists, such as postal codes, or Environment Canada Canadian Location Codes (CLC).

More precise means of location identification, such as geospatial polygons, are encouraged to more accurately identify the area to which the alert pertains. As such, future requirements for a geocode in a CAP-CP message may well become deprecated.

CAP-CP Rules

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

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.

Please note that the three CAP-CP documents are versioned independently, and that the versions used in the following examples are for reference only.

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:

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:

1. The Reference Standard allows for the inclusion of none, one, or many subject event types in a single alert message, but only one unique message <identifier>. An update to the information of any one of the events would appear as an update to the information of all the other event types, when that may not be the case.
2. A practical method of validating this rule is to ensure that all <info> blocks in an alert message have the same <eventCode> values.

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:0.3</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.4

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

Notes:

1. <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 referencing an additional Profile, layer identification, system specific functions, etc.

Example:

(Multiple profile reference)
<alert>
…
<scope>Public</scope>
<code>profile:CAP-CP:0.4</code>
<code>IPAWS v1.0</code>
<note></note>
…

(Additional Layer reference)

<alert>
…
<scope>Public</scope>
<code>profile:CAP-CP:0.4</code>
<code>layer:EnvironmentCanada:1.0</code>
<note></note>
…

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

Removed from CAP-CP as it has now been addressed in the Reference Standard.

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 at the time of this message

Notes:

Example:

CAP-CP

Element: <msgType>

Use: Required

Type: Policy

Value:

Description:
Alert 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 intended message to the public, and therefore 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.4</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.4</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. Enumerated CAP element values, such as those defined for <urgency>, <severity>, <certainty>, <responseType>, etc. are in English only, and are always used as specified by CAP within all <info> blocks.

Content in the <info> block, such as <description>, <resource> (ex. audio files), external <web> links, etc. should serve the needs of the language value within the <info> block.

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.

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:

1. The CAP-CP requires the use of an <eventCode> value from the CAP-CP Event References document that should match the corresponding <event> value.
2. There is a limit of one <eventCode> value from the CAP-CP Event References list per alert message even though multiple occurrences of the element <eventCode> may appear in an alert message.
3. The event code format is 4 to 12 characters, is not case-sensitive, and has no spaces allowed.
4. The <valueName> version suffix will change as new versions of the Event References document are published. As <eventCode> is a multi-use element, messages may be created that use codes from different versions of the Event References document in order to provide backward compatibility and to ease transition between list updates.

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> use is not encouraged in CAP. 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, however, when a higher level code may be used instead of all lower level codes, it should be.
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:

1. Geocodes are included so that all distribution systems are capable of distributing alerts, and for other purposes such as translation. In due course, the mandatory use a geocode is to be dropped from the CAP-CP rules.
2. Use of only the highest level all encompassing area division, that fully applies to a message, is recommended. For instance, if an area includes all Census Sub-Division (CSD) codes in a Census Division (CD), use the higher level CD code only.
3. Additional location codes from other lists such as a CLC or postal code may be included (Note: CLC is an Environment Canada Weather Radio location code).

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. CAP-CP requires that an <area> block contain one or more <geocode> values. It is recommended that geospatial values, such as <polygon> or <circle>, are 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 associated with the Location References document.

Notes:
Area descriptions (like events) will need to be translated by the originator of the message in cases where the location name is not associated with the Location References document.

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.

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

***NOTE: A request to re-consider this rule and remove this recommendation was received late in the process. The request recommends deferring back to the OASIS standard on the use of <expires> suggesting it is already best explained there when considering the element for use across all systems, users and distributors. The argument states that forcing a value into this element when none is apparent, as opposed to real time message updating or cancelling, may result in over-alerting and/or under-alerting of messages potentially misleading the audience of the message. While the CAP-CP Working Group concurs with this recommendation, a decision was made to insert this note rather than remove the rule since the CAP-CP community at large is still dealing with this issue. In either case, this rule is just a recommendation and the value remains optional.

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:

1. Only proper date and time formatted values should be used. Do not use a default value such as 0, an empty string or a null entry as this would be invalid.
2. To avoid misinterpretation, if the <expires> time is not known, the <expires> element should not be included in the CAP message at all.

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:

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.4: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.4: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.4: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 automated translation 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.4: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>

In the above alert, it is obvious that the AutoTranslated parameter is referring to the instruction element. However, in many cases it may not be so obvious and with several elements in CAP that can contain text and one parameter to address them all, it will require a detailed explanation in the supporting documentation for this parameter to be useful to end of the line distributors.

18. Preferential treatment of <polygon> and <circle>

CAP

Element: <area>

Use: Optional

Type: Technical

Value:

Description:
(1) Multiple occurrences permitted, in which case the target area for the <info> block is the union of all the included <area> blocks.
(2) MAY contain one or multiple instances of <polygon>, <circle> and/or <geocode>. If multiple <polygon>, <circle> and/or <geocode> elements are included, the location described by this <area> element is the union of those represented by the included elements.

Notes: <geocode> values are correlated to pre-defined geospatial locations, as in the case with the Standard Geographical Classification (SGC) values used in CAP-CP.

Example:

CAP-CP

Element:

Use: Optional

Type: Technical

Value:

Description:
CAP-CP requires a <geocode> value, and encourages the use of optional <polygon> and <circle> values. When <polygon> or <circle> values are present in an area block, the combination of <polygon> and <circle> values is the more accurate representation of the alert area. This is contrary to what is currently defined in CAP, which recognizes the area as the combination of the <geocode>, <polygon> and <circle> values.

Notes: The area(s) associated with <geocode> are often much larger than the targeted alert area, resulting in over alerting. This rule as defined now supports a more accurate representation of the alert area, while also supporting CAP-CP's mandatory inclusion of <geocode> in a CAP-CP message. System implementers that can support the more accurate location identification that comes with <polygon> and <circle> are encouraged to do so. Recipients that intend to process a CAP-CP message may choose to identify the alert area by the <polygon> and <circle> elements alone knowing that this does not represent anything less than the full intended alert area.

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>

The <polygon> provided is a more accurate representation of the alert area than is the combination of boundary files associated with the <geocode> values included in the alert.

Date modified:

2018-01-31