Interoperability API Overview

1. Interoperability API Overview May 21, 2003

2. Agenda • Welcome / Meeting Objectives – Mark Z. • EM-XML “Snapshot” – Matt Walton • Introduction – Dick Munnikhuysen • Tech Overview of DMIS – Joe Kessler • Interoperability in DMIS – Neil Bourgeois • Reportable Level API – Jerry Warden • API and EM-XML Standards. – Gary Ham • Roll out and Access – Dick Munnikhuysen • Q&A - All

3. Objectives • Explain the DM approach to APIs • Provide a technical overview

4. EM XML “Snapshot” Matt Walton

5. What’s that mean in the real world? • Consider: • St Louis Riverfront Festival, July 4 • Terrorist rocket into chlorine tank car • Lethal plume across: • Unprotected thousands • Multiple municipal jurisdictions • 2 states • 2 FEMA regions • With an interoperability service, organizations can: • Share information • Gain early awareness • Coordinate response • Save lives and minimize property damage • Despite differing automated systems

6. What’s the solution? • Leverage technology to gain efficiency • Develop a national emergency information interoperability service Interoperability Service enabling horizontal & vertical information sharing Nation Region State EOC EOC Local ICP

7. What’s an Interoperability Service? An infrastructure with common service functions that enable heterogeneous automated information systems to “talk to each other.” Interoperability Services Communications Infrastructure Transaction Management Transaction Queuing Transaction Re-synchronization Time Synchronization Access Reconciliation Transaction Alerts Receipts Posting Incident Command System A Incident Management System C Import/Export Acknowledgements Incident Management System B

8. Internal collaboration External sharing via Post function Another COG Your COG State EM DPH EMS Emergency Internet Manager Internet Shared View – Posted from your COG Collaboration View – Updated from within COG Shared View – of your information CMI-Services Interoperability Hub State Police Police Transportation Fire Dept. Current Configuration Two basic modes:

9. State DEM COG State EM DPH Internet Shared View – of your information Shared View – Posted from Local COGs Internet State Police Transportation How do COGs work? Future Configuration Internal collaboration External sharing via Post function Local Fire COG Fire Chief Station 1 EMS CMI-Services Interoperability Hub Local CMIS Interoperability Hub Police Chief Precinct 1 Local Police COG Precinct 2

10. In response to HSPD-5, converging roads to NIMS technologies. . . Geospatial One Stop Dhelp collaboration tools and expert reference Today! SAFECOM Mature NIMS NIMS quick start DM DMIS interoperability infrastructure and basic responder tools EM-XML E-Authentication Government / science / industry collaboration developing technologies for homeland security

11. Technical Overview

12. Goals & Constraints • Goals • Provide foundation for information sharing • Basic capabilities for “have not” stakeholders • Long-term focus on broader information sharing • Server Constraints • Flexibility to adapt to shifts in technology • Capacity to scale to the national level • Good measure of privacy • Desktop Constraints • Good performance on “real world” stakeholder hardware • Demonstrative of overall integration strategy • Strategy • Establish overarching paradigm & implement framework • Create basic tools to validate paradigm & provide core functionality • Extend paradigm and refine focus on vendor interoperability

13. Computing Requirements • Core access is through SOAP/XML • Platform independent • Language independent • Operating system • Windows, Unix, Linux, others … • No constraints are imposed, interaction is platform-independent • Programming languages • Java, C++, Microsoft .NET, others … • We have sample clients written in various environments • Internet access • Peripherals required by client applications • e.g. camera/microphone for on-line conferencing

14. Architectural Framework • Based on “messaging” technology • Resilient to disruption in communication • Location independence • Provides single point of entry into server (enhances security) • Works in concert with hardware infrastructure • Load balancing and redundancy • Reliability & scalability • Platform for interoperability • Messaging is an ideal foundation for a Service Oriented Architecture • Messages can be neatly wrapped using SOAP • Features built on messaging foundation • Interoperability features • Collaboration features • Offline operation features • Notification features

15. Application & Service Integration • Services reside on logical server • Most business logic is encapsulated remotely • Services are invoked using messages, collectively forming an API • Functions can be presented via GUI, HTTP, SOAP, etc. • Desktop is “container” for applications • Provides basic services such as authentication • Applications “snap in” by • Implementing specific interfaces • Being declared inside initialization files • Interaction with services is through messaging • Overall integration strategy • “Separation of Church and State”, or API-based integration • Modular services offering various functions • Modular clients focused on presentation • Integration points to be opened at both ends (server & desktop)

