Change Log

v2018.3.0 (upcoming release, planned for early 2019)
NOTE: This is a major release and introduces breaking changes that will require developers using our API to make updates to their client code
  • A new GUI is available for testing. After logging in, the user will now have access to two new applications, marked "Beta," which can be used as alternatives to the Home Energy Score GUI. In an upcoming release, this "Beta" GUI will become the new Home Energy Score GUI, and will replace the old GUI.
  • The API now features two new methods, available only to HES Administrators - csv_batch_import and csv_batch_import_status
  • The retrieve_buildings_by_id method has been updated: 
    • the date_range and building_id_range fields no longer exist. They have been replaced with min_building_id, max_building_id, min_assessment_date, and max_assessment_date. 
    • The page_number and rows_per_page parameters are now optional, and default to 1 and 1000 respectively if not passed. 
    • The "archive" and "locked" fields in both request and response are now booleans rather than integers.
    • The "create_date" and "assessment_date" fields in the response are now of type "xsd:date" rather than "xsd:string"

v2018.2.1 (September 10, 2018)
  • retrieve_buildings_by_id has been updated so that the date_range filter now correctly filters by the date a building was created rather than the assessment date
  • The API now features a new method, copy_building, which allows a new building to be created based on the values in another building. See the documentation under http://hes-documentation.labworks.org/home/api-definitions/api-methods/copy_building
  • The XSD has been updated to define a number of entities that were previously redundantly defined to refer to common definitions. None of these changes should require client updates, as they are simply consolidation of redundant code.
  • The GUI no longer offers "Puerto Rico" as a state -- this state was never supported by the API, and selecting it triggered an error.
  • The Partner and Administrator export methods have been updated so that the field create_label_date now correctly reflects the date on which the label was actually generated. Previously it contained the most recent date on which calculate_base_building or calculate_package_building had been called for that building, which could introduce inaccurate information for some buildings.

v2018.2.0 (August 2018)
  • Buildings now have a "status" attribute, accessible via the new "get_building_status" method. The method's documentation explains the meaning of each status. This feature supports a number of enhancements to the API, for example it makes it impossible to generate a label while calculate_package_building is running, and allows us to change how building deletion works in the backend to reduce the risk of losing historical data.

v2018.1.3 (July 2018)
  • An error that occurred for some buildings with evaporative coolers has been resolved.
  • upload_label can now optionally be called with the parameter pdf_url rather than pdf_base64. Using the new parameter allows passing the URL of a label PDF file, which is then downloaded and stored as the canonical copy of the label.
  • The API's XSD files have been updated to be more consistent with each other and with the underlying API functionality
    • user_key now has an identical definition across all methods
    • generate_custom_label's and generate_label's responses' "file" field now correctly includes only "png" and "pdf" values

v2018.1.2 (June 2018)
  • Added the new submit_hpwes and retrieve_hpwes methods.
  • The `archive` field of the retrieve_buildings_by_id method may now be omitted from the request, in which case both archived and unarchived buildings will be included in the result.
  • The export_label_results method now includes the label URL in the exported CSV files
  • The batch_update method now accepts a "void" assessment type, which cannot be assigned to a home via any other method
  • Updated internal SOAP client and server from the obsolete Zend_Soap_Server and nusoap classes to use the native SoapServer and SoapClient classes. This should be a seamless transition - the only known change is to the handling of invalid inputs, which will sometimes be cast automatically to a valid type in some circumstances. However, since this is a change to a library that is used in every call, there is the potential for unintended backwards compatibility breaks. These will be documented here if discovered.
GUI
  • Removed the "Detailed Label Results" page for Administrator users, as the information there is now available from the CSV export 
  • Added new "Home Performance with Energy Star" (HPwES) fields to the Systems page.
  • The batch update feature of the administrator's dashboard now supports setting assessment type to "void"
v2018.1.1 (May 2018)
  • Custom logos for the label footer were previously required to be exactly 550 or 820 pixels wide (the wider width was used for landscape) and the uploaded image was stretched to fit those proportions. This caused a problem with wide logos because they couldn't be made to fit properly on the portrait pages of a label. This has been changed in two ways: The maximum width of logos is now uniformly 550 pixels, and narrower images are no longer stretched.

