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
• QA - All

3
Objectives

• Explain the DM approach to APIs
• Provide a technical overview

4
EM XML Snapshot

• Matt Walton

5
Whats 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
Whats 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
Whats 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

Current Configuration
Two basic modes
9

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
SAFECOM
Today!
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)

16

17

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
Whats 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, see
  http//www.dmi-services.org/registration_center.as
  p.

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/yourLo
  ginHere")
• ((TieSoapBindingStub)tie).setPassword(easyPasswor
  d")
• VB example
• "ws" is our stub class in this example
• Dim myCred New System.Net.NetworkCredential(999
  9/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 charsetutf-8
• Accept application/soapxml, 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 JSESSIONID1EA6288365804756081F2E8338BAFCB
  6
• lsoap.org/soap/envelope/" xmlnsxsd"http//www.w3
  .org/2001/XMLSchema" xmlnsxsi"http//www.w3.org/
  2001/XMLSchema-instance"
• ttp//schemas.xmlsoap.org/soap/encoding/"
  xmlnsns1"http//dmi-services.org"/

9999/yourLoginHereeasyPassword
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

IncidentSite address Address criticalInfrastru
cture 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 IncidentNotifi
cationLevel IncidentPhase IncidentSeverity Inciden
tType
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 AttachmentDescripto
  rs.

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