18. Levels of Interoperability “Maturity” • Reportable – exchange of reports / attachments as files associated with a set of (primarily) delivery related data • Presentable – delivery of diverse information structures across applications without semantic assessment or translation • Processable – application of algorithms to process or validate the semantic meaning of exchanged information • Standards based (i.e., EM-XML) – standard data structures and business rules for processing • “Common Processable Form” - a standard dynamic structure with capabilities for dynamically capturing structure, business rules for processing, and even self-processable objects. • Expose Other Services – expose services provided by Interoperating Systems and other DMIS services (e.g., Structured Weather Data – Accuweather and NWS/NOAA in the future, National Street-Level Map Data (GDT, NavTech), Responder Alerting, etc.)

19. Interoperability

20. What’s an Interoperability Service? An infrastructure with common service functions that enable heterogeneous automated information systems to “talk to each other.” Interoperability Services Communications Infrastructure Transaction Management Transaction Queuing Transaction Re-synchronization Time Synchronization Access Reconciliation Transaction Alerts Receipts Posting Incident Management System C Import/Export Acknowledgements Incident Command System A Incident Management System B

21. The Approach • Standards-based web services • SOAP/XML

22. Why Web Services? • "Interoperable" means suitable for and capable of being implemented in a neutral manner on multiple operating systems and in multiple programming languages. • The World Wide Web is more and more used for application to application communication. The programmatic interfaces made available are referred to as Web services. • Web services interoperate across platforms, operating systems, and programming languages.

23. Terms TIE Tactical Information Exchange; the service that allows the interchanging of incident data. Incident The core of the TIE; an incident is any event requiring the notice of users of DMI-Services. This is often a disaster demanding the attention of various disaster management services, but could also be a training scenario.

24. Terms (cont) COG A Collaborative Operations Group within DMI-Services. This is a group of users that share incident data; the DMI-Services Web Services allows users from one COG to post information to or receive information from other COGs. In order to use the services, users must be members of a DMI-Services COG. For details about creating your own COG and gaining access to DMI-Services Web Services, seehttp://www.dmi-services.org/registration_center.asp.

25. Terms (cont) Post To “post” an incident is to make it available to other COGs. Attachment Logically, any file that is attached to an incident. This could be a map of the area, a statement from bystanders, or any other file germane to the incident in question.

26. API • Small API at first for basic capability

27. Typical interaction (Retrieval) • Ping() the service to make sure service is up, and user is authenticated. • A call to getAllIncidents() is made to retrieve a list of TieIncidents. • A call can then be issued on getIncident() to obtain detailed incident information in the form of a TieIncident object.

28. Typical interaction (Retrieval – cont) • A call to getAttachmentList() returns a list of AttachmentDescriptors for a given incident. • Attachments can then be downloaded via a call to getAttachments().

29. Typical interaction (Posting) • Ping() the service to make sure service is up, and user is authenticated. • A call can then be issued on getCogs() to obtain a list of SimpleCog objects. • Finally, call postIncident() with the list of SimpleCogs to post to, the TieIncident, and an optional list of AttachmentDescriptor objects.

30. Key systems  Certain calls through the Tie interface require an ID that references a particular incident. Since many clients will be using their own key systems, and some will not, we will provide a means to use either. When posting an incident, if the vendorUniqueId is not set, we will provide one as the return value of the postIncident() function call. This value can then be used in subsequent calls to reference that incident. For example, this value can be used to re-post an incident by setting vendorUniqueId to it.

31. Attachments There is a correlation between the files specified in the array of AttachmentDescriptor and the attachments appended to the soap message to be dispatched. They correspond in order. The only mandatory member in this object is the fileName, which is just the filename portion without path information. For a post with attachments inThisMessage should be set to ‘true’ and deleteMe should be set to false. To update and version an incident that has attachments which will be deleted in the current version, set deleteMe to true and inThisMessage to false.

32. Authentication Overview Authentication is handled through basic HTTP. An “Authorization: Basic” header must accompany every request. Typically, the stub implementation will provide a convenient way to set it. Incident Management System DMIS

33. Authentication Examples Java example ((TieSoapBindingStub)tie).setUsername(“9999/yourLoginHere"); ((TieSoapBindingStub)tie).setPassword(“easyPassword"); VB example "ws" is our stub class in this example: Dim myCred = New System.Net.NetworkCredential(“9999/yourLoginHere", “easyPassword") Dim myCache = New System.Net.CredentialCache() myCache.Add(New Uri(ws.Url), "Basic", myCred) ws.Credentials = myCache ws.PreAuthenticate = True

34. Web Service Sessions Client session (cookie) management is not absolutely required. However, performance gains may be realized if implemented. Java example ((TieSoapBindingStub)tie).setMaintainSession(true); VB example Dim cookieJar As CookieContainer ' Check to see if the cookies have already set up If (ws.CookieContainer Is Nothing) Then ' Assign the CookieContainer to the proxy class. ws.CookieContainer = New CookieContainer() End If