v2018.1.0 (March 2018)
  • Added the new batch_update method
  • The methods export_label_results and export_partner_label_results now generate CSV files rather than Excel files
GUI
  • Administrator users can now batch edit the external_building_id and assessment_type values of a building in the Administrator Dashboard
  • It is now possible to have a heatpump that provides only heating or only cooling by setting the other system type to “None” (though some such combinations will result in a model validation error)
  • Increased the size of the dashboard table in all dashboard views. The additional space was used to add more fields.
  • Fixed a validation error that allowed homes without any floor area
  • Fixed an issue that could cause an invalid address to be accepted without validation in some circumstances
  • Numerous minor bugfixes 


v2017.3.1 (February 2018)

  • retrieve_buildings_by_partner now correctly generates an error message when an invalid partner ID is passed
  • If a request is not parseable (invalid SOAP XML) it will now return an error response instead of failing silently

v2017.3 (January 2018)

  • Added the new "preconstruction" assessment type
  • The API now has a new upload_label method that allows an Assessor user to upload a label PDF rather than using the API's internal label generation.
  • Numerous improvements in error handling to make error messages more verbose and to provide meaningful specific errors rather than generic "unexpected error" responses in more situations.


v2017.2 (October, 2017)

This release adds authentication to the API to prevent inappropriate access to data.

New methods: get_session_token and destroy_session_token. A call to get_session_token requires the user's qualified_assessor_id (user name) and password. The response contains a session_token field, which must be provided as a parameter for every other API method. Upon completion of a session, the destroy_session_token method can be triggered to invalidate the session token.

The session_token allows the API to permit and deny access to methods or results depending on the logged in user's permissions. Attempting to access methods or values that are not permitted results in a SOAP Fault response.

We have also taken this opportunity to clean up the API a bit by removing obsolete methods and fields.

Every method (except for get_session_token) now includes a mandatory session_token field. In addition, the following methods have been altered as documented:

  • archive_buildings_by_id, delete_buildings_by_id: 
    • qualified_assessor_id is removed. The user is determined from the session token.
    • The user must have the Assessor role and be the creator of the requested building (Note: This is not changed behavior but was hard-coded into the method previously and is now handled by the common access control layer).
  • calculate_base_building, calculate_package_building, commit_results
    • The fields validate_inputslog_type, and is_polling have been removed
    • Admin: All building IDs are permitted
    • Assessor: Only buildings assessed by the assessor are permitted
  • retrieve_extended_results, retrieve_inputs, retrieve_recommendations, retrieve_results, retrieve_label_results
    • The fields validate_inputslog_type, and is_polling have been removed
    • The values allowed to be in buildings or building_id are restricted based on the user's role(s)
      • Admin: All building IDs are permitted
      • Partner: Only buildings assessed by an assessor belonging to the Partner are permitted
      • Assessor: Only buildings assessed by the assessor are permitted
  • export_label_results
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Admin role to call this method
  • export_partner_label_results
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Partner role to call this method
  • generate_custom_label
    • The user must have the Admin role or must have the Assessor role and be the assessor that created both buildings
  • generate_label
    • is_polling is removed - this method already does not support asynchronous calls, so this has no impact on the method
    • The user must have the Admin role or must have the Assessor role and be the assessor that created the building
  • retrieve_buildings_by_id
    • If the user has the Admin role, no restrictions apply
    • Otherwise, if the user has the Assessor role, qualified_assessor_id must be set to the user's name
    • Users with only the Partner role may not use this method. They should use retrieve_buildings_by_partner instead
  • submit_address, submit_hpxml_inputs
    • assessor_id is removed. The user is determined from the session token.
    • User must have the Assessor role
  • submit_inputs, validate_inputs
    • User must have the Assessor role and must be the user that created the building to be updated
  • retrieve_buildings_by_partner
    • partner is now optional
    • Admin: Must pass the partner field 
    • Partner: May not pass the partner field. Instead the method always returns results filtered for the currently logged-in partner.
  • These methods have been removed from the HEScore API
    • calculate_package_building_poll
    • calculate
    • doe2sim
    • doe2sim_multi
    • nearest_weather
    • retrieve_buildings_by_address (Use the address field of retrieve_buildings_by_id instead)
Comments