Guidance for IPAWS Common Alerting Protocol (CAP) Elements and Sub-Element Data Sean Donelan – [email protected]
Total Page:16
File Type:pdf, Size:1020Kb
Guidance for IPAWS Common Alerting Protocol (CAP) Elements and Sub-element Data Sean Donelan – [email protected] This guidance attempts to follow the Common Alerting Protocol philosophy -- one CAP message is intended to be distributed by multiple alerting channels. The guidance is intended to improve the consistency of CAP messages across all IPAWS distribution channels. Some items improve interoperability with different implementations, such as specifying case-sensitive versus case- insensitive values. Other items would improve the public presentation of alerts, but don’t affect the operation of the alert system. The guidance does not favor a particular IPAWS distribution channel. Nevertheless, this guidance does recognize some CAP elements are used for specific IPAWS distribution channels. For example, general CAP elements such as Headline, Description and Instructions used by multiple IPAWS distribution channels, should use mixed case text with normal punctuation according to the Info block language. But CMAMtext and CMAMlongtext Parameter elements, used only for WEA, should use only characters which can be transformed into the GSM 7-bit character set. Finally, some poorly specified CAP elements could be used by new IPAWS distribution channels, such as Internet and future alerting systems, if better specified. Geo-location elements and Resource blocks are examples. Interoperability items are always the most difficult to reach agreement, because multiple choices are possible. Different choices may be correct but may not be interoperable. This guidance intentionally makes some choices which are different than individual alerting origination software, but I believe improve the overall alerting ecosystem across all stakeholders. That does not mean those vendors were incorrect. I hope those vendors and customers will consider making compatible changes. CAP Alert Element and Sub-elements Details CAP v1.2 standard Liberal accept Conservative send Notes Alert <alert> Required. The container for all component parts of the alert message. (Required) Message ID <identifier> Must be unique (case- Automatically generate Must be something unique for The identifier of the alert sensitive) within same Sender Message ID when sent. each message. message. ID. Suggestion: A Universally (Required) Unique Identifier (UUID) or 3/13/19 1 Guidance for IPAWS Common Alerting Protocol (CAP) Elements and Sub-element Data Sean Donelan – [email protected] Must not include spaces, Use only URL and Filename (GUID), e.g., “123e4567-e89b- commas or restricted Safe Alphabet (RFC4648) [A- 12d3-a456-426655440000.” characters (< and &). Za-z0-9], hyphen and Use database or include underscore. workstation hash to avoid ID An identical Message ID could collisions. be used with multiple Sender Avoid case-sensitive values, Alternative: A structured string IDs. Message IDs are not i.e., use all upper or used to order and group universally unique, only lowercase. When used in events in other systems, such unique with the same Sender Reference ID, could be treated as used by IPAWS tests, NWS ID. as case-sensitive. and NCMEC. Maximum 64 characters. Do not reuse Message IDs with the same Sender ID. Sender ID <sender> Assigned globally unique Automatically populate based Avoid personally identifiable The identifier of the sender of (case-sensitive) name for alert on alerting organization. information, such as operator the alert message. originator. email addresses. “<name>@” (Required) Use only Internet domain portion usually unnecessary. Must not include spaces, name alphabet (RFC1035) [A- commas or restricted Za-z0-9], hyphen and period. Suggest using organization characters (< and &). fully qualified domain name: Avoid mixed case names, i.e., “fema.dhs.gov” Verify (Message ID and Sender use all upper or lowercase. “mshp.dps.missouri.gov” ID) is not a duplicate Alert. When used in Reference ID, “oem.nyc.gov” could be treated as case- Organization domain should sensitive. be consistent with COG. Maximum 64 characters. The Sender ID is always the actual originator, even if the Sender Name is a different 3/13/19 2 Guidance for IPAWS Common Alerting Protocol (CAP) Elements and Sub-element Data Sean Donelan – [email protected] agency name. The Sender ID element is not intended to be rendered as part of the public alert. Sent Date/Time <sent> Must have valid date / time / Automatically populate with Use local time and time zone The time and date of the offset format “CCYY-MM- the current time when sending offset of intended alert area or origination of the alert DDThh:mm:ssXzh:zm”. the CAP message. community. message. (Required) Verify the Sent Date/Time is Sent Date/Time must be If a nationwide alert, use recent, i.e., not older than the within +/- two minutes of Eastern time zone offset. expiration time interval for the current time. distribution channel. See notes below. Message Status <status> CAP v1.2 code values “Actual” Required for Public alerts. The code denoting the Allowed values Actual, appropriate handling of the Exercise, System, Test or Draft. alert message. (Required) Message Type <msgType> CAP v1.2 code values Alert, Update or Cancel Alert, Update and Cancel The code denoting the nature Allowed values Alert, Update, message types used for Public of the alert message. Cancel, Ack or Error. alerts. (Required) Source <source> Omit, if not used. May appear as the signature The text identifying the source line in the alert message in of the alert message. Automatically populate based some CAP distribution (Optional) on alert origination point. channels. Should be treated as metadata, not normally rendered as part of the public alert. 3/13/19 3 Guidance for IPAWS Common Alerting Protocol (CAP) Elements and Sub-element Data Sean Donelan – [email protected] See notes below. Scope <scope> CAP v1.2 code values “Public” Required for Public alerts. The code denoting the Allowed values Public, Public alerts are assumed to intended distribution of the Restricted or Private. be appropriate for immediate alert message. public release. (Required) Restriction <restriction> Required when Scope is Omit, if not used. CAP public distribution The text describing the rule for Restricted. channels should NOT render limiting distribution of the May be present even when Must not be present in Public CAP messages containing a restricted alert message. Scope is not Restricted. alerts. Restriction element, even if (Conditional) the Scope element is Public. Alert Originators should not rely on (public) exchange partners obeying the contents of the Restriction element. Addresses <addresses> Required when Scope is Omit, if not used. Not used by CAP public The group listing of intended Private, optional when Scope distribution channels. recipients of the alert is Public or Restricted. May be used for CAPEXCH, message. Space delimited string of all even when Scope is Public, to (Conditional) COG-ID(s) that the message notify other COGs. will be posted to. Handling Code <code> “IPAWSV1.0” Required for Public alerts. The code denoting the special handling of the alert message. (Optional, multiple occurrences allowed) Note <note> Omit, if not used. Not used by Public CAP The text describing the distribution channels. purpose or significance of the If present, should contain A Note element should be alert message. plain text, without control present when Message Status (Optional) 3/13/19 4 Guidance for IPAWS Common Alerting Protocol (CAP) Elements and Sub-element Data Sean Donelan – [email protected] codes or formatting is Exercise or Message Type is characters. Error. Reference IDs <references> Required when Message Type Cancel, Update, Ack or Error All related messages that have The group listing identifying is Update, Cancel, Ack or Error. should automatically populate not yet expired must be earlier message(s) referenced May be present when from unexpired, previous CAP referenced for Update and by the alert message. Message Type is Alert. message(s). Cancel messages. (Optional) If present, must reference earlier CAP message or Preserve exact element values Do not include Reference IDs messages and structured as from original CAP message, of expired CAP message(s). “sender,identifier,sent” including case. with 3 data elements and 2 Alerting organizations should commas. not Update or Cancel If multiple CAP messages are messages with different referenced, each reference ID Sender IDs, except in structure must be separated extraordinary circumstances. by whitespace. CAP exchange partners should check for exact match, including case-sensitive. If no previous message found, may check for case-insensitive match. Incident IDs <incidents> If multiple incident identifiers Omit if not used. Not used by Public CAP The group listing naming the are referenced, they shall be distribution channels. referent incident(s) of the separated by whitespace. May be used for CAPEXCH. alert message. Incident names containing (Optional) whitespace shall be surrounded by double-quotes. Notes on Sent Date/Time element: 3/13/19 5 Guidance for IPAWS Common Alerting Protocol (CAP) Elements and Sub-element Data Sean Donelan – [email protected] All time elements (Sent, Effective, Onset, Expires) in CAP message should use the local time zone of the alerting area of responsibility. If an alerting organization’s area of responsibility spans multiple time zones, choose a consistent local convention. For example, statewide Amber alerts could use the local time and time zone offset of the state capital. Avoid using Coordinated Universal