WEBEOC SOAP API WEBEOC SOAP API - HUBSPOT

WebEOC SOAP API

WebEOC SOAP API                     May 8, 2018   1

Presenter

                  Scott Johnson
                  Director, Software Engineering

                  Scott Johnson is the Director of Software Engineering for the WebEOC
                  suite of products.
                  As Director, Scott is responsible for the overall management of the
                  software engineering teams responsible for building WebEOC. As a
                  Director with more than 20 years of experience building enterprise web
                  applications for the emergency management industry, his current focus
                  is to develop new capabilities and incorporate new technologies into the
                  Juvare platform.

WebEOC SOAP API                                                             May 8, 2018      2

Course Objectives
    1    Gain familiarity with the API and how it is used

    2    Gain detailed information about each API function

    3    See first-hand examples of usage of the API

WebEOC SOAP API                                              May 8, 2018   3

Topics Covered
•   What is an API?
•   Examining the WebEOC API
•   Getting Started
•   Example – Public Website Interface

WebEOC SOAP API                          May 8, 2018   4

What is an API
An application programming interface (API) is a particular set of rules
and specifications that a software program can follow to access and
make use of the services and resources provided by another particular
software program that implements that API.

It serves as an interface between different software programs and
facilitates their interaction, similar to the way the user interface
facilitates interaction between humans and computers

                                                    -Wikipedia

What is an API?
• Web Development API Characteristics (“Web Service”)
   • Uses the HTTP protocol to communicate with the system
   • A simple URL serves as the API “end point”
   • Request message(s) posted to end point (XML, JSON, etc.)
   • Response message(s) returned from server (XML, JSON,
     etc.)
• Two dominant types of Web Service APIs
   • SOAP – XML response type
   • REST – XML, JSON, YAML, response types

Typical Uses of an API
• Internal Development
   • Create new features
   • Build interfaces to other systems
   • Examples: Subscription Boards, KC Interface, etc.
• External Development
   • Third-party development
   • Interfaces with other systems
   • Examples: External web site, administration, RSS feeds,
     etc.

Why Use an API?
• A powerful enabler
   •   Consistent method for accessing data in status boards
   •   Respects authentication and authorization mechanisms
   •   Maintains data integrity (foreign key relationships, constraints, etc.)
   •   Integrated with existing business logic (view filters, refreshing, etc.)
   •   Maintains backwards compatibility
   •   Eases support burden

Why Use an API? – The Bottom Line
• An API represents a contract between separate systems
   • The functions and their parameters will not change
   • Backwards compatibility will be maintained
• The API protects developers
   • From changes in the database (schema, version, etc.)
   • From changes in the underlying business logic

Using the API helps ensure that your code will not break when
the system is upgraded

What Skills Do You Need?
Development Skills
   •   Basic Programming principles
   •   Web development (client-server, http request/response, etc.)
   •   REST, SOAP and web service concepts
   •   Developer Tools (IDE, Code generation, etc.)

What Skills Do You Need?
An understanding of WebEOC concepts
   • Status boards and their structure
       • Views, tables, fields, options, etc.
   • Authentication and authorization
       • Users, positions, groups
   • Incidents and data hierarchy

The WebEOC API

WebEOC API – SOAP Web Service
Simple Object Access Protocol (SOAP) is an XML-based protocol
for exchanging structured information between systems
   • Transport method is usually HTTP, HTTPS, RPC
   • Message format is strict XML
A URL acts as the API end point
   • Provides a web services description language (WSDL)
   • The WSDL describes the methods and objects available

How to Use?
Methods to invoke
   • Manually construct envelope and messages
   • Use code generation tools (yay!)
Class Code samples rely on code generation
   • Microsoft Visual Studio
   • Creates sets of classes and methods that define the API
   • Abstracts the http calls, construction of soap envelope, etc.

WebEOC API – REST Web Service
Representational State Transfer (REST) is an HTTP-based
standard for exchanging structured information between
systems
   • Transport method is usually HTTP, HTTPS, RPC
   • Message format is often JSON, but could be others
A URL acts as the API end point
   • Different HTTP codes are used to invoke operations
   • URL typically used for indicating data type and parameters
Advantages of REST
   • Easily called with JavaScript
   • Inherits session – can be called from status board

Non-Admin Functions
•   AddAttachment       Ping
•   AddData
                        UpdateData
•   AddRelatedData
•   GetAttachment       UpdateDataBatch
•   GetData             UpdateRelatedData
•   GetDataByDataId
•   GetFilteredData
•   GetFilteredDataV2
•   GetIncidents
•   GetUpdatedData
•   GetUserPositions

Admin Functions
•   AddGroup                  GetDisplayViews
•   AddIncident               GetGroup
•   AddUser                   GetGroupNames
•   AddUserToPosition         GetIncidents
•   DeleteGroup               GetInputViews
•   DeleteList                GetListItems
•   DeleteListItem            GetListItemsByListName
•   DeleteUser                GetLists
•   DeleteUserIfNoPositions
                              GetPositions
•   EditGroup
                              GetPositionsForUser
•   EditUser
                              GetUser
•   GetBoardNames
                              GetUserNames

Admin Functions (Cont.)
•   GetUserPositions
•   GetUserByPosition
•   GetViewFields
•   RemoveuserFromPosition
•   SaveList
•   SaveListItem

API Classes
• WebEOCCredentials   WebEOCUser
   Username             Username
   Password
                        IsAdministrator
   Position
   Incident             IsMultipleUserLogin
   Jurisdiction         IsAccountDisabled
                        ChangePasswordAtNextL
                        ogin
                        IsDualCommitUser
                        PrimaryEmail
                        Color

API Classes (Cont.)
• WebEOCGroup
   Name
   Comment
   Organization
   AssignedPositions
   AssignedIncidents

Getting Started
   Visual Studio & C#

Typical API Usage
First, create a WebEOCCredentials object and populate it

Next, call the appropriate functions, passing the credentials object

Tutorial – Code Walkthrough
         Visual Studio & C#

Important Notes
• The API is stateless, so a valid credential object must be
  passed with every call
• Make sure your user account is an administrator, or at least
  has the appropriate admin profile permissions if calling an
  admin function
• If you encounter an error, inspect the XML that is returned
  from the API call (the “Detail” property is using .NET)

Example – Public Website
     Pulling & Pushing Board Data

Questions & Answers

WebEOC SOAP API          May 8, 2018   26

Thank You
                  for participating in our presentation!

WebEOC SOAP API                                            May 8, 2018   27