35. SOAP MESSAGE EXAMPLE POST /axis/services/Tie HTTP/1.0 Content-Type: text/xml; charset=utf-8 Accept: application/soap+xml, application/dime, multipart/related, text/* User-Agent: Axis/1.1beta Host: computerName Cache-Control: no-cache Pragma: no-cache SOAPAction: "" Content-Length: 394q Authorization: Basic Mi91c2VyMzpwd2QwMDM= Cookie: JSESSIONID=1EA6288365804756081F2E8338BAFCB6 <?xml version="1.0" encoding="UTF-8"?> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Body> <ns1:getAllIncidents soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://dmi-services.org"/> </soapenv:Body> </soapenv:Envelope> 9999/yourLoginHere:easyPassword

36. Types AttachmentDescriptor { deleteMe : boolean fileName : string inThisMessage : boolean modifiedDate : long pathName : string } SimpleCOG { id : long name: string } TieIncident { vendorUniqueId : string name : string number : string date : dateTime version : long hasAttachments : boolean description : string remarks : string confidence : IncidentConfidence category : IncidentCategory cog : SimpleCOG ownerCog : SimpleCOG notificationLevel : IncidentNotificationLevel phase : IncidentPhase severity : IncidentSeverity status : IncidentStatus type : IncidentType sites[] : IncidentSite } • IncidentSite • { • address : Address • criticalInfrastructure : int • description : string • hasContacts : boolean • id : long • name : string • plottableOnMap : boolean • populated : boolean • primarySite : boolean • propertyUse : string • timeZoneId : int • }

37. Types (cont) Address { addressLine1 : string addressLine2 : string city : string cogId : long crossStreets : string empty : boolean id : long latitudeCoordinate : double locatable : boolean longitudeCoordinate : double stateCode : USStateCodeType zip : string } Enumerated types: IncidentStatus { Unknown | Worsening | Improving | Under Control | Closed } IncidentConfidence IncidentCategory IncidentNotificationLevel IncidentPhase IncidentSeverity IncidentType

38. Method descriptions ping() This method takes no parameters and has no return value. It is used simply to verify that the service is up and running and user is authenticated. getAllIncidents() This method takes no parameters and returns a listing of core incident information returned in the form of an array of TieIncident.

39. Method descriptions (cont) getIncident() This method takes a incident ID and version number and returns detailed incident information returned in the form of a TieIncident. getAttachmentList() This method takes an incident ID and version number and returns an array of AttachmentDescriptors.

40. Method descriptions (cont) getAttachments() This method takes an incident ID, a version number, an array of file names and a boolean to specify whether attachments should be retrieved in DIME format or in conformance with the SOAP with Attachments specification (MIME). getCogs() Returns a list of valid SimpleCOGs. May be used to get the possible COGs for a postIncident() operation.

41. Method descriptions (cont) postIncident() This method takes three arguments: an instance of TieIncident, an array of SimpleCOGs and an array of AttachmentDescriptors. The array of SimpleCOGs should not contain duplicates or the source COG in the mailing list. The return value is the ID (either provided or a DMIS- generated ID as a result of the post) for the incident and could be used in subsequent calls.

42. Relating the “Reportable” API to EM – XML Standards

43. The Reportable API • Uses a simple wrapper around an information payload such that it can use DMI-S COG structure and distribution permissions to share information using DMIS “shared information space control” functionality. • Provides sharing to and from DMI-S COGS interacting with data sources external to DMI-S. • Can also provide “through service” from external source to external destination using the DMI-S controlled information space. • Can be standards compliant, but is not standards enforcing or standards exclusive • Could be used to increase the level of standards adoption.

44. Reportable API: The Attachment • Can be any file of any type: “standard” or not • If not standard: • The file must “known” on both ends • Become, in effect, point-to-point processing through a distributed interface • Current and Potential Standards: • Standard document types (e.g., Word, Excel) • Process capable standards (e.g., EM-XML) • Others (e.g., shape files, other OASIS and non-OASIS XML structures, etc.)

45. Sharing EM-XML Standard Data • Build attachment payloads that validate against an adopted standard. • Add elements to the DMI-S interoperability API that point to the standard represented in the payload. • Payloads could then be pre-validated in DMI-S against the standard. • Destinations could register their interest and/or ability to handle particular payloads. • The DMI-S “information space” provides security and a consistently organized common sharing environment under DHS auspices that preserves local management needs.

46. Future Levels of Interoperability • This is what could be done at the pure “reportable” level of interoperability. • Standards (such as EM-EML) add even more convenience at increased interoperability levels as operational interfaces (its not just the data) find their way into the schemas. • (But that is a future discussion).