SOAP API

HEAT LiveTime SOAP API

The HEAT LiveTime Web Services Interface enables third party applications to interact directly with the HEAT LiveTime application in a secure and controlled fashion. The interface is based on the SOAP standard for Web Services. For more information about SOAP Web Services, please see W3C.

SOAP Messages are essentially well formed XML blocks sent using http.

SOAP Interfaces represented the first iteration of Service Oriented Architectures. HEAT LiveTime, with it’s 13 year history continues to support this legacy interface for long term customers with existing integrations in place. The SOAP API of HEAT LiveTime currently consists of eight endpoints representing key pieces of data customers have needed to manipulate through a machine interface.

About Service Oriented Architectures

A Service-oriented architecture (SOA) is software built using loosely coupled software services to support the requirements of business processes and software users. Network resources in a SOA environment are made available as independent services that can be accessed irrespective of the underlying platform implementation.

More importantly, SOA architecture enables the creation of applications that are built by combining loosely coupled and interoperable services. These services inter-operate based on a formal definition (or contract, e.g., WSDL) that is independent of the underlying platform and programming language, and the interface definition hides the implementation of the language- specific service. SOA-based systems can therefore be independent of development technologies and platforms (such as Java, .NET etc), and can be made to interact between platforms.

SOA can support integration and consolidation of activities within complex enterprise systems, but does not specify or provide a methodology or framework for documenting capabilities or services.

Working with SOAP Interfaces

The easiest way to use SOAP Web Services is through an API that will wrap the XML parsing and calling for you. Most major Web Services from Google, Amazon and eBay operate this way. Several APIs exist for SOAP but the most prevalent is Axis from the Apache Group. If you are not familiar with the Axis API, please see the Axis User’s Guide. The Axis API Reference is also a useful guide if you are interested.

Versions of Axis are available for both Java and C++. Web Services in the HEAT LiveTime application conform to the SOAP specification, so there is no reason why you could not use the XML directly from the server and parse it directly. This will require the description document (wsdl) that explains the object types returned and provides other useful information. Use of the Web Services API via direct XML parsing is outside the scope of this document.

While Axis is not required, most of the examples use Axis as it is one of the most common web services API’s in use. In addition to Axis, successful customer implementations have been achieved using the XFire, CXF & ksoap2 Java API’s, VB.NET, C# and PHP.

Session management is equally as important when using web services as it is when using HEAT LiveTime via the user interface. It is up to the user (or the client API) to maintain the http headers returned from the authentication message so that state information is retained.

Typing

HEAT LiveTime initially supported loose typing of objects using this interface. The early driving force behind these implementations were of an internal nature, and thus returning maps of values was sufficient for the internal needs. As time went by customers began asking for a machine interface to integrate other tools with their service desks, and the internal interface was exposed, but it was still structured as an internal interface. As a result, much of the documentation refers to Java ‘Map’ objects being returned and manipulated using Apache Axis, and the developer is left to ‘know’ the keys to this map (and indeed, to ‘work out’ the structure).

This presented additional challenges for customers attempting to integrate using .NET based languages, as the .NET engine required strongly typed objects to manipulate. In order to not compromise existing implementations, a variant on the loosely typed ‘Map’ based implementation was created, that return an array of WsNameValuePair objects. These (as the name suggests) are simple name-value pairs, much like you would get in a ‘Map’ but the .NET languages are better able to cope with this ‘type’ as opposed to the loose typing used initially.

These variants share their name with the loosely typed siblings, but are prefixed with an underscore ‘_’ character. For example, the ‘About’ endpoint has a functionally identical implementation called ‘_About’ which returns an array of WsNameValuePair objects instead of a ‘Map’. This is consistent throughout all service endpoint implementations within HEAT LiveTime up to and including the current production release (v8.6.2).