The Distribution Element:The Basic Steps to Package and ...



An OASIS Emergency Management Technical Committee White Paper

The Distribution Element 2.0

The Basic Steps to Package and Address Your Emergency Information

By Jeff Waters and Rex Brooks

On behalf of the OASIS Emergency Management Technical Committee

Date: 1322 August April 20132

This paper provides a basic introduction to the Distribution Element 2.0 (DE2), one of the important OASIS EDXL standards for emergency management and response. As with the earlier version, the DE2 serves the same two primary purposes: (1) the DE2 allows an organization to wrap important pieces of emergency information into a single easy-to-distribute XML "package", and (2) the DE allows an organization to "address" the package in flexible ways to support intelligent routing, including specifying recipients by role, by geographic area, or by keywords. With the DE, organizations can use standardized lists of roles or keywords, or their own lists for additional flexibility and tailoring. So what’s new? This version of the DE expands the ability to use local community-defined terms, uses a profile of the Geographic Markup Language (GML), follows best practices for naming conventions, provides an extension mechanism for inclusion of supplemental community terms and information, provides the capability to link content objects, and is reorganized for increased flexibility and reuse of common types. Fortunately, the DE remains a simple, concise standard. This paper describes the DE version 2.0, highlighting changes from the original version. After reading this short paper, the reader will be ready to begin using the DE2.

This white paper was produced and approved by the OASIS Emergency Management Technical Committee as a Committee Draft. It has not been reviewed and/or approved by the OASIS membership at-large.

Copyright © 2012 OASIS. All rights reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Table of Contents

Introduction 4

Background 5

About OASIS 6

Purpose 7

What’s New? 8

Scope 11

What’s in the DE? 12

The DE Header Tags 12

The DE Descriptor Tags 13

The Content Wrapper Tags 18

Putting It All Together 19

Where is the Post Office? 22

Conclusion 23

References 24

APPENDIX A. Distribution Element (DE) 2.0 XML Schema 25

APPENDIX B. Distribution Element (DE) Domain Model 30

APPENDIX C. Distribution Element (DE) Completed Example 31

Introduction 4

Background 5

About OASIS 6

Purpose 7

What’s New? 8

Scope 11

What’s in the DE? 12

The DE Header Tags 12

The DE Descriptor Tags 14

The Content Wrapper Tags 19

Putting It All Together 20

Where is the Post Office? 24

Conclusion 25

References 26

APPENDIX A. Distribution Element (DE) 2.0 XML Schema 27

APPENDIX B. Distribution Element (DE) Domain Model 32

APPENDIX C. Distribution Element (DE) Completed Example 33

Introduction

Wouldn't it be nice if the important information about an emergency were available in a single package rather than scattered about in bits and pieces? And wouldn't it be nice if the package were addressable to the right groups of people, those with appropriate roles or those in certain geographic areas rather than distributed ad hoc or by local custom or not distributed at all? Yes, it would be nice and there exists today a standard to do just that: the Distribution Element 2.0 (DE).

Perhaps the best news about the DE is that it's simple. Anyone can learn and use the DE. In fact, by the time you finish reading this short paper, you too will know how to package and address your information the DE way. Welcome to Basics of the DE. Let's begin.

Background

The DE version 2.0 is an enhanced version of the original Distribution Element, one of a family of standards that comprise or support the Emergency Data Exchange Language (EDXL). EDXL began in 2004 as a project of the Disaster Management eGov Initiative of the U.S. Department of Homeland Security (DHS) as a means to enhance inter-agency emergency data communications. The standards which comprise or support EDXL are: (1) Common Alerting Protocol (CAP) for emergency alerts; (2) Resource Messaging (RM) for issuing and handling requests for emergency resources; (3) Hospital AVailability Exchange (HAVE) for communicating the status of a hospital and its resources; and (4) the Distribution Element 2.0 (DE) for packaging and addressing emergency information. (New standards emerging include Situation Reporting (SitRep) and Tracking of Emergency Patients (TEP)) All of these standards can be found under the names CAP, EDXL-DE, EDXL-RM and EDXL-HAVE at the OASIS website: . The goal of the EDXL initiative is to facilitate emergency information sharing and data exchange across the local, state, tribal, national and non-governmental organizations. The effort focuses on standardization of specific messages to facilitate emergency communication and coordination. Any technology vendor or organization can easily develop their XML-based messaging exchanges using these standards, leveraging their existing legacy information technology applications. For more background on EDXL, see .

About OASIS

