Integrated Public Alert and Warning System (IPAWS) Developer Webinar Open Platform for Emergency Networks (OPEN) Introduction to the New IPAWS-OPEN Developers Guide Wednesday January 18, 2012 12:00 Noon Eastern Avagene Moore: Ladies and Gentlemen: Welcome to the first Developers Special Interest Group Webinar of 2012. We are pleased that you chose to be with us today. As a reminder and especially for any new participants today, IPAWS-OPEN enables the interoperable sharing of emergency alerts and incident-related data between systems that comply with non-proprietary information standards, and serves as the alert aggregator for the Integrated Public Alert and Warning System. We are here today for an introduction and overview of the new IPAWS-OPEN Developers Guide. The purpose of the guide is to help developers successfully write IPAWS-OPEN interoperable code. The guide will be posted on the IPAWS Website soon. Our speaker will have more to say about that in his remarks. A friend to all of us, Gary Ham, System Architect, is our presenter today. Gary, thank you taking the time to be with us once again – we appreciate your effort and expertise. I now turn the floor to you. [Slide 1] Gary Ham: It is good to be here today. We have good things going on now—the test laboratory you have been using is up and stable and has been for a while now. [Slide 2] The documentation is almost completed. We are operational, live connections are in place, CMAS distribution is in place. The EAS connection and feed is live. The number of authorized alerting authorities is still rather small and the software in place for originators to build messages with IPAWS is still small and relatively immature. It has taken us awhile to get the documentation out and get everything stabilized. [Slide 3] The guide is still in its last iteration. It will be in a PDF file and put up on the website. We have some reference applications—if you worked in SOAP UI, that layout still works. I have a .jar file for signing if you use Java—it will sign a CAP message as an L-string. I completed an iteration of a 1.0 version of a CAP 12 property handler .jar that uses a properties file to drive all capabilities of IPAWS aggregator as a properties file. As a .jar file, it can be run from the command line or as an actual .jar from code. I haven’t finished all the documentation on it. If you are a dot netter upgrades to codes have been released with the ability to sign a signed CAP message. See the website on how to do that or reuse the code you find there. [Slide 4] I’m going to describe what is in the guide. It introduces how to get started, administrative steps and references to external documents. [Slide 5] It shows an architecture page which tells you what IPAWS-OPEN has in it. Most of you are a part of interoperating services. Most of you are interoperating alert originators. You can create messages and post CAP messages to the old CAP service, to the old NWEM service which still works. You can post an EDXL-DE message for exchange. You can post a CAP 1.2 message properly signed and the data will determine who will receive the message or if it will be pushed. You can put in the right information and send it to the EAS feed where it will be pulled by EAS devices. If it has the right data structure it could be sent to HazCollect where the 1.1 message goes because they are both translated backwards to the 1.0 message. The architecture it complicated but the interface is simple. [Slide 6] This shows what messages are. CAP 1.2 is the one that is important because it goes to the aggregator. There is a “submit request” message which asks for information back. You can ask for message lists. You can get a COG list or lists of data based on DE structure from value lists. You can get system acknowledgement, server time, whether the HazCollect server is active, what FIPS codes you can post to, if you have National Weather Service authority or unlimited authority. Something new in the aggregator—a consolidated message processsing status. You can send a message ID to us and we can tell you how it was distributed and its level of success. With CMAS, it will tell you which gateways picked it up. [Slide 7] The guide has a lot of information on the security aspects—SOAP level signature requirements and it provides a SOAP header sample. It also talks about CAP 1.2 level signature requirements and has an example that meets the requirements. [Slide 8] The message status structures identify name spaces to be used in each of the four services. One of the keys that is important is that while the function is the same, there is a different name space used in the service of each header to identify that server. Getting server information is important because in the 1.2 messages we will not forward them to a distribution method unless the time in the sent value is within five minutes of our server time. One thing we fixed about “getMessage” is if there is no message, you get back a system CAP message that tells you there is no message. This saves you from the exception handling you have to deal with when you get an error structure. [Slide 9] We have some examples—Legacy CAP, EDXL-DE, and some CAP 1.2 examples. There are examples, descriptions, and a significant numbers of programmers’ notes. [Slide 10] In CAP 1.2, there will be a validation path that is followed. First, it must pass the CAP 1.2 schema. If you get a 200 response, it passed and it has been saved. It can be retrieved. If you get an error code, the message did not pass the 1.2 schema and it cannot be retrieved. The 300 level is the core IPAWS validation. This checks if the message meets the core profile and if the signature is valid and verifiable on the message itself. If you get a 308 error, the message did not pass signature validation. There are other errors that could come back as well. There are three parallel paths. They are done independently of each other. Your message is checked for validation under the rules of the National Weather Service for Non-weather Emergency Message server and under the rules regarding the Emergency Alert Service, and the Cellular Mobile Alert Service. Some errors apply to more than one channel. Those will be in the 700s. You are looking for an even number in the 400s, 500s, or 600s. That means the message went out on that channel. [Slide 11] The CAP 1.2 aggregator does other checks. It checks if the COG is authorized or enabled for down range distribution. It checks if the COG is authorized for EAS and CMAS. If it is authorized for CMAS it could be CMAM text authorized. In CMAS, by default the message is created by using and translating value in the CAP message directly but by exception certain COGs are authorized to write their own 90 character text to be the message. Cellular providers do not want everyone to have CMAM text authorization. AMBER alerts (civil abduction) call for CMAM texts. Limited COGs will have this authorization. COGs can be allowed certain event codes and geocodes. Those checks are run against the COG and the data in the message to determine the results of where it is sent. We provide examples of messages and responses in the guide. [Slide 12] The tables are probably the best sources of information in the guide. The tables replace the CAP construction guide. They describe each CAP element mapped to the applicable requirements for each dissemination channel applied to that element. It shows the allowed elements by distribution channel for category, response type and event code. There is another table for special rules for area and geocodes. [Slide 13] There are tables for rules for use of resource elements, CMAM texts as a parameter, and the formula for formatting texts without the parameter. There is information on the DOM structure of the response format. Also there is a table with all the response codes and their meanings. [Slide 14] How do you send your message to one place but not another? We decided that the originator should have the ability to make choices. We are going to put “channelblock” in that will be generalizable. There may be other specialized distribution methods in the future and channelblock will be a parameter in the CAP message in which you can block a channel from receiving a message. There is a way around this now—leave out the parameter called “timezone” and your message will not be considered as an emergency message by HazCollect. Messages will not go to CMAS with a response type of “none”, but it will go to EAS. If you leave out the EAS-ORG parameter, it will not go to EAS. We are going to get better COG information so that you can retrieve permissions and we intend to give you the ability to query all un-expired public alerts, and we intended to create a public feed for all public alerts. We are interested in your requests also. This system will evolve and change. [Slide 15] There are still some issues. The NWEM issue is this—if you want a message to go to the non-weather emergency structure, you have to use only one geocode per area block. The NWEM server only reads the first one. We are looking for a way to use multiple geocodes in the same area block. The document has some examples of multi-parameter queries against the database. Right now the multi- parameter issue is not working correctly but it will be repaired. If you get an error response that is not a case that the post is read and come back, it may not match the WSDL. You may have to deal with some exceptions that do not match. We have fixed the biggest one. If you find something that you believe is an error, we would be interested in knowing. Do not hesitate to tell us. [Demo] The document is about 100 pages. It has an introduction and a description of the message structure, examples for security header, examples of digitally signed messages, descriptions of common service requests, query parameters and how those structures work and responses from those. There are multi-parameter queries. The most valuable part of the document is the element mapping to dissemination channel table. It takes an element, how it works at each level, and it has some comments on particular messages on what has to be for a message to work correctly on various distribution channels. The references are also important. The requirement for a references element is enforced at 300 up. The table gives you an understanding of how things work for various elements. We have a list of how values for info category are used in various systems. Particular event codes are used in particular kinds of messages—different codes will go to certain people and not others. There are descriptions of how area and geocodes are done. There are examples of using CMAM text and for using CMAS if you are not authorized to use CMAM text. There is a list of all event codes and descriptions of the structure of the system. There is a list of error codes. We have improved this system by sending numeric response for all errors that come back to you. You can see the error response that explains where the message was valid and where the message had an error. Avagene Moore: Thank you, Gary. We have a few questions for you. Audience Question: Is the Consolidated Messaging Status return message currently available? Are systems returning this info to the originator user? Gary Ham: IPAWS-OPEN, as part of its host message response type, or as the result of a request message response type that uses the “getMessage” status as its function call, is able to get that information. This is something developers can incorporate in their software to return the info to the originator. Audience Question: Does the COG check if proposed messages are within the jurisdiction of the COG before sending on to distribution? Gary Ham: The issue is if the COG is authorized in a particular area or not. You can send a message on a public or private message on a private basis to any COG in the system. NWEM, EAS and CMAS check if the COG is authorized as an alert originator to the public and which channels they are authorized for. Audience Question: Can Gary address the capability of the current IPAWS-OPEN to deliver audio files to broadcasters? Gary Ham: We have not stopped embedded information at this point. We have not created a place to put an audio file that can be downloaded, either. The message can refer to the file as a link, and IPAWS will pass that information, but we do not have a hosting facility for audio files. Audience Question: When will your guide be available? Gary Ham: It is being turned into a PDF file today so it should be done this afternoon. The IPAWS folks may want to review it before it goes to the website. Audience Question: If I were a small cellular company, can I ask that alerts be only sent to my distribution network COG if the alert destination or polygon is in my service area, or do I have to receive all posted alerts at the discretion of the sender COG? Gary Ham: In order to get a CMAC alert, which is a translation of CAP—those messages are made available according to standard J-101 from the cell phone industry itself. Messages can be filtered by geo-location filtering, but as far as getting the CAP message and using it your own way, I don’ t think anything can stop that except that COGs are managed by an emergency management organization. Most CMAS people are on a connection that is defined between FEMA and a CMSP gateway. That gateway is either owned by the provider or it is a hosted service provider. If you can get the CAP message you can do what you want to within the law, but to get a CMAS message, you get it through the CMSP gateway. Avagene Moore: Gary, on behalf of the IPAWS Developers, we thank you for the information shared with us today. [Slide 16] Our special thanks to you, the audience! We appreciate your presence, questions and interest. Please note the contact information included on the closing slide. We are available and willing to help if you contact us. The objective of our SIG Webinars is to keep you informed and updated as progress is made on IPAWS and IPAWS OPEN. We hope you will join us each time we meet – you are critical to the overall success of the IPAWS Program. Please stay in touch with us. We look forward to February’s SIG Webinars. The Practitioners SIG is scheduled for Weds Feb 1; the next Developers SIG meeting will be Weds Feb 15. Please watch for a mail list notice of topic and speaker for these dates. Make plans to join us! Amy Sebring: When the Developer’s guide is posted on the Website, we will send out a notice on the mailing list. We can also provide a status update with the SIG materials notice. Avagene Moore: Thank you all – the IPAWS Developers SIG Webinar is adjourned.