I’ve had a number of requests recently about integration at the B2B level with Microsoft Hohm. These range from the “how does it work” to “have you thought about X”, so I thought I’d put some of that information here for now. Before I go into any detail on the SDK, I just want to make it clear that this isn’t the Hohm Device SDK that’s been talked about and was recently announced. Stay tuned for more details on that as I’m able to talk about it.

The integration SDK is used for linking customer energy consumption data (gas, electricity, water, oil, propane), customer invoices, and pricing information with the specific customer account in Hohm. The SDK is standards-based, secure by design, and utility-friendly. The following is a stripped down but extended version of a presentation that I do for our utility partners. This is public information that can be found on MSDN, but with additional clarification and details.

One thing that needs to be stated up front though: “SDK” is a bad name because it implies technology requirements. This SDK is a collection of protocol specifications in WSDL and XSD. That’s it. Nothing more. No reason to buy anything from Microsoft to make it work (well, if you want to read the pretty documentation which is in CHM format you need something like Windows).

Overview

Secure customer data transfer authorization
Data transfer authorization is performed over a secure web services channel.
Utility-controlled transfer authorization
The utility is ulitately responsible for customer authentication and authorization. Hohm simply collects the information and forwards a request to the utility.
Utility-controlled customer de-authorization
At any time the utility can stop data transfer for an opted-in customer.
One-stop shopping for user access to data and connections
Hohm provides a single interface and experience for connecting to all of a customer's utilities. If the utility integrates with Hohm, the customer can manage that connection without leaving the experience. This is important for those cases where a customer has multiple service points to manage: different energy providers, different homes, etc.
User-controlled opt-in and opt-out
The user is responsible for opt-in. Hohm can't opt-in a customer. The utility can't opt-in a customer. The decision is in the customer's hands where it belongs.
More stuff on the horizon
We're actively extending the classes of data we accept for integration. Watch this space for announcements about new types.

Design goals

Integration independent of time and location
The overall integration pattern, and a core design in the application, is that everything is asynchronous. That is, each web service interaction is assumed to be a long-running transaction punctuated by short request / response messages. There will never be a time when the user interface is blocked waiting for something to happen over the integration channel, nor will there be a time where Hohm reaches into a utility back office system for information.
Standards-based
  • We bet heavily on WS-* for our core integration stack. It's proven over time. It's mature. Tooling is available. Utility IT departments have bet on it too.
  • SOAP 1.2 is the core of our message-passing architecture.
  • X.509 certificate-based authentication is used to identify both parties in a conversation. No special key or username / password pair is ever needed or stored.
  • HTTPS transport is used for the message channel and for moving the customer data.
  • No dependencies on specific technology or platform.
Scalable to many partners
Because of the asynchronous nature of the protocol, and the decision to separate message passing from API from data transfer, Hohm can easily scale to support all of our partners.
Version-safe and extensible
The request / response structure is distinct from the API and the data transfer formats are separate from both. We can release new messages over the same API and add file formats without affecting existing partners. Partners can migrate over time to handle new messages.
Lightweight
There are only three "methods" to implement and the request structure is shallow and easily understood.
Secure by design
we've been accused of taking a "belt and suspenders" approach to security for the integration, but can you be "too secure" with customer data? We didn't think so.

Security overview

Identity management
LiveId authentication of user at Hohm application.
Partner authentication
X.509 certificates (both ends of all connections are secured).
Customer authentication
Owned by the utility, not by Microsoft.
Data security – HTTPS, encryption
All file data is sent encrypted and signed in a channel distinct from that used for message passing.
Web services security – HTTPS, WS-Security
All traffic is sent over (bidirectional SSL) HTTPS and all requests are authenticated using certificates.
Privacy concerns
No PII is required.
The CustomerId is defined by the Utility and isn't convertable to PII.
Hohm will ignore all data for unknown customers.

SDK contents and availability

Publicly available on MSDN
Sample client and service implementations
  • Windows Communication Foundation (C#)
  • Metro / WSIT for java (Glassfish V2, V3, and Websphere)
  • Sample encryption / compression implementation in java and C#
  • Sample schema validation implementation in java and C#
WSDL for both web service endpoints
XML schema definitions for file formats
Additional documentation
.NET-based test and development tool