The Organization for the Advancement of Structured Information Systems (OASIS) is an international, not-for-profit, open standards organization which fosters the development, convergence and adoption of open standards in a variety of domains, including emergency management, cloud computing, service oriented architecture, the Smart Grid, and electronic publishing. Open standards are standards developed by an organization open for membership to all qualifying organizations or individuals, with an orderly, equal and fair opportunity for contribution to the development of the standards by all members. OASIS has more than 5,000 participants representing over 600 organizations with members from over 100 countries.

The benefits of open standards adhere to all members and non-members alike; however, the benefits of membership are unique to members. Open standards improve interoperability of systems, enabling plug-and-play opportunity for all vendors and individuals. Open standards lower overall cost of system development and maintenance, stimulate innovation, grow global markets, and protect the right of free choice of technology. The benefits of membership include early assessment, feedback, and education on the emerging standards that impact your business or agency. Your organization can help lead the standards development effort in your field of interest, defining data formats that will govern information exchange in your field for years to come.

Participation in OASIS is easy, low-cost, and fun, with direct benefits to your business and your bottom line. Technology is changing too rapidly for any individual or company to go it alone. The connections to members, who include business partners, customers, government organizations, and technology/standards experts, enable your organization to not only stay on top of but to design the technology-driven business landscape.

Please review the list of OASIS member organizations at and consider whether you too would like to join. The OASIS staff is friendly and helpful, ready to answer your questions. To reach a staff member to discuss how to participate, please send an email to XXX or call YYY. If you would like to join our Emergency Management Technical Committee, we would like to welcome you and we are also available to answer your questions. Please send an email to ZZZ or if you would like to chat by phone, the OASIS staff will put you in contact with one of our members. Thanks.

Purpose

The DE serves two important purposes. First, the DE allows an organization to wrap separate but related pieces of emergency information into a single "package" for easier and more useful distribution. Second, the DE allows an organization to "address" the package to organizations with specified roles or groups located in specified locations or those interested in specified keywords. In the absence of national standards on incident taxonomy, the DE allows an organization to use its own terms to characterize its content, such as roles and keywords. This version 2.0 of the DE expands the ability to use local community-defined terms, uses a profile of the Geographic Markup Language (GML), follows best practices for naming conventions, provides the capability to link content objects, and is reorganized for increased flexibility and reuse of common types.

DHS recommends the DE in their grant guidance to ensure systems are built to support sharing of emergency information. See . Use of the DE means that the wide variety of middleware systems do not have to develop separate capabilities to handle each kind of message. They only need to process the DE, without opening the content of the payload attached to it.

What’s New?

The new Version 2.0 of the DE keeps all the things that were good and worked well in the original Version 1.0 and adds improved customization, standardization, flexibility, and descriptive power:

Customization

In an emergency, it’s important to be able to use terms that are well-known and understood in your community. Version 1.0 was designed to allow some customization, so you could specify your own terms for roles and keywords. The ability to customize the DE has been expanded in Version 2.0. Now you can use Community Extensions to define your own terms for extending or tailoring other DE elements. Simply choose the best matching default term for use by outsiders and then use the extension mechanism to supply your own community-defined term. many other DE elements, including the type of distribution, the status of the distribution, kind of area, urgency, severity, confidence and classification. We’ll look at some examples in a bit. This increased ability to customize the DE puts you and your jurisdiction or community in control to use and expand your own terms to describe your emergency information. Of course, the customization is optional and you don’t have to use it. Default values are provided for your use as well. It’s your choice.

Standardization

When developing a standard like the DE, it’s useful and sensible to reuse well-known, existing standards. There is no need to reinvent the wheel and interoperability is fostered because many systems already understand the existing standards. Version 1.0 was largely homegrown, but now that it has matured we have had the opportunity to reuse some important standards in Version 2.0. The Geography Markup Language (GML) developed by the Open Geospatial Consortium (OGC) is now used in Version 2.0 to represent addressing information based on geographic area. Customer Information Quality (CIQ) developed by OASIS is now used to represent addressing information based on geopolitical information such as street, city, state, and country. To keep it simple, only a subset (profile) of the full standards were used. In addition, Xlink developed by the World Wide Web Consortium (W3C) is now used to enable you to better describe your content by providing meaningful links between your content objects. The net effect of using these standards is improved interoperability and robustness when sending your emergency information using the DE Version 2.0.

Flexibility

