Key Information

Register
Submit
The challenge is finished.

Challenge Overview

Challenge Overview

The Green Button Standard is a secure way of transmitting energy usage information developed by the United States Department of Energy.

The goal of this challenge is to develop a Ruby based gem to allow third-party applications the retrieval of Green Button XML formatted data and return the data as a Ruby objects with specific attributes.

This follows the path known as Green Button Connect in the Green Button Documentation.

Challenge Requirements

You are developing a Ruby based gem in this challenge that retrieves Retail Customer data using GreenButton RESTful API.

Before getting started coding, you are encouraged to look at this page that gives overview about GreenButton Concept, API and Entities.

General Notes

  • This version will only handle UsagePoints of service category (kind) = 0 (Electricity), if the downloaded data is not of type Electricity then returns error to caller stating that we only support Electricity data in this version.

    • For more information about UsagePoints kinds, refer to this xsd file that has rich documentation about the entities in GreenButton.

  • This gem will be extended in future to extract different kinds. Your solution should be flexible to add more parsers without much efforts (i.e. use facade and adapter design pattern to address this).

  • All dates are stored in UTC format, when parsed it should be converted to the local timezone using LocalTimeParameters returned in the XML response.

Expected SDK Usage

The gem should have a single module GreenButton, sample usage would look like this :

require ‘greenbutton’

gb = GreenButton.downloadData(accessToken, subscriptionId,.. some optional parameters .. )

where accessToken is retail customer access_token and subscriptionId is the retailCustomer resourceURI (i.e. https://services.greenbuttondata.org/DataCustodian/espi/1_1/resource/Batch/Subscription/5)

The returned gb is a collection of gb_data_description instances.

Parsing the XML response

The GreenButton Wrapper Classes

  • Define the module with name : GreenButton

    • It will expose ‘downloadData’ function with following parameters

      • accessToken : represents the retail customer access token

      • subscriptionId : represents the retail customer resourceURI

      • interval_start_time (optional) : represents the start date to retrieve data.

      • interval_end_time (optional) : represents the end date to retrieve data.

      • The method will call the GreenButton API using the subscriptionID URI and pass accessToken in header ‘Authorization’. and set the optional intervals if set. Refer to the Swagger documentation to understand the parameters to pass.

      • The XML response from API call will be passed to target Parser based on the service category (kind), we only support Electricity in this challenge.

    • Build  a Parser to handle parsing the returned XML. The referenced gem ruby library above should be helpful.

    • For each UsagePoint create gb_data_description for common attributes, and gb_data_array that hold gb_data entries of interval blocks.

    • Create the gb_data entries of interval blcoks from the parsed XML.

      • Below are the mapping between XML and attributes.

    • Return the gb_data_description entries.

    • Note the module should be initialized with following information :

      • the 3rd party admin access tokens :

        • Here is more details about the access tokens

        • ‘client_access_token’, and ‘registration_access_token’ should be a private members, and initialized before using the module.

      • applicationInformationURL : this is used to retrieve custodian ID, as it is available in the application information structure.

  • GreenButton should provide two classes :

    • gb_data_description

      • Handle attributes common to UsagePoint interval blocks (gb_data).

      • Attributes are:

        • custodian

          • When setting this value, you need to execute applicationInformationURL call with ‘registration_access_token’ set in Authorization header.

          • The response XML contains the custodian id, try it in sandbox to see the response sample.

        • user_id : this should be set to the passed access_token.

        • commodity

          • this info exists under Meter Reading Data XML

        • currency

          • this info exists under Meter Reading Data XML

        • unit_of_measure

          • this info exists under Meter Reading Data XML (uom element)

        • power_of_ten_multiplier

          • this info exists under Meter Reading Data XML

        • gb_data_array - collection of gb_data

        • updated - last updated date/time

          • this info exists under Interval Block Data XML

      • Methods are :

        • new()

          • Creates new instance

        • _parse

          • returns a hash (dictionary-like) of parsed elements

    • gb_data

      • Handles the green button entry values.

      • It holds Interval Block information

      • Attributes are:

        • gb_data_description_id

        • time_start - in local time

          • Use LocalTimeParameters to convert the date

          • this information retrieved from IntervalBlock > Interval > start

        • time_duration

          • this information retrieved from IntervalBlock > Interval > duration

        • interval_readings

          • This holds array of gb_data_interval.

      • Methods are :

        • _parse   

          • returns a hash of parsed elements

    • gb_data_readings

      • This holds interval readings

      • attributes are :

      • time_start - in local time

        • Use LocalTimeParameters to convert the date

        • this information retrieved from IntervalBlock > IntervalReading > timePeriod > start

      • time_duration

        • this information retrieved from IntervalBlock > IntervalReading > timePeriod > duration

      • value

        • this information retrieved from IntervalBlock > IntervalReading > value

      • cost

        • this information retrieved from IntervalBlock > IntervalReading > cost

GreenButton Data Model

You can find details about Greenbutton model definition in this page.

OAuth 2.0 and GreenButton API Endpoints

You need to pass OAuth 2.0 access token when communicating with the API. The SDK should accept an access token be passed as input to the downloadData method.

Sandbox has OAuth server turned-off so you will be using a predefined-tokens listed in this page for testing purpose.

Also since the module accepts the API endpoint to be executed as input parameter, you can use sample data (check References section below) instead of hitting the sandbox directly.

Ruby API Client Framework

To communicate with the GreenButton API, there are a number of HTTP client gems out there such as Typhoeus, Faraday and httparty. The standard library includes Net::HTTP, however it isn't very straightforward to use.

It is up to you to pick up an existing gem library or do it from scratch.

Abstracting

Please make sure to create mixin to include the common code/functionality.

Setting Up the Gem

Use Bundler to take care of gem dependencies.

A standard folder structure would look like this :

��������� Gemfile
��������� LICENSE.txt
��������� README.md
��������� Rakefile
��������� benzinator.gemspec
��������� lib
   ��������� greenbutton
   ���   ��������� version.rb

   |    ��������� <class-name>.rb

   |    ��������� model

   |          ��������� <model-name>.rb
   ��������� greenbutton.rb (the module entry point)

Writing Tests

All of your code should be test covered (RSpec preferred).

As mentioned above, you can use the Sandbox or host the sample data to test your solution.

If you see any problem with sandbox stopped behaving normally, post in challenge forums, and we will reset it (Sandbox).

Documentation

Because other programmers will be working with your code, and incorporating it into their projects, all functions must be documented in detail in the code (TomDoc preferred).

Coding Standard

Follows coding standards listed here:

https://github.com/copycopter/style-guide and  https://github.com/copycopter/style-guide

Readme

Provide a detailed readme file using Markdown language with following information :

  • Overview

  • Setup Prerequisites

  • How to install

  • Usage Example

  • Reference to GreenButton API Documentation

  • Reference this Ruby Gem Documentation

  • Any details about any limitations of your solution.

Please note, we're judging this competition not just on the code, but also on the quality of the documentation, test coverage, and ease of use.

References


 



Final Submission Guidelines

Deliverable

  • All source code files and scripts that addresses the challenge requirement.

  • Detailed readme file as clarified above.

ELIGIBLE EVENTS:

2015 topcoder Open

REVIEW STYLE:

Final Review:

Community Review Board

Approval:

User Sign-Off

SHARE:

ID: 30048922