What if you already distribute your emergency information using another standard “wrapper” like SOAP or ATOM? In Version 1.0 of the DE, there wasn’t much flexibility. Users felt they would have to abandon their existing standardized distribution mechanism and lose out on the benefits of the DE. In Version 2.0, the descriptive components are now usable outside the traditional wrapper components. So you can now have the benefits of the DE to describe your emergency information no matter which wrapper you use. It’s your choice.

Descriptive Power

A well-known problem with ensuring people have the information they need is to decide whether to use explicit addresses like an email address or implicit addresses like roles or keywords, such as “State Coordinating Officer”, “Disaster Recovery Center” or “Search and Rescue”. Although explicit addressing is easy and simple, just like sending an email, it has the same disadvantages as email. Often people don’t get the information they need because they weren’t on the address line and often, in an emergency, the senders don’t know everyone and don’t know their explicit addresses. So explicit addressing is easy but brittle and doesn’t scale effectively in an emergency. The better option is often implicit addressing where a role or keyword is specified and the target recipients are determined either by the distribution system using rules or by the recipients who have previously subscribed for the types of information they want. This better implicit option requires an ability to effectively describe the key content of the message.

An ideal addressing mechanism would allow for a range of addressing with significant capability for implicit addressing. Version 1.0 of the DE supported a range from specific to general, including explicit address, role, target area, and keywords. Version 2.0 expands this capability to describe your content. You can now specify the urgency, severity, and confidence of your message. You can specify multiple kinds of areas that describe your message, such as source area or evacuation area. You can specify your own any descriptive terms from your own list used in your community. You can specify the confidentiality of your message using your preferred list of terms. Now transport systems have a better description of the messages you are sending and be in a better position to do smarter routing, to apply rules and infer from those terms the target recipient(s).

Note: You can use both explicit and implicit addressing in the DE. You can specify someone specific and still provide keywords, areas, confidence, urgency and other terms so that all appropriate and interested users will receive your message.

LayersCommunity Extensions

The DE 2.0 now supports the inclusion of community-defined sets of name/value pairs, referred to here as “LayersCommunity Extensions” or simply “Extensions” for short. Users of the Common Alert Protocol (CAP) are familiar with this concept since CAP was the first EDXL standard to include the Parameter element which allows a user to add name/value data to a normal CAP alert. The Canadian Emergency Management community has been utilizing the Parameter elements to send supplemental business information, referred to as “layers”, with CAP for years. Now, you can do the same with the DE and other EDXL standards. For example, if you send a DE message with sent a CAP alert about anan alert or image about an earthquake, you might want to include some specific earthquake data, like the magnitude and depth of the earthquake. Since CAP is a more general alerting standard, thereThere are no earthquake-specific fields in the DE; however, your community can extend the DE to include that information, which you define as a set of Parameter elements specifically, designed to represent earthquake data. the designers of CAP realized this need would occur to add additional data. Rather than just stick this information into some arbitrary text field, the CAP designers allow you to add this data into the alert by using the Parameter element and including the name and value for each of these pieces of earthquake information. In Canada, this technique was formalized into the definition of sets of name/value pairs, referred to as “Layers”, that could be specified and shared across the Canadian emergency management community. So, for example, you could add to your CAP message a “layer” of earthquake data or perhaps a “layer” of event data or both. “Layers” are being used in Canada to document system specific, channel specific, community specific, and purpose specific values (and sometimes rules) associated with CAP alerts in Canada. (For more information on the use of Layers in Canada, see ) Although such extension mechanisms are sometimes frowned upon by standards’ developersstandards’ developers sometimes frown upon such extension mechanisms, since they appear to allow for arbitrary, non-standard representation of information, the “LayersCommunity Extensions” concept solves several major problems when for improving information sharing and developing standards for the emergency management community. First, the nature of emergencies is that the unexpected will happen and emergency managers need flexibility and the ability to send whatever information is needed adapt. Second, an emergency begins and often stays local, so local authorities and users need control to send the information they decide is important to address the current emergency. Third, communities need the opportunity to explore potential new standards. The Parameter name/value extension mechanism, along with the concept and formalism of “LayersCommunity Extensions”, provides an on-ramp for communities to determine what works well for them. T and those Community Extensionssolutions which are most successful can be formalized into future standards. Now, with support for Layers Community Extensions in the EDXL Common Types and the DE 2.0, you can add supplementaluse “lLayers” of business information and receive the same benefits whenever any EDXL message is sent.

A Few Problems Fixed

The development of Version 2.0 of the DE provided the opportunity to address a few specific problems that had cropped up with Version 1.0. These are specific problems, which may not have come up for you, but we can mention them quickly:

Grouping Areas: With Version 1.0, you could specify multiple target areas but it was never clear what this meant. Should the message go to everyone in any of these target areas? If the areas overlapped, should the message be sent to only those in the intersection? Or are the areas alternative descriptions of the same area? This created some confusion which is now fixed. In Version 2.0, you can specify not only the kind of area with defaults (e.g. source, target) or your own terms, but also how you want the areas grouped (e.g. union, intersection). So no more confusion over how to group multiple target areas.

Distribution Reference: If you sent a message, and then wanted to update or cancel it, in Version 1.0 you had to send another message and specify details to identify the previous message. The details were not standardized and the requirement created difficulties for users who were doing many updates. Also the requirement was more related to the mechanics of message transport. After all, from a user standpoint, it’s the same message, we’re just updating or canceling it. The solution in Version 2.0 is to do away with the requirement to specify details of the previous message. The recommended method to update or cancel is to use the same message id for both the original message and any updates. (Note that if a system needs to find the previous messages, it can do so using the date time sent.)

Expiration: If you send a message, when should your message expire? There was no specific way to specify this in Version 1.0 which created the obvious problem and burden of having to send many cancellation messages or leave it up to recipients to guess when the message should expire. If you were to look at a message, how would you know if it was out-of-date? For emergency messages, it’s important to know when they expire. The simple fix in Version 2.0 was to include DateTimeExpires as an element right next to DateTimeSent.

So what’s new in Version 2.0? The good old stuff from Version 1.0 is still there but what was good before is better now. More customization, more flexibility, more standardization, and more descriptive power are now at your fingertips. A new opportunity for emergency information sharing and interoperability awaits as soon as you start to use the DE.

Scope

The rest of the paper describes what is in the DE; however, for effective understanding and usage of the DE, it is equally important to say what is not in the DE. Although the DE facilitates improved routing of emergency information, the DE is not intended to replace or compete with standards covering core routing capabilities and routing needs that apply generally to any type of information sharing. These more general capabilities and needs include authentication, quality of service, redundancy, backup, message brokering or translation, choice of transport mechanism, and encryption, among others. Routing is an important topic of its own and is addressed by a number of organizations with a variety of standards.

The DE facilitates routing by packaging information and describing the message with labels such as keywords, intended recipient roles and sender roles; however, the DE assumes that other standards will be used to enable the routing itself and to address the routing concerns mentioned above that are typical of any information sharing framework across an enterprise. This separation of concern allows the DE to be a simple standard focused on its core purpose: packaging, describing and addressing emergency information. The OASIS Emergency Management Technical Committee has prepared a draft document advising on best practices for addressing these routing concerns from the perspective of the DE and the EDXL overall. The draft “Best Practices for Routing Using the Distribution Element”, can be found at

What’s in the DE?

The DE is simply a set of eXtensible Markup Language (XML) elements, sometimes referred to as “tags”. An XML element is a name for a piece of information defined in a schema. In fact, if you're familiar with XMLSchema, you may want to go straight to the schema in Appendix A and take a quick look. The DE is short and simple. For those with a graphical bent, you may want to take a quick look at the domain model diagram in Appendix B. For the rest of us, we'll go over the basics right here.

For explanatory purposes, we'll subdivide the DE into three parts or three sets of XML elements (“tags”): the Header tags, the Descriptive tags, and the Content Wrapper tags. We'll review each part of the DE with examples. This will give us a quick practical overview of the DE with xml examples for all the basic DE tags.

The DE Header Tags

The seven DE header tags are contained in a DE Envelope tag and are used for simple administrative annotations. The tags and their data types are:

1. DistributionID (EDXLStringType)

2. SenderID (EDXLStringType)

3. DateTimeSent (EDXLDateTimeType)

4. DateTimeExpires (EDXLDateTimeType)

5. DistributionStatus (DistributionStatusType)

6. DistributionKind (DistributionType)

The tags are fairly self-explanatory. If you choose to use the DE Envelope tag, as most users will, then all of these header tags are required.[1] You can put a unique string of your choice in the DistributionID to identify the package. In the senderID, an e-mail address will suffice.

The DateTimeSent tag is just what it says and contains the date and time. The DateTimeExpires is a new tag in the DE version 2.0 which represents the date and time after which the information in the package should no longer be relied upon. The only oddity for newcomers to XML dateTime is the format where, for example, August 7th, 2008 at 6:05pm in the U.S. Mountain timezone is represented as 2008-08-07T18:05:00-07:00. This format is borrowed from ISO 8601 and is of the form: CCYY-MM-DDThh:mm:ss[(+|-)hh:mm] where the timezone is specified as (+|-)hh:mm.[2]

Sometimes it’s nice to have a choice: either use default terms or use your own. The DE 2.0 supports interoperability by providing reliable defaults for many of the elements and allowing you to use your own terms utilizing the ValueList* where no defaults are available, such as for senderRole, or for providing supplemental information in Community Extensions. In the case of DistributionStatus and DistributionType, defaults values are provided and you select one. Both DistributionStatus and DistributionType give you this choice. The default DistributionStatus can be one of Actual, Exercise, System or Test. The default DistributionType can be one of Report, Update, Cancel or a few others. Usually, the DistributionType will just be Report. Both DistributionStatus and DistributionType are ValueLists *. See Figure 1 (below).



mary.thompson@

2009-11-15T16:53:00-05:00

2009-11-15T17:53:00-05:00

Exercise

Report

mary.thompson@

2009-11-15T16:53:00-05:00

2009-11-15T17:53:00-05:00

urn:oasis:names:tc:emergency:EDXL:DE:2.0:Defaults:StatusKind

Exercise

urn:oasis:names:tc:emergency:EDXL:DE:2.0:Defaults:DistributionType

Report

Figure 1. XML Snippet of Distribution Element Header Tags Using Default Values

There is nothing particularly fancy or special about these header tags, but they are important for purposes, such as message tracking and auditing. Here's what the tags look like when filled in with some sample data.

The DE Descriptor Tags

The fourteenten Descriptor Tags include:

7. cCombinedConfidentiality

8. lLanguage

9. sSenderRole

10. rRecipientRole

11. kKeyword

12. eExplicitAddress

13. tTargetAreas

14. uUrgency

15. sSeverity

16. cCertainty

17. iIncidentID

18. iIncidentDescription

19. lLink

20. ext:extensionLayer

These tags are primarily complex types which means they contain other tags, as shown in the examples below. All of these tags are optional, so you can just use the ones you need. The Distribution tags enable various ways of addressing your package, explicitly by specific address, or implicitly by geographic area, by recipient role, and by keyword. Let’s look at examples of how each of these tags can be used to aid description and distribution of your emergency information.

With the first two tags, cCombinedConfidentiality and lLanguage, you can describe the emergency information in terms of its level of privacy and written language. For cCombinedConfidentiality, you may reference a list of terms and then select one value from the listchoose classified or unclassified. (For more specific classification terms, you may include your own supplemental classification as a Community Extension.) Use the term describing the highest classification of your packaged content. For example, to specify that the emergency information is unclassified, one could do the following:

Unclassified

EN

urn:oasis:names:tc:emergency:EDXL:DE:2.0:Defaults:ConfidentialityType

Unclassified

EN

Figure 2. XML Snippet of Distribution Element Descriptor Tags: cCombinedConfidentiality and lLanguage

For Language, use the two-letter language code familiar to html developers, e.g. "EN" for English. (For a complete list of codes, see ISO639-1 at .)

You also can address information to a group of people (or computer systems) by their role in the emergency, such as the example below which indicates the sender is supporting “Search and Rescue” and the recipients are systems supporting situational awareness and warning devices:

urn:myagency:gov:sensors:senderRole

Search and Rescue

urn:myagency:gov:sensors:recipientRole

Situational Awareness Apps

Warning Devices

urn:myagency:gov:sensors:senderRole

Search and Rescue

urn:myagency:gov:sensors:recipientRole

Situational Awareness Apps

Warning Devices

Figure 3. XML Snippet of a DE sSenderRole and rRecipientRole

These particular roles are for demonstration purposes. You can select from lists of roles developed by your community or jurisdiction. Each of these roles is a ValueList, consisting of a list name and one or more selected values from the externally-managed list. The list name, the tag, is a Uniform Resource Name (URN) or a Uniform Resource Locator (URL) which are W3C standards for creating unique identifiers. The DE uses this construction of followed by one or more to give communities flexibility to define standard lists of terms for roles and keywords. For more information on URNs, see .

You can address a group of recipients by specifying keywords from a list. The keywords can be used for searching and filtering. Here is an example:

urn:myagency:gov:sensors:keywords

SNM Detection

XYZ

urn:myagency:gov:sensors:keywords

SNM Detection

XYZ

Figure 4. XML Snippet of a DE Keyword(s)

For specific address routing, just use the tag, specifying the distribution method and address. For example, to send the package via email to joe.smith@, you would do this:

e-mail

joe.smith@

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download